Integrering av vektorlager

Vektorlager håller ihop data och dess vektorbäddningar så att program kan hitta poster med semantisk likhet. I Agent Framework-program kan du använda vektorlager för att hämta jordningsdata för RAG (Retrieval Augmented Generation) eller för att lagra information som en agent kan återkalla senare.

Abstraktioner för vektorlager tillhandahåller gemensamma operationer för samlingar och poster, så att programmets logik hålls åtskild från den specifika implementeringen av vektorlagret. Du kan till exempel börja med en lokal implementering och växla till en hanterad tjänst med minimala ändringar.

Så här fungerar integreringar av vektorlager

Ett vanligt arbetsflöde för vektorlager innehåller följande steg:

  1. Definiera en datamodell som identifierar postnyckeln, datafälten och vektorfälten.
  2. Konfigurera en inbäddningsgenerator om vektorarkivet inte genererar inbäddningar.
  3. Anslut till ett vektorlager och välj eller skapa en samling.
  4. Generera embeddingar och infoga eller uppdatera poster i samlingen.
  5. Sök i samlingen med text eller en vektor, beroende på implementeringens funktioner.
  6. Skicka relevanta sökresultat till en agent som kontext eller exponera sökning som ett agentverktyg.

stöd för .NET vektorarkiv

Agent Framework använder .NET AI-ekosystemets fristående abstraktioner:

  • Microsoft.Extensions.VectorData innehåller vanliga API:er för vektorlagring, insamling, post och sökning.
  • Microsoft.Extensions.AI tillhandahåller abstraktioner, till exempel IEmbeddingGenerator för att generera inbäddningar oberoende av en specifik modellprovider.

Om en Agent Framework-komponent accepterar ett vektorlager kan du tillhandahålla en kompatibel Microsoft.Extensions.VectorData implementering. Varje databasimplementering distribueras separat från abstraktionspaketet.

Kärnabstraktioner

Abstraktion Purpose
VectorStore Tillhandahåller operationer för samlingar och skapar typade samlingsinstanser.
VectorStoreCollection<TKey, TRecord> Skapar eller tar bort en samling och infogar eller uppdaterar, hämtar eller tar bort posterna i den.
IVectorSearchable<TRecord> Söker efter vektor eller text när en inbäddningsgenerator eller inbäddningsfunktion på databassidan är tillgänglig.

Tillgängliga implementeringar av vektorlager

Följande implementeringar använder de vanliga .NET vektorlagringsabstraktioner. Granska dokumentationen för varje implementering för paketversioner, datatyper som stöds och tjänstspecifika begränsningar.

Implementation Availability Använder en databas-SDK som stöds officiellt Underhållare eller leverantör
Azure AI-sökning Tillgängligt Ja Microsoft
Azure Cosmos DB för MongoDB vCore Tillgängligt Ja Microsoft
Azure Cosmos DB för NoSQL Tillgängligt Ja Microsoft
Couchbase Tillgängligt Ja Couchbase
Elasticsearch Tillgängligt Ja Elastic
Chroma Planerat Ej tillämpligt Ej tillämpligt
Minnesinternt Tillgängligt Ej tillämpligt Microsoft
Milvus Planerat Ej tillämpligt Ej tillämpligt
MongoDB Tillgängligt Ja Microsoft
Neon Serverless Postgres Använda Postgres-implementeringen Ja Microsoft
Oracle Tillgängligt Ja Oracle
Tallkotte Tillgängligt No Microsoft
Postgres Tillgängligt Ja Microsoft
Qdrant Tillgängligt Ja Microsoft
Redis Tillgängligt Ja Microsoft
SQL Server Tillgängligt Ja Microsoft
SQLite Tillgängligt Ja Microsoft
Flyktig i minnet Inaktuell; använda implementeringen i minnet Ej tillämpligt Microsoft
Viaviate Tillgängligt Ja Microsoft

Important

Implementeringar av vektorlager tillhandahålls av flera utvecklare. Utvärdera varje implementerings kvalitet, licensiering, supportprincip och versionskompatibilitet innan du använder den. Vissa implementeringar använder databas-SDK:er som databasprovidern inte officiellt stöder.

