Définir votre modèle de données

Microsoft.Extensions.VectorData utilise une approche de premier modèle pour interagir avec les bases de données.

Toutes les méthodes pour upsert ou obtenir des enregistrements utilisent des classes de modèle fortement typées. Il existe deux façons de définir le modèle de données :

• En décorant des propriétés sur les classes de modèle avec des attributs qui indiquent l’objectif de chaque propriété.
• En définissant votre schéma de stockage à l’aide d’une définition d’enregistrement que vous fournissez séparément du modèle de données. La définition d’enregistrement est une VectorStoreCollectionDefinition propriété qui contient des propriétés.

Attributs

Voici un exemple de classe ou de modèle de données dont les propriétés sont décorées avec VectorStore*Attribute des attributs.

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; }
}

Définition d’enregistrement

Voici un exemple de définition d’enregistrement :

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
        },
    ]
};

Lorsque vous créez une définition d’enregistrement, vous fournissez un nom et un type pour chaque propriété de votre schéma, car ces informations sont requises pour la création d’index et le mappage des données.

Pour utiliser la définition, passez-la à la GetCollection<TKey,TRecord>(String, VectorStoreCollectionDefinition) méthode.

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

L’approche de définition d’enregistrement peut être utile lorsque :

• Vous souhaitez utiliser le même modèle de données avec plusieurs configurations.
• Vous souhaitez utiliser un type intégré, tel qu’un Dictionaryformat optimisé, comme un dataframe, et toujours utiliser la fonctionnalité de magasin de vecteurs.

Attributs de propriété de modèle de données

Les VectorStore*Attribute attributs qui définissent des modèles de données pour les bases de données vectorielles sont les suivants :

• VectorStoreKeyAttribute
• VectorStoreDataAttribute
• VectorStoreVectorAttribute

VectorStoreKeyAttribute

Utilisez l’attribut VectorStoreKeyAttribute pour indiquer que votre propriété est la clé primaire de l’enregistrement.

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

Le tableau suivant présente les paramètres pour VectorStoreKeyAttribute.

Paramètre	Obligatoire	Description
StorageName	Non	Peut être utilisé pour fournir un autre nom pour la propriété dans la base de données. Ce paramètre n’est pas pris en charge par tous les fournisseurs, par exemple, où des alternatives comme JsonPropertyNameAttribute celles-ci sont prises en charge.

VectorStoreDataAttribute

Utilisez l’attribut VectorStoreDataAttribute pour indiquer que votre propriété contient des données générales qui ne sont pas une clé ou un vecteur.

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

Le tableau suivant présente les paramètres pour VectorStoreDataAttribute.

Paramètre	Obligatoire	Description
IsIndexed	Non	Indique si la propriété doit être indexée pour le filtrage dans les cas où une base de données nécessite d’opter pour l’indexation par propriété. La valeur par défaut est false.
IsFullTextIndexed	Non	Indique si la propriété doit être indexée pour la recherche en texte intégral pour les bases de données qui prennent en charge la recherche en texte intégral. La valeur par défaut est false.
StorageName	Non	Peut être utilisé pour fournir un autre nom pour la propriété dans la base de données. Ce paramètre n’est pas pris en charge par tous les fournisseurs, par exemple, où des alternatives comme JsonPropertyNameAttribute celles-ci sont prises en charge.

VectorStoreVectorAttribute

Utilisez l’attribut VectorStoreVectorAttribute pour indiquer que votre propriété contient un vecteur.

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

Il est également possible d’utiliser VectorStoreVectorAttribute sur les propriétés qui n’ont pas de type vecteur, par exemple une propriété de type string. Lorsqu’une propriété est décorée de cette façon, vous devez fournir une IEmbeddingGenerator instance au magasin vectoriel. Lors de l’upserting de l’enregistrement, le texte qui se trouve dans la string propriété est automatiquement converti et stocké en tant que vecteur dans la base de données. (Il n’est pas possible de récupérer un vecteur à l’aide de ce mécanisme.)

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

Conseil / Astuce

Pour plus d’informations sur l’utilisation de la génération d’incorporation intégrée, consultez Let the vector store generate embeddings.

Le tableau suivant présente les paramètres pour VectorStoreVectorAttribute.

Paramètre	Obligatoire	Description
Dimensions	Oui	Nombre de dimensions dont le vecteur a. Cela est nécessaire lors de la création d’un index vectoriel pour une collection.
IndexKind	Non	Type d’index avec lequel indexer le vecteur. La valeur par défaut varie selon le type de magasin de vecteurs.
DistanceFunction	Non	Type de fonction à utiliser lors de la comparaison de vecteurs pendant la recherche vectorielle sur ce vecteur. La valeur par défaut varie selon le type de magasin de vecteurs.
StorageName	Non	Peut être utilisé pour fournir un autre nom pour la propriété dans la base de données. Ce paramètre n’est pas pris en charge par tous les fournisseurs, par exemple, où des alternatives comme JsonPropertyNameAttribute celles-ci sont prises en charge.

Les types de fonctions d’index courants et de distance sont fournis sous forme de valeurs statiques sur les classes et DistanceFunction les IndexKind classes. Les implémentations de magasin de vecteurs individuels peuvent également utiliser leurs propres types d’index et fonctions de distance, où la base de données prend en charge des types inhabituels.

Propriétés de définition d’enregistrement

Utilisez les VectorStore*Property classes pour créer une définition d’enregistrement que vous passez au modèle de données :

• VectorStoreKeyProperty
• VectorStoreDataProperty
• VectorStoreVectorProperty

