Definování datového modelu

Microsoft.Extensions.VectorData používá přístup založený na modelu při interakci s databázemi.

Všechny metody pro přenesení nebo získání záznamů používají třídy modelu silného typu. Datový model můžete definovat dvěma způsoby:

  • Dekorací vlastností tříd modelu s atributy , které označují účel každé vlastnosti.
  • Definováním schématu úložiště pomocí definice záznamu , kterou zadáte odděleně od datového modelu. Definice záznamu VectorStoreCollectionDefinition je definice, která obsahuje vlastnosti.

Tady je příklad třídy nebo datového modelu, jehož vlastnosti jsou zdobené VectorStore*Attribute atributy.

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

Vlastnosti datového modelu

Poznámka:

Typy vlastností .NET podporované pro klíče, data a vektory se v různých databázích liší. Informace o podporovaných typech najdete v dokumentaci zvoleného poskytovatele úložiště vektorů.

Klíčová vlastnost

Každý datový model musí mít klíčovou vlastnost, která jednoznačně identifikuje každý záznam v kolekci.

VectorStoreKeyAttribute Atribut použijte k označení, že vaše vlastnost je primárním klíčem záznamu.

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

Následující tabulka uvádí parametry pro VectorStoreKeyAttribute.

Parametr Povinné Description
IsAutoGenerated Ne Určuje, jestli je hodnota klíče automaticky generována databází. Výchozí hodnota je false.
StorageName Ne Lze použít k zadání alternativního názvu vlastnosti v databázi. Tento parametr nepodporuje všichni poskytovatelé, například pokud se podporují alternativy, jako JsonPropertyNameAttribute jsou podporované.

Datová vlastnost

Vlastnosti dat obsahují obsah pro obecné účely, jako je text, značky nebo jiná metadata, která se načtou při hledání záznamů, a dají se také indexovat pro filtrování.

VectorStoreDataAttribute Atribut použijte k označení, že vaše vlastnost obsahuje obecná data, která nejsou klíčem nebo vektorem.

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

Následující tabulka uvádí parametry pro VectorStoreDataAttribute.

Parametr Povinné Description
IsIndexed Ne Určuje, zda má být vlastnost indexována pro filtrování v případech, kdy databáze vyžaduje souhlas s indexováním na vlastnost. Výchozí hodnota je false.
IsFullTextIndexed Ne Určuje, zda má být vlastnost indexována pro fulltextové vyhledávání databází, které podporují fulltextové vyhledávání. Výchozí hodnota je false.
StorageName Ne Lze použít k zadání alternativního názvu vlastnosti v databázi. Tento parametr nepodporuje všichni poskytovatelé, například pokud jsou podporované alternativy, jako JsonPropertyNameAttribute jsou.

Vector – vlastnost

Vektorové vlastnosti obsahují vložené vektory používané pro vyhledávání podobnosti; v pokročilých scénářích může mít datový model více vektorových vlastností, které podporují vyhledávání v různých aspektech záznamu.

Pomocí atributu VectorStoreVectorAttribute označte, že vaše vlastnost obsahuje vektor.

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

Je také možné použít VectorStoreVectorAttribute u vlastností, které nemají typ vektoru, například vlastnost typu string. Když je vlastnost tímto způsobem zdobena, musíte poskytnout IEmbeddingGenerator instanci do úložiště vektorů. Při přenesení záznamu se text, který je ve string vlastnosti, automaticky převede a uloží jako vektor v databázi. (Pomocí tohoto mechanismu není možné načíst vektor.)

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

Návod

Další informace o tom, jak používat předdefinované generování vkládání, naleznete v tématu Vektorové vlastnosti a generování vkládání.

Následující tabulka uvádí parametry pro VectorStoreVectorAttribute.

Parametr Povinné Description
Dimensions Ano Počet dimenzí, které vektor má. To se vyžaduje při vytváření vektorového indexu pro kolekci.
IndexKind Ne Typ indexu indexu indexu vektoru. Výchozí nastavení se liší podle typu úložiště vektorů.
DistanceFunction Ne Typ funkce, která se má použít při porovnávání vektorů při hledání vektorů nad tímto vektorem. Výchozí nastavení se liší podle typu úložiště vektorů.
StorageName Ne Lze použít k zadání alternativního názvu vlastnosti v databázi. Tento parametr nepodporuje všichni poskytovatelé, například pokud se podporují alternativy jako JsonPropertyNameAttribute je podporováno.

