Uw gegevensmodel definiëren

Microsoft.Extensions.VectorData maakt gebruik van een model-first benadering voor interactie met databases.

Alle methoden voor upsert of het ophalen van records maken gebruik van sterk getypeerde modelklassen. Er zijn twee manieren om het gegevensmodel te definiëren:

• Door eigenschappen op de modelklassen te decoreren met kenmerken die het doel van elke eigenschap aangeven.
• Door uw opslagschema te definiëren met behulp van een recorddefinitie die u afzonderlijk van het gegevensmodel opgeeft. De recorddefinitie is een VectorStoreCollectionDefinition definitie die eigenschappen bevat.

Kenmerken

Hier volgt een voorbeeld van een klasse of gegevensmodel waarvan de eigenschappen zijn versierd met VectorStore*Attribute kenmerken.

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

Recorddefinitie

Hier volgt een voorbeeld van een recorddefinitie:

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

Wanneer u een recorddefinitie maakt, geeft u een naam en type op voor elke eigenschap in uw schema, omdat deze informatie vereist is voor het maken van indexen en het toewijzen van gegevens.

Als u de definitie wilt gebruiken, geeft u deze door aan de GetCollection<TKey,TRecord>(String, VectorStoreCollectionDefinition) methode.

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

De benadering van recorddefinities kan handig zijn wanneer:

• U wilt hetzelfde gegevensmodel gebruiken met meer dan één configuratie.
• U wilt een ingebouwd type, zoals een Dictionaryof een geoptimaliseerde indeling, zoals een dataframe, gebruiken en nog steeds gebruikmaken van de vectoropslagfunctionaliteit.

Kenmerken van gegevensmodeleigenschappen

De VectorStore*Attribute kenmerken die gegevensmodellen definiëren voor vectordatabases zijn:

• VectorStoreKeyAttribute
• VectorStoreDataAttribute
• VectorStoreVectorAttribute

VectorStoreKeyAttribute

Gebruik het VectorStoreKeyAttribute kenmerk om aan te geven dat uw eigenschap de primaire sleutel van de record is.

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

In de volgende tabel ziet u de parameters voor VectorStoreKeyAttribute.

Kenmerk	Verplicht	Beschrijving
StorageName	No	Kan worden gebruikt om een alternatieve naam op te geven voor de eigenschap in de database. Deze parameter wordt bijvoorbeeld niet ondersteund door alle providers, waarbij alternatieven zoals JsonPropertyNameAttribute worden ondersteund.

VectorStoreDataAttribute

Gebruik het VectorStoreDataAttribute kenmerk om aan te geven dat uw eigenschap algemene gegevens bevat die geen sleutel of vector zijn.

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

In de volgende tabel ziet u de parameters voor VectorStoreDataAttribute.

Kenmerk	Verplicht	Beschrijving
IsIndexed	No	Hiermee wordt aangegeven of de eigenschap moet worden geïndexeerd voor filteren in gevallen waarin een database moet inschakelen voor indexering per eigenschap. De standaardwaarde is false.
IsFullTextIndexed	No	Hiermee wordt aangegeven of de eigenschap moet worden geïndexeerd voor zoeken in volledige tekst naar databases die zoeken in volledige tekst ondersteunen. De standaardwaarde is false.
StorageName	No	Kan worden gebruikt om een alternatieve naam op te geven voor de eigenschap in de database. Deze parameter wordt bijvoorbeeld niet ondersteund door alle providers, waarbij alternatieven zoals JsonPropertyNameAttribute worden ondersteund.

VectorStoreVectorAttribute

Gebruik het VectorStoreVectorAttribute kenmerk om aan te geven dat uw eigenschap een vector bevat.

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

