Definire il modello di dati

Microsoft.Extensions.VectorData usa un approccio model-first per interagire con i database.

Tutti i metodi per eseguire l'upsert o ottenere i record usano classi di modelli fortemente tipizzato. Esistono due modi per definire il modello di dati:

• Decorating properties on the model classes with attributes that indicate the purpose of each property.
• Definendo lo schema di archiviazione usando una definizione di record fornita separatamente dal modello di dati. La definizione del record è un oggetto VectorStoreCollectionDefinition che contiene proprietà.

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

    [VectorStoreData(IsIndexed = true)]
    public required string HotelName { get; set; }

    [VectorStoreData(IsFullTextIndexed = true)]
    public required string Description { get; set; }

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

    [VectorStoreData(IsIndexed = true)]
    public required string[] Tags { get; set; }
}

VectorStoreCollectionDefinition hotelDefinition = new()
{
    Properties =
    [
        new VectorStoreKeyProperty("HotelId", typeof(ulong)),
        new VectorStoreDataProperty("HotelName", typeof(string)) { IsIndexed = true },
        new VectorStoreDataProperty("Description", typeof(string)) { IsFullTextIndexed = true },
        new VectorStoreVectorProperty("DescriptionEmbedding", typeof(float), dimensions: 4)
        {
            DistanceFunction = DistanceFunction.CosineSimilarity,
            IndexKind = IndexKind.Hnsw
        },
    ]
};

VectorStoreCollection<ulong, Hotel> collection =
    vectorStore.GetCollection<ulong, Hotel>("hotels", hotelDefinition);

Attributi delle proprietà del modello di dati

Gli VectorStore*Attribute attributi che definiscono i modelli di dati per i database vettoriali sono:

• VectorStoreKeyAttribute
• VectorStoreDataAttribute
• VectorStoreVectorAttribute

VectorStoreKeyAttribute

Usare l'attributo VectorStoreKeyAttribute per indicare che la proprietà è la chiave primaria del record.

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

La tabella seguente illustra i parametri per VectorStoreKeyAttribute.

VectorStoreDataAttribute

Usare l'attributo VectorStoreDataAttribute per indicare che la proprietà contiene dati generali che non sono una chiave o un vettore.

[VectorStoreData(IsIndexed = true)]
public required string HotelName { get; set; }

La tabella seguente illustra i parametri per VectorStoreDataAttribute.

VectorStoreVectorAttribute

Usare l'attributo VectorStoreVectorAttribute per indicare che la proprietà contiene un vettore.

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

È anche possibile usare VectorStoreVectorAttribute su proprietà che non hanno un tipo vettore, ad esempio una proprietà di tipo string. Quando una proprietà viene decorata in questo modo, è necessario fornire un'istanza IEmbeddingGenerator all'archivio vettoriale. Quando si esegue l'upserting del record, il testo presente nella string proprietà viene convertito e archiviato automaticamente come vettore nel database. Non è possibile recuperare un vettore usando questo meccanismo.

[VectorStoreVector(Dimensions: 4, DistanceFunction = DistanceFunction.CosineSimilarity, IndexKind = IndexKind.Hnsw)]
public string DescriptionEmbedding { get; set; }

La tabella seguente illustra i parametri per VectorStoreVectorAttribute.

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

Proprietà della definizione di record

Usare le VectorStore*Property classi per creare una definizione di record passata al modello di dati:

• VectorStoreKeyProperty
• VectorStoreDataProperty
• VectorStoreVectorProperty

VectorStoreKeyProperty

Usare la classe per indicare che la VectorStoreKeyProperty proprietà è la chiave del record.

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

La tabella seguente illustra le impostazioni di configurazione per VectorStoreKeyProperty.

VectorStoreDataProperty

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

new VectorStoreDataProperty("HotelName", typeof(string)) { IsIndexed = true },
new VectorStoreDataProperty("Description", typeof(string)) { IsFullTextIndexed = true },

La tabella seguente illustra le impostazioni di configurazione per VectorStoreDataProperty.

VectorStoreVectorProperty

Usare la VectorStoreVectorProperty classe per indicare che la proprietà contiene un vettore.

new VectorStoreVectorProperty("DescriptionEmbedding", typeof(float), dimensions: 4)

La tabella seguente illustra le impostazioni di configurazione per VectorStoreVectorProperty.

Usare astrazioni dell'archivio vettoriali senza definire un modello di dati

In alcuni casi non è consigliabile o possibile definire un modello di dati personalizzato. Si supponga, ad esempio, di non conoscere in fase di compilazione l'aspetto dello schema del database e che lo schema venga fornito solo tramite la configurazione. La creazione di un modello di dati che riflette lo schema sarebbe impossibile in questo caso. È invece possibile eseguire il mapping in modo dinamico usando un Dictionary<string, object?> oggetto per il tipo di record. Le proprietà vengono aggiunte a con la Dictionary chiave come nome della proprietà e il valore come valore della proprietà.

Fornire informazioni sullo schema quando si usa Dictionary

Quando si usa un Dictionary, i provider devono comunque conoscere l'aspetto dello schema del database. Senza le informazioni sullo schema, il provider non sarebbe in grado di creare una raccolta o sapere come eseguire il mapping da e verso la rappresentazione di archiviazione usata da ogni database.

È possibile usare una definizione di record per fornire le informazioni sullo schema. A differenza di un modello di dati, è possibile creare una definizione di record dalla configurazione in fase di esecuzione quando le informazioni sullo schema non sono note in fase di compilazione.

Esempio

Per usare Dictionary con un provider, specificarlo come modello di dati quando si crea la raccolta. Specificare anche una definizione di record.

VectorStoreCollectionDefinition definition = new()
{
    Properties =
    [
        new VectorStoreKeyProperty("Key", typeof(string)),
        new VectorStoreDataProperty("Term", typeof(string)),
        new VectorStoreDataProperty("Definition", typeof(string)),
        new VectorStoreVectorProperty("DefinitionEmbedding", typeof(ReadOnlyMemory<float>), dimensions: 1536)
    ]
};

// Use GetDynamicCollection instead of the regular GetCollection method
// to get an instance of a collection using Dictionary<string, object?>.
VectorStoreCollection<object, Dictionary<string, object?>> dynamicDataModelCollection =
    vectorStore.GetDynamicCollection("glossary", definition);

// Since schema information is available from the record definition,
// it's possible to create a collection with the right vectors,
// dimensions, indexes, and distance functions.
await dynamicDataModelCollection.EnsureCollectionExistsAsync();

// When retrieving a record from the collection,
// access key, data, and vector values via the dictionary entries.
Dictionary<string, object?>? record = await dynamicDataModelCollection.GetAsync("SK");
Console.WriteLine(record["Definition"]);