Integrace vektorových úložiště

Vektor ukládá data a jejich vektorové vkládání dohromady, aby aplikace mohly najít záznamy podle sémantické podobnosti. V aplikacích využívajících Agent Framework můžete pomocí vektorových úložišť získávat podkladová data pro generování rozšířené o vyhledávání (RAG) nebo ukládat informace, které si agent může později vybavit.

Abstrakce vektorového úložiště poskytují běžné operace pro kolekce a záznamy, přičemž logika aplikace je oddělená od implementace konkrétního úložiště vektorů. Můžete například začít místní implementací a přepnout na spravovanou službu s minimálními změnami.

Jak fungují integrace vektorových úložiště

Typický pracovní postup úložiště vektorů zahrnuje tyto kroky:

  1. Definujte datový model, který identifikuje klíč záznamu, datová pole a vektorová pole.
  2. Pokud úložiště vektorů negeneruje vkládání, nakonfigurujte generátor vkládání.
  3. Připojte se k úložišti vektorů a vyberte nebo vytvořte kolekci.
  4. Vygenerujte embeddingy a vložte nebo aktualizujte záznamy do kolekce.
  5. Vyhledejte kolekci pomocí textu nebo vektoru v závislosti na možnostech implementace.
  6. Předejte agentovi relevantní výsledky vyhledávání jako kontext nebo zpřístupněte vyhledávání jako nástroj agenta.

podpora úložiště vektorů .NET

Agent Framework používá samostatné abstrakce ekosystému AI .NET:

  • Microsoft.Extensions.VectorData poskytuje běžná rozhraní API pro ukládání vektorů, shromažďování, záznam a vyhledávání.
  • Microsoft.Extensions.AI poskytuje abstrakce, například IEmbeddingGenerator, pro generování embeddingů nezávisle na konkrétním poskytovateli modelu.

Kde komponenta Agent Framework přijímá úložiště vektorů, můžete zadat kompatibilní Microsoft.Extensions.VectorData implementaci. Každá implementace databáze se distribuuje odděleně od balíčku abstrakcí.

Základní abstrakce

Abstrakce Purpose
VectorStore Poskytuje operace napříč kolekcemi a vytváří typové instance kolekce.
VectorStoreCollection<TKey, TRecord> Vytváří nebo odstraňuje kolekci a vkládá nebo aktualizuje, načítá či odstraňuje její záznamy.
IVectorSearchable<TRecord> Vyhledá záznamy podle vektoru nebo textu, pokud je k dispozici funkce vkládání generátoru nebo vkládání na straně databáze.

Dostupné implementace úložiště vektorů

Následující implementace používají běžné abstrakce úložiště vektorů .NET. Projděte si dokumentaci každé implementace týkající se verzí balíčků, podporovaných datových typů a omezení specifických pro službu.

Implementace Availability Používá oficiálně podporovanou databázovou sadu SDK. Správce nebo dodavatel
Azure AI Vyhledávač Available Ano Microsoft
Azure Cosmos DB pro MongoDB vCore Available Ano Microsoft
Azure Cosmos DB pro NoSQL Available Ano Microsoft
Couchbase Available Ano Couchbase
Elasticsearch Available Ano Elastic
Chroma Naplánováno Není relevantní Není relevantní
V paměti Available Není relevantní Microsoft
Milvus Naplánováno Není relevantní Není relevantní
MongoDB Available Ano Microsoft
Neon Serverless Postgres Použití implementace Postgres Ano Microsoft
Oracle Available Ano Oracle
Borová šiška Available No Microsoft
Postgres Available Ano Microsoft
Qdrant Available Ano Microsoft
Redis Available Ano Microsoft
SQL Server Available Ano Microsoft
SQLite Available Ano Microsoft
Volatilní v operační paměti Zastaralé; použijte implementaci v paměti Není relevantní Microsoft
Weaviate Available Ano Microsoft

Important

Implementace vektorového úložiště pocházejí z více správců. Před použitím každé implementace vyhodnoťte kvalitu, licencování, zásady podpory a kompatibilitu verzí. Některé implementace používají databázové sady SDK, které poskytovatel databáze oficiálně nepodporuje.

Začínáme

  1. Přidejte Microsoft.Extensions.VectorData.Abstractions balíček a balíček pro implementaci vámi zvoleného vektorového úložiště.
  2. Definujte typ záznamu a identifikujte jeho klíč, data a vlastnosti vektoru.
  3. Nakonfigurujte IEmbeddingGenerator, pokud vaše implementace vyžaduje embeddingy vytvářené aplikací.
  4. Vytvořte implementaci VectorStorea poté získejte typ VectorStoreCollection<TKey, TRecord>.
  5. Ujistěte se, že kolekce existuje, vložte nebo aktualizujte záznamy a zavolejte SearchAsync s textem nebo vektorem.

