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

# createGraphRAGTool()

그만큼`createGraphRAGTool()`문서 간의 의미 관계 그래프를 작성하여 RAG를 향상시키는 Tool을 만듭니다. 그것은`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의 사용자 지정 설명입니다. 기본값: '연결과 패턴에 관한 복잡한 질문에 답하기 위해 지식 베이스의 정보 간 관계에 액세스하고 분석합니다.' (생성 시에만 설정할 수 있습니다.)

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

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

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

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

**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/ko/docs/server/request-context)
- [요청 컨텍스트](https://mastra.zisheng.pro/ko/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/ko/reference/tools/vector-query-tool)를 참조하세요.

## 관련된

- [createVectorQueryTool](https://mastra.zisheng.pro/ko/reference/tools/vector-query-tool)
- [그래프RAG](https://mastra.zisheng.pro/ko/reference/rag/graph-rag)