Vectoropslagintegraties

Vectorarchieven bewaren gegevens en de bijbehorende vector-insluitingen, zodat toepassingen records kunnen vinden op basis van semantische overeenkomsten. In Agent Framework-toepassingen kunt u vectorarchieven gebruiken om grondgegevens op te halen voor RAG (Retrieval Augmented Generation) of om informatie op te slaan die een agent later kan intrekken.

Abstracties van vectoropslag bieden algemene bewerkingen voor verzamelingen en records, waardoor uw toepassingslogica gescheiden blijft van de implementatie van het specifieke vectorarchief. U kunt bijvoorbeeld beginnen met een lokale implementatie en overschakelen naar een beheerde service met minimale wijzigingen.

Hoe vector store-integraties werken

Een typische vector store-werkstroom omvat deze stappen:

  1. Definieer een gegevensmodel dat de recordsleutel, gegevensvelden en vectorvelden identificeert.
  2. Configureer een insluitingsgenerator als het vectorarchief geen insluitingen genereert.
  3. Maak verbinding met een vectorarchief en selecteer of maak een verzameling.
  4. Genereer embeddings en upsert records in de collectie.
  5. Zoek in de verzameling met tekst of een vector, afhankelijk van de mogelijkheden van de implementatie.
  6. Geef relevante zoekresultaten door aan een agent als context of zoekfunctie beschikbaar maken als agenthulpprogramma.

ondersteuning voor .NET vector store

Agent Framework maakt gebruik van de zelfstandige abstracties van het .NET AI-ecosysteem:

Wanneer een Agent Framework-onderdeel een vectorarchief accepteert, kunt u een compatibele Microsoft.Extensions.VectorData implementatie leveren. Elke database-implementatie wordt afzonderlijk van het abstractiespakket gedistribueerd.

Kernabstracties

Abstractie Purpose
VectorStore Biedt bewerkingen in verzamelingen en maakt getypte verzamelingexemplaren.
VectorStoreCollection<TKey, TRecord> Hiermee maakt of verwijdert u een verzameling en voegt u records toe of werkt u deze bij, haalt u ze op of verwijdert u ze.
IVectorSearchable<TRecord> Zoekt records op basis van vectoren of tekst wanneer een embeddinggenerator of een databasezijdige embeddingmogelijkheid beschikbaar is.

Beschikbare implementaties voor vectoropslag

In de volgende implementaties worden de algemene abstracties van .NET vectoropslag gebruikt. Bekijk de documentatie van elke implementatie voor pakketversies, ondersteunde gegevenstypen en servicespecifieke beperkingen.

Implementation Availability Maakt gebruik van een officieel ondersteunde database-SDK Onderhouder of leverancier
Azure AI Zoeken Beschikbaar Yes Microsoft
Azure Cosmos DB voor MongoDB vCore Beschikbaar Yes Microsoft
Azure Cosmos DB voor NoSQL Beschikbaar Yes Microsoft
Couchbase Beschikbaar Yes Couchbase
Elasticsearch Beschikbaar Yes Elastic
Chroma Gepland Niet van toepassing Niet van toepassing
In-memory Beschikbaar Niet van toepassing Microsoft
Milvus Gepland Niet van toepassing Niet van toepassing
MongoDB Beschikbaar Yes Microsoft
Neon Serverless Postgres De Postgres-implementatie gebruiken Yes Microsoft
Oracle Beschikbaar Yes Oracle
Dennenappel Beschikbaar No Microsoft
Postgres Beschikbaar Yes Microsoft
Qdrant Beschikbaar Yes Microsoft
Redis Beschikbaar Yes Microsoft
SQL Server Beschikbaar Yes Microsoft
SQLite Beschikbaar Yes Microsoft
Vluchtig geheugen Afgeschaft; de in-memory implementatie gebruiken Niet van toepassing Microsoft
Weaviate Beschikbaar Yes Microsoft

Important

Vector Store-implementaties zijn afkomstig van meerdere onderhouders. Evalueer de kwaliteit, licentieverlening, ondersteuningsbeleid en versiecompatibiliteit van elke implementatie voordat u deze gebruikt. Sommige implementaties maken gebruik van database-SDK's die de databaseprovider niet officieel ondersteunt.