Get started

  1. Lägg till Microsoft.Extensions.VectorData.Abstractions paketet och paketet för implementeringen av din valda vektordatabas.
  2. Definiera en posttyp och identifiera dess nyckel-, data- och vektoregenskaper.
  3. Konfigurera en IEmbeddingGenerator om implementeringen kräver programgenererade inbäddningar.
  4. Skapa implementeringens VectorStore och hämta sedan en typad VectorStoreCollection<TKey, TRecord>.
  5. Kontrollera att samlingen finns, uppdatera eller infoga poster och anropa SearchAsync med text eller en vektor.

En fullständig introduktion till datamodeller, inmatning, inbäddningar och sökning finns i Vektordatabaser för .NET AI-appar.

stöd för Python vektorarkiv

Agent Framework tillhandahåller experimentella, inbyggda Python kontrakt för vektorlagermodeller, insamlingsåtgärder, butiksfabriker, vektor- och nyckelordshybridsökning och agentsökningsverktyg. Kontrakten ingår agent-framework-core i och kräver inte Pydantic, NumPy, Pandas eller Semantic Kernel.

Varning

Api:er för inbyggda Python vektorlager är experimentella. Begränsade icke-bakåtkompatibla ändringar kan inträffa innan de blir stabila.

Kärnabstraktioner

Abstraktion Purpose
VectorStoreField och VectorStoreCollectionDefinition Beskriv nyckel-, data- och vektorfält, inklusive lagringsnamn, index, dimensioner och avståndsfunktioner.
@vectorstoremodel och register_vectorstoremodel() Registrera dataklasser, pydantiska modeller, msgspec-structs, vanliga klasser eller externt ägda modelltyper.
BaseVectorCollection och SupportsVectorUpsert Definiera batchuppdatering och -infogning, hämta, ta bort, livscykeln för samlingar, konvertering av poster och valfri generering av inbäddningar.
BaseVectorStore Definierar en lagring som listar samlingar och skapar typade klienter för samlingar.
BaseVectorSearch och SupportsVectorSearch Definiera vektorsökning, hybridsökning med vektorer och nyckelord, sidindelning, filter, poängtrösklar och sökresultat.
Filter, FilterGroup och Param Definiera portabla filter, endast data, inklusive filterparametrar som tillhandahålls av modellen för sökverktyg.
InMemoryStore och InMemoryCollection Tillhandahåll processlokal CRUD och linjär genomsökning för utveckling och testning.
GenerateVectors Styr om upserts genererar alla, inga eller valda vektorfält.
create_vector_search_tool(), create_upsert_tool(), create_get_tool()och create_delete_tool() Exponera vektorsökning och CRUD-åtgärder för samlingar som funktionsverktyg i Agent Framework.
VectorStoreHistoryProvider Lagrar begränsad konversationshistorik i en leverantörsägd samling med valfri komprimering och fullständig historiksökning.
VectorCollectionContextProvider Lägger till konfigurerbara CRUD- och sökverktyg för en uppringarägd samling.

Följande exempel definierar vektorlagringsposter genom att kommentera nyckel-, data- och vektorfält:

# 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

Använd VectorStoreCollectionDefinition direkt för ordlistor. För modelltyper som ägs av ett annat paket använder du register_vectorstoremodel() med en explicit definition och valfri kodare och avkodare. Matrisliknande vektorvärden serialiserar igenom tolist() utan att lägga till ett NumPy-beroende.

Agent Framework innehåller en minnesintern implementering för utveckling och tester. Den lagrar poster i den aktuella processen och använder en linjär genomsökning, så använd en databasanslutning för produktionsarbetsbelastningar.

Ange alternativ för inbäddning för varje åtgärd

Skicka embeddings_options till upsert() för att använda leverantörsalternativ på varje genererat vektorfält. Använd embeddings_options_by_field när olika logiska vektorfält behöver olika alternativ. Dessa två argument utesluter varandra.

För inbäddning av frågor skickar du embeddings_options till search() eller create_vector_search_tool(). Agent Framework tillhandahåller det valda vektorfältets deklarerade dimensioner och avvisar ett motstridigt dimensions värde innan inbäddningsprovidern anropas.

Upsert-inbäddningsalternativ kräver genererade vektorer och kan inte kombineras med generate_vectors=False. Sökinbäddningsalternativ kräver en lokal inbäddningsgenerator och ignoreras när du anger en förberäknad frågevektor.

Följande exempel lagrar förkomputerade vektorer och söker igenom dem med ett portabelt filterträd:

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}")

