Integrações de armazenamento vetorial

Os armazenamentos vetoriais mantêm os dados e as suas incorporações vetoriais juntos para que as aplicações possam encontrar registos por similaridade semântica. Em aplicações do Agent Framework, pode utilizar repositórios vetoriais para obter dados de fundamentação para Retrieval Augmented Generation (RAG) ou para armazenar informações que um agente possa recuperar mais tarde.

As abstrações de armazenamento vetorial fornecem operações comuns para coleções e registos, mantendo a lógica da sua aplicação separada da implementação específica de armazenamento vetorial. Podes, por exemplo, começar com uma implementação local e mudar para um serviço gerido com alterações mínimas.

Como funcionam as integrações de armazenamento vetorial

Um fluxo de trabalho típico de armazenamento vetorial inclui estes passos:

  1. Defina um modelo de dados que identifique a chave de registo, os campos de dados e os campos vetoriais.
  2. Configure um gerador de embeddings se o armazenamento vetorial não gerar embeddings.
  3. Ligue-se a uma loja vetorial e selecione ou crie uma coleção.
  4. Gerar incorporações vetoriais e fazer upsert de registos na coleção.
  5. Pesquise a coleção com texto ou vetor, dependendo das capacidades da implementação.
  6. Transmitir resultados relevantes da pesquisa a um agente como contexto ou expor a pesquisa como uma ferramenta do agente.

Suporte a armazenamento vetorial .NET

O Agent Framework utiliza as abstrações autónomas do ecossistema de IA .NET:

Quando um componente do Agent Framework aceita um armazenamento vetorial, pode fornecer uma implementação compatível Microsoft.Extensions.VectorData . Cada implementação de base de dados é distribuída separadamente do pacote de abstrações.

Abstrações centrais

Abstração Purpose
VectorStore Fornece operações em coleções e cria instâncias de coleções com tipo definido.
VectorStoreCollection<TKey, TRecord> Cria ou apaga uma coleção e atualiza, recupera ou apaga os seus registos.
IVectorSearchable<TRecord> Pesquisa registos por vetor ou por texto quando estiver disponível um gerador de embeddings ou uma capacidade de embeddings na base de dados.

Implementações disponíveis de armazenamento vetorial

As implementações seguintes utilizam as abstrações comuns de armazenamento vetorial .NET. Revise a documentação de cada implementação para versões de pacotes, tipos de dados suportados e limitações específicas do serviço.

Implementation Availability Utiliza um SDK de base de dados oficialmente suportado Mantenedor ou fornecedor
Pesquisa de IA do Azure Available Sim Microsoft
Azure Cosmos DB para MongoDB vCore Available Sim Microsoft
Azure Cosmos DB para NoSQL Available Sim Microsoft
Couchbase Available Sim Couchbase
Elasticsearch Available Sim Elastic
Chroma Planeado Não aplicável Não aplicável
Em memória Available Não aplicável Microsoft
Milvus Planeado Não aplicável Não aplicável
MongoDB Available Sim Microsoft
Neon Serverless Postgres Usar a implementação do Postgres Sim Microsoft
Oracle Available Sim Oracle
Pinha Available No Microsoft
Postgres Available Sim Microsoft
Qdrant Available Sim Microsoft
Redis Available Sim Microsoft
SQL Server Available Sim Microsoft
SQLite Available Sim Microsoft
Volátil na memória Descontinuado; usar a implementação em memória Não aplicável Microsoft
Weaviate Available Sim Microsoft

Importante

As implementações de armazenamento vetorial vêm de múltiplos mantenedores. Avalie a qualidade de cada implementação, licenciamento, política de suporte e compatibilidade de versões antes de a utilizar. Algumas implementações usam SDKs de base de dados que o fornecedor da base de dados não suporta oficialmente.

Introdução

  1. Adiciona o Microsoft.Extensions.VectorData.Abstractions pacote e o pacote para a implementação de armazenamento vetorial escolhida.
  2. Defina um tipo de registo e identifique as suas propriedades de chave, dados e vetor.
  3. Configura uma IEmbeddingGenerator se a tua implementação exigir embeddings gerados pela aplicação.
  4. Crie o VectorStore da implementação e, em seguida, obtenha um VectorStoreCollection<TKey, TRecord> fortemente tipado.
  5. Certifique-se de que a coleção existe, insira ou atualize registos e chame SearchAsync com texto ou um vetor.

Para uma introdução completa a modelos de dados, ingestão, embeddings e pesquisa, consulte bases de dados vetoriais para aplicações de IA .NET.

Suporte a armazenamento vetorial em Python

O Agent Framework fornece contratos experimentais e nativos em Python para modelos de armazenamento vetorial, operações de coleção, fábricas de armazenamento, pesquisa vetorial e híbrida-palavra-chave, e ferramentas de pesquisa de agentes. Os contratos fazem parte de agent-framework-core e não requerem Pydantic, NumPy, pandas ou Kernel Semântico.

Advertência

As APIs nativas de armazenamento vetorial em Python são experimentais. Alterações limitadas de quebra podem ocorrer antes de se tornarem estáveis.

