图形RAG

🌐 GraphRAG

基于图的检索通过跟踪信息块之间的关系来增强传统的向量搜索。当信息分布在多个文档中或文档相互引用时，这种方法非常有用。

🌐 Graph-based retrieval enhances traditional vector search by following relationships between chunks of information. This approach is useful when information is spread across multiple documents or when documents reference each other.

何时使用 GraphRAG

🌐 When to use GraphRAG

当出现以下情况时，GraphRAG 特别有效：

🌐 GraphRAG is particularly effective when:

• 信息分散在多个文档中
• 文档相互引用
• 你需要遍历关系才能找到完整的答案
• 理解概念之间的联系很重要
• 简单的向量相似性忽略了重要的上下文关系

对于无需关系遍历的简单语义搜索，请使用 标准检索方法 。

🌐 For straightforward semantic search without relationship traversal, use standard retrieval methods.

GraphRAG 的工作原理

🌐 How GraphRAG works

GraphRAG 将向量相似性与知识图谱遍历相结合：

🌐 GraphRAG combines vector similarity with knowledge graph traversal:

1. 初始向量搜索根据语义相似性检索相关片段
2. 知识图谱是由检索到的片段构建而成的
3. 遍历图以找到连接的信息
4. 结果包括直接相关的内容块和相关内容

这一过程有助于揭示那些在语义上可能与查询不相似但通过关联在上下文中相关的信息。

🌐 This process helps surface information that might not be semantically similar to the query but is contextually relevant through connections.

创建图查询工具

🌐 Creating a graph query tool

图查询工具为代理提供了执行基于图的检索的能力：

🌐 The Graph Query Tool provides agents with the ability to perform graph-based retrieval:

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,
  },
});

配置选项

🌐 Configuration options

graphOptions 参数控制知识图谱的构建和遍历方式：

🌐 The graphOptions parameter controls how the knowledge graph is built and traversed:

• threshold：确定哪些块相关的相似度阈值（0-1）。较高的值会生成稀疏但连接更强的图；较低的值会生成更密集、潜在关系更多的图。
• dimension：向量嵌入维度。必须与嵌入模型的输出维度匹配（例如，OpenAI 的 text-embedding-3-small 为 1536）。

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

将 GraphRAG 与代理一起使用

🌐 Using GraphRAG with agents

将图查询工具与代理集成，以实现基于图的检索：

🌐 Integrate the graph query tool with an agent to enable graph-based retrieval:

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.1",
  tools: {
    graphQueryTool,
  },
});

文档处理与存储

🌐 Document processing and storage

在使用基于图的检索之前，将文档处理成块并存储它们的嵌入：

🌐 Before using graph-based retrieval, process documents into chunks and store their embeddings:

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 })),
});

使用 GraphRAG 进行查询

🌐 Querying with GraphRAG

配置完成后，代理可以执行基于图的查询：

🌐 Once configured, the agent can perform graph-based queries:

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

代理使用图形查询工具来：

🌐 The agent uses the graph query tool to:

1. 将查询转换为嵌入
2. 在向量存储中查找语义相似的块
3. 从相关块构建知识图
4. 遍历图以查找关联信息
5. 返回生成回应的全面上下文

选择合适的阈值

🌐 Choosing the right threshold

阈值参数显著影响检索质量：

🌐 The threshold parameter significantly impacts retrieval quality:

• 高阈值（0.8-0.9）：连接严格，关系较少，更精确但结果可能不完整
• 中等阈值 (0.6-0.8)：平衡的方法，适合大多数使用场景
• 低阈值（0.4-0.6）：连接更多，覆盖范围更广，但可能包含不太相关的信息

从0.7开始，并根据你的具体使用情况进行调整：

🌐 Start with 0.7 and adjust based on your specific use case:

// 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,
  },
});

与其他检索方法结合

🌐 Combining with other retrieval methods

GraphRAG 可以与其他检索方法一起使用：

🌐 GraphRAG can be used alongside other retrieval approaches:

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.1",
  tools: {
    vectorQueryTool,
    graphQueryTool,
  },
});

这使代理能够根据查询选择合适的检索方法，从而具有灵活性。

🌐 This gives the agent flexibility to choose the appropriate retrieval method based on the query.

参考

🌐 Reference

有关详细的 API 文档，请参见：

🌐 For detailed API documentation, see:

• GraphRAG 类
• createGraphRAGTool()