Aller au contenu principal

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
Lien direct vers Utilisation de base

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
Lien direct vers 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
= false
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.)

includeVectors?:

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

includeSources?:

boolean
= true
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.)

reranker?:

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

model:

MastraLanguageModel
Modèle de langage à utiliser pour le reclassement

options?:

RerankerOptions
Options du processus de reclassement
RerankerOptions

weights?:

WeightConfig
Pondérations des composantes du score (semantic: 0.4, vector: 0.4, position: 0.2)

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
PineconeConfig

namespace?:

string
Namespace Pinecone servant à organiser les vecteurs

sparseVector?:

{ indices: number[]; values: number[]; }
Vecteur creux pour la recherche hybride

pgvector?:

PgVectorConfig
Configuration propre à PostgreSQL avec l'extension pgvector
PgVectorConfig

minScore?:

number
Seuil minimal du score de similarité pour les résultats

ef?:

number
Paramètre de recherche HNSW : contrôle le compromis entre précision et vitesse

probes?:

number
Paramètre de sondage IVFFlat : nombre de cellules à parcourir pendant la recherche

chroma?:

ChromaConfig
Configuration propre à la base vectorielle Chroma
ChromaConfig

where?:

Record<string, any>
Conditions de filtrage des métadonnées

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
Lien direct vers 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
Lien direct vers queryresult-object-structure

{
  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
Lien direct vers 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
Lien direct vers 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
Lien direct vers Exemple avec des filtres

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 : 
    {
       "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.

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.

Exemple avec reclassement
Lien direct vers Exemple avec reclassement

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
Lien direct vers Exemple avec une description personnalisée

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
Lien direct vers 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.

Configuration de Pinecone
Lien direct vers Configuration de Pinecone

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

Remplacement de la configuration au moment de l'exécution
Lien direct vers 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 :

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
Lien direct vers Exemple : utilisation du contexte de requête

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 :

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 :

Utilisation sans serveur Mastra
Lien direct vers Utilisation sans serveur Mastra

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

src/index.ts
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
Lien direct vers 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 :

src/index.ts
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
Lien direct vers 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
On this page