--- title: "RAG 落地必备的 1 个开源 AI 原生向量数据库 —Chroma" source: "https://developer.volcengine.com/articles/7540557251812179987?gad_source=1&gad_campaignid=23655660653&gbraid=0AAAAA9fhLMQnDsAF6lvEMDoHlLhxabQ88&gclid=EAIaIQobChMI4vmtgoHYkwMViCSDAx39GhX3EAAYASAAEgJhIfD_BwE" author: - "[[沐雪架构师]]" published: 2025-08-20 created: 2026-04-06 description: "分享 AI人工智能 | AI大模型开发 | 软件架构 | 软件技术" tags: - "clippings" --- 一、Chroma 核心概念与优势 1. 什么是 Chroma? Chroma 是一款开源的向量数据库,专为高效存储和检索高维向量数据设计。其核心能力在于语义相似性搜索,支持文本、图像等嵌入向量的快速匹配,广泛应用于大模型上下文增强(RAG)、推荐系统、多模态检索等场景。与传统数据库不同,Chroma 基于向量距离(如余弦相似度、欧氏距离)衡量数据关联性,而非关键词匹配。 GitHub地址: [https://github.com/chroma-core/chroma](https://github.com/chroma-core/chroma) 官方文档: [https://docs.trychroma.com/](https://docs.trychroma.com/) 1. 核心优势 - 轻量易用:以 Python/JS 包形式嵌入代码,无需独立部署,适合快速原型开发。 - 灵活集成:支持自定义嵌入模型(如 OpenAI、HuggingFace),兼容 LangChain 等框架。 - 高性能检索:采用 HNSW 算法优化索引,支持百万级向量毫秒级响应。 - 多模式存储:内存模式用于开发调试,持久化模式支持生产环境数据落地。 ![picture.image](https://p6-volc-community-sign.byteimg.com/tos-cn-i-tlddhu82om/e167915cf0904e57b95068a5a661880d~tplv-tlddhu82om-image.image?=&rk3s=8031ce6d&x-expires=1775523082&x-signature=A2rwLobyN6WItmvTFKy1TR87NhE%3D) 二、安装和基础配置 1、安装Chroma 支持windows和ubuntu操作系统,Python>=3.9 创建虚拟环境以及安装: ``` #创建虚拟环境 conda create -n chromadb python==3.10 #激活 conda activate chromadb #安装chromadb pip install chromadb ``` 注意:Chroma 默认是本地嵌入式数据库,并不原生支持远程访问像传统数据库那样(比如 PostgreSQL 那种 client-server 模式)。 当然官方也提供了客户端-服务器端模式(Client-Server Mode)。服务器端的启动方式如下: ```bash #服务器端启动,默认端口号8000 chroma run --path /db_path ``` 2、初始化客户端 内存模式(调试,实验的场景): ``` import chromadb client = chromadb.Client() ``` 持久化模式(生产环境): 在创建的时候,可以配置本地的存储路径 ``` import chromadb # 数据保存至本地目录,path填写绝对路径 client = chromadb.PersistentClient(path="/path/to/save") ``` Client-Server模式的客户端: 前两种,都是本地模式,chroma的服务端和客户端需要位于同一台机器。CS模式可以独立部署,通过httpclient进行访问。 ``` import chromadb chroma_client = chromadb.HttpClient(host='localhost', port=8000) ``` ![picture.image](https://p6-volc-community-sign.byteimg.com/tos-cn-i-tlddhu82om/71f7543ed0954c1a8baaa7eb403e3760~tplv-tlddhu82om-image.image?=&rk3s=8031ce6d&x-expires=1775523082&x-signature=I3LzxY1nLq74ZMEx%2BEKgPMvrr20%3D) 三、增删改查操作 1. 创建集合(Collection) 集合是 Chroma 中管理数据的基本单元,类似传统数据库的表。 集合的name名称有以下约束: - 名称的长度必须介于 3 到 63 个字符之间。 - 名称必须以小写字母或数字开头和结尾,中间可以包含点、破折号和下划线。 - 名称不得包含两个连续的点。 - 该名称不能是有效的 IP 地址。 | | | --- | | | | Chroma 集合是用一个名称和一个可选的嵌入函数创建的。 | 如果您提供嵌入函数,则每次获取集合时都必须提供它。 | ``` # 创建 collection = client.create_collection(name="my_collection", embedding_function=emb_fn) # 获取 collection = client.get_collection(name="my_collection", embedding_function=emb_fn) # 若没有则创建,若有则获取 collection = chroma_client.get_or_create_collection(name="my_collection2") ``` 如果不提供嵌入函数,则使用默认的嵌入函数 sentence transformer 使用的的是一个小型的模型all-MiniLM-L6-v2,该模型主要是针对英语场景。一般我们都需要自定义一个嵌入函数: ```python import chromadb from sentence_transformers import SentenceTransformer class SentenceTransformerEmbeddingFunction: def __init__(self, model_path: str, device: str = "cuda"): self.model = SentenceTransformer(model_path, device=device) def __call__(self, input: list[str]) -> list[list[float]]: if isinstance(input, str): input = [input] return self.model.encode(input, convert_to_numpy=True).tolist() # 创建/加载集合(含自定义嵌入函数) embed_model = SentenceTransformerEmbeddingFunction( model_path=r"D:\Test\LLMTrain\testllm\llm\BAAI\bge-m3", device="cuda" # 无 GPU 改为 "cpu" ) # 创建客户端和集合 client = chromadb.Client() collection = client.create_collection("my_knowledge_base", metadata={"hnsw:space": "cosine"}, embedding_function=embed_model) ``` 创建collect时,可以配置如下参数。 - name标识collect的名称,是必填项; - embedding\_function,指定嵌入函数,不填为默认的嵌入模型。 - metadata,元数据,比如索引方式等,非必填。 ``` from datetime import datetime collection = client.create_collection( name="my_collection", embedding_function=emb_fn, metadata={ "description": "my first Chroma collection", "created": str(datetime.now()) } ) ``` 集合还有一些常用方法: - peek() - 返回集合中前 10 个项目的列表。 - count() -返回集合中的项目数。 - modify() -重命名集合 ``` collection.peek() collection.count() collection.modify(name="new_name") ``` 2、写入数据 写入数据时,配置以下参数: - document,原始的文本块。 - metadatas,描述文本块的元数据,kv键值对。 - ids,文本块的唯一标识,每个文档必须具有唯一关联的ID。 若添加两次相同的 ID 将导致仅存储初始值。 - embeddings,对于已经向量化的文本块,可以直接写入结果。如果不填,则在写入时,使用指定或者默认的嵌入函数对documents进行向量化。 ``` collection.add( documents=["lorem ipsum...", "doc2", "doc3", ...], metadatas=[{"chapter": "3", "verse": "16"}, {"chapter": "3", "verse": "5"}, {"chapter": "29", "verse": "11"}, ...], ids=["id1", "id2", "id3", ...] ) ``` 或者 ``` collection.add( embeddings=[[1.1, 2.3, 3.2], [4.5, 6.9, 4.4], [1.1, 2.3, 3.2], ...], metadatas=[{"chapter": "3", "verse": "16"}, {"chapter": "3", "verse": "5"}, {"chapter": "29", "verse": "11"}, ...], ids=["id1", "id2", "id3", ...] ) ``` 3、修改数据 提供ids(文本唯一标识)。 ``` collection.update( ids=["doc1"], # 使用已存在的ID documents=["RAG是一种检索增强生成技术222"] ) ``` 4、更新插入方法 Chroma 还支持更新插入操作,更新现有项目,如果项目尚不存在则添加它们。 ``` collection.upsert( ids=["id1", "id2", "id3", ...], embeddings=[[1.1, 2.3, 3.2], [4.5, 6.9, 4.4], [1.1, 2.3, 3.2], ...], metadatas=[{"chapter": "3", "verse": "16"}, {"chapter": "3", "verse": "5"}, {"chapter": "29", "verse": "11"}, ...], documents=["doc1", "doc2", "doc3", ...], ) ``` 5、删除数据 Chroma 支持通过以下方式从集合中删除项目ID使用delete。与每个项目相关的嵌入、文档和元数据将被删除。 还支持where过滤器。如果没有ID提供,它将删除集合中与where筛选。 ``` # 提供ids collection.delete(ids=["doc1"]) # where 条件删除 collection.delete( ids=["id1", "id2", "id3",...], where={"chapter": "20"} ) ``` 6、查询数据 (1)查询所有数据 ``` all_docs = collection.get() print("集合中所有文档:", all_docs) ``` (2)根据ids查询 可以通过以下方式从集合中检索项目ID使用get。 ``` collection.get( ids=["id1", "id2", "id3", ...], where={"style": "style1"} ) ``` (3)查询嵌入 可以通过多种方式查询 Chroma 集合,使用query方法。比如 使用query\_embedding。 ``` collection.query( query_embeddings=[[11.1, 12.1, 13.1],[1.1, 2.3, 3.2], ...], n_results=10, where={"metadata_field": "is_equal_to_this"}, where_document={"$contains":"search_string"} ) ``` - 查询将返回n\_result每个最接近的匹配查询嵌入,按顺序排列。 - 可选where过滤字典可以通过metadata与每个文档关联。 - 此外,where document可以提供过滤字典来根据文档内容进行过滤。 (4)查询相似文档 还可以通过一组查询文本query\_texts. Chroma 将首先嵌入每个查询文本与集合的嵌入函数,然后使用生成的嵌入执行查询。 ``` # 查询相似文档 results = collection.query( query_texts=["什么是RAG技术?"], n_results=3 ) print("查询的结果",results) ``` 查询结果配置 - 当使用 get 或 query 时,您可以使用include参数来指定您想要返回的数据包括:embeddings, documents,metadatas;include为数组,可以传多个值。 - 对于查询query,默认返回距离distances结果。 - embeddings出于性能考虑,默认不返回,直接显示None ,若想返回,则include中包含embeddings即可。 - ID始终会返回。 - 返回值里有included参数,表明本次返回的数据有哪些类型。 - embeddings将以二维 NumPy 数组的形式返回。 ``` # Only get documents and ids collection.get( include=["documents"] ) collection.query( query_embeddings=[[11.1, 12.1, 13.1],[1.1, 2.3, 3.2], ...], include=["documents"] ) ``` 查询的结果示例 ```lua {'ids': [['doc1', 'doc3', 'doc2']], 'embeddings': None, 'documents': [['RAG是一种检索增强生成技术', '三英战吕布', '向量数据库存储文档的嵌入表示']], 'uris': None, 'included': ['metadatas', 'documents', 'distances'], 'data': None, 'metadatas': [[{'source': 'tech_doc'}, {'source': 'tutorial1'}, {'source': 'tutorial'}]], 'distances': [[0.2373753786087036, 0.7460092902183533, 0.7651787400245667]] } ``` 四、实战操作 将一批数据插入向量数据库,再根据一个问题从向量数据库中找出相似数据。 1、安装包 ``` pip install sentence_transformers pip install modelscope ``` 2、下载Embedding模型到本地 ```python #模型下载 from modelscope import snapshot_download model_dir = snapshot_download('BAAI/bge-m3',cache_dir=r"D:\Test\LLMTrain\testllm\llm") ``` 3、核心逻辑:写入数据和查询相似度 ```python import chromadb from sentence_transformers import SentenceTransformer class SentenceTransformerEmbeddingFunction: def __init__(self, model_path: str, device: str = "cuda"): self.model = SentenceTransformer(model_path, device=device) def __call__(self, input: list[str]) -> list[list[float]]: if isinstance(input, str): input = [input] return self.model.encode(input, convert_to_numpy=True).tolist() # 创建/加载集合(含自定义嵌入函数) embed_model = SentenceTransformerEmbeddingFunction( model_path=r"D:\Test\LLMTrain\testllm\llm\BAAI\bge-m3", device="cpu" # 无 GPU 改为 "cpu",有则为cuda ) # 创建客户端和集合 client = chromadb.PersistentClient(path=r"D:\Test\LLMTrain\chromadb_test\chroma_data") collection = client.get_or_create_collection("my_knowledge_base", metadata={"hnsw:space": "cosine"}, embedding_function=embed_model) # 添加文档 collection.add( documents=[ "向量数据库存储文档的嵌入表示", "三英战吕布","RAG是一种检索增强生成技术"], metadatas=[{"source": "tech_doc"}, {"source": "tutorial"}, {"source": "tutorial1"}], ids=["doc1", "doc2", "doc3"] ) # 查询相似文档 results = collection.query( query_texts=["什么是RAG技术?"], n_results=3 ) print("查询的结果",results) ``` 执行返回结果: ```lua 查询的结果 { 'ids': [['doc3', 'doc2', 'doc1']], 'embeddings': None, 'documents': [['RAG是一种检索增强生成技术', '三英战吕布', '向量数据库存储文档的嵌入表示']], 'uris': None, 'included': ['metadatas', 'documents', 'distances'], 'data': None, 'metadatas': [[{'source': 'tutorial1'}, {'source': 'tutorial'}, {'source': 'tech_doc'}]], 'distances': [[0.2373753786087036, 0.7460092902183533, 0.7651787400245667]] } ``` 查看结果,我们重点看 distances,值是从小到大排序的,所以3条数据与问题“什么是RAG技术?”的相似度情况: distances值越小越相似。因此,第1条数据与问题最相似。 ![picture.image](https://p6-volc-community-sign.byteimg.com/tos-cn-i-tlddhu82om/80b6ec9f895944c18b35e9bd7ef4a38a~tplv-tlddhu82om-image.image?=&rk3s=8031ce6d&x-expires=1775523082&x-signature=%2FkRSvlsAbWmETmpu8%2BJG3b26n2I%3D) [RAG进阶:Embedding Models嵌入式模型原理和选型指南](https://mp.weixin.qq.com/s?__biz=MjM5MzQ5NTU0Mw==&mid=2455052368&idx=1&sn=750b18d83c09ad15888f108a5afee64e&scene=21#wechat_redirect) [LlamaIndex入门指南和RAG原理](https://mp.weixin.qq.com/s?__biz=MjM5MzQ5NTU0Mw==&mid=2455052363&idx=1&sn=820edf686033f9855e064f69265868ce&scene=21#wechat_redirect) [探秘 Hugging Face:何为 Hugging Face 及其核心组件全览](https://mp.weixin.qq.com/s?__biz=MjM5MzQ5NTU0Mw==&mid=2455052223&idx=1&sn=71a04ed4dab98ea327a30a3a3d8d4e0f&scene=21#wechat_redirect) [LLaMA Factory 如何对大模型进行微调、导出和量化!掌握这几步,轻松搞定!](https://mp.weixin.qq.com/s?__biz=MjM5MzQ5NTU0Mw==&mid=2455052237&idx=1&sn=74a1d3261f4ebf21ffce501663dcf3ac&scene=21#wechat_redirect) [大模型部署该选谁?Ollama、vLLM 和 LMDeploy,各有千秋!](https://mp.weixin.qq.com/s?__biz=MjM5MzQ5NTU0Mw==&mid=2455052248&idx=1&sn=9d48af4ef155001cdd023d3f21dc18cc&scene=21#wechat_redirect) [大型语言模型如何高效微调量化?答案就是 QLoRA!](https://mp.weixin.qq.com/s?__biz=MjM5MzQ5NTU0Mw==&mid=2455052254&idx=1&sn=0655a59d8d630bdd204893b59096560d&scene=21#wechat_redirect) [LLaMA Factory微调后的大模型在vLLM框架中对齐对话模版](https://mp.weixin.qq.com/s?__biz=MjM5MzQ5NTU0Mw==&mid=2455052264&idx=1&sn=31cac1d64d5ee6095cf22e0484b12d95&scene=21#wechat_redirect) [AI大模型分布式训练技术原理是什么?看这篇超犀利解析!](https://mp.weixin.qq.com/s?__biz=MjM5MzQ5NTU0Mw==&mid=2455052268&idx=1&sn=8c984a46307a9176411260716c7625d6&scene=21#wechat_redirect) [XTuner对大模型 微调训练、转换、合并和验证 !这篇文章让你轻松拿捏!](https://mp.weixin.qq.com/s?__biz=MjM5MzQ5NTU0Mw==&mid=2455052314&idx=1&sn=22ff97c2d8b90ef9bff8c711c30ddd10&scene=21#wechat_redirect) [基于Bert大模型增量微调训练:中文评价情感分析](https://mp.weixin.qq.com/s?__biz=MjM5MzQ5NTU0Mw==&mid=2455052314&idx=2&sn=b827cc47bebefb18e31390a9cd0410b5&scene=21#wechat_redirect) [大模型高并发请求和单卡显存不足怎么办?分布式推理和量化部署来救场!](https://mp.weixin.qq.com/s?__biz=MjM5MzQ5NTU0Mw==&mid=2455052321&idx=1&sn=11ae6dcb8fb02279b7f67d057e957ac0&scene=21#wechat_redirect) [AI 大模型评测难?OpenCompass 这个‘自动跑分神器’来破局!](https://mp.weixin.qq.com/s?__biz=MjM5MzQ5NTU0Mw==&mid=2455052340&idx=1&sn=9ad7cdfad6be86e8e1424db12e72be6b&scene=21#wechat_redirect)