Intégrations de bases de données vectorielles

Les vecteurs stockent les données et ses incorporations vectorielles afin que les applications puissent rechercher des enregistrements par similarité sémantique. Dans les applications basées sur Agent Framework, vous pouvez utiliser des bases de données vectorielles pour récupérer des données d’ancrage pour la génération augmentée par récupération (RAG) ou pour stocker des informations qu’un agent pourra retrouver plus tard.

Les abstractions de magasin de vecteurs fournissent des opérations courantes pour les collections et les enregistrements, ce qui sépare votre logique d’application de l’implémentation spécifique du magasin de vecteurs. Vous pouvez, par exemple, commencer par une implémentation locale et basculer vers un service managé avec des modifications minimales.

Fonctionnement des intégrations avec des bases de données vectorielles

Un flux de travail de magasin de vecteurs classique comprend les étapes suivantes :

  1. Définissez un modèle de données qui identifie la clé d’enregistrement, les champs de données et les champs vectoriels.
  2. Configurez un générateur d’incorporation si le magasin vectoriel ne génère pas d’incorporations.
  3. Connectez-vous à un magasin vectoriel et sélectionnez ou créez une collection.
  4. Générer des incorporations et faire un upsert des enregistrements dans la collection.
  5. Recherchez la collection avec du texte ou un vecteur, en fonction des fonctionnalités de l’implémentation.
  6. Transmettez les résultats de recherche pertinents à un agent en tant que contexte ou exposez la recherche en tant qu’outil d’agent.

Prise en charge des bases de données vectorielles dans .NET

Agent Framework utilise les abstractions autonomes de l'écosystème IA .NET :

  • Microsoft.Extensions.VectorData fournit des API courantes de magasin de vecteurs, de collection, d’enregistrement et de recherche.
  • Microsoft.Extensions.AI fournit des abstractions telles que IEmbeddingGenerator pour générer des embeddings indépendamment d’un fournisseur de modèles spécifique.

Lorsqu’un composant Agent Framework accepte un magasin de vecteurs, vous pouvez fournir une implémentation compatible Microsoft.Extensions.VectorData . Chaque implémentation de base de données est distribuée séparément du package d’abstractions.

Abstractions principales

Abstraction Purpose
VectorStore Fournit des opérations sur plusieurs collections et crée des instances de collection typées.
VectorStoreCollection<TKey, TRecord> Crée ou supprime une collection et insère ou met à jour, récupère ou supprime ses enregistrements.
IVectorSearchable<TRecord> Recherche les enregistrements par vecteur ou par texte lorsqu’un générateur d’incorporation ou une fonctionnalité d’incorporation côté base de données est disponible.

Implémentations disponibles de bases de données vectorielles

Les implémentations suivantes utilisent les abstractions communes de magasins vectoriels .NET. Passez en revue la documentation de chaque implémentation pour connaître les versions de package, les types de données pris en charge et les limitations spécifiques au service.

Implementation Availability Utilise un Kit de développement logiciel (SDK) de base de données officiellement pris en charge Maintenance ou fournisseur
Recherche Azure AI Available Yes Microsoft
Azure Cosmos DB pour MongoDB vCore Available Yes Microsoft
Azure Cosmos DB pour NoSQL Available Yes Microsoft
Couchbase Available Yes Couchbase
Elasticsearch Available Yes Elastic
Chroma Planifié Sans objet Sans objet
En mémoire Available Sans objet Microsoft
Milvus Planifié Sans objet Sans objet
MongoDB Available Yes Microsoft
Neon Serverless Postgres Utiliser l’implémentation postgres Yes Microsoft
Oracle Available Yes Oracle
Pinecone Available No Microsoft
Postgres Available Yes Microsoft
Qdrant Available Yes Microsoft
Redis Available Yes Microsoft
SQL Server Available Yes Microsoft
SQLite Available Yes Microsoft
Volatile en mémoire Déconseillé ; utiliser l’implémentation en mémoire Sans objet Microsoft
Weaviate Available Yes Microsoft

Importante

Les implémentations de magasins vectoriels proviennent de plusieurs mainteneurs. Évaluez la qualité, les licences, la stratégie de prise en charge et la compatibilité des versions de chaque implémentation avant de l’utiliser. Certaines implémentations utilisent des sdk de base de données que le fournisseur de base de données ne prend pas officiellement en charge.

