createGraphRAGTool()

createGraphRAGTool() crée un Tool qui améliore le RAG en construisant un graphe des relations sémantiques entre les documents. Il utilise en interne le système GraphRAG afin de proposer une recherche fondée sur un graphe, qui trouve du contenu pertinent aussi bien par similarité directe que par relations connectées.

Exemple d'utilisation

import { createGraphRAGTool } from '@mastra/rag'
import { ModelRouterEmbeddingModel } from '@mastra/core/llm'

const graphTool = createGraphRAGTool({
  vectorStoreName: 'pinecone',
  indexName: 'docs',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  graphOptions: {
    dimension: 1536,
    threshold: 0.7,
    randomWalkSteps: 100,
    restartProb: 0.15,
  },
})

Paramètres

remarque

Exigences relatives aux paramètres : la plupart des champs peuvent être définis lors de la création comme valeurs par défaut. Certains champs peuvent être remplacés à l'exécution via Request Context ou l'entrée. Si un champ requis est absent à la fois lors de la création et à l'exécution, une erreur est levée. Notez que model, id et description peuvent uniquement être définis lors de la création.

id?:

string

ID personnalisé du Tool. Par défaut : 'GraphRAG {vectorStoreName} {indexName} Tool'. (Défini uniquement lors de la création.)

description?:

string

Description personnalisée du Tool. Par défaut : 'Accéder aux relations entre les informations de la base de connaissances et les analyser afin de répondre à des questions complexes sur les connexions et les modèles.' (Définie uniquement lors de la création.)

vectorStoreName:

string

Nom du stockage vectoriel à interroger. (Peut être défini lors de la création ou remplacé à l’exécution.)

indexName:

string

Nom de l’index dans le stockage vectoriel. (Peut être défini lors de la création ou remplacé à l’exécution.)

model:

EmbeddingModel

Modèle d’embedding à utiliser pour la recherche vectorielle. (Défini uniquement lors de la création.)

enableFilter?:

boolean

= false

Active le filtrage des résultats selon les métadonnées. (Défini uniquement lors de la création, mais activé automatiquement si un filtre est fourni dans Request Context.)

includeSources?:

boolean

= true

Inclut les objets de recherche complets dans les résultats. (Peut être défini lors de la création ou remplacé à l’exécution.)

graphOptions?:

GraphOptions

= Options du graphe par défaut

Configuration de la recherche fondée sur un graphe

GraphOptions

dimension?:

number

Dimension des vecteurs d’embedding

threshold?:

number

Seuil de similarité pour créer des arêtes entre les nœuds (0-1)

randomWalkSteps?:

number

Nombre d’étapes de la marche aléatoire lors du parcours du graphe. (Peut être défini lors de la création ou remplacé à l’exécution.)

restartProb?:

number

Probabilité de relancer la marche aléatoire depuis le nœud de requête. (Peut être définie lors de la création ou remplacée à l’exécution.)

providerOptions?:

Record<string, Record<string, any>>

Options propres au Provider 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 de stockage vectoriel ou fonction de résolution pour une sélection dynamique. Utilisez une fonction pour les applications multi-tenants dans lesquelles le stockage vectoriel est sélectionné selon Request Context. Lorsque cette valeur est fournie, vectorStoreName devient facultatif.

Valeur renvoyée

Le Tool renvoie un objet contenant :

relevantContext:

string

Texte combiné des segments de documents les plus pertinents, récupérés à l’aide d’un classement fondé sur un graphe

sources:

QueryResult[]

Tableau d’objets contenant les résultats de recherche 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

{
  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 les points suivants :

• Analyser les relations entre les documents
• Trouver des modèles et des connexions
• Répondre à des requêtes complexes

Exemple avancé

const graphTool = createGraphRAGTool({
  vectorStoreName: 'pinecone',
  indexName: 'docs',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  graphOptions: {
    dimension: 1536,
    threshold: 0.8, // Higher similarity threshold
    randomWalkSteps: 200, // More exploration steps
    restartProb: 0.2, // Higher restart probability
  },
})

Exemple avec une description personnalisée

const graphTool = createGraphRAGTool({
  vectorStoreName: 'pinecone',
  indexName: 'docs',
  model: 'openai/text-embedding-3-small	',
  description:
    "Analyze document relationships to find complex patterns and connections in our company's historical data",
})

Cet exemple montre comment personnaliser la description du Tool pour un cas d'utilisation précis tout en conservant son objectif principal d'analyse des relations.

Exemple : utiliser Request Context

const graphTool = createGraphRAGTool({
  vectorStoreName: 'pinecone',
  indexName: 'docs',
  model: 'openai/text-embedding-3-small	',
})

Lorsque vous utilisez Request Context, fournissez les paramètres requis au moment de l'exécution par l'intermédiaire de Request Context :

const requestContext = new RequestContext<{
  vectorStoreName: string
  indexName: string
  topK: number
  filter: any
}>()
requestContext.set('vectorStoreName', 'my-store')
requestContext.set('indexName', 'my-index')
requestContext.set('topK', 5)
requestContext.set('filter', { category: 'docs' })
requestContext.set('randomWalkSteps', 100)
requestContext.set('restartProb', 0.15)

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

Pour en savoir plus sur Request Context, consultez :

• Request Context de l'Agent
• Request Context

Stockage vectoriel dynamique pour les applications multi-tenants

Pour les applications multi-tenants dans lesquelles chaque tenant dispose de données isolées, vous pouvez transmettre une fonction de résolution à la place d'un stockage vectoriel statique :

import { createGraphRAGTool, VectorStoreResolver } from '@mastra/rag'
import { PgVector } from '@mastra/pg'

const vectorStoreResolver: VectorStoreResolver = async ({ requestContext }) => {
  const tenantId = requestContext?.get('tenantId')

  return new PgVector({
    id: `pg-vector-${tenantId}`,
    connectionString: process.env.POSTGRES_CONNECTION_STRING!,
    schemaName: `tenant_${tenantId}`,
  })
}

const graphTool = createGraphRAGTool({
  indexName: 'embeddings',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  vectorStore: vectorStoreResolver,
})

Consultez la section createVectorQueryTool - Stockage vectoriel dynamique pour en savoir plus.

Ressources associées

• createVectorQueryTool
• GraphRAG