> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/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,
  },
})
```

## 參數

> **備註:** **參數要求：** 大部分欄位可在建立時設為預設值。 部分欄位可在執行階段透過請求上下文或輸入覆寫。如果建立時及執行階段都缺少 必填欄位，系統便會拋出錯誤。請注意，`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`): 要查詢的向量儲存庫名稱。（可在建立時設定，或在執行階段覆寫。）

**indexName** (`string`): 向量儲存庫內的索引名稱。（可在建立時設定，或在執行階段覆寫。）

**model** (`EmbeddingModel`): 用於向量搜尋的嵌入模型。（只可在建立時設定。）

**enableFilter** (`boolean`): 啟用根據中繼資料篩選結果。（只可在建立時設定，但如果請求上下文提供了篩選條件，便會自動啟用。） (Default: `false`)

**includeSources** (`boolean`): 在結果中包含完整的檢索物件。（可在建立時設定，或在執行階段覆寫。） (Default: `true`)

**graphOptions** (`GraphOptions`): 以圖為基礎的檢索設定 (Default: `預設圖形選項`)

**graphOptions.dimension** (`number`): 嵌入向量的維度

**graphOptions.threshold** (`number`): 在節點之間建立邊的相似度閾值（0 至 1）

**graphOptions.randomWalkSteps** (`number`): 圖遍歷的隨機遊走步數。（可在建立時設定，或在執行階段覆寫。）

**graphOptions.restartProb** (`number`): 從查詢節點重新開始隨機遊走的概率。（可在建立時設定，或在執行階段覆寫。）

**providerOptions** (`Record<string, Record<string, any>>`): 嵌入模型的 Provider 專用選項（例如 outputDimensionality）。只適用於 AI SDK EmbeddingModelV2 模型。如使用 V1 模型，請在建立模型本身時設定選項。

**vectorStore** (`MastraVector | VectorStoreResolver`): 直接提供向量儲存庫執行個體，或提供用於動態選擇的解析器函數。在根據請求上下文選擇向量儲存庫的多租戶應用程式中，請使用函數。提供此項後，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 描述，同時維持分析關係這項核心用途。

## 範例：使用請求上下文

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

使用請求上下文時，請在執行階段透過請求上下文提供必填參數：

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

如需請求上下文的詳細資料，請參閱：

- [Agent 請求上下文](https://mastra.zisheng.pro/zh-HK/docs/server/request-context)
- [請求上下文](https://mastra.zisheng.pro/zh-HK/docs/server/request-context)

## 多租戶應用程式的動態向量儲存庫

對於每個租戶均使用隔離資料的多租戶應用程式，可傳入解析器函數，而非靜態向量儲存庫：

```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 - 動態向量儲存庫](https://mastra.zisheng.pro/zh-HK/reference/tools/vector-query-tool)。

## 相關內容

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