Úplný úvod k datovým modelům, příjmu dat, vkládání a vyhledávání najdete v tématu Vektorové databáze pro .NET aplikace AI.

podpora úložiště vektorů Python

Agent Framework poskytuje experimentální nativní kontrakty Python pro modely vektorového úložiště, operace shromažďování, továrny úložiště, vektorové a hybridní vyhledávání podle klíčových slov a nástroje pro vyhledávání agentů. Kontrakty jsou součástí agent-framework-core A nevyžadují Pydantic, NumPy, pandas nebo Sémantické jádro.

Warning

Nativní rozhraní API úložiště vektorů Python jsou experimentální. Než se stanou stabilními, může dojít k omezeným změnám způsobujícím chybu.

Základní abstrakce

Abstrakce Purpose
VectorStoreField a VectorStoreCollectionDefinition Popis klíčových polí, dat a vektorů, včetně názvů úložišť, indexů, dimenzí a funkcí vzdálenosti
@vectorstoremodel a register_vectorstoremodel() Zaregistrujte datové třídy, Pydantické modely, struktury msgspec, prosté třídy nebo externě vlastněné typy modelů.
BaseVectorCollection a SupportsVectorUpsert Definujte dávkový upsert, načítání, mazání, životní cyklus kolekce, převod záznamů a volitelné generování embeddingů.
BaseVectorStore Definuje úložiště, které obsahuje seznamy kolekcí a vytváří typové klienty kolekce.
BaseVectorSearch a SupportsVectorSearch Definujte vektorové a hybridní vyhledávání s klíčovými slovy, stránkování, filtry, prahové hodnoty skóre a výsledky hledání.
Filter, FilterGroup a Param Definujte přenosné filtry jen pro data, včetně parametrů filtru zadaných modelem pro vyhledávací nástroje.
InMemoryStore a InMemoryCollection Poskytněte lokální operace CRUD v rámci procesu a sekvenční vyhledávání pro vývoj a testování.
GenerateVectors Určuje, zda upserty generují všechna, žádná nebo vybraná vektorová pole.
create_vector_search_tool(), create_upsert_tool(), create_get_tool() a create_delete_tool() Zpřístupněte vektorové vyhledávání a operace CRUD nad kolekcemi jako funkční nástroje rozhraní Agent Framework.
VectorStoreHistoryProvider Ukládá historii konverzací v daném rozsahu do kolekce spravované poskytovatelem s volitelnou kompakcí a vyhledáváním v celé historii.
VectorCollectionContextProvider Přidá konfigurovatelné nástroje CRUD a vyhledávací nástroje pro kolekci vlastněnou volajícím.

Následující ukázka definuje záznamy ve vektorovém úložišti pomocí anotace jejich polí klíče, dat a vektoru:

# 5. Dataclasses use the default registered codec.
@vectorstoremodel(collection_name="hotels")
@dataclass
class Hotel:
    hotel_id: Annotated[str, VectorStoreField("key")]
    name: Annotated[str, VectorStoreField("data", is_indexed=True)]
    description: Annotated[
        str | list[float] | None,
        VectorStoreField("vector", dimensions=3, distance_function="cosine_similarity"),
    ] = None


# 6. Pydantic models provide validation with additional round-trip cost.
@vectorstoremodel(collection_name="products")
class Product(BaseModel):
    product_id: Annotated[str, VectorStoreField("key")]
    name: Annotated[str, VectorStoreField("data", is_full_text_indexed=True)]
    vector: Annotated[list[float] | None, VectorStoreField("vector", dimensions=3)] = None

Používejte VectorStoreCollectionDefinition přímo pro slovníky. Pro typy modelů, které patří jinému balíčku, použijte register_vectorstoremodel() s explicitní definicí a volitelným kodérem a dekodérem. Vektorové hodnoty podobné poli se serializují přes tolist() bez přidání závislosti na knihovně NumPy.

Agent Framework obsahuje implementaci v paměti pro vývoj a testy. Ukládá záznamy v aktuálním procesu a používá lineární skenování, takže pro produkční úlohy použijte databázový konektor.

Následující ukázka ukládá předpočítané vektory a hledá je pomocí přenosného stromu filtru:

import asyncio
from dataclasses import dataclass
from typing import Annotated

