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:

Defina un modelo de datos que identifique la clave de registro, los campos de datos y los campos vectoriales.
Configure un generador de incrustaciones si el almacén de vectores no genera incrustaciones.
Conéctese a un almacén de vectores y seleccione o cree una colección.
Generar embeddings e insertar o actualizar registros en la colección.
Busque la colección con texto o vector, en función de las funcionalidades de la implementación.
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

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.
Defina un tipo de registro e identifique sus propiedades clave, datos y vector.
Configure un IEmbeddingGenerator si la implementación requiere incrustaciones generadas por la aplicación.
Crea el VectorStore de la implementación y, a continuación, obtén un VectorStoreCollection<TKey, TRecord> tipado.
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 con ámbito en una colección propiedad del proveedor, con compactación opcional y búsqueda en el historial completo.
`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.

Especifica las opciones de incrustación para cada operación

Pase embeddings_options a upsert() para aplicar las opciones del proveedor a todos los campos vectoriales generados. Úselo embeddings_options_by_field cuando los distintos campos de vector lógico necesiten diferentes opciones. Estos dos argumentos son mutuamente excluyentes.

Para la inserción de consultas, pase embeddings_options a search() o create_vector_search_tool(). Agent Framework proporciona las dimensiones declaradas del campo vectorial seleccionado y rechaza un valor de dimensions incompatible antes de llamar al proveedor de incrustaciones.

Las opciones de inserción de Upsert requieren vectores generados y no se pueden combinar con generate_vectors=False. Las opciones de inserción de búsqueda requieren un generador de inserción local y se omiten cuando se proporciona un vector de consulta precomputado.

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 de almacenamiento o espacios de nombres con el ámbito 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 `id`y 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.
DuckDB	`agent-framework-duckdb`; paquete alfa	No disponible	Vector denso exacto con filtros portátiles	Requiere Python 3.10+ y DuckDB 1.4.1–1.5.x. No se admiten índices aproximados, palabra clave e búsqueda híbrida, búsqueda de texto completo y vectorización del lado servidor. Los archivos locales solo permiten un proceso de escritura a la vez.
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. Los modelos que declaran `is_full_text_indexed` se rechazan y los registros recién escritos se pueden buscar de forma asincrónica.
Oracle Database	`agent-framework-oracle`; paquete alfa	Disponible	Vector denso con filtros portátiles	Requiere Oracle Database 23ai o posterior con `COMPATIBLE` establecido en 23.4.0 o superior y `python-oracledb` 2.2.x o 3.x. No se admite la administración de índices, la búsqueda por palabra clave e híbrida, los filtros JSON y los filtros anidados, la vectorización del lado servidor y la migración de esquemas.
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.
Servidor SQL	`agent-framework-sql-server`; paquete alfa	Disponible	Vector denso exacto con filtros portátiles	Requiere Python 3.10–3.14 y SQL Server 2025 o una base de datos de Azure SQL habilitada para vectores. No se admiten índices aproximados, palabra clave e búsqueda híbrida, vectorización del lado servidor y migración de esquemas.

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-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

En Python 3.10 a 3.14, agent-framework-postgres instala la distribución binaria de Psycopg. En Python 3.15 o posterior, utiliza Psycopg en Python puro, ya que no se han publicado paquetes binarios compatibles, por lo que el host debe proporcionar una instalación de libpq en el sistema.

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, ejemplos de DuckDB, ejemplos de operaciones vectoriales de MongoDB, ejemplos de MongoDB agent RAG, ejemplos de Oracle Database, ejemplos de Postgres, ejemplos de Qdrant, ejemplos de Redis y ejemplos de SQL Server.

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
Pinecone	Available	Sí	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

Use una implementación solo de Kernel semántico

Instale semantic-kernel y las dependencias necesarias para la implementación elegida.
Defina un modelo con el @vectorstoremodel decorador e identifique sus campos clave, datos y vector.
Cree una colección específica de implementación para ese modelo.
Asegúrese de que la colección exista y, a continuación, inserte o actualice los registros.
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

Comentarios

¿Le ha resultado útil esta página?

Se actualizó por última vez el 2026-10-09

Integraciones con bases de datos vectoriales

Funcionamiento de las integraciones de almacén de vectores

soporte para almacén vectorial de .NET

Abstracciones principales

Implementaciones de almacén de vectores disponibles

Get started

compatibilidad con el almacén de vectores de Python

Abstracciones principales

Especifica las opciones de incrustación para cada operación

Utiliza una colección de vectores con un agente

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

Implementaciones de Native Agent Framework

Implementaciones exclusivas de Kernel semántico

Use una implementación solo de Kernel semántico

Compatibilidad con almacenes vectoriales en Go

Escenarios relacionados de Agent Framework

Pasos siguientes

Comentarios

Recursos adicionales