Använd Param när modellen ska ange ett filtervärde. Dess Python typ, beskrivning och begränsningar blir en del av sökverktygets JSON-schema:

# 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}."
    ),
)

Använd en vektorsamling med en agent

Använd VectorCollectionContextProvider när ditt program äger insamlings- och datamodellen. Providern lägger till genererade CRUD- och sökverktyg. Upsert och delete kräver som standard godkännande, medan get och search inte gör det.

Ange scope_filter för att gruppera poster för de verktyg som genereras, men behandla inte filtret som en behörighetsgräns eller en atomisk garanti på serversidan. Sökverktyg som går via additional_search_tools behåller sina egna filter, så använd ett motsvarande filter för varje anpassat verktyg när en samling delas.

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:

Lagra konversationshistorik i ett vektorarkiv

Använd VectorStoreHistoryProvider när providern ska äga samlingsschemat och automatiskt läsa in och spara Agent Framework-meddelanden. Dess program-, klient-, agent-, käll- och sessionsidentifierare förhindrar oavsiktlig överlappning, men ditt program måste fortfarande auktorisera åtkomst och använda autentiseringsuppgifter eller namnrymder för lämpligt omfång.

När du konfigurerar inbäddningar anger du ett explicit samlingsnamn och inbäddningsdimensionerna. Komprimering minskar endast den historik som läses in i modellkontexten. Om du aktiverar sökverktyget söker det igenom den fullständiga omfångsavskriften.

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:

Implementeringar av native Agent Framework

Följande implementeringar använder de interna Agent Framework-kontrakten. Vissa är också tillgängliga som separata Semantic Kernel-anslutningar, men de två anslutningsfamiljerna är inte sinsemellan utbytbara.

Implementation Agent Framework-paket och livscykel Separat Semantic Kernel-anslutning Söklägen Viktiga begränsningar
I-minnet agent-framework-core; släppt paket med experimentella vektor-API:er Tillgängligt Tät vektor med portabla filter Processlokal linjär genomsökning efter utveckling och tester, inte en produktionsdatabas.
Azure AI-sökning agent-framework-azure-ai-search; beta-paket med experimentella vektor-API:er Tillgängligt Tät vektor- och nyckelordshybrid Ett toppnivåtätt vektorfält per fråga. Vissa tröskelvärden, hybridkontroller för textåterkallning, strikt efterfiltrering och behörigheter kräver en stöd för förhandsversions-SDK/API och allow_preview=True.
Azure Cosmos DB för NoSQL agent-framework-azure-cosmos; beta-paket med experimentella vektor-API:er Tillgängligt Tät vektor med portabla filter Nycklar måste vara strängar som lagras som idoch containrar använder partitionsnyckeln /id . Nyckelords- och hybridsökning stöds inte och euklidisk sökning stöder inte tröskelvärden för poäng.
Azure DocumentDB agent-framework-azure-documentdb; alfapaket Inte tillgänglig Tät vektor med portabla metadatafilter Nycklar måste vara strängar eller heltal. Genererade ObjectIds, hybrid- och fulltextsökning och kapslade filtersökvägar stöds inte.
DuckDB agent-framework-duckdb; alfapaket Inte tillgänglig Exakt tät vektor med portabla filter Kräver Python 3.10+ och DuckDB 1.4.1–1.5.x. Ungefärliga index, nyckelord och hybridsökning, fulltextsökning och vektorisering på serversidan stöds inte. Lokala filer tillåter endast en skrivprocess i taget.
MongoDB agent-framework-mongodb; alfapaket Tillgängligt Ungefärlig eller exakt tät vektor med portabla filter Kräver PyMongo 4.13.2+ och en distribution med MongoDB Vector Search. Nyckelords- och hybridsökning, kapslade filtersökvägar, inbäddningsgenerering på providersidan och automatisk schemamigrering stöds inte. Modeller som deklarerar is_full_text_indexed avvisas och nyligen skrivna poster blir sökbara asynkront.
Oracle Database agent-framework-oracle; alfapaket Tillgängligt Tät vektor med portabla filter Kräver Oracle Database 23ai eller senare med COMPATIBLE inställt på 23.4.0 eller högre och python-oracledb 2.2.x eller 3.x. Indexhantering, nyckelords- och hybridsökning, JSON och kapslade filter, vektorisering på serversidan och schemamigrering stöds inte.
PostgreSQL med pgvector agent-framework-postgres; alfapaket Tillgängligt Exakt tät vektor, HNSW och IVFFlat Kräver PostgreSQL 13+, pgvector 0.8.0+, ett befintligt schema och det aktiverade tillägget. Nyckelords- och hybridsökning stöds inte.
Qdrant agent-framework-qdrant; alfapaket Tillgängligt Tät vektor med portabla filter på serversidan Serverläget kräver Qdrant 1.16.2+. Nycklarna måste vara osignerade 64-bitars heltal eller UUID:er. Nyckelords- och hybridsökning stöds inte och filter är inte tillgängliga i lokalt SDK-läge.
Redis agent-framework-redis; beta-paket med experimentella vektor-API:er Tillgängligt Tät vektor över HASH- eller JSON-poster Kräver Redis 8.0.3+ med Search; JSON-poster kräver också RedisJSON. Redis-kluster, nyckelordssökning och hybridsökning stöds inte.
SQL Server agent-framework-sql-server; alfapaket Tillgängligt Exakt tät vektor med portabla filter Kräver Python 3.10–3.14 och SQL Server 2025 eller en vektoraktiverad Azure SQL databas. Ungefärliga index, nyckelord och hybridsökning, vektorisering på serversidan och schemamigrering stöds inte.

