> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# createVectorQueryTool()

La fonction `createVectorQueryTool()` crée un Tool permettant d'effectuer des recherches sémantiques dans des bases vectorielles. Elle prend en charge le filtrage, le reclassement et les configurations propres à chaque base de données, et s'intègre aux backends de bases vectorielles.

## Utilisation de base

```typescript
import { createVectorQueryTool } from '@mastra/rag'
import { ModelRouterEmbeddingModel } from '@mastra/core/llm'

const queryTool = createVectorQueryTool({
  vectorStoreName: 'pinecone',
  indexName: 'docs',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
})
```

## Paramètres

> **Remarque:** **Exigences relatives aux paramètres :** la plupart des champs peuvent recevoir une valeur par défaut lors de la création. Certains champs peuvent être remplacés au moment de l'exécution via le contexte de requête ou l'entrée. Si un champ requis n'est défini ni à la création ni à l'exécution, une erreur est générée. Notez que `model`, `id` et `description` ne peuvent être définis qu'à la création.

**id** (`string`): ID personnalisé du Tool. Par défaut : 'VectorQuery {vectorStoreName} {indexName} Tool'. (Défini uniquement à la création.)

**description** (`string`): Description personnalisée du Tool. Par défaut : 'Accéder à la base de connaissances pour trouver les informations nécessaires afin de répondre aux questions des utilisateurs' (Définie uniquement à la création.)

**model** (`EmbeddingModel`): Modèle d'embedding à utiliser pour la recherche vectorielle. (Défini uniquement à la création.)

**vectorStoreName** (`string`): Nom de la base vectorielle à interroger. (Peut être défini à la création ou remplacé au moment de l'exécution.)

**indexName** (`string`): Nom de l'index dans la base vectorielle. (Peut être défini à la création ou remplacé au moment de l'exécution.)

**enableFilter** (`boolean`): Active le filtrage des résultats d'après les métadonnées. (Défini uniquement à la création, mais activé automatiquement si un filtre est fourni dans le contexte de requête.) (Default: `false`)

**includeVectors** (`boolean`): Inclut les vecteurs d'embedding dans les résultats. (Peut être défini à la création ou remplacé au moment de l'exécution.) (Default: `false`)

