Integrações de repositório de vetores

Os repositórios de vetores mantêm os dados e suas inserções de vetor juntos para que os aplicativos possam encontrar registros por similaridade semântica. Em aplicativos do Agent Framework, você pode usar repositórios de vetores para recuperar dados de aterramento para RAG (Geração Aumentada de Recuperação) ou para armazenar informações que um agente pode recuperar mais tarde.

As abstrações do repositório de vetores fornecem operações comuns para coleções e registros, mantendo a lógica do aplicativo separada da implementação específica do repositório de vetores. Você pode, por exemplo, começar com uma implementação local e mudar para um serviço gerenciado com alterações mínimas.

Como funcionam as integrações do repositório de vetores

Um fluxo de trabalho típico do repositório de vetores inclui estas etapas:

  1. Defina um modelo de dados que identifique a chave de registro, os campos de dados e os campos de vetor.
  2. Configure um gerador de inserção se o repositório de vetores não gerar inserções.
  3. Conecte-se a um repositório de vetores e selecione ou crie uma coleção.
  4. Gere inserções e registros upsert na coleção.
  5. Pesquise a coleção com texto ou um vetor, dependendo dos recursos da implementação.
  6. Passe resultados de pesquisa relevantes para um agente como contexto ou exponha a pesquisa como uma ferramenta do agente.

.NET suporte ao repositório de vetores

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

Quando um componente do Agent Framework aceita um repositório de vetores, você pode fornecer uma implementação compatível Microsoft.Extensions.VectorData . Cada implementação de banco de dados é distribuída separadamente do pacote de abstrações.

Abstrações principais

Abstração Purpose
VectorStore Fornece operações em coleções e cria instâncias tipadas de coleção.
VectorStoreCollection<TKey, TRecord> Cria ou exclui uma coleção e insere ou atualiza, recupera ou exclui seus registros.
IVectorSearchable<TRecord> Pesquisa registros por vetor ou por texto quando um gerador de inserção ou funcionalidade de inserção do lado do banco de dados está disponível.

Implementações de repositório de vetores disponíveis

As implementações a seguir usam as abstrações comuns do repositório de vetores .NET. Examine a documentação de cada implementação para versões de pacote, tipos de dados compatíveis e limitações específicas do serviço.

Implementation Availability Usa um SDK de banco de dados com suporte oficial 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 Planejado Não aplicável Não aplicável
Na memória Available Não aplicável Microsoft
Milvus Planejado Não aplicável Não aplicável
MongoDB Available Sim Microsoft
Postgres Sem Servidor Neon Usar a implementação do Postgres Sim Microsoft
Oracle Available Sim Oracle
Pinecone 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 Obsoleto; use a implementação em memória Não aplicável Microsoft
Weaviate Available Sim Microsoft

Importante

As implementações do repositório vetor vêm de vários mantenedores. Avalie a qualidade, o licenciamento, a política de suporte e a compatibilidade de versão de cada implementação antes de usá-la. Algumas implementações usam SDKs de banco de dados que o provedor de banco de dados não dá suporte oficialmente.

Introdução

  1. Adicionar o Microsoft.Extensions.VectorData.Abstractions e o pacote para a implementação do repositório de vetores escolhido.
  2. Defina um tipo de registro e identifique suas propriedades de chave, dados e vetor.
  3. Configure um IEmbeddingGenerator caso sua implementação exija inserções geradas pelo aplicativo.
  4. Crie VectorStore da implementação e, depois, obtenha um VectorStoreCollection<TKey, TRecord> com tipo.
  5. Verifique se a coleção existe, faça upsert dos registros e chame SearchAsync com texto ou com um vetor.

Para obter uma introdução completa a modelos de dados, ingestão, inserções e pesquisa, consulte bancos de dados vetoriais para .NET aplicativos de IA.

Suporte a armazenamento vetorial em Python

O Agent Framework fornece contratos experimentais de Python nativos para modelos de repositório de vetores, operações de coleção, fábricas de repositórios, pesquisa vetor e de palavra-chave híbrida e ferramentas de pesquisa de agente. Os contratos fazem parte agent-framework-core e não exigem Pydantic, NumPy, pandas ou Kernel semântico.

Aviso

As APIs nativas do repositório de vetores Python são experimentais. Alterações significativas limitadas podem ocorrer antes de se tornarem estáveis.

Abstrações principais

