createGraphRAGTool()

그만큼createGraphRAGTool()문서 간의 의미 관계 그래프를 작성하여 RAG를 향상시키는 Tool을 만듭니다. 그것은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,
  },
})

매개변수

노트

매개변수 요구 사항:대부분의 필드는 생성 시 기본값으로 설정할 수 있습니다. 일부 필드는 요청 컨텍스트 또는 입력을 통해 런타임에 재정의할 수 있습니다. 생성 및 런타임 모두에서 필수 필드가 누락되면 오류가 발생합니다. model, id, description은 생성 시에만 설정할 수 있습니다.

id?:

string

Tool의 사용자 지정 ID입니다. 기본값: 'GraphRAG {vectorStoreName} {indexName} Tool'. (생성 시에만 설정할 수 있습니다.)

description?:

string

Tool의 사용자 지정 설명입니다. 기본값: '연결과 패턴에 관한 복잡한 질문에 답하기 위해 지식 베이스의 정보 간 관계에 액세스하고 분석합니다.' (생성 시에만 설정할 수 있습니다.)

vectorStoreName:

string

쿼리할 벡터 저장소의 이름입니다. (생성 시 설정하거나 런타임에 재정의할 수 있습니다.)

indexName:

string

벡터 저장소 내 인덱스의 이름입니다. (생성 시 설정하거나 런타임에 재정의할 수 있습니다.)

model:

EmbeddingModel

벡터 검색에 사용할 임베딩 Model입니다. (생성 시에만 설정할 수 있습니다.)

enableFilter?:

boolean

= false

메타데이터를 기반으로 결과 필터링을 활성화합니다. (생성 시에만 설정할 수 있지만 요청 컨텍스트에 필터가 제공되면 자동으로 활성화됩니다.)

includeSources?:

boolean

= true

전체 검색 객체를 결과에 포함합니다. (생성 시 설정하거나 런타임에 재정의할 수 있습니다.)

graphOptions?:

GraphOptions

= 기본 그래프 옵션

그래프 기반 검색을 위한 구성

GraphOptions

dimension?:

number

임베딩 벡터의 차원

threshold?:

number

노드 간 에지를 생성하기 위한 유사도 임계값(0~1)

randomWalkSteps?:

number

그래프 탐색을 위한 랜덤 워크의 단계 수입니다. (생성 시 설정하거나 런타임에 재정의할 수 있습니다.)

restartProb?:

number

쿼리 노드에서 랜덤 워크를 다시 시작할 확률입니다. (생성 시 설정하거나 런타임에 재정의할 수 있습니다.)

providerOptions?:

Record<string, Record<string, any>>

임베딩 Model을 위한 Provider별 옵션입니다(예: outputDimensionality). AI SDK EmbeddingModelV2 Model에서만 작동합니다. V1 Model의 경우 Model 자체를 생성할 때 옵션을 구성하세요.

vectorStore?:

MastraVector | VectorStoreResolver

직접 지정한 벡터 저장소 인스턴스 또는 동적 선택을 위한 리졸버 함수입니다. 요청 컨텍스트에 따라 벡터 저장소를 선택하는 멀티테넌트 애플리케이션에서는 함수를 사용하세요. 이 값을 제공하면 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 설명을 사용자 정의하는 방법을 보여줍니다.

예: 요청 컨텍스트 사용

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

요청 컨텍스트를 사용하는 경우 요청 컨텍스트를 통해 실행 시 필수 매개변수를 제공하세요.

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 요청 컨텍스트
• 요청 컨텍스트

다중 테넌트 애플리케이션을 위한 동적 벡터 저장소

각 테넌트에 격리된 데이터가 있는 다중 테넌트 애플리케이션의 경우 정적 벡터 저장소 대신 확인 함수를 전달할 수 있습니다.

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 - 동적 벡터 저장소를 참조하세요.

관련된

• createVectorQueryTool
• 그래프RAG