Integraciones con bases de datos vectoriales

Los almacenes de vectores mantienen los datos y sus incrustaciones vectoriales juntas para que las aplicaciones puedan encontrar registros por similitud semántica. En las aplicaciones de Agent Framework, puede usar almacenes de vectores para recuperar datos de base para la generación aumentada de recuperación (RAG) o para almacenar información que un agente pueda recuperar más adelante.

Las abstracciones de almacén de vectores proporcionan operaciones comunes para colecciones y registros, lo que mantiene la lógica de la aplicación separada de la implementación del almacén de vectores específico. Por ejemplo, puede empezar con una implementación local y cambiar a un servicio administrado con cambios mínimos.

Funcionamiento de las integraciones de almacén de vectores

Un flujo de trabajo de almacén de vectores típico incluye estos pasos:

  1. Defina un modelo de datos que identifique la clave de registro, los campos de datos y los campos vectoriales.
  2. Configure un generador de incrustaciones si el almacén de vectores no genera incrustaciones.
  3. Conéctese a un almacén de vectores y seleccione o cree una colección.
  4. Generar embeddings e insertar o actualizar registros en la colección.
  5. Busque la colección con texto o vector, en función de las funcionalidades de la implementación.
  6. Pasar los resultados de búsqueda relevantes como contexto para un agente o poner la búsqueda a disposición del agente como herramienta.

soporte para almacén vectorial de .NET

Agent Framework usa las abstracciones independientes del ecosistema de inteligencia artificial de .NET:

  • Microsoft.Extensions.VectorData proporciona API comunes para almacén vectorial, colección, registro y búsqueda.
  • Microsoft.Extensions.AI proporciona abstracciones como IEmbeddingGenerator para generar incrustaciones independientemente de un proveedor de modelos específico.

Cuando un componente de Agent Framework acepta un almacén de vectores, puede proporcionar una implementación Microsoft.Extensions.VectorData compatible. Cada implementación de base de datos se distribuye por separado del paquete de abstracciones.

Abstracciones principales

Abstracción propósito
VectorStore Proporciona operaciones en varias colecciones y crea instancias tipadas de colecciones.
VectorStoreCollection<TKey, TRecord> Crea o elimina una colección e inserta, actualiza, recupera o elimina sus registros.
IVectorSearchable<TRecord> Busca registros por vector o por texto cuando hay disponible un generador de inserción o una funcionalidad de inserción en el lado de la base de datos.

Implementaciones de almacén de vectores disponibles

Las implementaciones siguientes usan las abstracciones comunes del almacén de vectores de .NET. Revise la documentación de cada implementación para conocer las versiones del paquete, los tipos de datos admitidos y las limitaciones específicas del servicio.

Implementation Availability Usa un SDK de base de datos compatible oficialmente Encargado del mantenimiento o proveedor
Búsqueda de Azure AI Available Sí Microsoft
Azure Cosmos DB para núcleo virtual de MongoDB Available Sí Microsoft
Azure Cosmos DB para NoSQL Available Sí Microsoft
Couchbase Available Sí Couchbase
Elasticsearch Available Sí Elastic
Chroma Programado No es aplicable No es aplicable
En memoria Available No es aplicable Microsoft
Milvus Programado No es aplicable No es aplicable
MongoDB Available Sí Microsoft
Postgres Neon sin servidor Uso de la implementación de Postgres Sí Microsoft
Oracle Available Sí Oracle
Pinecone Available No Microsoft
Postgres Available Sí Microsoft
Qdrant Available Sí Microsoft
Redis Available Sí Microsoft
SQL Server Available Sí Microsoft
SQLite Available Sí Microsoft
Volátil en memoria En desuso; usar la implementación en memoria No es aplicable Microsoft
Weaviate Available Sí Microsoft

Importante

Las implementaciones del almacén de vectores proceden de varios mantenedores. Evalúe la calidad, las licencias, la directiva de soporte técnico y la compatibilidad de versiones de cada implementación antes de usarla. Algunas implementaciones usan SDK de base de datos que el proveedor de bases de datos no admite oficialmente.

Get started

  1. Añade el Microsoft.Extensions.VectorData.Abstractions el paquete y el paquete para la implementación de la base de datos vectorial que hayas elegido.
  2. Defina un tipo de registro e identifique sus propiedades clave, datos y vector.
  3. Configure un IEmbeddingGenerator si la implementación requiere incrustaciones generadas por la aplicación.
  4. Crea el VectorStore de la implementación y, a continuación, obtén un VectorStoreCollection<TKey, TRecord> tipado.
  5. Asegúrese de que la colección esté creada, inserte o actualice registros y llame a SearchAsync con texto o un vector.

Para obtener una introducción completa a los modelos de datos, la ingesta, las incrustaciones y la búsqueda, consulte Bases de datos vectoriales para aplicaciones de inteligencia artificial de .NET.

compatibilidad con el almacén de vectores de Python