Het is ook mogelijk om te gebruiken VectorStoreVectorAttribute voor eigenschappen die geen vectortype hebben, bijvoorbeeld een eigenschap van het type string. Wanneer een eigenschap op deze manier is ingericht, moet u een IEmbeddingGenerator exemplaar opgeven voor het vectorarchief. Wanneer u de record upsert, wordt de tekst in de string eigenschap automatisch geconverteerd en opgeslagen als vector in de database. (Het is niet mogelijk om een vector op te halen met behulp van dit mechanisme.)

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

Aanbeveling

Zie Het vectorarchief insluiten genereren voor meer informatie over het gebruik van ingebouwde insluitingen.

In de volgende tabel ziet u de parameters voor VectorStoreVectorAttribute.

Kenmerk	Verplicht	Beschrijving
Dimensions	Ja	Het aantal dimensies dat de vector heeft. Dit is vereist bij het maken van een vectorindex voor een verzameling.
IndexKind	No	Het type index waarmee de vector moet worden geïndexeer. De standaardinstelling is afhankelijk van het type vectorarchief.
DistanceFunction	No	Het type functie dat moet worden gebruikt bij het uitvoeren van vectorvergelijking tijdens vectorzoekopdrachten over deze vector. De standaardinstelling is afhankelijk van het type vectorarchief.
StorageName	No	Kan worden gebruikt om een alternatieve naam op te geven voor de eigenschap in de database. Deze parameter wordt bijvoorbeeld niet ondersteund door alle providers, waarbij alternatieven zoals JsonPropertyNameAttribute worden ondersteund.

Algemene indextypen en functietypen voor afstand worden geleverd als statische waarden voor de IndexKind en DistanceFunction klassen. Implementaties van afzonderlijke vectoropslag kunnen ook hun eigen indextypen en afstandsfuncties gebruiken, waarbij de database ongebruikelijke typen ondersteunt.

Eigenschappen van recorddefinities

Gebruik de VectorStore*Property klassen om een recorddefinitie te maken die u doorgeeft aan het gegevensmodel:

• VectorStoreKeyProperty
• VectorStoreDataProperty
• VectorStoreVectorProperty

VectorStoreKeyProperty

Gebruik de VectorStoreKeyProperty klasse om aan te geven dat uw eigenschap de sleutel van de record is.

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

In de volgende tabel ziet u de configuratie-instellingen voor VectorStoreKeyProperty.

Kenmerk	Verplicht	Beschrijving
Name	Ja	De naam van de eigenschap in het gegevensmodel. Wordt door de mapper gebruikt om automatisch toe te wijzen tussen het opslagschema en het gegevensmodel en voor het maken van indexen.
Type	No	Het type eigenschap in het gegevensmodel. Wordt door de mapper gebruikt om automatisch toe te wijzen tussen het opslagschema en het gegevensmodel en voor het maken van indexen.
StorageName	No	Kan worden gebruikt om een alternatieve naam op te geven voor de eigenschap in de database. Deze parameter wordt bijvoorbeeld niet ondersteund door alle providers, waarbij alternatieven zoals JsonPropertyNameAttribute worden ondersteund.

VectorStoreDataProperty

Gebruik de VectorStoreDataProperty klasse om aan te geven dat uw eigenschap algemene gegevens bevat die geen sleutel of vector zijn.

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

In de volgende tabel ziet u de configuratie-instellingen voor VectorStoreDataProperty.

Kenmerk	Verplicht	Beschrijving
Name	Ja	De naam van de eigenschap in het gegevensmodel. Wordt door de mapper gebruikt om automatisch toe te wijzen tussen het opslagschema en het gegevensmodel en voor het maken van indexen.
Type	No	Het type eigenschap in het gegevensmodel. Wordt door de mapper gebruikt om automatisch toe te wijzen tussen het opslagschema en het gegevensmodel en voor het maken van indexen.
IsIndexed	No	Hiermee wordt aangegeven of de eigenschap moet worden geïndexeerd voor filteren in gevallen waarin een database moet inschakelen voor indexering per eigenschap. De standaardwaarde is vals.
IsFullTextIndexed	No	Hiermee wordt aangegeven of de eigenschap moet worden geïndexeerd voor zoeken in volledige tekst naar databases die zoeken in volledige tekst ondersteunen. De standaardwaarde is vals.
StorageName	No	Kan worden gebruikt om een alternatieve naam op te geven voor de eigenschap in de database. Deze parameter wordt bijvoorbeeld niet ondersteund door alle providers, waarbij alternatieven zoals JsonPropertyNameAttribute worden ondersteund.

