Definizione dello schema di archiviazione tramite una definizione di record (anteprima)

Avviso

La funzionalità di archiviazione vettoriale del kernel semantico è in anteprima e i miglioramenti che richiedono modifiche di rilievo possono ancora verificarsi in circostanze limitate prima del rilascio.

Panoramica

I connettori dell'archivio vettoriale del kernel semantico usano un approccio basato sul modello per interagire con i database e consentono di annotare i modelli di dati con le informazioni necessarie per la creazione di indici o il mapping dei dati allo schema del database.

Un altro modo per fornire queste informazioni è tramite definizioni di record, che possono essere definite e fornite separatamente al modello di dati. Ciò può essere utile in più scenari:

• Può verificarsi un caso in cui uno sviluppatore voglia usare lo stesso modello di dati con più configurazioni.
• Può verificarsi un caso in cui lo sviluppatore voglia archiviare i dati usando uno schema molto diverso per il modello e voglia fornire un mapper personalizzato per la conversione tra il modello di dati e lo schema di archiviazione.
• Può verificarsi un caso in cui uno sviluppatore voglia usare un tipo predefinito, ad esempio un dict o un formato ottimizzato come un dataframe e vuole comunque sfruttare la funzionalità di archiviazione vettoriale.

Di seguito è riportato un esempio di come creare una definizione di record.

using Microsoft.Extensions.VectorData;

var hotelDefinition = new VectorStoreRecordDefinition
{
    Properties = new List<VectorStoreRecordProperty>
    {
        new VectorStoreRecordKeyProperty("HotelId", typeof(ulong)),
        new VectorStoreRecordDataProperty("HotelName", typeof(string)) { IsFilterable = true },
        new VectorStoreRecordDataProperty("Description", typeof(string)) { IsFullTextSearchable = true },
        new VectorStoreRecordVectorProperty("DescriptionEmbedding", typeof(float)) { Dimensions = 4, DistanceFunction = DistanceFunction.CosineDistance, IndexKind = IndexKind.Hnsw },
    }
};

Quando si crea una definizione, è sempre necessario specificare un nome e un tipo per ogni proprietà nello schema, poiché è necessario per la creazione dell'indice e il mapping dei dati.

Per usare la definizione, passarla al metodo GetCollection.

var collection = vectorStore.GetCollection<ulong, Hotel>("skhotels", hotelDefinition);

Classi di configurazione della proprietà record

VectorStoreRecordKeyProperty

Utilizzare questa classe per indicare che la proprietà è la chiave del record.

new VectorStoreRecordKeyProperty("HotelId", typeof(ulong)),

Impostazioni di configurazione vectorStoreRecordKeyProperty

Parametro	Richiesto	Descrizione
DataModelPropertyName	Sì	Nome della proprietà nel modello di dati. Usato dai mapper predefiniti per eseguire automaticamente il mapping tra lo schema di archiviazione e il modello di dati e per la creazione di indici.
PropertyType	Sì	Tipo della proprietà nel modello di dati. Usato dai mapper predefiniti per eseguire automaticamente il mapping tra lo schema di archiviazione e il modello di dati e per la creazione di indici.
StoragePropertyName	No	Può essere utilizzato per specificare un nome alternativo per la proprietà nel database. Si noti che questo parametro non è supportato da tutti i connettori, ad esempio se le alternative come JsonPropertyNameAttribute sono supportate.

Suggerimento

Per altre informazioni sui connettori che supportano StoragePropertyName e sulle alternative disponibili, vedere la documentazione per ogni connettore.

VectorStoreRecordDataProperty

Utilizzare questa classe per indicare che la proprietà contiene dati generali che non sono una chiave o un vettore.

new VectorStoreRecordDataProperty("HotelName", typeof(string)) { IsFilterable = true },

Impostazioni di configurazione vectorStoreRecordDataProperty

Parametro	Richiesto	Descrizione
DataModelPropertyName	Sì	Nome della proprietà nel modello di dati. Usato dai mapper predefiniti per eseguire automaticamente il mapping tra lo schema di archiviazione e il modello di dati e per la creazione di indici.
PropertyType	Sì	Tipo della proprietà nel modello di dati. Usato dai mapper predefiniti per eseguire automaticamente il mapping tra lo schema di archiviazione e il modello di dati e per la creazione di indici.
IsFilterable	No	Indica se la proprietà deve essere indicizzata per il filtro nei casi in cui un database richiede il consenso esplicito per l'indicizzazione per proprietà. Il valore predefinito è false.
IsFullTextSearchable	No	Indica se la proprietà deve essere indicizzata per la ricerca full-text per i database che supportano la ricerca full-text. Il valore predefinito è false.
StoragePropertyName	No	Può essere utilizzato per specificare un nome alternativo per la proprietà nel database. Si noti che questo parametro non è supportato da tutti i connettori, ad esempio se le alternative come JsonPropertyNameAttribute sono supportate.

Suggerimento

Per altre informazioni sui connettori che supportano StoragePropertyName e sulle alternative disponibili, vedere la documentazione per ogni connettore.

VectorStoreRecordVectorProperty