from agent_framework import Filter, FilterGroup, InMemoryCollection, VectorStoreField, vectorstoremodel
@vectorstoremodel(collection_name="hotels")
@dataclass
class Hotel:
    hotel_id: Annotated[str, VectorStoreField("key")]
    name: Annotated[str, VectorStoreField("data")]
    city: Annotated[str, VectorStoreField("data")]
    rating: Annotated[float, VectorStoreField("data")]
    amenities: Annotated[list[str], VectorStoreField("data")]
    vector: Annotated[
        list[float] | None,
        VectorStoreField("vector", dimensions=2, distance_function="cosine_similarity"),
    ] = None


async def main() -> None:
    """Store precomputed vectors and search them with direct filters."""
    collection: InMemoryCollection[str, Hotel] = InMemoryCollection(Hotel)
    await collection.ensure_collection_exists()

    # 1. The sample already has vectors, so generation is disabled explicitly.
    await collection.upsert(
        [
            Hotel("hotel-1", "Harbor View", "Lisbon", 4.8, ["wifi", "pool"], [1.0, 0.1]),
            Hotel("hotel-2", "Old Town Rooms", "Lisbon", 4.1, ["wifi"], [0.8, 0.2]),
            Hotel("hotel-3", "City Center", "Seattle", 4.7, ["wifi", "gym"], [0.1, 1.0]),
        ],
        generate_vectors=False,
    )

    # 2. Filter values are ordinary data. No Python source is parsed or executed.
    search_filter = FilterGroup(
        "and",
        (
            Filter("city", "eq", "Lisbon"),
            Filter("rating", "between", (4.5, 5.0)),
            Filter("amenities", "contains", "pool"),
        ),
    )
    results = await collection.search(
        vector=[1.0, 0.0],
        filter=search_filter,
        top=5,
    )

    # 3. Search results are consumed asynchronously.
    async for result in results:
        print(f"{result['record'].name}: {result['score']:.3f}")

Použijte Param , když má model zadat hodnotu filtru. Jeho Python typ, popis a omezení se stanou součástí schématu JSON vyhledávacího nástroje:

# 2. Param values become optional model-visible filter arguments.
# When the allowed values are known, use Literal so the tool schema exposes
# them as an enum.
category = Param(
    "category",
    Literal["Boutique", "Budget", "Extended-Stay", "Luxury", "Resort and Spa", "Suite"],
    description="Only return hotels in this category.",
)
min_rating = Param(
    "min_rating",
    float,
    description="The minimum guest rating.",
    minimum=0,
    maximum=5,
)
tool = create_vector_search_tool(
    collection,
    description="Search the hotel dataset, optionally filtering by category and minimum rating.",
    filter=FilterGroup(
        "and",
        (
            Filter("category", "eq", category),
            Filter("rating", "gte", min_rating),
        ),
    ),
    result_mapper=lambda result: (
        f"(hotel_id: {result['record'].hotel_id}) {result['record'].hotel_name} "
        f"(rating {result['record'].rating}) - {result['record'].description}. "
        f"Address: {result['record'].address.city}, {result['record'].address.country}."
    ),
)

Použití vektorové kolekce s agentem

Použijte VectorCollectionContextProvider , když vaše aplikace vlastní kolekci a datový model. Poskytovatel přidá vygenerované nástroje CRUD a nástroje pro vyhledávání. Funkce Upsert a odstranění ve výchozím nastavení vyžadují schválení, zatímco funkce get a search ne.

Použijte scope_filter k seskupení záznamů pro generované nástroje, ale nepovažujte filtr za hranici autorizace ani za garanci atomického chování backendu. Vyhledávací nástroje předávané prostřednictvím additional_search_tools zachovávají vlastní filtry, takže při sdílení kolekce použijte ekvivalentní filtr pro každý vlastní nástroj.

collection: InMemoryCollection[str, ProjectNote] = InMemoryCollection(
    ProjectNote,
    embedding_generator=OpenAIEmbeddingClient(
        model="text-embedding-3-small",
    ),
)
await collection.ensure_collection_exists()

# Omitted mapping entries keep their safe defaults. This sample disables
# approval for upsert so the scripted interaction can run unattended;
# delete still requires approval, while get and search remain read-only.
collection_context = VectorCollectionContextProvider(
    collection,
    # This process-local collection contains records for only this sample.
    scope_filter=None,
    approval_mode={"upsert": "never_require"},
)

async with Agent(
    client=OpenAIChatClient(model="gpt-5.4-nano"),
    name="ProjectNotesAssistant",
    instructions="Use the collection tools to manage project notes. Do not invent stored notes.",
    context_providers=[collection_context],
) as agent:

Ukládání historie konverzací v vektorovém úložišti

