chroma-ops

Chroma 向量库的自托管运行、认证、备份与容量运维。

补充说明

Chroma 以 SQLite 加 HNSW 段文件为本地存储，既能嵌入式运行，也能起 HTTP 服务。自托管运维的关键是单写者约束、持久卷、认证、批量上限和版本兼容。

基础 API 见 chroma；本页聚焦服务端运行和生产故障。

安装与启动

pip install -U chromadb
chroma run --path ./chroma-data --host 0.0.0.0 --port 8000
curl -s http://localhost:8000/api/v2/heartbeat

常用示例

用 Docker 启动并开启 token 认证：

docker run -d --name chroma \
  -p 8000:8000 \
  -v "$PWD/chroma-data:/data" \
  -e CHROMA_SERVER_AUTHN_PROVIDER="chromadb.auth.token_authn.TokenAuthenticationServerProvider" \
  -e CHROMA_SERVER_AUTHN_CREDENTIALS="$CHROMA_TOKEN" \
  chromadb/chroma:"$CHROMA_VERSION"

镜像版本的挂载点可能是 /data，也可能是 /chroma/chroma；先 docker inspect 或查看该版本文档确认。

客户端带 token 访问，并做一次写入和查询：

python - <<'PY'
import chromadb

client = chromadb.HttpClient(
    host="localhost", port=8000,
    headers={"X-Chroma-Token": "test-token"},
)
print("heartbeat:", client.heartbeat())
col = client.get_or_create_collection("docs", metadata={"hnsw:space": "cosine"})
col.add(ids=["1"], documents=["df -h 查看磁盘使用率"],
        metadatas=[{"source": "ops"}])
print(col.query(query_texts=["磁盘满了"], n_results=3))
PY

服务停止后做一致性备份：

docker stop chroma
tar czf "chroma-backup-$(date +%F).tgz" chroma-data
docker start chroma

恢复时解压到新目录，再用相同版本启动并校验 collection 数量与抽样查询。

易错点与排错

嵌入式 PersistentClient 和 HTTP 服务不能同时打开同一个持久化目录；SQLite 锁冲突可能导致损坏。
单机 Chroma 不建议多进程/多 worker 同时写同一目录；需要横向扩展时按 collection 分片或使用托管方案。
认证 provider 类名和变量随版本变化；升级后先对照该版本文档，客户端 token 头默认是 X-Chroma-Token。
客户端与服务端大版本不一致会出现 404 或 tenant/database 参数错误；例如 0.5 与 1.x 的 API 路径不同。
单次 add/update 有批量上限（常见实现约 5461 条），超过会报 batch size 错误；按固定大小切批。
不传 embeddings 时会用默认 embedding 函数，首次运行下载 ONNX 模型；离线环境会卡住或失败。
HNSW 的 hnsw:space、hnsw:M、hnsw:construction_ef 等参数在创建集合时确定，事后改 metadata 不会重建索引。
metadata 过滤只支持简单类型；嵌套对象、数组和空 $in 列表容易报错，写入前先规范化。
直接复制运行中的 SQLite 文件和段目录可能得到不一致快照；先停止写入或使用 SQLite backup。
删除 collection 后磁盘不一定立即回收；确认该版本是否提供 vacuum/compaction，必要时重建实例。

读完自测

合上页面，先回答，再展开对照。

为什么不能让嵌入式和 HTTP 服务共用同一个目录？
开启 token 认证需要哪些环境变量？
HNSW 参数什么时候能改？

答案

两者都基于 SQLite 和本地段文件，缺少跨进程的协调。并发写入会争抢文件锁，可能报 database is locked，严重时损坏数据。
设置 CHROMA_SERVER_AUTHN_PROVIDER=chromadb.auth.token_authn.TokenAuthenticationServerProvider 和 CHROMA_SERVER_AUTHN_CREDENTIALS=<token>；客户端在请求头带同一个 token。
空间距离和构图参数在集合创建时生效，之后修改 metadata 不会重建索引。需要调整时新建集合并重新写入向量。