Chroma怎麼用 Python向量資料庫入門教程

Chroma是一個輕量級的Python向量資料庫，幾行程式碼就能上手，特別適合做AI知識庫原型和開發測試。它可以把文字轉換為向量並儲存，再根據問題的語義找出相關內容。下面從安裝、寫入到查詢走一遍流程；示例使用本地持久化目錄，適合邊學邊改。

第一步：安裝Chroma

先確認電腦已安裝Python，再開啟終端執行 pip install chromadb。建議在專案目錄建立虛擬環境，避免依賴和其他專案衝突：執行 python -m venv .venv，啟用環境後再安裝。Windows可用 .venv\Scripts\activate，macOS或Linux可用 source .venv/bin/activate。

安裝完成後，新建一個Python檔案，例如 demo.py，輸入 import chromadb 並執行。如果沒有報錯，就說明基礎環境已經就緒。若電腦上有多個Python版本，安裝和執行時儘量使用同一個直譯器，比如用 python -m pip install chromadb 安裝，能減少“裝好了卻匯入失敗”的情況。

第二步：建立集合和新增文件

Chroma用集合（collection）組織資料，可以把它理解成存放一類文字的容器。建立客戶端時使用 PersistentClient(path=”./chroma_data”)，資料會寫入本地目錄，程式關閉後仍可讀取。接著呼叫 get_or_create_collection(name=”notes”) 獲取集合；重複執行指令碼時也能繼續使用已有集合。

準備好文字後，用 collection.add() 新增記錄。每條記錄都要有唯一ID，文件正文放在documents裡，還可以把來源、分類等資訊放進metadatas。示例：collection.add(ids=[“a1″,”a2”], documents=[“退款需要提供訂單號。”,”工作日客服線上時間為上午九點到下午六點。”], metadatas=[{“topic”:”售後”},{“topic”:”客服”}])。ID重複時不要再次用add寫入同一條資料，可改用更新或upsert思路。

配置嵌入函式

向量是文字含義的數字表示。入門時可以先不傳嵌入函式，Chroma會使用預設嵌入配置，把文件和查詢文字轉換成向量；這樣最少程式碼就能完成語義檢索。首次執行可能需要下載模型資源，請保持網路可用，並給程式一些時間。實際專案中，新增資料和查詢時應使用匹配的嵌入模型。

如果要換成自定義模型，可以建立符合Chroma介面的嵌入函式，並在建立集合時透過 embedding_function 引數傳入。無論選擇內建還是自定義方案，都要確保寫入文件和查詢文字使用同一套向量生成方式；模型不一致會讓相似度結果失去可比性。還要留意模型所需依賴、執行裝置和文字長度限制。

第三步：語義搜尋查詢

查詢時呼叫 collection.query(query_texts=[“怎樣聯絡線上客服？”], n_results=2)，Chroma會返回語義上接近的記錄。結果通常包含匹配到的ID、文件、後設資料和距離值。可以先列印結果檢查召回內容，再調整返回數量。距離值的解釋取決於所用距離度量，一般先比較同一配置下的結果，不要直接把數值當作機率。

例如，儘管問題裡沒有“工作日”或“客服線上時間”的原句，系統仍可能找到客服時間說明，因為它們表達的意思相關。需要進一步縮小範圍時，可在查詢中新增 where={“topic”:”客服”} 進行後設資料篩選。若結果不理想，先檢查文字是否切分合理、嵌入模型是否一致，再最佳化查詢措辭或篩選條件。

完成入門流程後，可以把文件切成適當長度的片段，記錄來源和頁碼，並在檢索後將片段交給生成模型回答，這就是常見的知識庫檢索流程。測試階段可先用本地持久化目錄；準備部署時，再評估備份、併發訪問和權限需求。國內也可瞭解01Agent，官網地址：01agent.cgref.cn。本文由潤滅整理，建議先用少量樣例驗證效果，再逐步擴充資料。