Použijte VectorStoreHistoryProvider, když má poskytovatel vlastnit schéma kolekce a automaticky načítat a ukládat zprávy rozhraní Agent Framework. Identifikátory aplikace, tenanta, agenta, zdroje a relace zabraňují nechtěnému překryvu, ale vaše aplikace musí i tak autorizovat přístup a používat přihlašovací údaje k úložišti nebo obory názvů s odpovídajícím rozsahem oprávnění.

Při konfiguraci vkládání zadejte explicitní název kolekce a dimenze vkládání. Komprimace snižuje pouze historii načtenou do kontextu modelu. Pokud vyhledávací nástroj povolíte, prohledá úplný přepis s vymezeným oborem.

history = VectorStoreHistoryProvider(
    InMemoryStore(),
    application_id="release-planning",
    tenant_id="contoso",
    agent_id="release-assistant",
    collection_name="release_planning_history_text_embedding_3_small",
    contents_format="json",
    embedding_generator=OpenAIEmbeddingClient(
        model="text-embedding-3-small",
    ),
    embedding_options={
        "dimensions": 1536,
        "encoding_format": "float",
    },
    compaction_strategy=SlidingWindowStrategy(
        keep_last_groups=2,
        preserve_system=True,
    ),
    include_search_tool=True,
)

# 2. Only the compacted projection is loaded into the model context. The
#    provider-owned search tool can still retrieve older scoped messages.
async with Agent(
    client=OpenAIChatClient(model="gpt-5.4-nano"),
    name="ReleaseAssistant",
    instructions=(
        "Help with release planning. Use the history search tool when an "
        "older detail is not present in the loaded conversation."
    ),
    context_providers=[history],
) as agent:

Implementace frameworku nativního agenta

Následující implementace používají nativní kontrakty Agent Framework. Některé jsou také k dispozici jako samostatné Sémantické jádro konektory, ale tyto dvě rodiny konektorů se nedají zaměnit.

Implementace Balíček a životní cyklus agenta Framework Samostatný konektor Sémantické jádro Režimy hledání Klíčová omezení
V paměti agent-framework-core; Vydaný balíček s experimentálními vektorovými rozhraními API Dostupný Hustý vektor s přenosnými filtry Místní lineární prohledávání procesů pro vývoj a testy, nikoli produkční databázi.
Azure AI Vyhledávač agent-framework-azure-ai-search; Beta balíček s experimentálními vektorovými rozhraními API Dostupný Hustý vektor a hybridní vyhledávání podle klíčových slov Jedno husté vektorové pole nejvyšší úrovně pro každý dotaz. Některé prahové hodnoty, ovládací prvky hybridního odvolání textu, striktní následné filtrování a oprávnění vyžadují podporu sady SDK nebo rozhraní API verze Preview a allow_preview=True.
Azure Cosmos DB for NoSQL agent-framework-azure-cosmos; Beta balíček s experimentálními vektorovými rozhraními API Dostupný Hustý vektor s přenosnými filtry Klíče musí být řetězce uložené jako ida kontejnery používají klíč oddílu /id . Vyhledávání podle klíčových slov a hybridní vyhledávání nejsou podporovány a eukleidovské vyhledávání nepodporuje prahové hodnoty skóre.
Azure DocumentDB agent-framework-azure-documentdb; alfa balíček Není k dispozici Hustý vektor s přenositelnými filtry metadat Klíče musí být řetězce nebo celá čísla. Vygenerované ID objektu, hybridní a fulltextové vyhledávání a vnořené cesty filtru se nepodporují.
DuckDB agent-framework-duckdb; alfa balíček Není k dispozici Přesný hustý vektor s přenosnými filtry Vyžaduje Python 3.10 nebo novější a DuckDB 1.4.1–1.5.x. Přibližné indexy, klíčové slovo a hybridní vyhledávání, fulltextové vyhledávání a vektorizace na straně serveru se nepodporují. Místní soubory umožňují současně pouze jeden proces zápisu.
MongoDB agent-framework-mongodb; alfa balíček Dostupný Přibližný nebo přesný hustý vektor s přenosnými filtry Vyžaduje PyMongo 4.13.2 nebo novější a nasazení s MongoDB Vector Search. Vyhledávání podle klíčových slov a hybridní vyhledávání, cesty k vnořeným filtrům, generování embeddingů na straně poskytovatele a automatická migrace schématu nejsou podporovány.
PostgreSQL s pgvectorem agent-framework-postgres; alfa balíček Dostupný Přesný hustý vektor, HNSW a IVFFlat Vyžaduje PostgreSQL 13+, pgvector 0.8.0+, existující schéma a povolené rozšíření. Klíčové slovo a hybridní vyhledávání se nepodporují.
Qdrant agent-framework-qdrant; alfa balíček Dostupný Hustý vektor s přenositelnými filtry na straně serveru Režim serveru vyžaduje Qdrant 1.16.2+. Klíče musí být 64bitová celá čísla bez znaménka nebo identifikátory UUID. Klíčové slovo a hybridní vyhledávání nejsou podporované a filtry nejsou dostupné v místním režimu sady SDK.
Redis agent-framework-redis; Beta balíček s experimentálními vektorovými rozhraními API Dostupný Zhuštěný vektor nad záznamy HASH nebo JSON Vyžaduje Redis 8.0.3 nebo novější s vyhledáváním; Záznamy JSON také vyžadují RedisJSON. Cluster Redis, vyhledávání klíčových slov a hybridní vyhledávání se nepodporují.
SQL Server agent-framework-sql-server; alfa balíček Dostupný Přesný hustý vektor s přenosnými filtry Vyžaduje Python 3.10–3.14 a SQL Server 2025 nebo vektorově povolenou databázi Azure SQL. Přibližné indexy, klíčové slovo a hybridní vyhledávání, vektorizace na straně serveru a migrace schématu se nepodporují.