Installera ett förhandsversionsanslutningspaket för den databas som du använder:

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-oracle --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

På Python 3.10 till 3.14 agent-framework-postgres installerar Psycopgs binära distribution. I Python 3.15 eller senare används den rena Python-versionen av Psycopg eftersom kompatibla binära wheels inte publiceras, så värdsystemet måste tillhandahålla en system libpq-installation.

Varje anslutning implementerar de gemensamma kontrakten för modell, samling, CRUD, filter och sökning. Databasspecifika funktioner och begränsningar gäller fortfarande. Fullständiga exempel finns i exemplen för Azure AI-sökning, DuckDB, MongoDB-vektoråtgärder, MongoDB-agenten RAG, Oracle Database, Postgres, Qdrant, Redis och SQL Server.

implementeringar med endast Semantic Kernel

Program kan fortsätta att använda Semantic Kernel Python vektorlager direkt. Dessa implementeringar använder separata Semantic Kernel vektorlagringskontrakt i stället för de interna Agent Framework-kontrakten. Följande implementeringar har för närvarande inte någon inbyggd Agent Framework-anslutning:

Implementation Availability Använder en databas-SDK som stöds officiellt Underhållare eller leverantör
Azure Cosmos DB för MongoDB vCore Tillgängligt Ja Microsoft Semantic Kernel projekt
Chroma Tillgängligt Ja Microsoft Semantic Kernel projekt
Elasticsearch Planerat Ej tillämpligt Ej tillämpligt
Faiss Tillgängligt Ja Microsoft Semantic Kernel projekt
Neon Serverless Postgres Använda Postgres-implementeringen Ja Microsoft Semantic Kernel projekt
Tallkotte Tillgängligt Ja Microsoft Semantic Kernel projekt
SQLite Planerat Ej tillämpligt Microsoft Semantic Kernel projekt
Viaviate Tillgängligt Ja Microsoft Semantic Kernel projekt

Important

Implementeringar av vektorlager tillhandahålls av flera utvecklare. Utvärdera varje implementerings kvalitet, licensiering, supportprincip och versionskompatibilitet innan du använder den.

Använda en implementering med endast Semantic Kernel

  1. Installera semantic-kernel och de beroenden som krävs av den valda implementeringen.
  2. Definiera en modell med dekoratören @vectorstoremodel och identifiera dess nyckel-, data- och vektorfält.
  3. Skapa en implementeringsspecifik samling för den modellen.
  4. Se till att samlingen finns och infoga eller uppdatera sedan poster.
  5. Använd samlingens sök-API:er för att hämta poster för ditt program.

För implementeringskonfiguration och fullständiga exempel, se Semantic Kernel Vector Stores.

Stöd för Go-vektordatabaser

Vektorlagringsintegrering är ännu inte tillgängligt i Agent Framework för Go. Se Agent Framework Go-lagringsplatsen för den senaste statusen.

Nästa steg

Lägga till RAG i en agent

  • Uppdaterades senast