跳至主要內容

DatabaseConfig

使用向量查詢工具時，DatabaseConfig 類型可讓你指定資料庫專用設定。這些設定讓你運用不同向量資料庫提供的功能及最佳化選項。

類型定義
類型定義 的直接連結

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

各資料庫專用類型
各資料庫專用類型 的直接連結

PineconeConfig
pineconeconfig 的直接連結

Pinecone 向量資料庫專用的設定選項。

namespace?:

string
Pinecone namespace，用於整理及隔離同一索引內的向量，適合多租戶或環境分隔。

sparseVector?:

{ indices: number[]; values: number[]; }
用於混合搜尋的稀疏向量，結合密集及稀疏 embedding，可改善關鍵字查詢的搜尋質素。indices 及 values 陣列的長度必須相同。
object

indices:

number[]
稀疏向量組成部分的索引陣列

values:

number[]
與索引對應的值陣列

使用情境：

  • 多租戶應用程式（每個租戶使用獨立 namespace）
  • 環境隔離（dev/staging/prod namespace）
  • 結合語意及關鍵字配對的混合搜尋

PgVectorConfig
pgvectorconfig 的直接連結

配合 pgvector 擴充功能的 PostgreSQL 專用設定選項。

minScore?:

number
結果的最低相似度分數門檻。只會傳回相似度分數高於此值的向量。

ef?:

number
HNSW 搜尋參數，控制搜尋期間動態候選清單的大小。數值越高，準確度越高，但速度會下降。通常設定在 topK 至 200 之間。

probes?:

number
IVFFlat probe 參數，指定搜尋期間要存取的索引單元數目。數值越高，召回率越高，但速度會下降。

效能指引：

  • ef：由 topK 值的 2 至 4 倍開始，需要更高準確度時再提高
  • probes：由 1 至 10 開始，需要更高召回率時再提高
  • minScore：視乎質素要求，使用 0.5 至 0.9 之間的值

使用情境：

  • 針對高負載情境最佳化效能
  • 透過質素篩選移除不相關結果
  • 微調搜尋準確度與速度之間的取捨

ChromaConfig
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
turbopufferconfig 的直接連結

Turbopuffer 向量資料庫專用的設定選項。

consistency?:

'strong' | 'eventual'
查詢的一致性級別。"strong"（預設）保證查詢可看到查詢開始前寫入的所有資料，但延遲較高。"eventual" 的延遲較低，但最近寫入的資料可能尚未可見。

使用情境：

  • 對延遲敏感並可接受資料略為過時的查詢（eventual）
  • 必須看到最新資料的寫後讀工作流程（strong）

使用範例
使用範例 的直接連結

基本資料庫設定
基本資料庫設定 的直接連結

import { createVectorQueryTool } from '@mastra/rag'

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

擴充性
擴充性 的直接連結

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. 環境設定：不同環境使用不同的 namespace 或設定
  2. 效能調校：先使用預設值，再按具體需要調整
  3. 質素篩選：使用 minScore 篩除質素較低的結果
  4. 執行階段彈性：在執行階段覆寫設定，以配合執行階段定義的情境
  5. 文件記錄：記錄具體設定選擇，供團隊成員參考

遷移指南
遷移指南 的直接連結

現有向量查詢工具無需修改即可繼續運作。要加入資料庫設定：

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