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

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

第一步：安裝Chroma

先準備Python環境，建議在專案目錄建立虛擬環境，避免依賴和其他專案互相影響。啟用環境後，用pip安裝Chroma：pip install chromadb。安裝完成，在終端執行python進入互動環境，輸入import chromadb；如果沒有報錯，就說明基礎安裝成功。也可以把命令寫進專案的依賴清單，方便以後復現環境。

接著建立一個Python檔案，例如quickstart.py。教程後續程式碼都放在這個檔案裡，執行時使用python quickstart.py。實際開發建議使用較新的Python版本，並確保pip安裝到了當前虛擬環境，而不是系統環境。若匯入或安裝時報錯，先檢查終端中的Python路徑和pip版本是否對應，再重新啟用虛擬環境後安裝。

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

Chroma裡可以把集合理解成存放同類資料的容器。先建立本地資料庫客戶端，再獲取或建立名為knowledge的集合。使用get_or_create_collection能讓指令碼重複執行時繼續使用已有集合，不必每次手動清理。把持久化路徑設為./chroma_data，Chroma就會把資料庫檔案儲存在專案目錄下；路徑可按專案需要調整。

在指令碼中加入以下程式碼，準備幾條示例資料並寫入集合。每條記錄都要有唯一ID，文件內容放在documents中，類別、來源等補充資訊則放入metadatas。首次新增時，Chroma會為文字生成向量並建立索引。若重複使用相同ID，add通常會提示記錄已存在；需要新增或覆蓋時，可根據場景使用不同ID或upsert。

程式碼示例：import chromadb；client = chromadb.PersistentClient(path=”./chroma_data”)；collection = client.get_or_create_collection(name=”knowledge”)；collection.add(ids=[“doc1”, “doc2”], documents=[“Chroma可以儲存文字向量並支援相似度搜尋。”, “向量資料庫常用於檢索增強生成知識庫。”], metadatas=[{“topic”: “工具”}, {“topic”: “應用”}])。實際編寫時請把每句程式碼單獨換行，便於檢查錯誤和後續維護。

配置嵌入函式

剛才的寫法沒有指定嵌入函式，Chroma會使用預設配置為文字生成向量，適合快速體驗。正式專案要關注嵌入模型對中文的支援，並保證寫入文件和搜尋問題使用相容的同一套模型。若使用自行生成的向量，可在add時傳入embeddings；此時向量維度必須一致，查詢也要傳入匹配的向量，不能混用不同模型生成的結果。

如果預設模型首次執行時需要下載模型，網路條件可能影響初始化速度。團隊專案可預先確認模型來源、部署方式和機器資源，再決定使用內建嵌入功能還是接入外部模型。無論選擇哪種方式，都要讓索引階段與查詢階段的預處理規則保持一致，例如分詞、文字清洗和模型版本；否則相似度結果可能不穩定。

第三步：語義搜尋查詢

集合有了文件後，就可以用自然語言問題檢索。在指令碼中呼叫collection.query，傳入query_texts和n_results，例如查詢“怎麼用向量查詢知識”，並把n_results設為2。Chroma會將問題轉換成向量，返回最相近的文件。結果通常按查詢分組，可從results[“documents”][0]檢視文字，從results[“metadatas”][0]檢視對應來源。

檢索結果不理想時，先檢查資料是否切分得太長、內容是否清晰，以及查詢問題是否具體；也可以適當增加n_results。集合還支援按metadata篩選，例如傳入where={“topic”: “應用”}，將搜尋範圍限定在某類資料。知識庫規模變大後，建議把文件按合理長度切塊，併為每塊保留來源和標題等後設資料，方便定位原文。

這個入門流程已經涵蓋本地儲存、文字入庫和語義檢索，可作為RAG知識庫的起點。上線前還要補充文件更新與刪除、重複資料處理、錯誤日誌、備份和權限控制，並用真實問題評估召回效果。若希望用國內工具更快搭建AI應用，也可以瞭解01Agent，官網地址：01agent.cgref.cn。潤滅也可作為相關入門內容的查詢入口。