Definizione del modello di dati (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.

Tutti i metodi per eseguire l'upsert o ottenere i record usano classi di modelli fortemente tipizzato. Le proprietà di queste classi sono decorate con attributi che indicano lo scopo di ogni proprietà.

Suggerimento

Per un'alternativa all'uso degli attributi, fare riferimento alla definizione dello schema con una definizione di record.

Suggerimento

Per un'alternativa alla definizione del proprio modello di dati, fare riferimento all'uso delle astrazioni di Vector Store senza definire il proprio modello di dati.

Di seguito è riportato un esempio di modello decorato con questi attributi.

using Microsoft.Extensions.VectorData;

public class Hotel
{
    [VectorStoreRecordKey]
    public ulong HotelId { get; set; }

    [VectorStoreRecordData(IsFilterable = true)]
    public string HotelName { get; set; }

    [VectorStoreRecordData(IsFullTextSearchable = true)]
    public string Description { get; set; }

    [VectorStoreRecordVector(4, DistanceFunction.CosineDistance, IndexKind.Hnsw)]
    public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }

    [VectorStoreRecordData(IsFilterable = true)]
    public string[] Tags { get; set; }
}

Attributi

VectorStoreRecordKeyAttribute

Utilizzare questo attributo per indicare che la proprietà è la chiave del record.

[VectorStoreRecordKey]
public ulong HotelId { get; set; }

Parametri VectorStoreRecordKeyAttribute

Parametro	Richiesto	Descrizione
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.

VectorStoreRecordDataAttribute

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

[VectorStoreRecordData(IsFilterable = true)]
public string HotelName { get; set; }

Parametri VectorStoreRecordDataAttribute

Parametro	Richiesto	Descrizione
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.

VectorStoreRecordVectorAttribute

Utilizzare questo attributo per indicare che la proprietà contiene un vettore.

[VectorStoreRecordVector(Dimensions: 4, DistanceFunction.CosineDistance, IndexKind.Hnsw)]
public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }

Parametri VectorStoreRecordVectorAttribute

Parametro	Richiesto	Descrizione
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.

I tipi di funzione di indice e di distanza comuni vengono forniti come valori statici nelle Microsoft.SemanticKernel.Data.IndexKind classi e Microsoft.SemanticKernel.Data.DistanceFunction . Le singole implementazioni di Vector Store possono anche usare i propri tipi di indice e funzioni di distanza, in cui il database supporta tipi insoliti.

Suggerimento

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

Tutti i metodi per eseguire l'upsert o ottenere i record usano una classe e una definizione di record dell'archivio vettoriale.

Questa operazione può essere eseguita definendo la propria classe con annotazioni per i campi o usando una classe/tipo in combinazione con una definizione di record. Due cose devono essere eseguite per una classe, la prima consiste nell'aggiungere le annotazioni con i tipi di campo, la seconda consiste nel decorare la classe con l'elemento vectorstoremodel decorator.

Suggerimento

Per l'approccio alternativo usando una definizione di record, fare riferimento alla definizione dello schema con una definizione di record.

Di seguito è riportato un esempio di modello decorato con queste annotazioni.

from dataclasses import dataclass, field
from typing import Annotated
from semantic_kernel.data import (
    DistanceFunction,
    IndexKind,
    VectorStoreRecordDataField,
    VectorStoreRecordDefinition,
    VectorStoreRecordKeyField,
    VectorStoreRecordVectorField,
    vectorstoremodel,
)

@vectorstoremodel
@dataclass
class Hotel:
    hotel_id: Annotated[str, VectorStoreRecordKeyField()] = field(default_factory=lambda: str(uuid4()))
    hotel_name: Annotated[str, VectorStoreRecordDataField(is_filterable=True)]
    description: Annotated[str, VectorStoreRecordDataField(is_full_text_searchable=True)]
    description_embedding: Annotated[list[float], VectorStoreRecordVectorField(dimensions=4, distance_function=DistanceFunction.COSINE, index_kind=IndexKind.HNSW)]
    tags: Annotated[list[str], VectorStoreRecordDataField(is_filterable=True)]

Suggerimento

La definizione di una classe con queste annotazioni può essere eseguita in diversi modi, uno dei quali usa il dataclasses modulo in Python, illustrato di seguito. Questo esempio mostra anche altri approcci (usando le classi BaseModel pydantic e python di vaniglia).

Annotazioni

Esistono tre tipi di annotazioni da usare e hanno una classe base comune.

VectorStoreRecordField

Questa è la classe base per tutte le annotazioni, non deve essere usata direttamente.

Parametri VectorStoreRecordField

Parametro	Richiesto	Descrizione
name	No	Può essere aggiunto direttamente, ma verrà impostato durante l'analisi del modello.
property_type	No	Deve essere una stringa, verrà anche derivata durante l'analisi.

Suggerimento

Le annotazioni vengono analizzate dall'elemento vectorstoremodel Decorator e una delle operazioni eseguite consiste nel creare una definizione di record per la classe, pertanto non è necessario creare un'istanza di una classe di campo quando non vengono impostati parametri, il campo può essere annotato con solo la classe , come illustrato di seguito:

hotel_id: Annotated[str, VectorStoreRecordKeyField]

VectorStoreRecordKeyField

Utilizzare questa annotazione per indicare che questo attributo è la chiave del record.

VectorStoreRecordKeyField()

Parametri VectorStoreRecordKeyField

Non sono definiti altri parametri all'esterno della classe di base.

