데이터베이스구성

그만큼DatabaseConfigtype을 사용하면 벡터 쿼리 Tool을 사용할 때 데이터베이스별 구성을 지정할 수 있습니다. 이러한 구성을 통해 다양한 벡터 스토어에서 제공하는 기능과 최적화를 사용할 수 있습니다.

유형 정의

export type DatabaseConfig = {
  pinecone?: PineconeConfig
  pgvector?: PgVectorConfig
  chroma?: ChromaConfig
  turbopuffer?: TurbopufferConfig
  [key: string]: any // Extensible for future databases
}

데이터베이스별 유형

PineconeConfig

Pinecone 벡터 저장소와 관련된 구성 옵션입니다.

namespace?:

string

동일한 인덱스 내에서 벡터를 구성하고 격리하는 Pinecone 네임스페이스입니다. 다중 테넌시 또는 환경 분리에 유용합니다.

sparseVector?:

{ indices: number[]; values: number[]; }

밀집 임베딩과 희소 임베딩을 결합하는 하이브리드 검색용 희소 벡터입니다. 키워드 기반 쿼리의 검색 품질을 높입니다. indices 배열과 values 배열의 길이는 같아야 합니다.

object

indices:

number[]

희소 벡터 구성 요소의 인덱스 배열입니다.

values:

number[]

인덱스에 대응하는 값의 배열입니다.

사용 사례:

• 다중 테넌트 애플리케이션(테넌트당 별도의 네임스페이스)
• 환경 격리(dev/staging/prod 네임스페이스)
• 의미론적 일치와 키워드 일치를 결합한 하이브리드 검색

PgVectorConfig

pgVector 확장자를 사용하는 PostgreSQL 관련 구성 옵션입니다.

minScore?:

number

결과의 최소 유사도 점수 임곗값입니다. 유사도 점수가 이 값보다 높은 벡터만 반환됩니다.

ef?:

number

검색 중 동적 후보 목록의 크기를 제어하는 HNSW 검색 매개변수입니다. 값이 클수록 속도를 희생하여 정확도가 높아집니다. 일반적으로 topK와 200 사이로 설정합니다.

probes?:

number

검색 중 방문할 인덱스 셀 수를 지정하는 IVFFlat 프로브 매개변수입니다. 값이 클수록 속도를 희생하여 재현율이 높아집니다.

성능 지침:

• 에프: topK 값의 2~4배로 시작하고 정확도를 높이려면 높이세요.
• 프로브: 1-10으로 시작하고 더 나은 기억을 위해 증가시킵니다.
• 최소점수: 품질 요구 사항에 따라 0.5-0.9 사이의 값을 사용하십시오.

사용 사례:

• 고부하 시나리오를 위한 성능 최적화
• 관련 없는 결과를 제거하는 품질 필터링
• 검색 정확도와 속도 균형의 미세 조정

ChromaConfig

Chroma 벡터 저장소와 관련된 구성 옵션입니다.

where?:

Record<string, any>

MongoDB 방식 쿼리 구문을 사용하는 메타데이터 필터링 조건입니다. 메타데이터 필드를 기준으로 결과를 필터링합니다.

whereDocument?:

Record<string, any>

문서 콘텐츠 필터링 조건입니다. 실제 문서의 텍스트 콘텐츠를 기준으로 필터링할 수 있습니다.

필터 구문 예:

// Simple equality
where: { "category": "technical" }

// Operators
where: { "price": { "$gt": 100 } }

// Multiple conditions
where: {
  "category": "electronics",
  "inStock": true
}

// Document content filtering
whereDocument: { "$contains": "API documentation" }

사용 사례:

• 고급 메타데이터 필터링
• 컨텐츠 기반 문서 필터링
• 복잡한 쿼리 조합

TurbopufferConfig

Turbopuffer 벡터 저장소와 관련된 구성 옵션입니다.

consistency?:

'strong' | 'eventual'

쿼리의 일관성 수준입니다. "strong"(기본값)은 지연 시간이 늘어나는 대신 쿼리가 시작되기 전에 기록된 모든 데이터를 쿼리에서 볼 수 있도록 보장합니다. "eventual"은 지연 시간이 짧지만 최근에 기록된 데이터가 아직 표시되지 않을 수 있습니다.

사용 사례:

• 약간 오래된 데이터가 허용되는 지연 시간에 민감한 쿼리(eventual)
• 최신 데이터를 확인해야 하는 작성한 내용 읽기 Workflow(strong)

사용 예

Basic Usage

기본 데이터베이스 구성

import { createVectorQueryTool } from '@mastra/rag'

const vectorTool = createVectorQueryTool({
  vectorStoreName: 'pinecone',
  indexName: 'documents',
  model: embedModel,
  databaseConfig: {
    pinecone: {
      namespace: 'production',
    },
  },
})

Runtime Override

런타임 구성 재정의

import { RequestContext } from '@mastra/core/request-context'

// Initial configuration
const vectorTool = createVectorQueryTool({
  vectorStoreName: 'pinecone',
  indexName: 'documents',
  model: embedModel,
  databaseConfig: {
    pinecone: {
      namespace: 'development',
    },
  },
})

// Override at runtime
const requestContext = new RequestContext()
requestContext.set('databaseConfig', {
  pinecone: {
    namespace: 'production',
  },
})

await vectorTool.execute({ queryText: 'search query' }, { mastra, requestContext })

Multi-Database

다중 데이터베이스 구성

const vectorTool = createVectorQueryTool({
  vectorStoreName: 'dynamic', // Will be determined at runtime
  indexName: 'documents',
  model: embedModel,
  databaseConfig: {
    pinecone: {
      namespace: 'default',
    },
    pgvector: {
      minScore: 0.8,
      ef: 150,
    },
    chroma: {
      where: { type: 'documentation' },
    },
  },
})

노트

다중 데이터베이스 지원: 여러 데이터베이스를 구성하는 경우 실제 사용되는 벡터 저장소와 일치하는 구성만 적용됩니다.

Performance Tuning

성능 튜닝

// High accuracy configuration
const highAccuracyTool = createVectorQueryTool({
  vectorStoreName: 'postgres',
  indexName: 'embeddings',
  model: embedModel,
  databaseConfig: {
    pgvector: {
      ef: 400, // High accuracy
      probes: 20, // High recall
      minScore: 0.85, // High quality threshold
    },
  },
})

// High speed configuration
const highSpeedTool = createVectorQueryTool({
  vectorStoreName: 'postgres',
  indexName: 'embeddings',
  model: embedModel,
  databaseConfig: {
    pgvector: {
      ef: 50, // Lower accuracy, faster
      probes: 3, // Lower recall, faster
      minScore: 0.6, // Lower quality threshold
    },
  },
})

확장성

DatabaseConfig 타입은 확장할 수 있도록 설계되었습니다. 새 벡터 데이터베이스 지원을 추가하려면 다음을 수행하세요.

// 1. Define the configuration interface
export interface NewDatabaseConfig {
  customParam1?: string
  customParam2?: number
}

// 2. Extend DatabaseConfig type
export type DatabaseConfig = {
  pinecone?: PineconeConfig
  pgvector?: PgVectorConfig
  chroma?: ChromaConfig
  newdatabase?: NewDatabaseConfig
  [key: string]: any
}

// 3. Use in vector query tool
const vectorTool = createVectorQueryTool({
  vectorStoreName: 'newdatabase',
  indexName: 'documents',
  model: embedModel,
  databaseConfig: {
    newdatabase: {
      customParam1: 'value',
      customParam2: 42,
    },
  },
})

모범 사례

1. 환경 구성: 다양한 환경에 대해 서로 다른 네임스페이스 또는 구성을 사용합니다.
2. 성능 튜닝: 기본값으로 시작하고 특정 요구 사항에 따라 조정합니다.
3. 품질 필터링: minScore를 사용하여 품질이 낮은 결과를 필터링합니다.
4. 런타임 유연성: 런타임 정의 시나리오에 대해 런타임 시 구성 재정의
5. 선적 서류 비치: 팀 구성원을 위한 특정 구성 선택 사항을 문서화합니다.

마이그레이션 가이드

기존 벡터 쿼리 Tool은 변경 없이 계속 작동합니다. 데이터베이스 구성을 추가하려면 다음을 수행하십시오.

const vectorTool = createVectorQueryTool({
  vectorStoreName: 'pinecone',
  indexName: 'documents',
  model: embedModel,
+ databaseConfig: {
+   pinecone: {
+     namespace: 'production'
+   }
+ }
});

관련된

• createVectorQueryTool()
• 하이브리드 벡터 검색
• 메타데이터 필터