VectorStoreVectorProperty

Gebruik de VectorStoreVectorProperty klasse om aan te geven dat uw eigenschap een vector bevat.

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

In de volgende tabel ziet u de configuratie-instellingen voor VectorStoreVectorProperty.

Kenmerk	Verplicht	Beschrijving
Name	Ja	De naam van de eigenschap in het gegevensmodel. Wordt door de mapper gebruikt om automatisch toe te wijzen tussen het opslagschema en het gegevensmodel en voor het maken van indexen.
Type	No	Het type eigenschap in het gegevensmodel. Wordt door de mapper gebruikt om automatisch toe te wijzen tussen het opslagschema en het gegevensmodel en voor het maken van indexen.
Dimensions	Ja	Het aantal dimensies dat de vector heeft. Dit is vereist voor het maken van een vectorindex voor een verzameling.
IndexKind	No	Het type index waarmee de vector moet worden geïndexeer. De standaardinstelling is afhankelijk van het type vectorarchief.
DistanceFunction	No	Het type functie dat moet worden gebruikt bij het uitvoeren van vectorvergelijking tijdens vectorzoekopdrachten over deze vector. De standaardinstelling is afhankelijk van het type vectorarchief.
StorageName	No	Kan worden gebruikt om een alternatieve naam op te geven voor de eigenschap in de database. Deze parameter wordt bijvoorbeeld niet ondersteund door alle providers, waarbij alternatieven zoals JsonPropertyNameAttribute worden ondersteund.
EmbeddingGenerator	No	Hiermee kunt u een Microsoft.Extensions.AI.IEmbeddingGenerator exemplaar opgeven dat moet worden gebruikt voor het automatisch genereren van insluitingen voor de versieringseigenschap.

Abstracties van vectoropslag gebruiken zonder een gegevensmodel te definiëren

Er zijn gevallen waarin het niet wenselijk of mogelijk is om uw eigen gegevensmodel te definiëren. Stel dat u tijdens het compileren niet weet hoe uw databaseschema eruitziet en dat het schema alleen via de configuratie wordt opgegeven. Het maken van een gegevensmodel dat het schema weerspiegelt, is in dit geval onmogelijk. In plaats daarvan kunt u dynamisch toewijzen met behulp van een Dictionary<string, object?> recordtype. Eigenschappen worden toegevoegd aan de Dictionary with-sleutel als de eigenschapsnaam en de waarde als de eigenschapswaarde.

Opmerking

De meeste apps gebruiken gewoon sterk getypte .NET-typen om hun gegevens te modelleren. Dynamische toewijzing via Dictionary<string, object?> is bedoeld voor geavanceerde, willekeurige scenario's voor gegevenstoewijzing.

Schemagegevens opgeven bij gebruik Dictionary

Wanneer u een Dictionarydatabase gebruikt, moeten providers nog steeds weten hoe het databaseschema eruitziet. Zonder de schemagegevens kan de provider geen verzameling maken of weten hoe deze kan worden toegewezen aan en van de opslagweergave die door elke database wordt gebruikt.

U kunt een recorddefinitie gebruiken om de schemagegevens op te geven. In tegenstelling tot een gegevensmodel kan tijdens runtime een recorddefinitie worden gemaakt op basis van configuratie wanneer schemagegevens niet bekend zijn tijdens het compileren.

Voorbeeld

Als u een provider wilt gebruiken Dictionary , geeft u dit op als uw gegevensmodel wanneer u de verzameling maakt. Geef ook een recorddefinitie op.

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