Abstrações centrais

Abstração Purpose
VectorStoreField e VectorStoreCollectionDefinition Descreva campos-chave, dados e vetores, incluindo nomes de armazenamento, índices, dimensões e funções de distância.
@vectorstoremodel e register_vectorstoremodel() Registe classes de dados, modelos Pydantic, estruturas do msgspec, classes simples ou tipos de modelos pertencentes a entidades externas.
BaseVectorCollection e SupportsVectorUpsert Define upsert em lote, obtenção, eliminação, ciclo de vida da coleção, conversão de registos e geração opcional de embedding.
BaseVectorStore Define uma loja que lista coleções e cria clientes de coleções tipadas.
BaseVectorSearch e SupportsVectorSearch Defina pesquisa vetorial e híbrida por palavra-chave, paginação, filtros, limiares de pontuação e resultados de pesquisa.
Filter, FilterGroupe Param Defina filtros portáteis, apenas para dados, incluindo parâmetros de filtro fornecidos pelo modelo para ferramentas de pesquisa.
InMemoryStore e InMemoryCollection Fornecer CRUD local de processos e pesquisa linear para desenvolvimento e testes.
GenerateVectors Controla se os upserts geram todos, nenhum ou campos vetoriais selecionados.
create_vector_search_tool(), create_upsert_tool(), create_get_tool()e create_delete_tool() Expor operações de pesquisa vetorial e recolha CRUD como ferramentas de função do Agent Framework.
VectorStoreHistoryProvider Armazena o histórico de conversas delimitado por âmbito numa coleção do fornecedor, com compactação opcional e pesquisa em todo o histórico.
VectorCollectionContextProvider Adiciona CRUD configurável e ferramentas de pesquisa para uma coleção propriedade do chamador.

O exemplo seguinte define registos de armazenamento vetorial anotando as suas chaves, dados e campos vetoriais:

# 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

Use VectorStoreCollectionDefinition diretamente para dicionários. Para tipos de modelo pertencentes a outro pacote, use register_vectorstoremodel() com uma definição explícita e um codificador e um descodificador opcionais. Valores vetoriais do tipo array são serializados através de tolist() sem adicionar uma dependência de NumPy.

O Agent Framework inclui uma implementação em memória para desenvolvimento e testes. Armazena registos no processo atual e utiliza uma varredura linear, por isso usa um conector de base de dados para cargas de trabalho de produção.

O exemplo seguinte armazena vetores pré-computados e pesquisa-os com uma árvore de filtros portátil:

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

Use Param quando o modelo deve fornecer um valor de filtro. O seu tipo, descrição e restrições em Python tornam-se parte do esquema JSON da ferramenta de pesquisa:

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

Utilize uma coleção de vetores com um agente

Use VectorCollectionContextProvider quando a sua aplicação for proprietária da coleção e do modelo de dados. O fornecedor adiciona ferramentas CRUD e de pesquisa geradas. Upsert e delete exigem aprovação por predefinição, enquanto get e search não.

Passe scope_filter para agrupar registos das ferramentas geradas, mas não trate o filtro como um limite de autorização ou uma garantia atómica do backend. As ferramentas de pesquisa transmitidas através de additional_search_tools mantêm os seus próprios filtros, por isso, aplique um filtro equivalente a cada ferramenta personalizada quando uma coleção é partilhada.

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:

Armazenar o histórico de conversas numa loja vetorial

Use VectorStoreHistoryProvider quando o fornecedor deve ser proprietário do esquema de recolha e carregar e guardar automaticamente as mensagens do Agent Framework. Os identificadores de aplicação, inquilino, agente, origem e sessão evitam sobreposições acidentais, mas a sua aplicação deve ainda autorizar o acesso e usar credenciais de armazenamento ou namespaces devidamente definidos.

Ao configurar as incorporações, forneça um nome de coleção explícito e as dimensões das incorporações. A compactação reduz apenas o histórico carregado no contexto do modelo. Se ativar a ferramenta de pesquisa, esta pesquisa toda a transcrição no âmbito definido.

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:

Implementações do Native Agent Framework

As implementações seguintes utilizam os contratos nativos do Agent Framework. Alguns também estão disponíveis como conectores Kernel Semântico separados, mas as duas famílias de conectores não são intercambiáveis.

