Chroma 向量数据库怎么用：Python 本地写入与查询验证
Chroma 是一个轻量级向量数据库，适合在本地或单机环境快速验证语义检索。
它不需要单独部署服务端，用 Python 包就能启动，数据默认保存在内存或指定目录。
本文从零开始，用一段可运行的代码完成安装、写入和查询，并说明容易卡住的地方。
安装前确认 Python 与依赖环境
Chroma 要求 Python 3.8 及以上版本。
建议单独建虚拟环境，避免和系统包冲突：
python3 -m venv chroma-env
source chroma-env/bin/activate
pip install chromadb安装完成后用下面命令确认版本，不同版本的 API 细节可能有差异，后续代码以当前主流 0.5.x 为例：
pip show chromadb如果 pip 安装很慢，
可以临时换国内镜像源，
例如 pip install chromadb -i https:。
//pypi.tuna.tsinghua.edu.cn/simple
用持久化模式启动客户端并建集合
Chroma 支持内存模式和持久化模式。
内存模式重启后数据丢失，适合一次性测试；
持久化模式会把数据写到本地目录，适合后续反复查询。
import chromadb
client = chromadb.PersistentClient(path="./chroma_data")
collection = client.get_or_create_collection(name="demo_docs")get_or_create_collection 在集合不存在时创建，已存在时直接获取，重复执行不会报错。
集合名建议用小写字母和下划线，避免特殊字符。
写入文档并执行相似度查询
Chroma 默认自带一个轻量 Embedding 函数，首次写入时会自动下载模型文件。
如果网络受限，可以改用自定义 Embedding 函数，或者先把模型文件缓存到本地。
下面写入三条带元数据的文档，然后查询与“如何备份数据库”最接近的结果：
collection.add(
ids=["doc1", "doc2", "doc3"],
documents=[
"定期备份数据库可以防止数据丢失",
"服务器重启前应先保存当前配置",
"向量检索适合处理语义相似度问题"
],
metadatas=[
{"category": "backup"},
{"category": "ops"},
{"category": "search"}
]
)
result = collection.query(
query_texts=["数据库备份方法"],
n_results=2
)
print(result["documents"])
print(result["distances"])预期输出中第一条文档应该是与备份最相关的内容，distances 数值越小表示越相似。
如果返回空列表，先检查 documents 是否为空，再确认 Embedding 函数是否成功加载。
常见报错与避坑说明
下载模型超时：默认 Embedding 函数依赖外网下载模型。
可以设置环境变量 HF_ENDPOINT 指向镜像，或改用 sentence-transformers 本地模型。
集合已存在但结构不一致：修改 Embedding 函数后建议新建集合名，不要复用旧集合，否则维度可能不匹配。
持久化目录权限不足：path 指向的目录需要当前用户有读写权限，建议用绝对路径并提前创建目录。
查询结果为空但文档已写入：用 collection.count() 确认文档数量，再检查 query_texts 是否为空字符串。
验证数据是否真正持久化
关闭 Python 进程后重新打开，重新执行 PersistentClient 和 get_collection，用 collection.count() 查看文档数。
如果数量与写入时一致，说明持久化正常。
再执行一次 query，确认返回结果稳定。
对于生产环境，建议把 Chroma 放在独立目录，并定期备份 chroma_data 文件夹。
单机 Chroma 适合中小规模数据；
数据量很大或需要多节点并发时，应评估服务端模式或专用向量数据库。
常见疑问
Chroma 必须单独安装服务端吗？
不需要。Python 客户端内置了本地存储，直接 PersistentClient 就能用。只有需要多客户端共享数据时才考虑启动独立服务。
默认 Embedding 函数可以换成中文模型吗？
可以。创建集合时传入自定义 embedding_function，例如 sentence-transformers 的中文模型，但要注意后续查询必须使用同一个函数。
写入数据后修改文档内容怎么办？
Chroma 支持 update 方法，按 id 更新文档和元数据。如果只是追加新文档，继续调用 add 即可。
查询时如何按元数据过滤？
在 query 中传入 where={"category": "backup"} 即可只检索指定分类的文档，适合按业务标签缩小范围。