Utilizzare questa classe per indicare che la proprietà contiene un vettore.

new VectorStoreRecordVectorProperty("DescriptionEmbedding", typeof(float)) { Dimensions = 4, DistanceFunction = DistanceFunction.CosineDistance, IndexKind = IndexKind.Hnsw },

Impostazioni di configurazione vectorStoreRecordVectorProperty

Parametro	Richiesto	Descrizione
DataModelPropertyName	Sì	Nome della proprietà nel modello di dati. Usato dai mapper predefiniti per eseguire automaticamente il mapping tra lo schema di archiviazione e il modello di dati e per la creazione di indici.
PropertyType	Sì	Tipo della proprietà nel modello di dati. Usato dai mapper predefiniti per eseguire automaticamente il mapping tra lo schema di archiviazione e il modello di dati e per la creazione di indici.
Dimensioni	Sì per la creazione della raccolta, facoltativo in caso contrario	Numero di dimensioni del vettore. Questa operazione è in genere necessaria quando si crea un indice vettoriale per una raccolta.
IndexKind	No	Tipo di indice con cui indicizzare il vettore. Il valore predefinito varia in base al tipo di archivio vettoriale.
DistanceFunction	No	Tipo di funzione di distanza da usare quando si esegue il confronto tra vettori durante la ricerca vettoriale su questo vettore. Il valore predefinito varia in base al tipo di archivio vettoriale.
StoragePropertyName	No	Può essere utilizzato per specificare un nome alternativo per la proprietà nel database. Si noti che questo parametro non è supportato da tutti i connettori, ad esempio se le alternative come JsonPropertyNameAttribute sono supportate.

Suggerimento

Per altre informazioni sui connettori che supportano StoragePropertyName e sulle alternative disponibili, vedere la documentazione per ogni connettore.

Di seguito è riportato un esempio di come creare una definizione di record da usare con un dataframe pandas.

Nota

Gli stessi campi della definizione del modello di dati vengono usati qui per un modello di dati che vengono aggiunti come annotazioni, in questo caso come un dect con il nome.

Ci sono un paio di aspetti importanti da notare, altri quindi le definizioni dei campi stessi. Il primo è il container_mode parametro . Se è impostata su True, questo indica che il modello di dati è un tipo di contenitore, ad esempio un dataframe, e che il modello di dati è pertanto un contenitore di record, anziché un singolo record, un record contenitore può essere usato nello stesso modo, la differenza principale è che get e get_batch restituirà lo stesso tipo di dati, con un singolo record per un get oggetto e uno o più per un oggetto get_batch. Quando si vuole eseguire un upsert upsert e upsert_batch può essere usato in modo intercambiabile, in altre parole, il passaggio di un contenitore a upsert comporterà più upsert, anziché uno singolo.

Il secondo è l'aggiunta dei to_dict metodi e from_dict , usati per eseguire la conversione tra il modello di dati e lo schema di archiviazione. In questo caso, il to_dict metodo viene utilizzato per convertire il dataframe in un elenco di record e il from_dict metodo viene utilizzato per convertire un elenco di record in un dataframe. È anche possibile usare un serialize metodo e deserialize (non illustrato nell'esempio seguente), per informazioni dettagliate sulla differenza tra quelle disponibili nella documentazione di serializzazione.

from semantic_kernel.data import (
    VectorStoreRecordDataField,
    VectorStoreRecordDefinition,
    VectorStoreRecordKeyField,
    VectorStoreRecordVectorField,
)

hotel_definition = VectorStoreRecordDefinition(
    fields={
        "hotel_id": VectorStoreRecordKeyField(property_type="str"),
        "hotel_name": VectorStoreRecordDataField(property_type="str", is_filterable=True),
        "description": VectorStoreRecordDataField(
            property_type="str", has_embedding=True, embedding_property_name="description_embedding"
        ),
        "description_embedding": VectorStoreRecordVectorField(property_type="list[float]"),
    },
    container_mode=True,
    to_dict=lambda record, **_: record.to_dict(orient="records"),
    from_dict=lambda records, **_: DataFrame(records),
)

Quando si crea una definizione, è sempre necessario specificare un nome (come chiave nel dict) e digitare per ogni proprietà nello schema, poiché è necessario per la creazione dell'indice fields e il mapping dei dati.

Per usare la definizione, passarla al metodo GetCollection o a un costruttore di raccolta, insieme al tipo di modello di dati.

collection = vector_store.get_collection(
    collection_name="skhotels", 
    data_model_type=pd.DataFrame, 
    data_model_definition=hotel_definition,
)

Di seguito è riportato un esempio di come creare una definizione di record.

var hotelDefinition = VectorStoreRecordDefinition.fromFields(
    Arrays.asList(
        VectorStoreRecordKeyField.builder().withName("hotelId").withFieldType(String.class).build(),
        VectorStoreRecordDataField.builder()
            .withName("name")
            .withFieldType(String.class)
            .isFilterable(true).build(),
        VectorStoreRecordDataField.builder()
            .withName("description")
            .withFieldType(String.class)
            .isFullTextSearchable(true).build(),
        VectorStoreRecordVectorField.builder().withName("descriptionEmbedding")
            .withDimensions(4)
            .withIndexKind(IndexKind.HNSW)
            .withDistanceFunction(DistanceFunction.COSINE_DISTANCE)
            .withFieldType(List.class).build()
    )
);