Get started

  1. Ajouter le Package Microsoft.Extensions.VectorData.Abstractions et le package pour l'implémentation de votre magasin de vecteurs choisi.
  2. Définissez un type d’enregistrement et identifiez sa clé, ses données et ses propriétés vectorielles.
  3. Configurez une IEmbeddingGenerator configuration si votre implémentation nécessite des incorporations générées par l’application.
  4. Créez l’implémentation VectorStore, puis obtenez un type VectorStoreCollection<TKey, TRecord>.
  5. Vérifiez que la collection existe, effectuez une opération d’upsert sur les enregistrements, et appelez SearchAsync avec du texte ou un vecteur.

Pour une présentation complète des modèles de données, de l’ingestion, des incorporations et de la recherche, consultez les bases de données Vector pour .NET applications IA.

prise en charge des bases de données vectorielles Python

Agent Framework fournit des contrats Python natifs expérimentaux pour les modèles de magasins vectoriels, les opérations sur les collections, les fabriques de magasins, la recherche vectorielle et hybride combinant recherche vectorielle et recherche par mots clés, ainsi que les outils de recherche des agents. Les contrats font partie agent-framework-core et ne nécessitent pas Pydantic, NumPy, pandas ou Noyau sémantique.

Avertissement

Les API natives de magasin de vecteurs Python sont expérimentales. Des changements cassants limités peuvent se produire avant qu’ils ne deviennent stables.

Abstractions principales

Abstraction Purpose
VectorStoreField et VectorStoreCollectionDefinition Décrire les champs clés, données et vecteurs, y compris les noms de stockage, les index, les dimensions et les fonctions de distance.
@vectorstoremodel et register_vectorstoremodel() Inscrivez des classes de données, des modèles Pydantic, des structs msgspec, des classes simples ou des types de modèles appartenant à l’externe.
BaseVectorCollection et SupportsVectorUpsert Définissez la mise à jour ou insertion par lot, la récupération, la suppression, le cycle de vie des collections, la conversion des enregistrements et la génération facultative d'embeddings.
BaseVectorStore Définit un magasin qui répertorie les collections et crée des clients de collection typés.
BaseVectorSearch et SupportsVectorSearch Définissez la recherche vectorielle et hybride par mot clé, la pagination, les filtres, les seuils de score et les résultats de recherche.
Filter, FilterGroup et Param Définissez des filtres portables uniquement basés sur des données, y compris les paramètres de filtre fournis par le modèle pour des outils de recherche.
InMemoryStore et InMemoryCollection Fournissez la recherche CRUD locale et l’analyse linéaire pour le développement et les tests.
GenerateVectors Détermine si les upserts génèrent tous les champs vectoriels, aucun, ou uniquement ceux sélectionnés.
create_vector_search_tool(), create_upsert_tool(), create_get_tool() et create_delete_tool() Exposez les opérations CRUD de recherche vectorielle et de collection en tant qu’outils de fonction Agent Framework.
VectorStoreHistoryProvider Stocke l’historique des conversations limité au périmètre dans une collection détenue par le fournisseur, avec compactage facultatif et recherche dans l’historique complet.
VectorCollectionContextProvider Ajoute des outils CRUD et de recherche configurables pour une collection appartenant à l’appelant.

L’exemple suivant définit les enregistrements de magasin de vecteurs en annoteant leurs champs clé, données et vecteurs :

# 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

Utilisez VectorStoreCollectionDefinition directement pour les dictionnaires. Pour les types de modèles appartenant à un autre package, utilisez register_vectorstoremodel() une définition explicite et un encodeur et décodeur facultatifs. Les valeurs vectorielles de type tableau sont sérialisées via tolist() sans ajouter de dépendance à NumPy.

Agent Framework inclut une implémentation en mémoire pour le développement et les tests. Il stocke les enregistrements dans le processus actuel et utilise une analyse linéaire. Utilisez donc un connecteur de base de données pour les charges de travail de production.

Passer des options d’incorporation pour chaque opération

Passez upsert() à embeddings_options pour appliquer les options du fournisseur à tous les champs vectoriels générés. Utilisez embeddings_options_by_field quand différents champs de vecteur logique ont besoin d’options différentes. Ces deux arguments s’excluent mutuellement.

Pour l’incorporation de requêtes, passez embeddings_options à search() ou create_vector_search_tool(). Agent Framework fournit les dimensions déclarées du champ de vecteurs sélectionné et rejette une valeur dimensions incompatible avant d’appeler le fournisseur d’embeddings.

Les options d’incorporation Upsert nécessitent des vecteurs générés et ne peuvent pas être combinées avec generate_vectors=False. Les options d’incorporation de recherche nécessitent un générateur d’incorporation local et sont ignorées lorsque vous fournissez un vecteur de requête précomputé.