Agent Framework proporciona contratos experimentales, nativos Python para modelos de almacén de vectores, operaciones de recopilación, generadores de almacenes, búsqueda híbrida de vectores y palabras clave y herramientas de búsqueda del agente. Los contratos forman parte de agent-framework-core y no requieren Pydantic, NumPy, pandas ni Kernel semántico.

Warning

Las API de almacén de vectores de Python nativas son experimentales. Es posible que se produzcan cambios importantes limitados antes de que se conviertan en estables.

Abstracciones principales

Abstracción propósito
VectorStoreField y VectorStoreCollectionDefinition Describir los campos de clave, de datos y vectoriales, incluidos los nombres de almacenamiento, los índices, las dimensiones y las funciones de distancia.
@vectorstoremodel y register_vectorstoremodel() Registra dataclasses, modelos de Pydantic, estructuras de msgspec, clases simples o tipos de modelo externos.
BaseVectorCollection y SupportsVectorUpsert Defina las operaciones de inserción o actualización por lotes, obtención, eliminación, ciclo de vida de la colección, conversión de registros y generación opcional de embeddings.
BaseVectorStore Define un almacén que enumera las colecciones y crea clientes de colección tipados.
BaseVectorSearch y SupportsVectorSearch Defina búsqueda vectorial e híbrida con palabras clave, paginación, filtros, umbrales de puntuación y resultados de búsqueda.
Filter, FilterGroup y Param Defina filtros portátiles de solo datos, incluidos los parámetros de filtro proporcionados por el modelo para las herramientas de búsqueda.
InMemoryStore y InMemoryCollection Proporcione CRUD local de proceso y búsqueda de análisis lineal para el desarrollo y las pruebas.
GenerateVectors Controla si los upserts generan todos los campos vectoriales, ninguno o solo los seleccionados.
create_vector_search_tool(), create_upsert_tool(), create_get_tool() y create_delete_tool(). Exponga las operaciones CRUD de búsqueda de vectores y recopilación como herramientas de funciones de Agent Framework.
VectorStoreHistoryProvider Almacena el historial de conversaciones limitado al ámbito en una colección del proveedor, con compactación opcional y búsqueda en todo el historial.
VectorCollectionContextProvider Añade herramientas de CRUD y búsqueda configurables para una colección que pertenece a quien realiza la llamada.

En el ejemplo siguiente se definen los registros de almacén de vectores mediante la anotación de sus campos clave, datos y vector:

# 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 directamente para diccionarios. Para los tipos de modelo que pertenecen a otro paquete, use register_vectorstoremodel() con una definición explícita y un codificador y descodificador opcionales. Los valores de vectores de tipo array se serializan a través de tolist() sin añadir una dependencia de NumPy.

Agent Framework incluye una implementación en memoria para desarrollo y pruebas. Almacena registros en el proceso actual y utiliza una búsqueda lineal, por lo que se debe usar un conector de base de datos para cargas de trabajo de producción.

En el ejemplo siguiente se almacenan vectores precomputados y se buscan con un árbol 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 cuando el modelo debe proporcionar un valor de filtro. Su tipo en Python, su descripción y sus restricciones pasan a formar parte del esquema JSON de la herramienta de búsqueda:

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

Utiliza una colección de vectores con un agente

Use VectorCollectionContextProvider cuando su aplicación posee la colección y el modelo de datos. El proveedor agrega las herramientas CRUD y de búsqueda generadas. Upsert y delete requieren aprobación de forma predeterminada, mientras que get y search no.

Pase scope_filter para agrupar registros de las herramientas generadas, pero no considere el filtro un límite de autorización ni una garantía atómica del backend. Las herramientas de búsqueda que se transfieren mediante additional_search_tools conservan sus propios filtros, así que aplica un filtro equivalente a cada herramienta personalizada cuando se comparta una colección.

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:

Almacenar el historial de conversaciones en un almacén de vectores

Use VectorStoreHistoryProvider cuando el proveedor deba poseer el esquema de recopilación y cargar y guardar automáticamente los mensajes de Agent Framework. Sus identificadores de aplicación, inquilino, agente, origen y sesión evitan solapamientos accidentales, pero su aplicación debe seguir autorizando el acceso y utilizar credenciales del almacén o espacios de nombres con el alcance adecuado.

Al configurar inserciones, proporcione un nombre de colección explícito y las dimensiones de inserción. La compactación reduce solo el historial cargado en el contexto del modelo. Si habilitas la herramienta de búsqueda, buscará en toda la transcripción dentro del á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:

Implementaciones de Native Agent Framework

Las implementaciones siguientes usan los contratos nativos de Agent Framework. Algunos también están disponibles como conectores de Kernel semántico independientes, pero las dos familias de conectores no son intercambiables.

