Použití vektorových úložišť v aplikacích .NET AI

📦 Balíček Microsoft.Extensions.VectorData.Abstractions (MEVD) poskytuje jednotné rozhraní API pro práci s vektorovými úložišti v .NET. Stejný kód můžete použít k ukládání a vyhledávání vložených objektů napříč různými poskytovateli vektorové databáze.

V tomto článku se dozvíte, jak používat klíčové funkce knihovny.

Předpoklady

Instalace balíčků

Nainstalujte balíček zprostředkovatele pro vaši vektorovou databázi. Balíček Microsoft.Extensions.VectorData.Abstractions se automaticky přenese jako tranzitivní závislost. Následující příklad používá poskytovatele v paměti pro účely vývoje a testování:

dotnet package add Microsoft.SemanticKernel.Connectors.InMemory --prerelease

V produkčních scénářích nahraďte Microsoft.SemanticKernel.Connectors.InMemory poskytovatelem vaší databáze. Dostupné poskytovatele najdete v části Hotoví poskytovatelé vektorového úložiště. (Navzdory zahrnutí "SemanticKernel" do názvů balíčků zprostředkovatele nemají tito zprostředkovatelé nic společného s Sémantické jádro a jsou použitelné kdekoli v .NET, včetně Agent Framework.)

Definování datového modelu

Definujte .NET třídu, která představuje záznamy, které chcete uložit v úložišti vektorů. Pomocí atributů můžete anotovat vlastnosti ve třídě podle toho, zda představují primární klíč, obecná data nebo vektorová data. Tady je jednoduchý příklad:

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

Jako alternativu k používání atributů můžete schéma definovat programově pomocí .VectorStoreCollectionDefinition Tento přístup je užitečný, když chcete použít stejný datový model s různými konfiguracemi nebo když nemůžete přidat atributy do třídy datového modelu.

Další informace najdete v tématu Definování datového modelu.

Vytvoření úložiště vektorů

Vytvořte instanci VectorStore implementace pro zvolenou databázi. Následující příklad vytvoří úložiště vektorů v paměti:

// Create an in-memory vector store (no external service required).
// For production, replace this with a connector for your preferred database.
var vectorStore = new InMemoryVectorStore();

Získání kolekce

Zavolejte GetCollection na VectorStore, abyste získali typovaný VectorStoreCollection<TKey,TRecord> odkaz. Potom zavolejte EnsureCollectionExistsAsync , aby se kolekce vytvořila, pokud ještě neexistuje:

// Get a reference to a collection named "hotels".
VectorStoreCollection<int, Hotel> collection =
    vectorStore.GetCollection<int, Hotel>("hotels");

// Ensure the collection exists in the database.
await collection.EnsureCollectionExistsAsync();

Název kolekce se mapuje na základní koncept úložiště pro vaši databázi (například tabulku ve službě SQL Server, index v Azure AI Vyhledávač nebo kontejner v Cosmos DB).

Upsert records

Slouží UpsertAsync k vložení nebo aktualizaci záznamů v kolekci. Pokud záznam se stejným klíčem již existuje, aktualizuje se:

// Upsert records into the collection.
// In a real app, generate embeddings using an IEmbeddingGenerator.
// The CreateFakeEmbedding helper at the bottom of this file generates
// placeholder vectors for demonstration purposes only.
var hotels = new List<Hotel>
{
    new()
    {
        HotelId = 1,
        HotelName = "Seaside Retreat",
        Description = "A peaceful hotel on the coast with stunning ocean views.",
        DescriptionEmbedding = CreateFakeEmbedding(1),
        Tags = ["beach", "ocean", "relaxation"]
    },
    new()
    {
        HotelId = 2,
        HotelName = "Mountain Lodge",
        Description = "A cozy lodge in the mountains with hiking trails nearby.",
        DescriptionEmbedding = CreateFakeEmbedding(2),
        Tags = ["mountain", "hiking", "nature"]
    },
    new()
    {
        HotelId = 3,
        HotelName = "City Centre Hotel",
        Description = "A modern hotel in the heart of the city, close to attractions.",
        DescriptionEmbedding = CreateFakeEmbedding(3),
        Tags = ["city", "business", "urban"]
    }
};

foreach (Hotel h in hotels)
{
    await collection.UpsertAsync(h);
}

Důležité

Ve skutečné aplikaci doporučujeme před uložením záznamů nechat nástroj MEVD vygenerovat vektorové reprezentace.

Získání záznamů

Slouží GetAsync k načtení jednoho záznamu podle jeho klíče. Pro načtení více záznamů předejte `IEnumerable<TKey>` do `GetAsync`.

// Get a specific record by its key.
Hotel? hotel = await collection.GetAsync(1);
if (hotel is not null)
{
    Console.WriteLine($"Hotel: {hotel.HotelName}");
    Console.WriteLine($"Description: {hotel.Description}");
}

Načtení více záznamů najednou:

// Get multiple records by their keys.
IAsyncEnumerable<Hotel> hotelBatch = collection.GetAsync([1, 2, 3]);
await foreach (Hotel h in hotelBatch)
{
    Console.WriteLine($"Batch hotel: {h.HotelName}");
}

Slouží SearchAsync k vyhledání záznamů, které jsou sémanticky podobné dotazu. Předejte vektor vkládání dotazu a počet výsledků, které se mají vrátit:

// Search for the top 2 hotels most similar to the query embedding.
IAsyncEnumerable<VectorSearchResult<Hotel>> searchResults =
    collection.SearchAsync(queryEmbedding, top: 2);

await foreach (VectorSearchResult<Hotel> result in searchResults)
{
    Console.WriteLine($"Found: {result.Record.HotelName} (score: {result.Score:F4})");
}

Každý VectorSearchResult<TRecord> obsahuje odpovídající záznam a skóre podobnosti. Vyšší skóre naznačují bližší sémantickou shodu.

Filtrování výsledků vyhledávání

Slouží VectorSearchOptions<TRecord> k filtrování výsledků hledání před porovnáním vektoru. Můžete filtrovat podle libovolné vlastnosti označené pomocí IsIndexed = true.

// Filter results before the vector comparison.
// Only properties marked with IsIndexed = true can be used in filters.
var searchOptions = new VectorSearchOptions<Hotel>
{
    Filter = h => h.HotelName == "Seaside Retreat"
};

IAsyncEnumerable<VectorSearchResult<Hotel>> filteredResults =
    collection.SearchAsync(queryEmbedding, top: 2, searchOptions);

await foreach (VectorSearchResult<Hotel> result in filteredResults)
{
    Console.WriteLine($"Filtered: {result.Record.HotelName} (score: {result.Score:F4})");
}

Filtry se vyjadřují jako výrazy LINQ. Podporované operace se liší podle poskytovatele, ale všichni poskytovatelé podporují běžná porovnání, jako je rovnost, nerovnost a logická && a ||.

Řízení chování hledání pomocí VectorSearchOptions

Slouží VectorSearchOptions<TRecord> k řízení různých aspektů chování vektorového vyhledávání:

// Use VectorSearchOptions to control paging and vector inclusion.
var pagedOptions = new VectorSearchOptions<Hotel>
{
    Skip = 1,           // Skip the first result (useful for paging).
    IncludeVectors = false  // Don't include vector data in results (default).
};

IAsyncEnumerable<VectorSearchResult<Hotel>> pagedResults =
    collection.SearchAsync(queryEmbedding, top: 2, pagedOptions);

await foreach (VectorSearchResult<Hotel> result in pagedResults)
{
    Console.WriteLine($"Paged: {result.Record.HotelName}");
}

Následující tabulka popisuje dostupné možnosti:

Možnost Description
Filter Výraz LINQ pro filtrování záznamů před porovnáním vektorů.
VectorProperty Vektorová vlastnost, na které se má hledat. Vyžaduje se, pokud má datový model více vektorových vlastností.
Skip Počet výsledků, které budou přeskočeny před vrácením. Užitečné pro stránkování. Výchozí hodnota je 0.
IncludeVectors Zda zahrnout vektorová data do vrácených záznamů. Vynechání vektorů snižuje přenos dat. Výchozí hodnota je false.

Další informace naleznete v tématu Vektorové vyhledávání.

Použití integrované generace vkládání

Místo ručního generování vložených vektorů před každým upsertem můžete nakonfigurovat IEmbeddingGenerator vektorové úložiště nebo kolekci. Když to uděláte, deklarujte vlastnost vektoru string jako typ (zdrojový text) a úložiště generuje vkládání automaticky.

Další informace naleznete v tématu Automatické generování vkládání.

Některá úložiště vektorů podporují hybridní vyhledávání, které kombinuje podobnost vektorů s párování klíčových slov. Tento přístup může zlepšit relevanci výsledků ve srovnání s hledáním pouze vektorem.

Pokud chcete použít hybridní vyhledávání, zkontrolujte, jestli vaše kolekce implementuje IKeywordHybridSearchable<TRecord>. Toto rozhraní implementují pouze poskytovatelé pro databáze, které tuto funkci podporují.

Další informace najdete v tématu hybridní vyhledávání.

Odstranění záznamů

Pokud chcete odstranit jeden záznam podle klíče, použijte DeleteAsync:

// Delete a record by its key.
await collection.DeleteAsync(3);

Odstranit kolekci

Chcete-li odebrat celou kolekci z úložiště vektorů, použijte EnsureCollectionDeletedAsync:

// Delete the entire collection from the vector store.
await collection.EnsureCollectionDeletedAsync();

Změnit poskytovatele úložiště vektorů

Vzhledem k tomu, že všichni zprostředkovatelé implementují stejnou VectorStore abstraktní třídu, můžete mezi nimi přepínat změnou konkrétního typu při spuštění. Ve většině případů zůstává váš kód kolekce a vyhledávání stejný. Některé úpravy se ale obvykle vyžadují, protože různé databáze podporují různé datové typy.

Související obsah

  • Last updated on