L’exemple suivant stocke les vecteurs précomputés et les recherche avec une arborescence de filtre portable :

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

Utilisez Param quand le modèle doit fournir une valeur de filtre. Son type Python, sa description et ses contraintes font partie du schéma JSON de l'outil de recherche :

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

Utiliser une collection de vecteurs avec un agent

Utilisez VectorCollectionContextProvider cette option lorsque votre application possède le modèle de collecte et de données. Le fournisseur ajoute des outils CRUD et de recherche générés. Upsert et delete nécessitent une approbation par défaut, tandis que get et search n’en nécessitent pas.

Passez scope_filter pour regrouper les enregistrements des outils générés, mais ne traitez pas le filtre comme une frontière d’autorisation ni comme une garantie atomique du back-end. Les outils de recherche transmis par le biais additional_search_tools conservent leurs propres filtres. Appliquez donc un filtre équivalent à chaque outil personnalisé lorsqu’une collection est partagée.

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:

Stocker l’historique des conversations dans un magasin vectoriel

Utilisez VectorStoreHistoryProvider quand le fournisseur doit posséder le schéma de collection et charger et enregistrer automatiquement les messages Agent Framework. Ses identifiants d’application, de locataire, d’agent, de source et de session empêchent les collisions accidentelles, mais votre application doit toujours autoriser l’accès et utiliser des identifiants du magasin de données ou des espaces de noms correctement délimités.

Lorsque vous configurez des incorporations, fournissez un nom de collection explicite et les dimensions d’incorporation. Le compactage réduit uniquement l’historique chargé dans le contexte du modèle. Si vous activez l’outil de recherche, il recherche la transcription complète.

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:

Implémentations du cadre d’agent natif

Les implémentations suivantes utilisent les contrats Framework d’agent natifs. Certains sont également disponibles en tant que connecteurs Noyau sémantique distincts, mais les deux familles de connecteurs ne sont pas interchangeables.

Implementation Package et cycle de vie du framework d’agent Connecteur Noyau sémantique séparé Modes de recherche Limites clés
En mémoire agent-framework-core; package publié avec des API vectorielles expérimentales Disponible Vecteur dense avec filtres portables Analyse linéaire locale de processus pour le développement et les tests, et non pas une base de données de production.
Recherche d’IA Azure agent-framework-azure-ai-search; package bêta avec des API vectorielles expérimentales Disponible Vecteur dense et hybride à mots-clés Un champ vectoriel dense de niveau supérieur par requête. Certains seuils, certains contrôles hybrides de rappel de texte, le post-filtrage strict et les autorisations nécessitent une version préliminaire du SDK/de l’API et allow_preview=True.
Azure Cosmos DB pour NoSQL agent-framework-azure-cosmos; package bêta avec des API vectorielles expérimentales Disponible Vecteur dense avec filtres portables Les clés doivent être des chaînes stockées sous la forme de id, et les conteneurs utilisent la clé de partition /id. Les mots clés et la recherche hybride ne sont pas pris en charge, et la recherche euclide ne prend pas en charge les seuils de score.
Azure DocumentDB agent-framework-azure-documentdb; paquet alpha Non disponible Vecteur dense avec des filtres de métadonnées portables Les clés doivent être des chaînes ou des entiers. Les ObjectIds générés, la recherche hybride et en texte intégral et les chemins de filtre imbriqués ne sont pas pris en charge.
DuckDB agent-framework-duckdb; paquet alpha Non disponible Vecteur dense exact avec des filtres portables Nécessite Python 3.10+ et DuckDB 1.4.1 à 1.5.x. Les index approximatifs, les mots clés et la recherche hybride, la recherche en texte intégral et la vectorisation côté serveur ne sont pas pris en charge. Les fichiers locaux n’autorisent qu’un seul processus d’écriture à la fois.
MongoDB agent-framework-mongodb; paquet alpha Disponible Vecteur dense approximatif ou exact avec des filtres portables Nécessite PyMongo 4.13.2+ et un déploiement avec Recherche vectorielle MongoDB. La recherche par mots-clés et hybride, les chemins de filtre imbriqués, la génération de représentations vectorielles du côté du fournisseur et la migration automatique du schéma ne sont pas prises en charge. Les modèles qui déclarent is_full_text_indexed sont rejetés et les enregistrements nouvellement écrits deviennent pouvant faire l’objet d’une recherche asynchrone.
PostgreSQL avec pgvector agent-framework-postgres; paquet alpha Disponible Vecteur dense exact, HNSW et IVFFlat Nécessite PostgreSQL 13+, pgvector 0.8.0+, un schéma existant et l’extension activée. Les mots clés et la recherche hybride ne sont pas pris en charge.
Qdrant agent-framework-qdrant; paquet alpha Disponible Vecteur dense avec des filtres portables côté serveur Le mode serveur nécessite Qdrant 1.16.2+. Les clés doivent être des entiers 64 bits non signés ou des UUID. Les mots clés et la recherche hybride ne sont pas pris en charge, et les filtres ne sont pas disponibles en mode SDK local.
Redis agent-framework-redis; package bêta avec des API vectorielles expérimentales Disponible Vecteur dense sur les enregistrements HASH ou JSON Nécessite Redis 8.0.3+ avec la recherche ; Les enregistrements JSON nécessitent également RedisJSON. Le cluster Redis, la recherche de mots clés et la recherche hybride ne sont pas pris en charge.
SQL Server agent-framework-sql-server; paquet alpha Disponible Vecteur dense exact avec des filtres portables Nécessite Python 3.10 à 3.14 et SQL Server 2025 ou une base de données Azure SQL vectorielle. Les index approximatifs, les mots clés et la recherche hybride, la vectorisation côté serveur et la migration de schéma ne sont pas pris en charge.

