createGraphRAGTool()

createGraphRAGTool() 會建立一個 Tool，透過建構文件間語意關係的圖來強化 RAG。其底層使用 GraphRAG 系統提供圖形擷取，同時透過直接相似度與相連關係找出相關內容。

使用範例

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

= false

啟用根據中繼資料篩選結果的功能。（只能在建立時設定，但若 request context 提供 filter，則會自動啟用。）

includeSources?:

boolean

= true

在結果中包含完整擷取物件。（可在建立時設定，或在執行階段覆寫。）

graphOptions?:

GraphOptions

= 預設圖形選項

圖形擷取的設定

GraphOptions

dimension?:

number

embedding 向量的維度

threshold?:

number

在節點間建立邊的相似度門檻（0–1）

randomWalkSteps?:

number

圖遍歷時隨機漫步的步數。（可在建立時設定，或在執行階段覆寫。）

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 物件結構

{
  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 說明

預設說明著重於：

• 分析文件間的關係
• 找出模式與關聯
• 回答複雜查詢

進階範例

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

自訂說明範例

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

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

使用 request context 時，請在執行階段透過 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,
})

如需 request context 的詳細資訊，請參閱：

• Agent Request Context
• Request Context

多租戶應用程式的動態 vector store

若多租戶應用程式會隔離各租戶的資料，你可以傳入 resolver function，而不是靜態 vector store：

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。

相關內容

• createVectorQueryTool
• GraphRAG