Chroma 運作模式
Chroma 常見有兩種本地使用模式：
1. **記憶體模式（Ephemeral / In-memory）**
2. **永久儲存模式（Persistent）**
兩者的 API 很接近，主要差別在於資料是否寫入磁碟。
---
## 1. 記憶體模式
記憶體模式會將 collection、文件與向量存放在目前 Python 程序的記憶體中。
### 建立記憶體客戶端
```python
import chromadb
client = chromadb.Client()
# 或：
# client = chromadb.EphemeralClient()
```
建立 collection 並加入資料：
```python
collection = client.get_or_create_collection(
name="my_collection"
)
collection.add(
ids=["id1", "id2"],
documents=[
"Chroma 是一個向量資料庫。",
"向量資料庫可以用於語意搜尋。"
],
metadatas=[
{"category": "database"},
{"category": "search"}
]
)
```
執行查詢：
```python
results = collection.query(
query_texts=["什麼是向量資料庫？"],
n_results=2
)
print(results)
```
### 特性
- 資料只存在於目前程序中
- Python 程序結束後，資料會消失
- 不需要管理資料庫目錄
- 適合：
- 單元測試
- 快速原型
- 臨時實驗
- Notebook 測試
- 不需要保留資料的工作
例如，下列程式重新啟動後，之前的資料不會存在：
```python
import chromadb
client = chromadb.Client()
collection = client.get_or_create_collection("my_collection")
print(collection.count())
```
每次建立新的 `Client()`，通常都是新的暫存資料庫。
---
## 2. 永久儲存模式
永久儲存模式會將 Chroma 的資料寫入指定的本地目錄。程式重新啟動後，可以使用同一個路徑重新載入資料。
### 建立永久儲存客戶端
```python
import chromadb
client = chromadb.PersistentClient(
path="./chroma_data"
)
```
加入資料：
```python
collection = client.get_or_create_collection(
name="my_collection"
)
collection.add(
ids=["id1", "id2"],
documents=[
"Chroma 是一個向量資料庫。",
"向量資料庫可以用於語意搜尋。"
]
)
```
資料會儲存在：
```text
./chroma_data
```
之後重新執行程式，只要使用相同的路徑和 collection 名稱，就能讀取原本的資料：
```python
import chromadb
client = chromadb.PersistentClient(
path="./chroma_data"
)
collection = client.get_collection(
name="my_collection"
)
print(collection.count())
results = collection.query(
query_texts=["什麼是向量資料庫？"],
n_results=2
)
print(results)
```
### 特性
- 資料會寫入磁碟
- 程序結束後資料仍會保留
- 不需要自行呼叫 `persist()`
- 適合：
- 本地 RAG 應用程式
- 文件索引
- 聊天機器人的知識庫
- 開發環境資料儲存
- 小型或中型本地向量資料庫
目前版本通常會自動儲存變更，因此不需要像舊版本一樣手動執行：
```python
client.persist()
```
---
## 3. 兩種模式的完整比較
| 項目 | 記憶體模式 | 永久儲存模式 |
|---|---|---|
| 建立方式 | `chromadb.Client()` | `chromadb.PersistentClient(path=...)` |
| 儲存位置 | RAM | 磁碟 |
| 程序結束後資料 | 消失 | 保留 |
| 是否需要指定路徑 | 否 | 是 |
| 適合測試 | 很適合 | 可以，但較慢 |
| 適合正式本地應用 | 通常不適合 | 適合 |
| 備份方式 | 無法直接備份 | 備份資料目錄 |
| 多程序共享 | 不適合 | 需要考慮存取限制 |
---
## 4. 使用 embedding function
如果使用文件查詢，Chroma 需要將文字轉換成向量。可以使用預設 embedding function，也可以指定自己的 embedding function。
例如：
```python
import chromadb
from chromadb.utils import embedding_functions
client = chromadb.PersistentClient(
path="./chroma_data"
)
embedding_fn = embedding_functions.SentenceTransformerEmbeddingFunction(
model_name="all-MiniLM-L6-v2"
)
collection = client.get_or_create_collection(
name="documents",
embedding_function=embedding_fn
)
```
加入與查詢：
```python
collection.add(
ids=["doc1", "doc2"],
documents=[
"Python 是一種程式語言。",
"Chroma 可以儲存文字向量。"
]
)
results = collection.query(
query_texts=["如何儲存文件向量？"],
n_results=1
)
print(results["documents"])
```
重新開啟同一個永久資料庫時，最好使用一致的 embedding 設定：
```python
client = chromadb.PersistentClient(
path="./chroma_data"
)
collection = client.get_collection(
name="documents",
embedding_function=embedding_fn
)
```
否則可能造成查詢向量與原有文件向量使用不同模型，導致搜尋品質不正確。
---
## 5. 使用 Chroma Server 的方式
除了在同一個 Python 程序中使用 Chroma，也可以啟動 Chroma Server，讓其他程式透過 HTTP 存取。
啟動伺服器：
```bash
chroma run --path ./chroma_data
```
Python 客戶端：
```python
import chromadb
client = chromadb.HttpClient(
host="localhost",
port=8000
)
collection = client.get_or_create_collection(
name="my_collection"
)
```
這種方式的特點是：
- Chroma Server 負責管理資料
- 資料可持久化到指定目錄
- 多個應用程式可以透過 HTTP 存取
- 適合將 Chroma 與應用程式分離
- 比單純的 `PersistentClient` 更適合服務化部署
---
## 6. 建議的選擇方式
### 測試或實驗
```python
client = chromadb.EphemeralClient()
```
適合不需要保存資料的情況。
### 本地 RAG 或文件搜尋
```python
client = chromadb.PersistentClient(
path="./data/chroma"
)
```
這通常是最簡單的永久儲存方案。
### 多個服務或正式部署
```python
client = chromadb.HttpClient(
host="chroma-server",
port=8000
)
```
由獨立 Chroma Server 管理資料。
---
## 7. 常見注意事項
### 不要混用不同的資料路徑
以下兩個 client 指向不同資料庫：
```python
chromadb.PersistentClient(path="./db1")
chromadb.PersistentClient(path="./db2")
```
即使 collection 名稱相同，資料也不會互通。
### Collection 名稱需要一致
重新載入資料時：
```python
collection = client.get_collection("my_collection")
```
名稱必須與建立時相同。
### 永久資料庫目錄需要備份
對本地部署而言，可以備份：
```text
./chroma_data
```
但在備份時最好先停止正在寫入資料的程序，以避免資料不一致。
### 不要讓多個程序任意同時寫入同一個本地資料庫
如果多個程序需要同時存取，建議使用 Chroma Server，而不是讓多個程序直接操作同一個 `PersistentClient` 資料目錄。
---
簡單來說：
```python
# 記憶體模式：程式結束後資料消失
client = chromadb.Client()
```
```python
# 永久儲存模式：資料寫入指定目錄
client = chromadb.PersistentClient(
path="./chroma_data"
)
```
若只是測試，使用記憶體模式；若要建立可重複使用的知識庫或 RAG 應用，通常應使用永久儲存模式。
相關學習地圖、教學課程
Python 人工智慧