Installez un package de connecteur de préversion pour la base de données que vous utilisez :

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

Sur Python 3.10 à 3.14, agent-framework-postgres installe la distribution binaire de Psycopg. Dans Python 3.15 ou version ultérieure, il utilise pure-Python Psycopg car les roues binaires compatibles ne sont pas publiées, de sorte que l'hôte doit fournir une installation systèmelibpq.

Chaque connecteur implémente le modèle commun, la collection, CRUD, le filtre et les contrats de recherche. Les fonctionnalités et restrictions spécifiques à la base de données s’appliquent toujours. Pour obtenir des exemples complets, consultez les exemples Recherche Azure AI, DuckDB, MongoDB vector operations, MongoDB agent RAG, Postgres, Qdrant, Redis et SQL Server exemples.

Implémentations utilisant uniquement Noyau sémantique

Les applications peuvent continuer à utiliser directement les magasins vectoriels Python de Noyau sémantique. Ces implémentations utilisent les contrats de magasin vectoriel distincts de Noyau sémantique plutôt que les contrats natifs d’Agent Framework. Les implémentations suivantes ne disposent pas actuellement d’un connecteur Agent Framework natif :

Implementation Availability Utilise un Kit de développement logiciel (SDK) de base de données officiellement pris en charge Maintenance ou fournisseur
Azure Cosmos DB pour MongoDB vCore Available Yes projet Microsoft Noyau sémantique
Chroma Available Yes projet Microsoft Noyau sémantique
Elasticsearch Planifié Sans objet Sans objet
Faiss Available Yes projet Microsoft Noyau sémantique
Neon Serverless Postgres Utiliser l’implémentation postgres Yes projet Microsoft Noyau sémantique
Oracle Available Yes Oracle
Pinecone Available Yes projet Microsoft Noyau sémantique
SQLite Planifié Sans objet projet Microsoft Noyau sémantique
Weaviate Available Yes projet Microsoft Noyau sémantique

Importante

Les implémentations de magasins vectoriels proviennent de plusieurs mainteneurs. Évaluez la qualité, les licences, la stratégie de prise en charge et la compatibilité des versions de chaque implémentation avant de l’utiliser.

Utiliser une implémentation Noyau sémantique uniquement

  1. Installez semantic-kernel et les dépendances requises par votre implémentation choisie.
  2. Définissez un modèle avec le @vectorstoremodel décorateur et identifiez ses champs clé, données et vecteurs.
  3. Créez une collection spécifique à l’implémentation pour ce modèle.
  4. Vérifiez que la collection existe, puis insérez ou mettez à jour des enregistrements.
  5. Utilisez les API de recherche de la collection pour récupérer des enregistrements pour votre application.

Pour la configuration de l’implémentation et des exemples complets, consultez Magasins de vecteurs Noyau sémantique.

Prise en charge des bases de données vectorielles en Go

L’intégration du magasin de vecteurs n’est pas encore disponible dans Agent Framework pour Go. Consultez le référentiel Agent Framework Go pour connaître l’état le plus récent.

Étapes suivantes

Ajouter RAG à un agent

  • Last updated on