Get started

  1. Voeg de Microsoft.Extensions.VectorData.Abstractions pakket en het pakket voor de door jou gekozen implementatie van de vectorstore.
  2. Definieer een recordtype en identificeer de sleutel, gegevens en vectoreigenschappen.
  3. Configureer een IEmbeddingGenerator als uw implementatie toepassingsgegenereerde insluitingen vereist.
  4. Maak de VectorStore van de implementatie en haal vervolgens een getypeerde VectorStoreCollection<TKey, TRecord> op.
  5. Zorg ervoor dat de verzameling bestaat, voeg records in of werk ze bij, en roep SearchAsync aan met tekst of een vector.

Zie Vector-databases voor .NET AI-apps voor een volledige inleiding tot gegevensmodellen, opname, insluitingen en zoeken.

ondersteuning voor Python vectoropslag

Agent Framework biedt experimentele, systeemeigen Python contracten voor vectoropslagmodellen, verzamelingsbewerkingen, winkelfabrieken, vector- en hybride zoekopdrachten voor trefwoorden en zoekhulpprogramma's voor agents. De contracten maken deel uit van agent-framework-core en vereisen geen Pydantic, NumPy, pandas of Semantic Kernel.

Warning

De systeemeigen PYTHON vector store-API's zijn experimenteel. Er kunnen beperkte incompatibele wijzigingen optreden voordat deze stabiel zijn.

Kernabstracties

Abstractie Purpose
VectorStoreField en VectorStoreCollectionDefinition Beschrijf sleutel-, gegevens- en vectorvelden, waaronder opslagnamen, indexen, dimensies en afstandsfuncties.
@vectorstoremodel en register_vectorstoremodel() Registreer dataclasses, Pydantic-modellen, msgspec-structs, gewone klassen of modeltypen die extern eigendom zijn.
BaseVectorCollection en SupportsVectorUpsert Definieer batch-upsert, ophalen, verwijderen, de levenscyclus van collecties, recordconversie en optionele embeddinggeneratie.
BaseVectorStore Definieert een opslag die verzamelingen opsomt en getypeerde clients voor verzamelingen maakt.
BaseVectorSearch en SupportsVectorSearch Definieer vectorzoekopdrachten en trefwoord-hybride zoekopdrachten, paginering, filters, scoredrempels en zoekresultaten.
Filter, FilterGroup en Param Definieer draagbare, alleen gegevensfilters, inclusief door het model geleverde filterparameters voor zoekhulpprogramma's.
InMemoryStore en InMemoryCollection Ondersteunt proceslokale CRUD en lineaire zoekopdrachten via scans voor ontwikkeling en tests.
GenerateVectors Hiermee bepaalt u of upserts alle, geen of geselecteerde vectorvelden genereren.
create_vector_search_tool(), create_upsert_tool(), create_get_tool() en create_delete_tool() Stel vectorzoekopdrachten en CRUD-bewerkingen voor verzamelingen beschikbaar als functiehulpmiddelen van Agent Framework.
VectorStoreHistoryProvider Slaat gespreksgeschiedenis binnen een bepaalde scope op in een verzameling van de provider, met optionele compactie en zoeken in de volledige gespreksgeschiedenis.
VectorCollectionContextProvider Hiermee worden configureerbare CRUD- en zoekhulpprogramma's toegevoegd voor een verzameling die eigendom is van een beller.

In het volgende voorbeeld worden records voor vectoropslag gedefinieerd door aantekeningen te maken op de sleutel, gegevens en vectorvelden:

# 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

Rechtstreeks VectorStoreCollectionDefinition gebruiken voor woordenlijsten. Gebruik voor modeltypen die eigendom zijn van een ander pakket register_vectorstoremodel() met een expliciete definitie en optionele encoder en decoder. Matrixachtige vectorwaarden serialiseren door tolist() zonder een NumPy-afhankelijkheid toe te voegen.

Agent Framework bevat een in-memory implementatie voor ontwikkeling en tests. Het slaat records op binnen het huidige proces en gebruikt een lineaire doorzoeking, dus gebruik een databaseconnector voor productieomgevingen.

In het volgende voorbeeld worden vooraf berekende vectoren opgeslagen en worden ze doorzocht met een draagbare filterstructuur:

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

