GraphRAG

La récupération fondée sur les graphes améliore la recherche vectorielle traditionnelle en suivant les relations entre des segments d’information. Cette approche est utile lorsque les informations sont réparties entre plusieurs documents ou lorsque les documents se font référence mutuellement.

Quand utiliser GraphRAG

GraphRAG est particulièrement efficace lorsque :

• Les informations sont réparties entre plusieurs documents
• Les documents se font référence mutuellement
• Vous devez parcourir les relations pour trouver des réponses complètes
• Il est important de comprendre les liens entre les concepts
• Une simple similarité vectorielle omet des relations contextuelles importantes

Pour une recherche sémantique simple sans parcours de relations, utilisez les méthodes de récupération standard.

Fonctionnement de GraphRAG

GraphRAG combine la similarité vectorielle et le parcours d’un graphe de connaissances :

1. Une recherche vectorielle initiale récupère les segments pertinents selon leur similarité sémantique
2. Un graphe de connaissances est construit à partir des segments récupérés
3. Le graphe est parcouru afin de trouver des informations connectées
4. Les résultats comprennent à la fois des segments directement pertinents et du contenu associé

Ce processus fait ressortir des informations qui ne sont pas forcément sémantiquement similaires à la requête, mais qui sont pertinentes dans leur contexte grâce à leurs connexions.

Créer un Tool de requête de graphe

Le Tool de requête de graphe permet aux Agents d’effectuer une récupération fondée sur les graphes :

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

const graphQueryTool = createGraphRAGTool({
  vectorStoreName: 'pgVector',
  indexName: 'embeddings',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  graphOptions: {
    threshold: 0.7,
  },
})

Options de configuration

Le paramètre graphOptions contrôle la création et le parcours du graphe de connaissances :

• threshold : seuil de similarité (0-1) qui détermine quels segments sont liés. Des valeurs plus élevées créent des graphes plus clairsemés aux connexions plus fortes. Des valeurs plus faibles créent des graphes plus denses avec davantage de relations potentielles.
• dimension : dimension d’intégration vectorielle. Elle doit correspondre à la dimension de sortie du modèle d’intégration, par exemple 1536 pour text-embedding-3-small d’OpenAI.

const graphQueryTool = createGraphRAGTool({
  vectorStoreName: 'pgVector',
  indexName: 'embeddings',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  graphOptions: {
    dimension: 1536,
    threshold: 0.7,
  },
})

Utiliser GraphRAG avec des Agents

Intégrez le Tool de requête de graphe à un Agent pour activer la récupération fondée sur les graphes :

import { Agent } from '@mastra/core/agent'

const ragAgent = new Agent({
  id: 'rag-agent',
  name: 'GraphRAG Agent',
  instructions: `You are a helpful assistant that answers questions based on the provided context.
When answering questions, use the graph query tool to find relevant information and relationships.
Base your answers on the context provided by the tool, and clearly state if the context doesn't contain enough information.`,
  model: 'openai/gpt-5.6-sol',
  tools: {
    graphQueryTool,
  },
})

Traitement et stockage des documents

Avant d’utiliser la récupération fondée sur les graphes, découpez les documents en segments et stockez leurs intégrations vectorielles :

import { MDocument } from '@mastra/rag'
import { embedMany } from 'ai'
import { ModelRouterEmbeddingModel } from '@mastra/core/llm'

// Create and chunk document
const doc = MDocument.fromText('Your document content here...')

const chunks = await doc.chunk({
  strategy: 'recursive',
  size: 512,
  overlap: 50,
  separator: '\n',
})

// Generate embeddings
const { embeddings } = await embedMany({
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  values: chunks.map(chunk => chunk.text),
})

// Store in vector database
const vectorStore = mastra.getVector('pgVector')
await vectorStore.createIndex({
  indexName: 'embeddings',
  dimension: 1536,
})
await vectorStore.upsert({
  indexName: 'embeddings',
  vectors: embeddings,
  metadata: chunks?.map(chunk => ({ text: chunk.text })),
})

Interroger avec GraphRAG

Une fois configuré, l’Agent peut effectuer des requêtes fondées sur les graphes :

const query = 'What are the effects of infrastructure changes on local businesses?'
const response = await ragAgent.generate(query)
console.log(response.text)

L’Agent utilise le Tool de requête de graphe pour :

1. Convertir la requête en intégration vectorielle
2. Trouver des segments sémantiquement similaires dans le stockage vectoriel
3. Construire un graphe de connaissances à partir de segments associés
4. Parcourir le graphe pour trouver des informations connectées
5. Retourner le contexte complet permettant de générer la réponse

Choisir le bon seuil

Le paramètre de seuil influe fortement sur la qualité de récupération :

• Seuil élevé (0.8-0.9) : connexions strictes et moins de relations ; résultats plus précis, mais potentiellement incomplets
• Seuil moyen (0.6-0.8) : approche équilibrée, adaptée à la plupart des cas d’utilisation
• Seuil faible (0.4-0.6) : davantage de connexions et un contexte plus large, avec le risque d’inclure des informations moins pertinentes

Commencez avec 0.7 et ajustez selon votre cas d’utilisation :

// Strict connections for precise answers
const strictGraphTool = createGraphRAGTool({
  vectorStoreName: 'pgVector',
  indexName: 'embeddings',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  graphOptions: {
    threshold: 0.85,
  },
})

// Broader connections for exploratory queries
const broadGraphTool = createGraphRAGTool({
  vectorStoreName: 'pgVector',
  indexName: 'embeddings',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  graphOptions: {
    threshold: 0.5,
  },
})

Combiner avec d’autres méthodes de récupération

GraphRAG peut être utilisé avec d’autres approches de récupération :

import { createVectorQueryTool } from '@mastra/rag'

const vectorQueryTool = createVectorQueryTool({
  vectorStoreName: 'pgVector',
  indexName: 'embeddings',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
})

const graphQueryTool = createGraphRAGTool({
  vectorStoreName: 'pgVector',
  indexName: 'embeddings',
  model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
  graphOptions: {
    threshold: 0.7,
  },
})

const agent = new Agent({
  id: 'rag-agent',
  name: 'RAG Agent',
  instructions: `Use vector search for simple fact-finding queries.
Use graph search when you need to understand relationships or find connected information.`,
  model: 'openai/gpt-5.6-sol',
  tools: {
    vectorQueryTool,
    graphQueryTool,
  },
})

L’Agent peut ainsi choisir la méthode de récupération appropriée selon la requête.

Référence

Pour la documentation API détaillée, consultez :

• Classe GraphRAG
• createGraphRAGTool()