VectorStoreRecordDataField

Usare questa annotazione per indicare che l'attributo contiene dati generali che non sono una chiave o un vettore.

VectorStoreRecordDataField(is_filterable=True)

Parametri VectorStoreRecordDataField

Parametro	Richiesto	Descrizione
has_embedding	No	Indica se alla proprietà è associato un incorporamento, il valore predefinito è Nessuno.
embedding_property_name	No	Il nome della proprietà che contiene l'incorporamento, il valore predefinito è Nessuno.
is_filterable	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.
is_full_text_searchable	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.

VectorStoreRecordVectorField

Usare questa annotazione per indicare che l'attributo contiene un vettore.

VectorStoreRecordVectorField(dimensions=4, distance_function=DistanceFunction.COSINE, index_kind=IndexKind.HNSW)

Parametri VectorStoreRecordVectorField

Parametro	Richiesto	Descrizione
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.
index_kind	No	Tipo di indice con cui indicizzare il vettore. Il valore predefinito varia in base al tipo di archivio vettoriale.
distance_function	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.
local_embedding	No	Indica se alla proprietà è associato un incorporamento locale, il valore predefinito è Nessuno.
embedding_settings	No	Le impostazioni per l'incorporamento, sotto forma di dict con service_id come chiave e PromptExecutionSettings come valore, il valore predefinito è Nessuno.
serialize_function	No	Funzione da usare per serializzare il vettore, se il tipo non è un elenco[float | int] questa funzione è necessaria o l'intero modello deve essere serializzato.
deserialize_function	No	Funzione da usare per deserializzare il vettore, se il tipo non è un elenco[float | int] questa funzione è necessaria o l'intero modello deve essere deserializzato.

I tipi di funzione di indice e di distanza comuni vengono forniti come valori statici nelle semantic_kernel.data.IndexKind classi e semantic_kernel.data.DistanceFunction . Le singole implementazioni di Vector Store possono anche usare i propri tipi di indice e funzioni di distanza, in cui il database supporta tipi insoliti.

Tutti i metodi per eseguire l'upsert o ottenere i record usano classi di modelli fortemente tipizzato. I campi di queste classi sono decorati con annotazioni che indicano lo scopo di ogni campo.

Suggerimento

Per un'alternativa all'uso degli attributi, fare riferimento alla definizione dello schema con una definizione di record.

Di seguito è riportato un esempio di modello decorato con queste annotazioni. Per impostazione predefinita, la maggior parte degli archivi vettoriali predefiniti usa Jackson, quindi è una procedura consigliata per garantire che l'oggetto modello possa essere serializzato da Jackson, ovvero la classe è visibile, ha getter, costruttore, annotazioni e così via.

import com.microsoft.semantickernel.data.vectorstorage.annotations.VectorStoreRecordData;
import com.microsoft.semantickernel.data.vectorstorage.annotations.VectorStoreRecordKey;
import com.microsoft.semantickernel.data.vectorstorage.annotations.VectorStoreRecordVector;
import com.microsoft.semantickernel.data.vectorstorage.definition.DistanceFunction;
import com.microsoft.semantickernel.data.vectorstorage.definition.IndexKind;

import java.util.List;

public class Hotel {
    @VectorStoreRecordKey
    private String hotelId;

    @VectorStoreRecordData(isFilterable = true)
    private String name;

    @VectorStoreRecordData(isFullTextSearchable = true)
    private String description;

    @VectorStoreRecordVector(dimensions = 4, indexKind = IndexKind.HNSW, distanceFunction = DistanceFunction.COSINE_DISTANCE)
    private List<Float> descriptionEmbedding;

    @VectorStoreRecordData(isFilterable = true)
    private List<String> tags;

    public Hotel() { }

    public Hotel(String hotelId, String name, String description, List<Float> descriptionEmbedding, List<String> tags) {
        this.hotelId = hotelId;
        this.name = name;
        this.description = description;
        this.descriptionEmbedding = descriptionEmbedding;
        this.tags = tags;
    }

    public String getHotelId() { return hotelId; }
    public String getName() { return name; }
    public String getDescription() { return description; }
    public List<Float> getDescriptionEmbedding() { return descriptionEmbedding; }
    public List<String> getTags() { return tags; }
}

Annotazioni

VectorStoreRecordKey

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

@VectorStoreRecordKey
private String hotelId;

Parametri VectorStoreRecordKey

Parametro	Richiesto	Descrizione
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.

VectorStoreRecordData

Usare questa annotazione per indicare che il campo contiene dati generali che non sono una chiave o un vettore.

@VectorStoreRecordData(isFilterable = true)
private String name;

Parametri VectorStoreRecordData

Parametro	Richiesto	Descrizione
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.

VectorStoreRecordVector

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

@VectorStoreRecordVector(dimensions = 4, indexKind = IndexKind.HNSW, distanceFunction = DistanceFunction.COSINE_DISTANCE)
private List<Float> descriptionEmbedding;

Parametri VectorStoreRecordVector

Parametro	Richiesto	Descrizione
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.

I tipi di funzione di indice e di distanza comuni vengono forniti nelle com.microsoft.semantickernel.data.vectorstorage.definition.IndexKind enumerazioni e com.microsoft.semantickernel.data.vectorstorage.definition.DistanceFunction . Le singole implementazioni di Vector Store possono anche usare i propri tipi di indice e funzioni di distanza, in cui il database supporta tipi insoliti.

Suggerimento

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

Altre informazioni saranno presto disponibili.