421 lines
16 KiB
Markdown
421 lines
16 KiB
Markdown
---
|
||
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 算法优化索引,支持百万级向量毫秒级响应。
|
||
- 多模式存储:内存模式用于开发调试,持久化模式支持生产环境数据落地。
|
||
|
||

|
||
|
||
二、安装和基础配置
|
||
|
||
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)
|
||
```
|
||
|
||

|
||
|
||
三、增删改查操作
|
||
|
||
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条数据与问题最相似。
|
||
|
||

|
||
|
||
[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) |