Gebruik Param wanneer het model een filterwaarde moet opgeven. Het Python type, beschrijving en beperkingen worden onderdeel van het JSON-schema van het zoekprogramma:

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

Een vectorverzameling gebruiken met een agent

Gebruik VectorCollectionContextProvider deze functie wanneer uw toepassing eigenaar is van het verzamelings- en gegevensmodel. De provider voegt gegenereerde CRUD- en zoekhulpprogramma's toe. Upsert en verwijderen vereisen standaard goedkeuring, terwijl opvragen en zoeken dat niet doen.

Geef scope_filter door om records te groeperen voor de gegenereerde tools, maar beschouw het filter niet als een autorisatiegrens of atomaire backendgarantie. Zoekhulpmiddelen die via additional_search_tools worden doorgegeven, behouden hun eigen filters, dus pas een gelijkwaardig filter toe op elk aangepast hulpprogramma wanneer een verzameling wordt gedeeld.

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:

Gespreksgeschiedenis opslaan in een vectorarchief

Gebruik VectorStoreHistoryProvider deze functie wanneer de provider eigenaar moet zijn van het verzamelingsschema en automatisch Agent Framework-berichten laadt en opslaat. De bijbehorende toepassings-, tenant-, agent-, bron- en sessie-id's voorkomen onbedoelde overlapping, maar uw toepassing moet nog steeds toegang verlenen en de juiste opslagreferenties of naamruimten binnen het bereik gebruiken.

Wanneer u insluitingen configureert, geeft u een expliciete verzamelingsnaam en de insluitingsdimensies op. Compactie vermindert alleen de geschiedenis die in de modelcontext wordt geladen. Als u het zoekprogramma inschakelt, wordt in het volledige bereik van het transcript gezocht.

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:

Native Agent Framework implementaties

De volgende implementaties maken gebruik van de systeemeigen Agent Framework-contracten. Sommige zijn ook beschikbaar als afzonderlijke Semantic Kernel connectors, maar de twee connectorfamilies zijn niet uitwisselbaar.

Implementation Agent Framework-pakket en levenscyclus Afzonderlijke Semantic Kernel-connector Zoekmodi Belangrijke beperkingen
In het geheugen agent-framework-core; uitgebracht pakket met experimentele vector-API's beschikbaar Compacte vector met draagbare filters Procesgebonden lineaire scan voor ontwikkeling en tests, niet een productiedatabase.
Azure AI Zoeken agent-framework-azure-ai-search; bètapakket met experimentele vector-API's beschikbaar Hybride van dichte vectoren en trefwoorden Eén dicht vectorveld op het hoogste niveau per query. Voor sommige drempelwaarden, besturingselementen voor hybride tekstherhaling, strikte nafiltering en machtigingen is een ondersteunende preview-SDK/API vereist en allow_preview=True.
Azure Cosmos DB voor NoSQL agent-framework-azure-cosmos; bètapakket met experimentele vector-API's beschikbaar Compacte vector met draagbare filters Sleutels moeten tekenreeksen zijn die zijn opgeslagen als iden containers gebruiken de /id partitiesleutel. Trefwoorden en hybride zoekopdrachten worden niet ondersteund en Zoekopdrachten in Euclidean bieden geen ondersteuning voor scoredrempels.
Azure DocumentDB agent-framework-azure-documentdb; alfapakket Niet beschikbaar Compacte vector met draagbare metagegevensfilters Sleutels moeten tekenreeksen of gehele getallen zijn. Gegenereerde ObjectIds, hybride zoekopdrachten, volledige-tekstzoekopdrachten en geneste filterpaden worden niet ondersteund.
MongoDB agent-framework-mongodb; alfapakket beschikbaar Geschatte of exacte compacte vector met draagbare filters Vereist PyMongo 4.13.2+ en een implementatie met MongoDB Vector Search. Zoeken op trefwoorden en hybride zoekopdrachten, geneste filterpaden, door de provider uitgevoerde embeddinggeneratie en automatische schemamigratie worden niet ondersteund.
PostgreSQL met pgvector agent-framework-postgres; alfapakket beschikbaar Exacte dichte vector, HNSW en IVFFlat Vereist PostgreSQL 13+, pgvector 0.8.0+, een bestaand schema en de ingeschakelde extensie. Trefwoorden en hybride zoekopdrachten worden niet ondersteund.
Qdrant agent-framework-qdrant; alfapakket beschikbaar Compacte vector met draagbare filters aan de serverzijde Voor de servermodus is Qdrant 1.16.2+ vereist. Sleutels moeten niet-ondertekende 64-bits gehele getallen of UUID's zijn. Trefwoorden en hybride zoekopdrachten worden niet ondersteund en filters zijn niet beschikbaar in de lokale SDK-modus.
Redis agent-framework-redis; bètapakket met experimentele vector-API's beschikbaar Dichte vector voor HASH- of JSON-records Vereist Redis 8.0.3+ met Zoeken; Voor JSON-records is ook RedisJSON vereist. Redis Cluster, trefwoorden zoeken en hybride zoeken worden niet ondersteund.