Abstração Purpose
VectorStoreField e VectorStoreCollectionDefinition Descreva campos de chave, dados e vetores, incluindo nomes de armazenamento, índices, dimensões e funções de distância.
@vectorstoremodel e register_vectorstoremodel() Registre classes de dados, modelos Pydantic, estruturas msgspec, classes simples ou tipos de modelo pertencentes a terceiros.
BaseVectorCollection e SupportsVectorUpsert Defina upsert, get, delete, ciclo de vida da coleção, conversão de registro e geração de inserção opcional.
BaseVectorStore Define uma loja que lista coleções e cria clientes tipados de coleção.
BaseVectorSearch e SupportsVectorSearch Defina a pesquisa vetorial e a pesquisa híbrida por vetor e palavra-chave, paginação, filtros, limiares de pontuação e resultados da pesquisa.
Filter, FilterGroup e Param Defina filtros portáteis somente de dados, incluindo parâmetros de filtro fornecidos por modelo para ferramentas de pesquisa.
InMemoryStore e InMemoryCollection Oferece CRUD local ao processo e busca por varredura linear para desenvolvimento e testes.
GenerateVectors Controla se os upserts geram todos, nenhum ou campos de vetor selecionados.
create_vector_search_tool(), create_upsert_tool(), create_get_tool()e create_delete_tool() Expor operações CRUD de pesquisa e coleção de vetores como ferramentas de função do Agent Framework.
VectorStoreHistoryProvider Armazena o histórico de conversas com escopo definido em uma coleção pertencente ao provedor, com compactação opcional e pesquisa em todo o histórico.
VectorCollectionContextProvider Adiciona ferramentas configuráveis de CRUD e busca para uma coleção pertencente ao chamador.

O exemplo a seguir define os registros de repositório de vetores anotando seus campos de chave, dados e vetor:

# 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 codificador e decodificador opcionais. Valores vetoriais do tipo array são serializados por meio de tolist(), sem adicionar uma dependência do NumPy.

O Agent Framework inclui uma implementação na memória para desenvolvimento e testes. Ele armazena registros na memória do processo atual e usa uma varredura linear, por isso, use um conector de banco de dados para cargas de trabalho de produção.

O exemplo a seguir armazena vetores pré-compilados e os pesquisa com uma árvore de filtro 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. Seu tipo de Python, descrição e restrições 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}."
    ),
)

Usar uma coleção de vetores com um agente

Use VectorCollectionContextProvider quando seu aplicativo possui a coleção e o modelo de dados. O provedor adiciona ferramentas de CRUD e busca geradas. Upsert e delete exigem aprovação por padrão, enquanto get e search não.

Passe scope_filter para agrupar registros para as ferramentas geradas, mas não trate o filtro como uma fronteira de autorização ou uma garantia atômica de back-end. As ferramentas de pesquisa transmitidas por additional_search_tools mantêm seus próprios filtros, portanto aplique um filtro equivalente a cada ferramenta personalizada ao compartilhar uma coleção.

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 em um repositório de vetores

Use VectorStoreHistoryProvider quando o provedor deve possuir o esquema de coleção e carregar e salvar automaticamente mensagens do Agent Framework. Seus identificadores de aplicação, locatário, agente, origem e sessão evitam sobreposição acidental, mas sua aplicação ainda deve autorizar o acesso e usar credenciais ou namespaces de armazenamento com escopo apropriado.