Nainstalujte předem připravený balíček konektoru pro databázi, kterou používáte:

pip install agent-framework-azure-ai-search --pre
pip install agent-framework-azure-cosmos --pre
pip install agent-framework-azure-documentdb --pre
pip install agent-framework-duckdb --pre
pip install agent-framework-mongodb --pre
pip install agent-framework-postgres --pre
pip install agent-framework-qdrant --pre
pip install agent-framework-redis --pre
pip install agent-framework-sql-server --pre

Na Python 3.10 až 3.14 agent-framework-postgres nainstaluje binární distribuci Psycopg. Na Python 3.15 nebo novější používá pure-Python Psycopg, protože kompatibilní binární kola nejsou publikována, takže hostitel musí poskytnout instalaci systémulibpq.

Každý konektor implementuje společný model, kolekci, CRUD, filtrování a kontrakty vyhledávání. Možnosti a omezení specifické pro databázi se stále vztahují. Kompletní příklady najdete v ukázkách Azure AI Vyhledávač, DuckDB, MongoDB, Postgres, Qdrant, Redis a SQL Server.

implementace využívající pouze Sémantické jádro

Aplikace můžou dál používat Python vektorové úložiště Sémantické jádro. Tyto implementace používají samostatné kontrakty úložiště vektorů Sémantické jádro místo nativních kontraktů agenta Framework. Následující implementace aktuálně nemají nativní konektor Agent Framework:

Implementace Availability Používá oficiálně podporovanou databázovou sadu SDK. Správce nebo dodavatel
Azure Cosmos DB pro MongoDB vCore Available Ano projekt Microsoft Sémantické jádro
Sytost barvy Available Ano projekt Microsoft Sémantické jádro
Elasticsearch Naplánováno Není relevantní Není relevantní
Faiss Available Ano projekt Microsoft Sémantické jádro
Neon Serverless Postgres Použití implementace Postgres Ano projekt Microsoft Sémantické jádro
Oracle Available Ano Oracle
Borová šiška Available Ano projekt Microsoft Sémantické jádro
SQLite Naplánováno Není relevantní projekt Microsoft Sémantické jádro
Weaviate Available Ano projekt Microsoft Sémantické jádro

Important

Implementace vektorového úložiště pocházejí z více správců. Před použitím každé implementace vyhodnoťte kvalitu, licencování, zásady podpory a kompatibilitu verzí.

Použijte implementaci využívající pouze Sémantické jádro

  1. Nainstalujte semantic-kernel a závislosti vyžadované vámi zvolenou implementací.
  2. Definujte model s dekorátorem @vectorstoremodel a identifikujte jeho klíčová pole, data a vektorová pole.
  3. Vytvořte pro tento model kolekci specifickou pro implementaci.
  4. Ujistěte se, že kolekce existuje, a poté aktualizujte existující záznamy a vložte nové.
  5. K načtení záznamů pro vaši aplikaci použijte rozhraní API pro vyhledávání kolekce.

Informace o nastavení implementace a úplných příkladech najdete v tématu Sémantické jádro Vector Stores.

Podpora úložiště vektorů Go

Integrace vektorového úložiště ještě není dostupná v rozhraní Agent Framework for Go. Nejnovější stav najdete v úložišti Agent Framework Go .

Další kroky

Přidejte RAG agentovi

  • Last updated on