ChromaDB 是什麼、怎麼用：安裝、建集合、寫入與查詢（Python 快速上手）

本文根據 Chroma 官方文檔《Getting Started》和官方倉庫 README 整理，資料核對於 2026-10-11。文中代碼取自官方頁面，沒有在本機運行驗證。

適用於誰

• 搜「chromadb 是什麼」「chromadb 安裝」「chromadb 教學」「chromadb python」的人；
• 想給大模型加一個「先檢索資料再回答」的環節，需要一個最簡單的向量庫來起步的人；
• 在 Dify 之類的平台上用過知識庫，想弄明白底下那一層在做什麼的人。

結論先說

1. Chroma 是一個開源的向量數據庫（官方現在的說法是面向 AI 的開源數據基礎設施），Apache 2.0 許可。
2. pip install chromadb 之後幾行代碼就能用，不需要單獨啟動服務。
3. 你給文本，它負責向量化和索引。官方說明：分詞、嵌入、索引都自動處理；也可以跳過這一步，傳入你自己算好的向量。
4. chromadb.Client() 是內存客戶端，程序結束數據就沒了。要儲存數據，用持久化客戶端或者客戶端-伺服器模式。
5. 查詢返回的是「列表的列表」，因為可以一次查多個問題。

一、向量數據庫是幹什麼的

把一段文字交給嵌入模型，會得到一串數字（向量）。意思相近的文字，向量也相近。向量數據庫做兩件事：把文檔和它們的向量存起來；給一個問題，找出向量最接近的幾段文檔。

這就是 RAG（檢索增強生成）裏「檢索」那一步：先從你的資料裏找出相關片段，再把片段連同問題一起交給大模型。分段和檢索參數怎麼影響效果，可以對照《Dify 知識庫搭建教學》裏的說明，原理是相通的。

二、安裝

bash
pip install chromadb

官方還列了 Poetry（poetry add chromadb）和 uv（uv pip install chromadb）的寫法。JavaScript 客戶端是 npm install chromadb。

三、創建客戶端和集合

python
import chromadb
chroma_client = chromadb.Client()

這是內存客戶端，適合試驗，程序結束後數據不保留。

集合（collection）相當於一張表，用來放一組文檔：

python
collection = chroma_client.create_collection(name="my_collection")

腳本會反覆運行時，用下面這個，避免每次都新建：

python
collection = chroma_client.get_or_create_collection(name="my_collection")

四、寫入文檔

python
collection.add(
    ids=["id1", "id2"],
    documents=[
        "This is a document about pineapple",
        "This is a document about oranges"
    ]
)

• documents：原文。Chroma 會儲存文本，並自動完成嵌入和索引；
• ids：每條文檔一個唯一的字符串 ID，必須自己提供。

還可以帶上元數據，README 的例子：

python
collection.add(
    documents=["This is document1", "This is document2"],
    metadatas=[{"source": "notion"}, {"source": "google-docs"}],
    ids=["doc1", "doc2"],
)

元數據用來記錄來源、日期、類別等資訊，之後可以按它過濾。

add 還是 upsert：官方建議把 add 換成 upsert，這樣同一個腳本重複運行時，不會把同樣的文檔反覆添加：

python
collection.upsert(
    documents=[
        "This is a document about pineapple",
        "This is a document about oranges"
    ],
    ids=["id1", "id2"]
)

五、查詢

python
results = collection.query(
    query_texts=["This is a query document about hawaii"], # Chroma will embed this for you
    n_results=2 # how many results to return
)
print(results)

• query_texts：一個列表，可以同時放多個問題，Chroma 會替你把它們向量化；
• n_results：每個問題返回幾條。官方說明不寫時預設返回 10 條。

返回結果的結構是一個字典，主要的鍵：

每個值都是「列表的列表」：外層對應每個問題，內層是該問題的結果。只查了一個問題時，取 results["documents"][0]。

過濾（README 的註釋裏給出的兩個可選參數）：

• where={"metadata_field": "is_equal_to_this"}：按元數據過濾；
• where_document={"$contains":"search_string"}：按文檔內容是否包含某段文字過濾。

另外可以用 .get 按 ID 直接取文檔。

六、儲存數據

內存客戶端不保留數據。兩條路：

• 持久化客戶端：把數據存到本地磁盤，官方入門頁指向了專門的文檔；
• 客戶端-伺服器模式：單獨運行一個 Chroma 服務，應用通過網絡連接。README 給的啟動命令：

bash
chroma run --path /chroma_db_path

官方還有託管的 Chroma Cloud，提供無伺服器的向量、混合和全文檢索，頁面上寫新用戶有 5 美元的免費額度（2026-10-11 核對，以官網為準）。

七、拿來做 RAG 時的注意點

• 寫入和查詢必須用同一個嵌入模型。換了模型，原來存的向量就對不上了，需要重建；
• 預設的嵌入模型未必適合中文。官方入門頁沒有寫預設用的是哪個模型；處理中文資料時，查一下官方的 Embedding Functions 文檔，選一個支持中文的模型，或者自己算好向量再傳入；
• 先分段再寫入。一整篇長文檔作為一條寫入，檢索出來的也是一整篇，既不準也浪費上下文。按段落或小節切開，每段一條；
• ID 要穩定。用「文檔路徑 + 段落序號」這類可以重複生成的 ID，配合 upsert，更新文檔時才不會產生重複；
• 元數據提前設計。來源、更新時間、權限範圍，之後過濾時都用得上。

常見問題

Q：需要 GPU 嗎？

官方入門頁沒有提硬件要求。數據量不大時在普通電腦上就能試；嵌入模型的計算量取決於你選的模型。

Q：和 Milvus、pgvector 怎麼選？

Chroma 上手最簡單，適合原型和中小規模；已經在用 PostgreSQL 的看《pgvector 是什麼》；預計數據量很大、之後要上集群的看《Milvus Lite 使用教學》。

Q：可以完全離線用嗎？

數據庫本身在本地運行。自動嵌入需要用到嵌入模型，模型從哪裏獲取、是否需要聯網，以官方 Embedding Functions 文檔為準。

Q：結果不準怎麼辦？

先看檢索出來的片段對不對。片段不對，調分段方式或換嵌入模型；片段對但回答不對，問題在提示詞或模型。

參考資料

• Getting Started（Chroma 官方文檔）：https://docs.trychroma.com/docs/overview/getting-started
• chroma-core/chroma（官方倉庫）：https://github.com/chroma-core/chroma