**includeSources** (`boolean`): Inclut les objets de récupération complets dans les résultats. (Peut être défini à la création ou remplacé au moment de l'exécution.) (Default: `true`)

**reranker** (`RerankConfig`): Options de reclassement des résultats. (Peuvent être définies à la création ou remplacées au moment de l'exécution.)

**reranker.model** (`MastraLanguageModel`): Modèle de langage à utiliser pour le reclassement

**reranker.options** (`RerankerOptions`): Options du processus de reclassement

**reranker.options.weights** (`WeightConfig`): Pondérations des composantes du score (semantic: 0.4, vector: 0.4, position: 0.2)

**reranker.options.topK** (`number`): Nombre de meilleurs résultats à renvoyer

**databaseConfig** (`DatabaseConfig`): Options de configuration propres à la base de données pour optimiser les requêtes. (Peuvent être définies à la création ou remplacées au moment de l'exécution.)

**databaseConfig.pinecone** (`PineconeConfig`): Configuration propre à la base vectorielle Pinecone

**databaseConfig.pinecone.namespace** (`string`): Namespace Pinecone servant à organiser les vecteurs

**databaseConfig.pinecone.sparseVector** (`{ indices: number[]; values: number[]; }`): Vecteur creux pour la recherche hybride

**databaseConfig.pgvector** (`PgVectorConfig`): Configuration propre à PostgreSQL avec l'extension pgvector

**databaseConfig.pgvector.minScore** (`number`): Seuil minimal du score de similarité pour les résultats

**databaseConfig.pgvector.ef** (`number`): Paramètre de recherche HNSW : contrôle le compromis entre précision et vitesse

**databaseConfig.pgvector.probes** (`number`): Paramètre de sondage IVFFlat : nombre de cellules à parcourir pendant la recherche

**databaseConfig.chroma** (`ChromaConfig`): Configuration propre à la base vectorielle Chroma

**databaseConfig.chroma.where** (`Record<string, any>`): Conditions de filtrage des métadonnées

**databaseConfig.chroma.whereDocument** (`Record<string, any>`): Conditions de filtrage du contenu des documents

**providerOptions** (`Record<string, Record<string, any>>`): Options propres au fournisseur pour le modèle d'embedding (par exemple, outputDimensionality). Fonctionne uniquement avec les modèles AI SDK EmbeddingModelV2. Pour les modèles V1, configurez les options lors de la création du modèle lui-même.

**vectorStore** (`MastraVector | VectorStoreResolver`): Instance directe d'une base vectorielle ou fonction de résolution pour une sélection dynamique. Utilisez une fonction pour les applications mutualisées dans lesquelles la base vectorielle est sélectionnée d'après le contexte de requête. Lorsque ce paramètre est fourni, vectorStoreName devient facultatif.

## Valeur renvoyée

Le Tool renvoie un objet contenant :

**relevantContext** (`string`): Texte combiné provenant des segments de document les plus pertinents

**sources** (`QueryResult[]`): Tableau d'objets de résultats de récupération complets. Chaque objet contient toutes les informations nécessaires pour référencer le document d'origine, le segment et le score de similarité.

### Structure de l'objet `QueryResult`

```typescript
{
  id: string;         // Unique chunk/document identifier
  metadata: any;      // All metadata fields (document ID, etc.)
  vector: number[];   // Embedding vector (if available)
  score: number;      // Similarity score for this retrieval
  document: string;   // Full chunk/document text (if available)
}
```

## Description par défaut du Tool

La description par défaut met l'accent sur :

- La recherche d'informations pertinentes dans les connaissances stockées
- Les réponses aux questions des utilisateurs
- La récupération de contenu factuel

## Gestion des résultats

Le Tool détermine le nombre de résultats à renvoyer en fonction de la requête de l'utilisateur, avec une valeur par défaut de 10 résultats. Ce nombre peut être ajusté selon les besoins de la requête.

## Exemple avec des filtres

```typescript
const queryTool = createVectorQueryTool({
  vectorStoreName: 'pinecone',
  indexName: 'docs',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  enableFilter: true,
})
```

Lorsque le filtrage est activé, le Tool traite les requêtes afin de construire des filtres de métadonnées qui se combinent à la recherche sémantique. Le processus se déroule comme suit :

1. Un utilisateur effectue une requête avec des critères de filtrage précis, par exemple « trouver le contenu dont le champ 'version' est supérieur à 2.0 »
2. L'Agent analyse la requête et construit les filtres appropriés :
   ```typescript
   {
      "version": { "$gt": 2.0 }
   }
   ```

Cette approche pilotée par l'Agent :

- Convertit les requêtes en langage naturel en spécifications de filtres
- Implémente la syntaxe de filtrage propre à chaque base vectorielle
- Convertit les termes de la requête en opérateurs de filtrage

Pour en savoir plus sur la syntaxe des filtres et les fonctionnalités propres à chaque base, consultez la documentation sur les [filtres de métadonnées](https://mastra.zisheng.pro/fr/reference/rag/metadata-filters).

Pour voir un exemple du fonctionnement du filtrage piloté par un Agent, consultez l'exemple de [filtrage des métadonnées piloté par un Agent](https://github.com/mastra-ai/mastra/tree/main/examples/basics/rag/filter-rag).

## Exemple avec reclassement

```typescript
const queryTool = createVectorQueryTool({
  vectorStoreName: 'milvus',
  indexName: 'documentation',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  reranker: {
    model: 'openai/gpt-5.6-sol',
    options: {
      weights: {
        semantic: 0.5, // Semantic relevance weight
        vector: 0.3, // Vector similarity weight
        position: 0.2, // Original position weight
      },
      topK: 5,
    },
  },
})
```

Le reclassement améliore la qualité des résultats en combinant :

- Pertinence sémantique : utilisation d'une évaluation de la similarité textuelle basée sur un LLM
- Similarité vectorielle : scores de distance vectorielle d'origine
- Biais de position : prise en compte de l'ordre initial des résultats
- Analyse de la requête : ajustements fondés sur les caractéristiques de la requête

Le module de reclassement traite les résultats initiaux de la recherche vectorielle et renvoie une liste réordonnée afin d'optimiser la pertinence.

## Exemple avec une description personnalisée

```typescript
const queryTool = createVectorQueryTool({
  vectorStoreName: 'pinecone',
  indexName: 'docs',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  description:
    'Search through document archives to find relevant information for answering questions about company policies and procedures',
})
```

Cet exemple montre comment personnaliser la description du Tool pour un cas d'utilisation précis tout en conservant sa fonction principale de récupération d'informations.

## Exemples de configuration propres aux bases de données

Le paramètre `databaseConfig` permet d'utiliser des fonctionnalités et des optimisations propres à chaque base de données vectorielle. Ces configurations sont automatiquement appliquées pendant l'exécution des requêtes.

**Pinecone**:

### Configuration de Pinecone

```typescript
const pineconeQueryTool = createVectorQueryTool({
  vectorStoreName: 'pinecone',
  indexName: 'docs',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  databaseConfig: {
    pinecone: {
      namespace: 'production', // Organize vectors by environment
      sparseVector: {
        // Enable hybrid search
        indices: [0, 1, 2, 3],
        values: [0.1, 0.2, 0.15, 0.05],
      },
    },
  },
})
```

**Fonctionnalités de Pinecone :**

- **Namespace** : isole différents jeux de données au sein du même index
- **Vecteur creux** : combine des embeddings denses et creux pour améliorer la qualité de la recherche
- **Cas d'utilisation** : applications mutualisées, recherche sémantique hybride

**pgVector**:

### Configuration de pgVector

```typescript
const pgVectorQueryTool = createVectorQueryTool({
  vectorStoreName: 'postgres',
  indexName: 'embeddings',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  databaseConfig: {
    pgvector: {
      minScore: 0.7, // Only return results above 70% similarity
      ef: 200, // Higher value = better accuracy, slower search
      probes: 10, // For IVFFlat: more probes = better recall
    },
  },
})
```

**Fonctionnalités de pgVector :**

- **minScore** : exclut les correspondances de faible qualité
- **ef (HNSW)** : contrôle le compromis entre précision et vitesse pour les index HNSW
- **probes (IVFFlat)** : contrôle le compromis entre rappel et vitesse pour les index IVFFlat
- **Cas d'utilisation** : réglage des performances, filtrage selon la qualité

**Chroma**:

### Configuration de Chroma

```typescript
const chromaQueryTool = createVectorQueryTool({
  vectorStoreName: 'chroma',
  indexName: 'documents',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  databaseConfig: {
    chroma: {
      where: {
        // Metadata filtering
        category: 'technical',
        status: 'published',
      },
      whereDocument: {
        // Document content filtering
        $contains: 'API',
      },
    },
  },
})
```

**Fonctionnalités de Chroma :**

- **where** : filtre selon les champs de métadonnées
- **whereDocument** : filtre selon le contenu du document
- **Cas d'utilisation** : filtrage avancé, recherche fondée sur le contenu

**Turbopuffer**:

### Configuration de Turbopuffer

```typescript
const turbopufferQueryTool = createVectorQueryTool({
  vectorStoreName: 'turbopuffer',
  indexName: 'docs',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  databaseConfig: {
    turbopuffer: {
      consistency: 'eventual', // Lower latency, recently written data may not be visible yet
    },
  },
})
```

**Fonctionnalités de Turbopuffer :**

- **consistency** : permet de choisir entre `strong` (valeur par défaut, lecture de ses propres écritures) et `eventual` (latence plus faible)
- **Cas d'utilisation** : requêtes sensibles à la latence pour lesquelles des données légèrement obsolètes restent acceptables

**Configurations multiples**:

### Configurations de plusieurs bases de données

```typescript
// Configure for multiple databases (useful for dynamic stores)
const multiDbQueryTool = createVectorQueryTool({
  vectorStoreName: 'dynamic-store', // Will be set at runtime
  indexName: 'docs',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  databaseConfig: {
    pinecone: {
      namespace: 'default',
    },
    pgvector: {
      minScore: 0.8,
      ef: 150,
    },
    chroma: {
      where: { type: 'documentation' },
    },
  },
})
```

**Avantages des configurations multiples :**

- Prise en charge de plusieurs bases vectorielles avec un seul Tool
- Application automatique des optimisations propres à chaque base de données
- Scénarios de déploiement flexibles

### Remplacement de la configuration au moment de l'exécution

Vous pouvez remplacer les configurations de base de données au moment de l'exécution afin de les adapter à différents scénarios :

```typescript
import { RequestContext } from '@mastra/core/request-context'

const queryTool = createVectorQueryTool({
  vectorStoreName: 'pinecone',
  indexName: 'docs',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  databaseConfig: {
    pinecone: {
      namespace: 'development',
    },
  },
})

// Override at runtime
const requestContext = new RequestContext()
requestContext.set('databaseConfig', {
  pinecone: {
    namespace: 'production', // Switch to production namespace
  },
})

const response = await agent.generate('Find information about deployment', {
  requestContext,
})
```

Cette approche permet de :

- Passer d'un environnement à un autre (dev/staging/prod)
- Ajuster les paramètres de performance en fonction de la charge
- Appliquer différentes stratégies de filtrage selon la requête

## Exemple : utilisation du contexte de requête

```typescript
const queryTool = createVectorQueryTool({
  vectorStoreName: 'pinecone',
  indexName: 'docs',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
})
```

Lorsque vous utilisez le contexte de requête, fournissez les paramètres requis au moment de l'exécution via ce contexte :

```typescript
const requestContext = new RequestContext<{
  vectorStoreName: string
  indexName: string
  topK: number
  filter: VectorFilter
  databaseConfig: DatabaseConfig
}>()
requestContext.set('vectorStoreName', 'my-store')
requestContext.set('indexName', 'my-index')
requestContext.set('topK', 5)
requestContext.set('filter', { category: 'docs' })
requestContext.set('databaseConfig', {
  pinecone: { namespace: 'runtime-namespace' },
})
requestContext.set('model', 'openai/text-embedding-3-small')

const response = await agent.generate('Find documentation from the knowledge base.', {
  requestContext,
})
```

Pour en savoir plus sur le contexte de requête, consultez :

- [Contexte de requête de l'Agent](https://mastra.zisheng.pro/fr/docs/server/request-context)
- [Contexte de requête](https://mastra.zisheng.pro/fr/docs/server/request-context)

## Utilisation sans serveur Mastra

Le Tool peut être utilisé seul pour récupérer les documents correspondant à une requête :

```typescript
import { RequestContext } from '@mastra/core/request-context'
import { createVectorQueryTool } from '@mastra/rag'
import { PgVector } from '@mastra/pg'

const pgVector = new PgVector({
  id: 'pg-vector',
  connectionString: process.env.POSTGRES_CONNECTION_STRING!,
})

const vectorQueryTool = createVectorQueryTool({
  vectorStoreName: 'pgVector', // optional since we're passing in a store
  vectorStore: pgVector,
  indexName: 'embeddings',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
})

const requestContext = new RequestContext()
const queryResult = await vectorQueryTool.execute({ queryText: 'foo', topK: 1 }, { requestContext })

console.log(queryResult.sources)
```

## Base vectorielle dynamique pour les applications mutualisées

Pour les applications mutualisées dans lesquelles les données de chaque locataire sont isolées (par exemple dans des schémas PostgreSQL distincts), vous pouvez transmettre une fonction de résolution à la place d'une instance statique de base vectorielle. La fonction reçoit le contexte de requête et peut renvoyer la base vectorielle appropriée pour le locataire actuel :

```typescript
import { createVectorQueryTool, VectorStoreResolver } from '@mastra/rag'
import { PgVector } from '@mastra/pg'

// Cache for tenant-specific vector stores
const vectorStoreCache = new Map<string, PgVector>()

// Resolver function that returns the correct vector store based on tenant
const vectorStoreResolver: VectorStoreResolver = async ({ requestContext }) => {
  const tenantId = requestContext?.get('tenantId')

  if (!tenantId) {
    throw new Error('tenantId is required in request context')
  }

  // Return cached instance or create new one
  if (!vectorStoreCache.has(tenantId)) {
    vectorStoreCache.set(
      tenantId,
      new PgVector({
        id: `pg-vector-${tenantId}`,
        connectionString: process.env.POSTGRES_CONNECTION_STRING!,
        schemaName: `tenant_${tenantId}`, // Each tenant has their own schema
      }),
    )
  }

  return vectorStoreCache.get(tenantId)!
}

const vectorQueryTool = createVectorQueryTool({
  indexName: 'embeddings',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  vectorStore: vectorStoreResolver, // Dynamic resolution!
})

// Usage with tenant context
const requestContext = new RequestContext()
requestContext.set('tenantId', 'acme-corp')

const result = await vectorQueryTool.execute(
  { queryText: 'company policies', topK: 5 },
  { requestContext },
)
```

Ce modèle est similaire à la manière dont `Agent.memory` prend en charge une configuration définie au moment de l'exécution et permet :

- **Isolation des schémas** : les données de chaque locataire sont placées dans des schémas PostgreSQL distincts
- **Isolation des bases de données** : les requêtes sont dirigées vers différentes instances de base de données selon le locataire
- **Configuration dynamique** : les paramètres de la base vectorielle sont ajustés en fonction du contexte de requête

## Détails du Tool

Le Tool est créé avec les éléments suivants :

- **ID** : `VectorQuery {vectorStoreName} {indexName} Tool`
- **Schéma d'entrée** : nécessite les objets queryText et filter
- **Schéma de sortie** : renvoie la chaîne relevantContext

## Voir aussi

- [rerank()](https://mastra.zisheng.pro/fr/reference/rag/rerank)
- [createGraphRAGTool](https://mastra.zisheng.pro/fr/reference/tools/graph-rag-tool)