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

# createGraphRAGTool()

`createGraphRAGTool()` 会创建一个 Tool，通过建构文档间语意关系的图来强化 RAG。其底层使用 `GraphRAG` 系统提供图形截取，同时通过直接相似度与相连关系找出相关内容。

## 使用示例

```typescript
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,
  },
})
```

## 参数

> **备注:** **参数要求：** 大多数字段都可在创建时设为默认值。部分字段可在运行时通过 request context 或输入覆盖。如果创建时和运行时都未提供必填字段，系统将抛出错误。请注意，`model`、`id` 和 `description` 只能在创建时设置。

**id** (`string`): 自定义 Tool ID。默认为：'GraphRAG {vectorStoreName} {indexName} Tool'。（只能在创建时设置。）

**description** (`string`): 自定义 Tool 描述。默认为：'Access and analyze relationships between information in the knowledge base to answer complex questions about connections and patterns.'（只能在创建时设置。）

**vectorStoreName** (`string`): 要查找的 vector store 名称。（可在创建时设置，或在运行阶段覆写。）

**indexName** (`string`): vector store 中的索引名称。（可在创建时设置，或在运行阶段覆写。）

**model** (`EmbeddingModel`): 用于矢量搜索的 embedding 模型。（只能在创建时设置。）

**enableFilter** (`boolean`): 激活根据中继数据筛选结果的功能。（只能在创建时设置，但若 request context 提供 filter，则会自动激活。） (Default: `false`)

**includeSources** (`boolean`): 在结果中包含完整截取对象。（可在创建时设置，或在运行阶段覆写。） (Default: `true`)

**graphOptions** (`GraphOptions`): 图形截取的设置 (Default: `缺省图形选项`)

**graphOptions.dimension** (`number`): embedding 矢量的维度

**graphOptions.threshold** (`number`): 在节点间创建边的相似度门槛（0–1）

**graphOptions.randomWalkSteps** (`number`): 图遍历时随机漫步的步数。（可在创建时设置，或在运行阶段覆写。）

**graphOptions.restartProb** (`number`): 从查找节点重新开始随机漫步的几率。（可在创建时设置，或在运行阶段覆写。）

**providerOptions** (`Record<string, Record<string, any>>`): embedding 模型的 Provider 特定选项（例如 outputDimensionality）。仅适用于 AI SDK EmbeddingModelV2 模型。若使用 V1 模型，请在创建模型本身时设置选项。

**vectorStore** (`MastraVector | VectorStoreResolver`): 直接提供 vector store instance，或提供用于动态选取的 resolver function。多租户应用程序可使用函数，根据 request context 选取 vector store。提供此值后，vectorStoreName 会变成选填。

## 返回值

此 Tool 会返回具有下列字段的对象：

**relevantContext** (`string`): 使用图形排序截取而得、由最相关文档区块合并而成的文本

**sources** (`QueryResult[]`): 完整截取结果对象的数组。每个对象都包含参照原始文档、区块与相似度分数所需的全部信息。

### `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)
}
```

## 缺省 Tool 说明

默认描述侧重于：

- 分析文档间的关系
- 找出模式与关联
- 回答复杂查找

## 高端示例

```typescript
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
  },
})
```

## 自订说明示例

```typescript
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",
})
```

此示例示范如何针对特定使用情境自订 Tool 说明，同时保留分析关系的内核用途。

## 示例：使用 request context

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

使用 request context 时，请在运行阶段通过 request context 提供必要参数：

```typescript
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,
})
```

如需 request context 的详细信息，请参阅：

- [Agent Request Context](https://mastra.zisheng.pro/docs/server/request-context)
- [Request Context](https://mastra.zisheng.pro/docs/server/request-context)

## 多租户应用程序的动态 vector store

若多租户应用程序会隔离各租户的数据，你可以传入 resolver function，而不是静态 vector store：

```typescript
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,
})
```

如需详细信息，请参阅 [createVectorQueryTool－动态 vector store](https://mastra.zisheng.pro/reference/tools/vector-query-tool)。

## 相关内容

- [createVectorQueryTool](https://mastra.zisheng.pro/reference/tools/vector-query-tool)
- [GraphRAG](https://mastra.zisheng.pro/reference/rag/graph-rag)