Běžné typy indexů a typy funkcí vzdálenosti jsou zadány jako statické hodnoty v těchto IndexKind třídách DistanceFunction . Implementace jednotlivých vektorových úložiště můžou také používat vlastní typy indexů a funkce vzdálenosti, kde databáze podporuje neobvyklé typy.

Generování vektorových vlastností a vkládání

Vektorové databáze se týkají ukládání vložených dat nebo číselných reprezentací dat, které generuje model vkládání. Při ukládání nebo vyhledávání dat je nutné nejprve provést generování vkládání, aby bylo možné převést prohledávatelná data na takové vkládání. MEVD poskytuje dva přístupy ke generování vkládání: ruční a automatické.

Ruční, nízkoúrovňové generování vkládání

Vlastnost vektoru můžete definovat jako float[] nebo ReadOnlyMemory<float>, která představuje vložení přímo, a vygenerovat vkládání sami před každou operací:

[VectorStoreVector(Dimensions: 1536)]
public ReadOnlyMemory<float>? DescriptionEmbedding { get; set; }

Při hledání byste vygenerovali vkládání textu dotazu a předali ho:SearchAsync

ReadOnlyMemory<float> searchEmbedding =
    (await embeddingGenerator.GenerateAsync("Find a happy hotel")).Vector;

var searchResult = collection.SearchAsync(searchEmbedding, top: 3);

I když to funguje, vyžaduje správu generování vkládání v každé lokalitě volání.

Doporučeným přístupem je konfigurace úložiště vektorů IEmbeddingGenerator<TInput,TEmbedding> . To vám umožní definovat vektorovou vlastnost pomocí zdrojového typu (například string) namísto float[] nebo ReadOnlyMemory<float>. MeVD pak zpracovává generování vkládání automaticky během operací upsertu i vyhledávání.

Nejprve definujte vektor vlastnost takto string:

[VectorStoreVector(Dimensions: 1536)]
public string DescriptionEmbedding { get; set; }

Při vytváření vektorového úložiště pak nakonfigurujte generátor vkládání:

VectorStore vectorStore = new QdrantVectorStore(
    new QdrantClient("localhost"),
    ownsClient: true,
    new QdrantVectorStoreOptions
    {
        EmbeddingGenerator = embeddingGenerator
    });

Teď můžete předat text přímo – MEVD generuje vkládání pod kapucí:

// Search with a plain text query - embedding is generated automatically.
var searchResult = collection.SearchAsync("Find a happy hotel", top: 3);

Důležité

Vlastnosti vektoru nakonfigurované tímto způsobem nepodporují načtení generovaného vektoru ani původního textu z databáze. Pokud potřebujete uložit původní text, přidejte samostatnou datovou vlastnost.

Generátory vkládání lze také nakonfigurovat na úrovni kolekce, definice záznamu nebo jednotlivých vektorových vlastností. Různé modely vkládání podporují různé velikosti vektorů; ujistěte se, Dimensions že hodnota odpovídá modelu, který jste nakonfigurovali. Další informace o vkládání generátorů a abstrakcí Microsoft.Extensions.AI najdete v tématu Obsazení v .NET.

Dynamické mapování na slovník .NET

Existují případy, kdy není žádoucí nebo je možné mapovat typ silného typu .NET do databáze. Představte si například, že v době kompilace nevíte, jak vypadá schéma databáze, a schéma se poskytuje pouze prostřednictvím konfigurace. Vytvoření typu .NET, který odráží schéma, by v tomto případě nebylo možné. Místo toho můžete dynamicky mapovat pomocí Dictionary<string, object?> typu záznamu. Vlastnosti se přidají do Dictionary klíče s klíčem jako název vlastnosti a hodnota jako hodnota vlastnosti.

Poznámka:

Většina aplikací jednoduše použije typy silného typu .NET k modelování dat. Dynamické mapování prostřednictvím Dictionary<string, object?> je určené pro pokročilé scénáře mapování dat.

Zadání informací o schématu při použití Dictionary

Když použijete operátory Dictionary, poskytovatelé stále potřebují vědět, jak schéma databáze vypadá. Bez informací o schématu by zprostředkovatel nemohl vytvořit kolekci nebo vědět, jak namapovat a z reprezentace úložiště, kterou každá databáze používá.

K poskytnutí informací o schématu můžete použít definici záznamu. Na rozdíl od datového modelu lze definici záznamu vytvořit z konfigurace za běhu , pokud informace o schématu nejsou v době kompilace známé.

Příklad

Pokud chcete použít Dictionary s poskytovatelem, zadejte ho jako datový model při vytváření kolekce. Zadejte také definici záznamu.

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"]);
  • Last updated on