Integrazioni con database vettoriali

supporto per gli archivi vettoriali in .NET

Agent Framework usa le astrazioni autonome dell'ecosistema di intelligenza artificiale .NET:

• Microsoft.Extensions.VectorData fornisce API di archiviazione vettoriale, raccolta, record e ricerca comuni.
• Microsoft.Extensions.AI fornisce astrazioni, IEmbeddingGenerator ad esempio per la generazione di incorporamenti indipendentemente da un provider di modelli specifico.

Se un componente di Agent Framework accetta un archivio vettoriale, è possibile fornire un'implementazione compatibile Microsoft.Extensions.VectorData . Ogni implementazione del database viene distribuita separatamente dal pacchetto di astrazioni.

Astrazioni di base

Implementazioni dell'archivio vettoriale disponibili

Le implementazioni seguenti usano le astrazioni comuni .NET dell'archivio vettoriale. Esaminare la documentazione di ogni implementazione per le versioni dei pacchetti, i tipi di dati supportati e le limitazioni specifiche del servizio.

Get started

1. Aggiungi il Pacchetto Microsoft.Extensions.VectorData.Abstractions e pacchetto per l'implementazione dell'archivio di vettori scelto.
2. Definire un tipo di record e identificarne la chiave, i dati e le proprietà vettoriali.
3. Configurare un'IEmbeddingGenerator se l'implementazione richiede embedding generati dall'applicazione.
4. Creare l'elemento VectorStore dell'implementazione e quindi ottenere un VectorStoreCollection<TKey, TRecord> tipizzato.
5. Assicurati che la raccolta esista, esegui l'upsert dei record e chiama SearchAsync con testo o un vettore.

Per un'introduzione completa ai modelli di dati, all'inserimento, agli incorporamenti e alla ricerca, vedere Database vettoriali per le app di intelligenza artificiale .NET.

supporto dell'archivio vettoriale Python

Agent Framework offre contratti sperimentali, nativi Python per modelli di archivio vettoriale, operazioni di raccolta, factory di archiviazione, ricerca ibrida di vettori e parole chiave e strumenti di ricerca degli agenti. I contratti fanno parte di agent-framework-core e non richiedono Pydantic, NumPy, pandas o Kernel semantico.

Astrazioni di base

L'esempio seguente definisce i record dell'archivio vettoriale annotando i relativi campi chiave, dati e vettore:

# 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

Usare VectorStoreCollectionDefinition direttamente per i dizionari. Per i tipi di modello di proprietà di un altro pacchetto, usare register_vectorstoremodel() con una definizione esplicita e un codificatore e decodificatore facoltativo. I valori vettoriali simili a matrice vengono serializzati tramite tolist() senza aggiungere una dipendenza NumPy.

Agent Framework include un'implementazione in memoria per lo sviluppo e i test. Archivia i record nel processo corrente e usa un'analisi lineare, quindi usa un connettore di database per i carichi di lavoro di produzione.

L'esempio seguente archivia i vettori pre-calcolati e li cerca con un albero di filtro portabile:

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

Usare Param quando il modello deve fornire un valore di filtro. Il suo tipo Python, la descrizione e i vincoli diventano parte dello schema JSON dello strumento di ricerca:

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

Usare una raccolta vettoriale con un agente

Usare VectorCollectionContextProvider quando l'applicazione è proprietaria della raccolta e del modello di dati. Il provider aggiunge strumenti CRUD e di ricerca generati. Upsert ed eliminazione richiedono l'approvazione per impostazione predefinita, mentre get e ricerca no.

Passa scope_filter per raggruppare i record per i tool generati, ma non considerare il filtro come un confine di autorizzazione o una garanzia di atomicità del backend. Gli strumenti di ricerca trasmessi tramite additional_search_tools mantengono i propri filtri, quindi applica un filtro equivalente a ogni strumento personalizzato quando si condivide una raccolta.

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:

Archiviare la cronologia delle conversazioni in un archivio vettoriale

Usare VectorStoreHistoryProvider quando il provider deve possedere lo schema di raccolta e caricare e salvare automaticamente i messaggi di Agent Framework. Gli identificatori dell'applicazione, del tenant, dell'agente, dell'origine e della sessione evitano sovrapposizioni accidentali, ma la tua applicazione deve comunque autorizzare gli accessi e usare credenziali dell'archivio o namespace con ambito appropriato.

Quando si configurano gli incorporamenti, specificare un nome di raccolta esplicito e le dimensioni di incorporamento. La compattazione riduce solo la cronologia caricata nel contesto del modello. Se si attiva lo strumento di ricerca, la ricerca viene eseguita nell'intera trascrizione inclusa nell'ambito.

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:

Implementazioni di Native Agent Framework

Le implementazioni seguenti usano i contratti native di Agent Framework. Alcuni sono disponibili anche come connettori Kernel semantico separati, ma le due famiglie di connettori non sono intercambiabili.

Installare un pacchetto del connettore in versione preliminare per il database in uso:

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

Ogni connettore implementa il modello comune, la raccolta, CRUD, il filtro e i contratti di ricerca. Le funzionalità e le restrizioni specifiche del database sono ancora valide. Per esempi completi, vedere gli esempi di Azure AI Search, MongoDB, Postgres, Qdrant e Redis.

Implementazioni esclusivamente basate su Kernel semantico

Le applicazioni possono continuare a usare direttamente gli archivi vettoriali Python di Kernel semantico. Queste implementazioni usano i contratti di archiviazione vettoriale Kernel semantico separati anziché i contratti di Agent Framework nativi. Le implementazioni seguenti non hanno attualmente un connettore nativo di Agent Framework:

Usare un'implementazione basata esclusivamente su Kernel semantico

1. Installare semantic-kernel e le dipendenze richieste dall'implementazione scelta.
2. Definire un modello con l'elemento @vectorstoremodel Decorator e identificarne la chiave, i dati e i campi vettoriali.
3. Crea una raccolta specifica per l'implementazione per quel modello.
4. Assicurati che la raccolta esista, quindi aggiorna o inserisci i record.
5. Usare le API di ricerca della raccolta per recuperare i record per l'applicazione.

Per l'installazione dell'implementazione e esempi completi, vedere Kernel semantico Vector Stores.

Supporto dell'archivio di vettori Go

L'integrazione con l'archivio vettoriale non è ancora disponibile in Agent Framework for Go. Vedere il repository di Agent Framework Go per lo stato più aggiornato.