Quando si crea una definizione, è sempre necessario specificare un nome e un tipo per ogni campo nello schema, poiché è necessario per la creazione dell'indice e il mapping dei dati.

Per usare la definizione, passarla al metodo GetCollection.

var collection = vectorStore.getCollection("skhotels",
        JDBCVectorStoreRecordCollectionOptions.builder()
            .withRecordDefinition(hotelDefinition)
            .build()
    );

Classi di configurazione del campo dei record

VectorStoreRecordKeyField

Utilizzare questa classe per indicare che il campo è la chiave del record.

VectorStoreRecordKeyField.builder().withName("hotelId").withFieldType(String.class).build(),

Impostazioni di configurazione vectorStoreRecordKeyField

Parametro	Richiesto	Descrizione
name	Sì	Nome del campo nel modello di dati. Usato dai mapper predefiniti per eseguire automaticamente il mapping tra lo schema di archiviazione e il modello di dati e per la creazione di indici.
fieldType	Sì	Tipo del campo nel modello di dati. Usato dai mapper predefiniti per eseguire automaticamente il mapping tra lo schema di archiviazione e il modello di dati e per la creazione di indici.
storageName	No	Può essere usato per specificare un nome alternativo per il campo nel database. Si noti che questo parametro non è supportato da tutti i connettori, ad esempio in cui viene usato Jackson, in tal caso il nome di archiviazione può essere specificato usando le annotazioni Jackson.

Suggerimento

Per altre informazioni sui connettori che supportano storageName e sulle alternative disponibili, vedere la documentazione per ogni connettore.

VectorStoreRecordDataField

Utilizzare questa classe per indicare che la proprietà contiene dati generali che non sono una chiave o un vettore.

VectorStoreRecordDataField.builder()
    .withName("name")
    .withFieldType(String.class)
    .isFilterable(true).build(),

Impostazioni di configurazione vectorStoreRecordDataField

Parametro	Richiesto	Descrizione
name	Sì	Nome del campo nel modello di dati. Usato dai mapper predefiniti per eseguire automaticamente il mapping tra lo schema di archiviazione e il modello di dati e per la creazione di indici.
fieldType	Sì	Tipo del campo nel modello di dati. Usato dai mapper predefiniti per eseguire automaticamente il mapping tra lo schema di archiviazione e il modello di dati e per la creazione di indici.
isFilterable	No	Indica se il campo deve essere indicizzato per filtrare nei casi in cui un database richiede il consenso esplicito per l'indicizzazione per campo. Il valore predefinito è false.
isFullTextSearchable	No	Indica se il campo deve essere indicizzato per la ricerca full-text per i database che supportano la ricerca full-text. Il valore predefinito è false.
storageName	No	Può essere usato per specificare un nome alternativo per il campo nel database. Si noti che questo parametro non è supportato da tutti i connettori, ad esempio in cui viene usato Jackson, in tal caso il nome di archiviazione può essere specificato usando le annotazioni Jackson.

Suggerimento

Per altre informazioni sui connettori che supportano storageName e sulle alternative disponibili, vedere la documentazione per ogni connettore.

VectorStoreRecordVectorField

Usare questa classe per indicare che il campo contiene un vettore.

VectorStoreRecordVectorField.builder().withName("descriptionEmbedding")
    .withDimensions(4)
    .withIndexKind(IndexKind.HNSW)
    .withDistanceFunction(DistanceFunction.COSINE_DISTANCE)
    .withFieldType(List.class).build(),

Impostazioni di configurazione vectorStoreRecordVectorField

Parametro	Richiesto	Descrizione
name	Sì	Nome del campo nel modello di dati. Usato dai mapper predefiniti per eseguire automaticamente il mapping tra lo schema di archiviazione e il modello di dati e per la creazione di indici.
fieldType	Sì	Tipo del campo nel modello di dati. Usato dai mapper predefiniti per eseguire automaticamente il mapping tra lo schema di archiviazione e il modello di dati e per la creazione di indici.
dimensioni	Sì per la creazione della raccolta, facoltativo in caso contrario	Numero di dimensioni del vettore. Questa operazione è in genere necessaria quando si crea un indice vettoriale per una raccolta.
indexKind	No	Tipo di indice con cui indicizzare il vettore. Il valore predefinito varia in base al tipo di archivio vettoriale.
distanceFunction	No	Tipo di funzione di distanza da usare quando si esegue il confronto tra vettori durante la ricerca vettoriale su questo vettore. Il valore predefinito varia in base al tipo di archivio vettoriale.
storageName	No	Può essere usato per specificare un nome alternativo per il campo nel database. Si noti che questo parametro non è supportato da tutti i connettori, ad esempio in cui viene usato Jackson, in tal caso il nome di archiviazione può essere specificato usando le annotazioni Jackson.

Suggerimento

Per altre informazioni sui connettori che supportano storageName e sulle alternative disponibili, vedere la documentazione per ogni connettore.