Installeer een prerelease-connectorpakket voor de database die u gebruikt:

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-mongodb --pre
pip install agent-framework-postgres --pre
pip install agent-framework-qdrant --pre
pip install agent-framework-redis --pre

Installeert op Python 3.10 tot en met 3.14 de agent-framework-postgres binaire distributie van Psycopg. Op Python 3.15 of hoger wordt gebruikgemaakt van pure Python Psycopg omdat compatibele binaire wielen niet worden gepubliceerd, dus moet de host een systeeminstallatie libpq leveren.

Elke connector implementeert het algemene model, verzameling, CRUD, filter en zoekcontracten. Databasespecifieke mogelijkheden en beperkingen zijn nog steeds van toepassing. Zie de voorbeelden Azure AI Zoeken, MongoDB, Postgres, Qdrant en Redis voor volledige voorbeelden.

Implementaties die alleen Semantic Kernel gebruiken

Toepassingen kunnen de Python-vectoropslag van Semantic Kernel rechtstreeks blijven gebruiken. Deze implementaties maken gebruik van de afzonderlijke Semantic Kernel vector store-contracten in plaats van de systeemeigen Agent Framework-contracten. De volgende implementaties hebben momenteel geen systeemeigen Agent Framework-connector:

Implementation Availability Maakt gebruik van een officieel ondersteunde database-SDK Onderhouder of leverancier
Azure Cosmos DB voor MongoDB vCore Beschikbaar Yes Microsoft Semantic Kernel project
Chroma Beschikbaar Yes Microsoft Semantic Kernel project
Elasticsearch Gepland Niet van toepassing Niet van toepassing
Faiss Beschikbaar Yes Microsoft Semantic Kernel project
Neon Serverless Postgres De Postgres-implementatie gebruiken Yes Microsoft Semantic Kernel project
Oracle Beschikbaar Yes Oracle
Dennenappel Beschikbaar Yes Microsoft Semantic Kernel project
SQL Server Beschikbaar pyodbc Microsoft Semantic Kernel project
SQLite Gepland Niet van toepassing Microsoft Semantic Kernel project
Weaviate Beschikbaar Yes Microsoft Semantic Kernel project

Important

Vector Store-implementaties zijn afkomstig van meerdere onderhouders. Evalueer de kwaliteit, licentieverlening, ondersteuningsbeleid en versiecompatibiliteit van elke implementatie voordat u deze gebruikt.

Een implementatie gebruiken die alleen Semantic Kernel gebruikt

  1. Installeer semantic-kernel en de afhankelijkheden die vereist zijn voor de door u gekozen implementatie.
  2. Definieer een model met de @vectorstoremodel decorator en identificeer de sleutel-, gegevens- en vectorvelden.
  3. Maak een implementatiespecifieke verzameling voor dat model.
  4. Zorg ervoor dat de verzameling bestaat en voeg vervolgens records in of werk ze bij.
  5. Gebruik de zoek-API's van de verzameling om records voor uw toepassing op te halen.

Zie Semantic Kernel Vector Stores voor het instellen van de implementatie en volledige voorbeelden.

Ondersteuning voor Go Vector Store

Vector Store-integratie is nog niet beschikbaar in Agent Framework voor Go. Zie de opslagplaats Agent Framework Go voor de meest recente status.

Volgende stappen 

RAG toevoegen aan een agent

  • Last updated on