Chroma 向量儲存

ChromaVector 類別使用開放原始碼的嵌入資料庫 Chroma 提供向量搜尋。 它提供高效率的向量搜尋、中繼資料篩選與混合搜尋功能。

資訊

Chroma Cloud

Chroma Cloud 支援無伺服器向量搜尋與全文搜尋，具備極高速度、成本效益與大容量，且使用簡便。只需不到 30 秒即可建立資料庫，並使用 5 美元的免費額度試用。

開始使用 Chroma Cloud

建構函式選項

host?:

string

Chroma 伺服器的主機位址。預設為 'localhost'

port?:

number

Chroma 伺服器的連接埠號碼。預設為 8000

ssl?:

boolean

連線是否使用 SSL/HTTPS。預設為 false

apiKey?:

string

Chroma Cloud API 金鑰

tenant?:

string

要連線的 Chroma 伺服器租戶名稱。單節點 Chroma 預設為 'default_tenant'。Chroma Cloud 使用者會依提供的 API 金鑰自動解析

database?:

string

要連線的資料庫名稱。單節點 Chroma 預設為 'default_database'。Chroma Cloud 使用者會依提供的 API 金鑰自動解析

headers?:

Record<string, any>

隨要求一併傳送的其他 HTTP 標頭

fetchOptions?:

RequestInit

HTTP 要求的其他 fetch 選項

執行 Chroma 伺服器

如果你是 Chroma Cloud 使用者，請將 API 金鑰、租戶和資料庫名稱提供給 ChromaVector 建構函式。

安裝 @mastra/chroma 套件後，你便可使用 Chroma CLI，並透過 chroma db connect [DB-NAME] --env-file 將這些值設為環境變數。

否則，你可以透過下列方式設定單節點 Chroma 伺服器：

• 使用 Chroma CLI 在本機執行：chroma run。更多設定選項請參閱 Chroma 文件。
• 使用 Chroma 官方映像檔在 Docker 上執行。
• 在你選擇的 Provider 上部署自己的 Chroma 伺服器。Chroma 提供 AWS、Azure 與 GCP 的範例範本。

方法

createIndex()

indexName:

string

要建立的索引名稱

dimension:

number

向量維度（必須與嵌入模型相符）

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

相似度搜尋使用的距離度量

forkIndex()

注意：只有 Chroma Cloud 或自行部署的開放原始碼分散式 Chroma 支援分叉。

forkIndex 可讓你立即分叉現有的 Chroma 索引。對分叉索引執行的操作不會影響原始索引。詳情請參閱 Chroma 文件。

indexName:

string

要分叉的索引名稱

newIndexName:

string

分叉後的索引名稱

upsert()

indexName:

string

要 upsert 資料的索引名稱

vectors:

number[][]

嵌入向量陣列

metadata?:

Record<string, any>[]

每個向量的中繼資料

ids?:

string[]

選用的向量 ID（未提供時會自動產生）

documents?:

string[]

Chroma 專用：與向量關聯的原始文字文件

query()

使用 queryVector 查詢索引。此方法會依與 queryVector 的距離排序，傳回語意相似的記錄陣列。每筆記錄的結構如下：

{
  id: string;
  score: number;
  document?: string;
  metadata?: Record<string, string | number | boolean>;
  embedding?: number[]
}

你也可以在呼叫 query 時提供中繼資料的結構，以進行型別推斷：query<T>()。

indexName:

string

要查詢的索引名稱

queryVector:

number[]

用於尋找相似向量的查詢向量

topK?:

number

= 10

要傳回的結果數量

filter?:

Record<string, any>

查詢的中繼資料篩選條件

includeVector?:

boolean

= false

結果是否包含向量

documentFilter?:

Record<string, any>

Chroma 專用：要套用至文件內容的篩選條件

get()

依 ID、中繼資料和文件篩選條件，從 Chroma 索引取得記錄。此方法會傳回具下列結構的記錄陣列：

{
  id: string;
  document?: string;
  metadata?: Record<string, string | number | boolean>;
  embedding?: number[]
}

你也可以在呼叫 get 時提供中繼資料的結構，以進行型別推斷：get<T>()。

indexName:

string

要查詢的索引名稱

ids?:

string[]

要傳回的記錄 ID 清單。若未提供，則傳回所有記錄。

filter?:

Record<string, any>

中繼資料篩選條件。

includeVector?:

boolean

= false

結果是否包含向量

documentFilter?:

Record<string, any>

Chroma 專用：要套用至文件內容的篩選條件

limit?:

number

= 100

要傳回的記錄數上限

offset?:

number

0

傳回記錄的位移量。請搭配 limit 使用，以分頁顯示結果。

listIndexes()

以字串陣列傳回索引名稱。

describeIndex()

indexName:

string

要描述的索引名稱

傳回：

interface IndexStats {
  dimension: number
  count: number
  metric: 'cosine' | 'euclidean' | 'dotproduct'
}

deleteIndex()

indexName:

string

要刪除的索引名稱

updateVector()

依 ID 或中繼資料篩選條件更新單一向量。必須提供 id 或 filter 其中一項，但不能同時提供兩者。

indexName:

string

包含待更新向量的索引名稱

id?:

string

要更新的向量 ID（不可與 filter 同時使用）

filter?:

Record<string, any>

用於識別待更新向量的中繼資料篩選條件（不可與 id 同時使用）

update:

object

更新參數

update 物件可包含：

vector?:

number[]

用來取代現有向量的新向量

metadata?:

Record<string, any>

用來取代現有中繼資料的新中繼資料

範例：

// Update by ID
await vectorStore.updateVector({
  indexName: 'docs',
  id: 'vec_123',
  update: { metadata: { status: 'reviewed' } },
})

// Update by filter
await vectorStore.updateVector({
  indexName: 'docs',
  filter: { source_id: 'manual.pdf' },
  update: { metadata: { version: 2 } },
})

deleteVector()

indexName:

string

包含待刪除向量的索引名稱

id:

string

要刪除的向量 ID

deleteVectors()

依 ID 或中繼資料篩選條件刪除多個向量。此方法支援大量刪除與依來源管理向量。必須提供 ids 或 filter 其中一項，但不能同時提供兩者。

indexName:

string

包含待刪除向量的索引名稱

ids?:

string[]

要刪除的向量 ID 陣列（不可與 filter 同時使用）

filter?:

Record<string, any>

用於識別待刪除向量的中繼資料篩選條件（不可與 ids 同時使用）

範例：

// Delete all chunks from a document
await vectorStore.deleteVectors({
  indexName: 'docs',
  filter: { source_id: 'manual.pdf' },
})

// Delete multiple vectors by ID
await vectorStore.deleteVectors({
  indexName: 'docs',
  ids: ['vec_1', 'vec_2', 'vec_3'],
})

// Delete old temporary documents
await vectorStore.deleteVectors({
  indexName: 'docs',
  filter: {
    $and: [{ bucket: 'temp' }, { indexed_at: { $lt: '2025-01-01' } }],
  },
})

回應型別

查詢結果會以下列格式傳回：

interface QueryResult {
  id: string
  score: number
  metadata: Record<string, any>
  document?: string // Chroma-specific: Original document if it was stored
  vector?: number[] // Only included if includeVector is true
}

錯誤處理

此儲存會擲回可攔截的具型別錯誤：

try {
  await store.query({
    indexName: 'index_name',
    queryVector: queryVector,
  })
} catch (error) {
  if (error instanceof VectorStoreError) {
    console.log(error.code) // 'connection_failed' | 'invalid_dimension' | etc
    console.log(error.details) // Additional error context
  }
}

相關內容

• 中繼資料篩選條件