Implementation Pacote e ciclo de vida do Agent Framework Conector separado do Kernel Semântico Modos de pesquisa Principais limitações
Dentro da memória agent-framework-core; pacote lançado com APIs vetoriais experimentais Disponível Vetor denso com filtros portáteis Varredura linear local de processos para desenvolvimento e testes, não uma base de dados de produção.
Pesquisa de IA do Azure agent-framework-azure-ai-search; pacote beta com APIs vetoriais experimentais Disponível Vetor denso e híbrido de palavra-chave Um campo vetorial denso de topo por consulta. Alguns limiares, controlos híbridos de recuperação de texto, pós-filtragem rigorosa e permissões requerem uma SDK/API de pré-visualização compatível e allow_preview=True.
Azure Cosmos DB for NoSQL agent-framework-azure-cosmos; pacote beta com APIs vetoriais experimentais Disponível Vetor denso com filtros portáteis As chaves devem ser strings armazenadas como id, e os contentores usam a /id chave de partição. A pesquisa por palavras-chave e a pesquisa híbrida não são suportadas, e a pesquisa euclidiana não suporta limiares de pontuação.
Azure DocumentDB agent-framework-azure-documentdb; Pacote Alpha Não disponível Vetor denso com filtros de metadados portáteis As chaves têm de ser cadeias de caracteres ou números inteiros. ObjectIds gerados, pesquisa híbrida e pesquisa de texto completo e caminhos de filtro aninhados não são suportados.
MongoDB agent-framework-mongodb; Pacote Alpha Disponível Vetor denso aproximado ou exato com filtros portáteis Requer o PyMongo 4.13.2+ e uma implementação com Pesquisa Vetorial do MongoDB. A pesquisa por palavras-chave e a pesquisa híbrida, os caminhos de filtros aninhados, a geração de incorporações no lado do fornecedor e a migração automática de esquemas não são suportadas.
PostgreSQL com pgvector agent-framework-postgres; Pacote Alpha Disponível Vetor denso exato, HNSW e IVFFlat Requer PostgreSQL 13+, pgvector 0.8.0+, um esquema existente e a extensão ativada. A pesquisa por palavras-chave e a pesquisa híbrida não são suportadas.
Qdrant agent-framework-qdrant; Pacote Alpha Disponível Vetor denso com filtros portáteis do lado do servidor O modo servidor requer Qdrant 1.16.2+. As chaves devem ser inteiros de 64 bits sem sinal ou UUIDs. A pesquisa por palavras-chave e a pesquisa híbrida não são suportadas, e os filtros não estão disponíveis no modo SDK local.
Redis agent-framework-redis; pacote beta com APIs vetoriais experimentais Disponível Vetor denso sobre registos HASH ou JSON Requer Redis 8.0.3+ com Pesquisa; Os registos JSON também requerem RedisJSON. Redis Cluster, pesquisa por palavras-chave e pesquisa híbrida não são suportados.

Instale um pacote de conectores pré-lançamento para a base de dados que utiliza:

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

No Python 3.10 a 3.14, agent-framework-postgres instala-se a distribuição binária do Psycopg. Em Python 3.15 ou posterior, utiliza Psycopg puramente em Python porque as rodas binárias compatíveis não são publicadas, pelo que o host tem de fornecer uma instalação do sistemalibpq.

Cada conector implementa os contratos comuns de modelo, coleção, CRUD, filtro e pesquisa. As capacidades e restrições específicas da base de dados continuam a aplicar-se. Para exemplos completos, veja os exemplos do Pesquisa de IA do Azure, MongoDB,Postgres, Qdrant e Redis.

Implementações exclusivamente com Kernel Semântico

As aplicações podem continuar a usar diretamente as memórias vetoriais Python do Kernel Semântico. Estas implementações utilizam os contratos separados de armazenamento vetorial do Kernel Semântico em vez dos contratos nativos do Agent Framework. As seguintes implementações não possuem atualmente um conector nativo de Agent Framework:

Implementation Availability Utiliza um SDK de base de dados oficialmente suportado Mantenedor ou fornecedor
Azure Cosmos DB para MongoDB vCore Available Sim Microsoft Kernel Semântico projeto
Cromo Available Sim Microsoft Kernel Semântico projeto
Elasticsearch Planeado Não aplicável Não aplicável
Faiss Available Sim Microsoft Kernel Semântico projeto
Neon Serverless Postgres Usar a implementação do Postgres Sim Microsoft Kernel Semântico projeto
Oracle Available Sim Oracle
Pinha Available Sim Microsoft Kernel Semântico projeto
SQL Server Available pyodbc Microsoft Kernel Semântico projeto
SQLite Planeado Não aplicável Microsoft Kernel Semântico projeto
Weaviate Available Sim Microsoft Kernel Semântico projeto

Importante

As implementações de armazenamento vetorial vêm de múltiplos mantenedores. Avalie a qualidade de cada implementação, licenciamento, política de suporte e compatibilidade de versões antes de a utilizar.

Use uma implementação apenas com o Kernel Semântico

  1. Instalar semantic-kernel e as dependências exigidas pela implementação que escolheste.
  2. Defina um modelo com o @vectorstoremodel decorador e identifique a sua chave, dados e campos vetoriais.
  3. Crie uma coleção específica para a implementação desse modelo.
  4. Certifique-se de que a coleção existe e, em seguida, atualize ou insira os registos.
  5. Use as APIs de pesquisa da coleção para recuperar registos da sua aplicação.

Para configuração da implementação e exemplos completos, veja Kernel Semântico Vector Stores.

Suporte para armazenamento vetorial em Go

A integração com a Vector Store ainda não está disponível no Agent Framework for Go. Consulte o repositório Agent Framework Go para o estado mais recente.

Passos seguintes

Adicionar RAG a um agente

  • Last updated on