Implementation Paquete y ciclo de vida de Agent Framework Conector de Kernel semántico independiente Modos de búsqueda Principales limitaciones
En memoria agent-framework-core; paquete publicado con API de vector experimentales Disponible Vector denso con filtros portátiles Examen lineal local de procesos para desarrollo y pruebas, no una base de datos de producción.
Búsqueda de Azure AI agent-framework-azure-ai-search; paquete beta con API vectoriales experimentales Disponible Vector denso e híbrido de palabras clave Un campo vectorial denso de nivel superior por consulta. Algunos umbrales, los controles híbridos de recuperación de texto, el filtrado posterior estricto y los permisos requieren un SDK o API de versión preliminar compatible y allow_preview=True.
Azure Cosmos DB para NoSQL agent-framework-azure-cosmos; paquete beta con API vectoriales experimentales Disponible Vector denso con filtros portátiles Las claves deben ser cadenas almacenadas como idy los contenedores usan la /id clave de partición. No se admiten las palabras clave ni la búsqueda híbrida, y la búsqueda euclidiana no admite umbrales de puntuación.
Azure DocumentDB agent-framework-azure-documentdb; paquete alfa No disponible Vector denso con filtros de metadatos portátiles Las claves deben ser cadenas o enteros. No se admiten los ObjectIds generados, la búsqueda híbrida y de texto completo, ni las rutas de filtro anidadas.
MongoDB agent-framework-mongodb; paquete alfa Disponible Vector denso aproximado o exacto con filtros portátiles Requiere PyMongo 4.13.2+ y una implementación con MongoDB Vector Search. La búsqueda por palabras clave y la búsqueda híbrida, las rutas de filtro anidadas, la generación de embeddings del lado del proveedor y la migración automática del esquema no son compatibles.
PostgreSQL con pgvector agent-framework-postgres; paquete alfa Disponible Vector denso exacto, HNSW y OBJECTFlat Requiere PostgreSQL 13+, pgvector 0.8.0+, un esquema existente y la extensión habilitada. No se admite la palabra clave ni la búsqueda híbrida.
Qdrant agent-framework-qdrant; paquete alfa Disponible Vector denso con filtros transferibles en el servidor El modo de servidor requiere Qdrant 1.16.2+. Las claves deben tener enteros de 64 bits sin signo o UUID. No se admiten las palabras clave ni la búsqueda híbrida, y los filtros no están disponibles en el modo del SDK local.
Redis agent-framework-redis; paquete beta con API vectoriales experimentales Disponible Vector denso a través de registros HASH o JSON Requiere Redis 8.0.3+ con Search; Los registros JSON también requieren RedisJSON. No se admite el clúster de Redis, la búsqueda de palabras clave ni la búsqueda híbrida.

Instale un paquete de conector de versión preliminar para la base de datos que use:

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

Cada conector implementa el modelo común, la recopilación, CRUD, el filtro y los contratos de búsqueda. Todavía se aplican restricciones y funcionalidades específicas de la base de datos. Para obtener ejemplos completos, consulte los ejemplos de Búsqueda de Azure AI, MongoDB, Postgres, Qdrant y Redis.

Implementaciones exclusivas de Kernel semántico

Las aplicaciones pueden seguir usando los almacenes de vectores de Python de Kernel semántico directamente. Estas implementaciones usan los contratos de almacén de vectores de Kernel semántico independientes en lugar de los contratos nativos de Agent Framework. Las implementaciones siguientes no tienen actualmente un conector de Agent Framework nativo:

Implementation Availability Usa un SDK de base de datos compatible oficialmente Encargado del mantenimiento o proveedor
Azure Cosmos DB para núcleo virtual de MongoDB Available Sí proyecto de Microsoft Kernel semántico
Croma Available Sí proyecto de Microsoft Kernel semántico
Elasticsearch Programado No es aplicable No es aplicable
Faiss Available Sí proyecto de Microsoft Kernel semántico
Postgres Neon sin servidor Uso de la implementación de Postgres Sí proyecto de Microsoft Kernel semántico
Oracle Available Sí Oracle
Pinecone Available Sí proyecto de Microsoft Kernel semántico
SQL Server Available pyodbc proyecto de Microsoft Kernel semántico
SQLite Programado No es aplicable proyecto de Microsoft Kernel semántico
Weaviate Available Sí proyecto de Microsoft Kernel semántico

Importante

Las implementaciones del almacén de vectores proceden de varios mantenedores. Evalúe la calidad, las licencias, la directiva de soporte técnico y la compatibilidad de versiones de cada implementación antes de usarla.

Use una implementación solo de Kernel semántico

  1. Instale semantic-kernel y las dependencias necesarias para la implementación elegida.
  2. Defina un modelo con el @vectorstoremodel decorador e identifique sus campos clave, datos y vector.
  3. Cree una colección específica de implementación para ese modelo.
  4. Asegúrese de que la colección exista y, a continuación, inserte o actualice los registros.
  5. Use las API de búsqueda de la colección para recuperar registros de la aplicación.

Para la configuración de la implementación y ejemplos completos, consulte Almacenes vectoriales de Kernel semántico.

Compatibilidad con almacenes vectoriales en Go

La integración del almacén de vectores aún no está disponible en Agent Framework for Go. Consulte el repositorio de Agent Framework Go para obtener el estado más reciente.

Pasos siguientes

Añade RAG a un agente

  • Last updated on