Chroma 向量儲存

ChromaVector 類別使用開源 embedding 資料庫 Chroma 提供向量搜尋。 它提供高效的向量搜尋，並支援 metadata 篩選及混合搜尋。

資訊

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 header

fetchOptions?:

RequestInit

HTTP 請求的其他 fetch 選項

執行 Chroma 伺服器

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

安裝 @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

向量維度（必須與你的 embedding 模型相符）

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

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

forkIndex()

注意：只有 Chroma Cloud，或自行部署的 OSS 分散式 Chroma 支援 fork。

forkIndex 讓你即時 fork 現有的 Chroma 索引。對 fork 後索引進行的操作不會影響原始索引。詳情請參閱 Chroma 說明文件。

indexName:

string

要 fork 的索引名稱

newIndexName:

string

fork 後的索引名稱

upsert()

indexName:

string

要 upsert 的索引名稱

vectors:

number[][]

embedding 向量陣列

metadata?:

Record<string, any>[]

每個向量的 metadata

ids?:

string[]

選填的向量 ID（如未提供則自動產生）

documents?:

string[]

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

query()

使用 queryVector 查詢索引。按與 queryVector 的距離排序，傳回語意相似的記錄陣列。每項記錄的結構如下：

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

你亦可向 query 呼叫提供 metadata 的結構，以進行類型推斷：query<T>()。

indexName:

string

要查詢的索引名稱

queryVector:

number[]

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

topK?:

number

= 10

要傳回的結果數量

filter?:

Record<string, any>

查詢所用的 metadata 篩選條件

includeVector?:

boolean

= false

是否在結果中包含向量

documentFilter?:

Record<string, any>

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

get()

按 ID、metadata 及文件篩選條件，從 Chroma 索引取得記錄。它會傳回結構如下的記錄陣列：

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

你亦可向 get 呼叫提供 metadata 的結構，以進行類型推斷：get<T>()。

indexName:

string

要查詢的索引名稱

ids?:

string[]

要傳回的記錄 ID 列表。如未提供，則傳回所有記錄。

filter?:

Record<string, any>

Metadata 篩選條件.

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 或 metadata 篩選條件更新單一向量。必須提供 id 或 filter，但不可同時提供兩者。

indexName:

string

包含該向量的索引名稱 to update

id?:

string

要更新的向量 ID（與 filter 互斥）

filter?:

Record<string, any>

用於識別要更新向量的 metadata 篩選條件（與 id 互斥）

update:

object

更新參數

update 物件可包含：

vector?:

number[]

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

metadata?:

Record<string, any>

用於取代現有 metadata 的新 metadata

範例：

// 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

包含該向量的索引名稱 to delete

id:

string

要刪除的向量 ID

deleteVectors()

按 ID 或 metadata 篩選條件刪除多個向量。此方法支援批量刪除及按來源管理向量。必須提供 ids 或 filter，但不可同時提供兩者。

indexName:

string

包含該向量的索引名稱s to delete

ids?:

string[]

要刪除的向量 ID 陣列（與 filter 互斥）

filter?:

Record<string, any>

用於識別要刪除向量的 metadata 篩選條件（與 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
  }
}

相關內容

• Metadata 篩選條件