Ao configurar inserções, forneça um nome de coleção explícito e as dimensões de inserção. A compactação reduz apenas o histórico carregado no contexto do modelo. Se você habilitar a ferramenta de pesquisa, ela pesquisará a transcrição de escopo completo.

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 a seguir usam 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 Separar conector do Kernel semântico Modos de pesquisa Principais limitações
Na memória agent-framework-core; pacote liberado com APIs de vetor experimental Disponível Vetor denso com filtros portáteis Verificação linear local do processo para desenvolvimento e testes, não um banco de dados de produção.
Pesquisa de IA do Azure  agent-framework-azure-ai-search; pacote beta com APIs de vetor experimental Disponível Vetor denso e palavra-chave híbrida Um campo de vetor denso de nível superior por consulta. Alguns limites, controles híbridos de recuperação de texto, pós-filtragem rigorosa e permissões exigem um SDK/API de versão prévia com suporte e allow_preview=True.
Azure Cosmos DB for NoSQL agent-framework-azure-cosmos; pacote beta com APIs de vetor experimental Disponível Vetor denso com filtros portáteis As chaves devem ser cadeias de caracteres armazenadas como ide os contêineres usam a /id chave de partição. Não há suporte para a palavra-chave e a pesquisa híbrida, e a pesquisa euclidiana não dá suporte a limites de pontuação.
Azure DocumentDB agent-framework-azure-documentdb; pacote alfa Não disponível Vetor denso com filtros de metadados portáteis As chaves devem ser cadeias de caracteres ou inteiros. Não há suporte para ObjectIds gerados, pesquisa híbrida e de texto completo e caminhos de filtro aninhados.
DuckDB agent-framework-duckdb; pacote alfa Não disponível Vetor denso exato com filtros portáveis Requer Python 3.10+ e DuckDB 1.4.1–1.5.x. Não há suporte para índices aproximados, palavra-chave e pesquisa híbrida, pesquisa de texto completo e vetorização do lado do servidor. Os arquivos locais permitem apenas um processo de gravação por vez.
MongoDB agent-framework-mongodb; pacote alfa Disponível Vetor denso aproximado ou exato com filtros portáteis Requer o PyMongo 4.13.2+ e uma implantação com a Pesquisa de Vetores do MongoDB. Pesquisa por palavra-chave e pesquisa híbrida, caminhos de filtro aninhados, geração de embeddings pelo provedor e migração automática de esquema não são compatíveis.
PostgreSQL com pgvector agent-framework-postgres; pacote alfa Disponível Vetor denso exato, HNSW e IVFFlat Requer PostgreSQL 13+, pgvector 0.8.0+, um esquema existente e a extensão habilitada. Não há suporte para a palavra-chave e a pesquisa híbrida.
Qdrant agent-framework-qdrant; pacote alfa Disponível Vetor denso com filtros portáteis do lado do servidor O modo de servidor requer qdrant 1.16.2+. As chaves devem ser inteiros de 64 bits sem sinal ou UUIDs. Não há suporte para a palavra-chave e a pesquisa híbrida e os filtros não estão disponíveis no modo SDK local.
Redis agent-framework-redis; pacote beta com APIs de vetor experimental Disponível Vetor denso sobre registros HASH ou JSON Requer Redis 8.0.3+ com Pesquisa; Os registros JSON também exigem RedisJSON. Não há suporte para o Cluster Redis, pesquisa de palavras-chave e pesquisa híbrida.
SQL Server agent-framework-sql-server; pacote alfa Disponível Vetor denso exato com filtros portáveis Requer Python 3.10–3.14 e SQL Server 2025 ou um banco de dados SQL do Azure habilitado para vetor. Não há suporte para índices aproximados, palavra-chave e pesquisa híbrida, vetorização do servidor e migração de esquema.

Instale um pacote de conector de pré-lançamento para o banco de dados que você usa:

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

No Python 3.10 a 3.14, agent-framework-postgres instala a distribuição binária do Psycopg. No Python 3.15 ou posterior, ele usa o Psycopg em Python puro porque pacotes binários compatíveis não são publicados, então o host deve fornecer uma instalação do sistema libpq.

Cada conector implementa o modelo comum, a coleção, o CRUD, o filtro e os contratos de pesquisa. As funcionalidades e restrições específicas do banco de dados ainda se aplicam. Para obter exemplos completos, consulte os exemplos Pesquisa de IA do Azure , DuckDB, MongoDB, Postgres, Qdrant, Redis e SQL Server.

Implementações apenas com Kernel semântico

Os aplicativos podem continuar a usar os repositórios de vetores Python do Kernel semântico diretamente. Essas implementações usam os contratos de repositório de vetores Kernel semântico separados em vez dos contratos nativos do Agent Framework. No momento, as seguintes implementações não têm um conector nativo do Agent Framework:

Implementation Availability Usa um SDK de banco de dados com suporte oficial Mantenedor ou fornecedor
Azure Cosmos DB para MongoDB vCore Available Sim Microsoft Kernel semântico projeto
Chroma Available Sim Microsoft Kernel semântico projeto
Elasticsearch Planejado Não aplicável Não aplicável
Faiss Available Sim Microsoft Kernel semântico projeto
Postgres Sem Servidor Neon Usar a implementação do Postgres Sim Microsoft Kernel semântico projeto
Oracle Available Sim Oracle
Pinecone Available Sim Microsoft Kernel semântico projeto
SQLite Planejado Não aplicável Microsoft Kernel semântico projeto
Weaviate Available Sim Microsoft Kernel semântico projeto

Importante

As implementações do repositório vetor vêm de vários mantenedores. Avalie a qualidade, o licenciamento, a política de suporte e a compatibilidade de versão de cada implementação antes de usá-la.

Usar uma implementação apenas com Kernel semântico

  1. Instale semantic-kernel e as dependências exigidas pela implementação escolhida.
  2. Defina um modelo com o @vectorstoremodel decorador e identifique sua chave, dados e campos de vetor.
  3. Crie uma coleção específica de implementação para esse modelo.
  4. Verifique se a coleção existe e, em seguida, faça upsert dos registros.
  5. Use as APIs de pesquisa da coleção para recuperar registros para seu aplicativo.

Para obter a configuração de implementação e exemplos completos, consulte Kernel semântico Vector Stores.

Suporte a armazenamento vetorial em Go

A integração com armazenamento vetorial ainda não está disponível no Agent Framework for Go. Consulte o repositório Agent Framework Go para obter o status mais recente.

Próximas Etapas 

Adicionar RAG a um agente

  • Last updated on