VectorStoreKeyProperty

Utilisez la VectorStoreKeyProperty classe pour indiquer que votre propriété est la clé de l’enregistrement.

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

Le tableau suivant présente les paramètres de configuration pour VectorStoreKeyProperty.

Paramètre	Obligatoire	Description
Name	Oui	Nom de la propriété sur le modèle de données. Utilisé par le mappeur pour mapper automatiquement entre le schéma de stockage et le modèle de données et pour créer des index.
Type	Non	Type de la propriété sur le modèle de données. Utilisé par le mappeur pour mapper automatiquement entre le schéma de stockage et le modèle de données et pour créer des index.
StorageName	Non	Peut être utilisé pour fournir un autre nom pour la propriété dans la base de données. Ce paramètre n’est pas pris en charge par tous les fournisseurs, par exemple, où des alternatives comme JsonPropertyNameAttribute celles-ci sont prises en charge.

VectorStoreDataProperty

Utilisez la VectorStoreDataProperty classe pour indiquer que votre propriété contient des données générales qui ne sont pas une clé ou un vecteur.

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

Le tableau suivant présente les paramètres de configuration pour VectorStoreDataProperty.

Paramètre	Obligatoire	Description
Name	Oui	Nom de la propriété sur le modèle de données. Utilisé par le mappeur pour mapper automatiquement entre le schéma de stockage et le modèle de données et pour créer des index.
Type	Non	Type de la propriété sur le modèle de données. Utilisé par le mappeur pour mapper automatiquement entre le schéma de stockage et le modèle de données et pour créer des index.
IsIndexed	Non	Indique si la propriété doit être indexée pour le filtrage dans les cas où une base de données nécessite d’opter pour l’indexation par propriété. La valeur par défaut est false.
IsFullTextIndexed	Non	Indique si la propriété doit être indexée pour la recherche en texte intégral pour les bases de données qui prennent en charge la recherche en texte intégral. La valeur par défaut est false.
StorageName	Non	Peut être utilisé pour fournir un autre nom pour la propriété dans la base de données. Ce paramètre n’est pas pris en charge par tous les fournisseurs, par exemple, où des alternatives comme JsonPropertyNameAttribute celles-ci sont prises en charge.

VectorStoreVectorProperty

Utilisez la VectorStoreVectorProperty classe pour indiquer que votre propriété contient un vecteur.

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

Le tableau suivant présente les paramètres de configuration pour VectorStoreVectorProperty.

Paramètre	Obligatoire	Description
Name	Oui	Nom de la propriété sur le modèle de données. Utilisé par le mappeur pour mapper automatiquement entre le schéma de stockage et le modèle de données et pour créer des index.
Type	Non	Type de la propriété sur le modèle de données. Utilisé par le mappeur pour mapper automatiquement entre le schéma de stockage et le modèle de données et pour créer des index.
Dimensions	Oui	Nombre de dimensions dont le vecteur a. Cela est nécessaire pour créer un index vectoriel pour une collection.
IndexKind	Non	Type d’index avec lequel indexer le vecteur. La valeur par défaut varie selon le type de magasin de vecteurs.
DistanceFunction	Non	Type de fonction à utiliser lors de la comparaison de vecteurs pendant la recherche vectorielle sur ce vecteur. La valeur par défaut varie selon le type de magasin de vecteurs.
StorageName	Non	Peut être utilisé pour fournir un autre nom pour la propriété dans la base de données. Ce paramètre n’est pas pris en charge par tous les fournisseurs, par exemple, où des alternatives comme JsonPropertyNameAttribute celles-ci sont prises en charge.
EmbeddingGenerator	Non	Permet de spécifier une Microsoft.Extensions.AI.IEmbeddingGenerator instance à utiliser pour générer automatiquement des incorporations pour la propriété décorée.

Utiliser des abstractions de magasin de vecteurs sans définir de modèle de données

Il existe des cas où il n’est pas souhaitable ou possible de définir votre propre modèle de données. Par exemple, imaginez que vous ne savez pas au moment de la compilation ce que votre schéma de base de données ressemble, et que le schéma est fourni uniquement par le biais de la configuration. La création d’un modèle de données qui reflète le schéma serait impossible dans ce cas. Au lieu de cela, vous pouvez mapper dynamiquement à l’aide d’un Dictionary<string, object?> type d’enregistrement. Les propriétés sont ajoutées à la Dictionary clé comme nom de propriété et à la valeur comme valeur de propriété.

Note

La plupart des applications utilisent simplement des types .NET fortement typés pour modéliser leurs données. Le mappage dynamique via Dictionary<string, object?> est destiné aux scénarios avancés de mappage de données arbitraires.

Fournir des informations de schéma lors de l’utilisation Dictionary

Lorsque vous utilisez un Dictionaryfournisseur, vous devez toujours savoir à quoi ressemble le schéma de base de données. Sans les informations de schéma, le fournisseur ne serait pas en mesure de créer une collection ou de savoir comment mapper vers et à partir de la représentation de stockage utilisée par chaque base de données.

Vous pouvez utiliser une définition d’enregistrement pour fournir les informations de schéma. Contrairement à un modèle de données, une définition d’enregistrement peut être créée à partir de la configuration au moment de l’exécution lorsque les informations de schéma ne sont pas connues au moment de la compilation.

Exemple

Pour utiliser Dictionary un fournisseur, spécifiez-le comme modèle de données lorsque vous créez la collection. Fournissez également une définition d’enregistrement.

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"]);