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

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

第一步：安装Chroma

先准备Python环境，建议在项目目录创建虚拟环境，避免依赖和其他项目互相影响。激活环境后，用pip安装Chroma：pip install chromadb。安装完成，在终端运行python进入交互环境，输入import chromadb；如果没有报错，就说明基础安装成功。也可以把命令写进项目的依赖清单，方便以后复现环境。

接着创建一个Python文件，例如quickstart.py。教程后续代码都放在这个文件里，运行时使用python quickstart.py。实际开发建议使用较新的Python版本，并确保pip安装到了当前虚拟环境，而不是系统环境。若导入或安装时报错，先检查终端中的Python路径和pip版本是否对应，再重新激活虚拟环境后安装。

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

Chroma里可以把集合理解成存放同类资料的容器。先创建本地数据库客户端，再获取或创建名为knowledge的集合。使用get_or_create_collection能让脚本重复运行时继续使用已有集合，不必每次手动清理。把持久化路径设为./chroma_data，Chroma就会把数据库文件保存在项目目录下；路径可按项目需要调整。

在脚本中加入以下代码，准备几条示例资料并写入集合。每条记录都要有唯一ID，文档内容放在documents中，类别、来源等补充信息则放入metadatas。首次添加时，Chroma会为文本生成向量并建立索引。若重复使用相同ID，add通常会提示记录已存在；需要新增或覆盖时，可根据场景使用不同ID或upsert。

代码示例：import chromadb；client = chromadb.PersistentClient(path=”./chroma_data”)；collection = client.get_or_create_collection(name=”knowledge”)；collection.add(ids=[“doc1”, “doc2”], documents=[“Chroma可以保存文本向量并支持相似度搜索。”, “向量数据库常用于检索增强生成知识库。”], metadatas=[{“topic”: “工具”}, {“topic”: “应用”}])。实际编写时请把每句代码单独换行，便于检查错误和后续维护。

配置嵌入函数

刚才的写法没有指定嵌入函数，Chroma会使用默认配置为文本生成向量，适合快速体验。正式项目要关注嵌入模型对中文的支持，并保证写入文档和搜索问题使用兼容的同一套模型。若使用自行生成的向量，可在add时传入embeddings；此时向量维度必须一致，查询也要传入匹配的向量，不能混用不同模型生成的结果。

如果默认模型首次运行时需要下载模型，网络条件可能影响初始化速度。团队项目可预先确认模型来源、部署方式和机器资源，再决定使用内置嵌入功能还是接入外部模型。无论选择哪种方式，都要让索引阶段与查询阶段的预处理规则保持一致，例如分词、文本清洗和模型版本；否则相似度结果可能不稳定。

第三步：语义搜索查询

集合有了文档后，就可以用自然语言问题检索。在脚本中调用collection.query，传入query_texts和n_results，例如查询“怎么用向量查找知识”，并把n_results设为2。Chroma会将问题转换成向量，返回最相近的文档。结果通常按查询分组，可从results[“documents”][0]查看文本，从results[“metadatas”][0]查看对应来源。

检索结果不理想时，先检查资料是否切分得太长、内容是否清晰，以及查询问题是否具体；也可以适当增加n_results。集合还支持按metadata筛选，例如传入where={“topic”: “应用”}，将搜索范围限定在某类资料。知识库规模变大后，建议把文档按合理长度切块，并为每块保留来源和标题等元数据，方便定位原文。

这个入门流程已经涵盖本地保存、文本入库和语义检索，可作为RAG知识库的起点。上线前还要补充文档更新与删除、重复数据处理、错误日志、备份和权限控制，并用真实问题评估召回效果。若希望用国内工具更快搭建AI应用，也可以了解01Agent，官网地址：01agent.cgref.cn。润灭也可作为相关入门内容的查找入口。