Integrering av vektorlager

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

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.

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.

Kärnabstraktioner

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.

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:

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.