Chroma怎么用 Python向量数据库入门教程

Chroma是一个轻量级的Python向量数据库，几行代码就能上手，特别适合做AI知识库原型和开发测试。它可以把文本转换为向量并保存，再根据问题的语义找出相关内容。下面从安装、写入到查询走一遍流程；示例使用本地持久化目录，适合边学边改。

第一步：安装Chroma

先确认电脑已安装Python，再打开终端运行 pip install chromadb。建议在项目目录创建虚拟环境，避免依赖和其他项目冲突：运行 python -m venv .venv，激活环境后再安装。Windows可用 .venv\Scripts\activate，macOS或Linux可用 source .venv/bin/activate。

安装完成后，新建一个Python文件，例如 demo.py，输入 import chromadb 并运行。如果没有报错，就说明基础环境已经就绪。若电脑上有多个Python版本，安装和运行时尽量使用同一个解释器，比如用 python -m pip install chromadb 安装，能减少“装好了却导入失败”的情况。

第二步：创建集合和添加文档

Chroma用集合（collection）组织数据，可以把它理解成存放一类文本的容器。创建客户端时使用 PersistentClient(path=”./chroma_data”)，数据会写入本地目录，程序关闭后仍可读取。接着调用 get_or_create_collection(name=”notes”) 获取集合；重复运行脚本时也能继续使用已有集合。

准备好文本后，用 collection.add() 添加记录。每条记录都要有唯一ID，文档正文放在documents里，还可以把来源、分类等信息放进metadatas。示例：collection.add(ids=[“a1″,”a2”], documents=[“退款需要提供订单号。”,”工作日客服在线时间为上午九点到下午六点。”], metadatas=[{“topic”:”售后”},{“topic”:”客服”}])。ID重复时不要再次用add写入同一条数据，可改用更新或upsert思路。

配置嵌入函数

向量是文本含义的数字表示。入门时可以先不传嵌入函数，Chroma会使用默认嵌入配置，把文档和查询文本转换成向量；这样最少代码就能完成语义检索。首次运行可能需要下载模型资源，请保持网络可用，并给程序一些时间。实际项目中，添加数据和查询时应使用匹配的嵌入模型。

如果要换成自定义模型，可以创建符合Chroma接口的嵌入函数，并在创建集合时通过 embedding_function 参数传入。无论选择内置还是自定义方案，都要确保写入文档和查询文本使用同一套向量生成方式；模型不一致会让相似度结果失去可比性。还要留意模型所需依赖、运行设备和文本长度限制。

第三步：语义搜索查询

查询时调用 collection.query(query_texts=[“怎样联系在线客服？”], n_results=2)，Chroma会返回语义上接近的记录。结果通常包含匹配到的ID、文档、元数据和距离值。可以先打印结果检查召回内容，再调整返回数量。距离值的解释取决于所用距离度量，一般先比较同一配置下的结果，不要直接把数值当作概率。

例如，尽管问题里没有“工作日”或“客服在线时间”的原句，系统仍可能找到客服时间说明，因为它们表达的意思相关。需要进一步缩小范围时，可在查询中添加 where={“topic”:”客服”} 进行元数据筛选。若结果不理想，先检查文本是否切分合理、嵌入模型是否一致，再优化查询措辞或筛选条件。

完成入门流程后，可以把文档切成适当长度的片段，记录来源和页码，并在检索后将片段交给生成模型回答，这就是常见的知识库检索流程。测试阶段可先用本地持久化目录；准备部署时，再评估备份、并发访问和权限需求。国内也可了解01Agent，官网地址：01agent.cgref.cn。本文由润灭整理，建议先用少量样例验证效果，再逐步扩充数据。