当前位置：首页 > news >正文

[智能体-301]：Chroma向量数据库详解，包括主要接口，代码示例

news 2026/6/7 13:24:02

一、Chroma 概述

Chroma是开源、轻量级、嵌入式向量数据库，专为 LLM/RAG 设计，主打：

✅零依赖：内置 SQLite+DuckDB，无需单独部署
✅本地优先：支持内存 / 持久化两种模式
✅自动嵌入：内置OpenAI / 句子嵌入模型，开箱即用
✅简单 API：Python/JS 多语言，5 分钟上手
✅LangChain 原生集成

核心用途：文档语义检索、知识库问答、Agent 记忆、相似内容推荐。

二、安装

bash

运行

# 基础版（核心功能） pip install chromadb # 完整版（含内置嵌入、可视化） pip install "chromadb[all]"

三、核心概念

Client：数据库连接入口（内存 / 持久化 / 云）
Collection：向量集合（类比 “表”），含：
- ids：唯一标识（必填）
- embeddings：向量（可选，可自动生成）
- documents：原始文本（可选）
- metadatas：元数据（过滤用）

四、主要接口（Python）

1. 客户端（Client）

python

运行

import chromadb # 1）内存模式（临时，程序退出丢失） client = chromadb.Client() # 2）持久化模式（数据存文件夹，常用） client = chromadb.PersistentClient(path="./chroma_db") # 3）云服务模式（Chroma Cloud） client = chromadb.CloudClient(tenant="xxx", database="yyy", api_key="zzz")

2. 集合（Collection）管理

python

运行

# 创建/获取集合（不存在则创建，存在则获取） collection = client.get_or_create_collection( name="my_knowledge", metadata={"hnsw:space": "cosine"} # 距离度量：cosine/l2/ip ) # 列出所有集合 client.list_collections() # 删除集合 client.delete_collection(name="my_knowledge")

3. 增（add/upsert）

python

运行

# 方式1：自动生成向量（推荐，传文本即可） collection.add( documents=[ "RAG 检索增强生成", "Chroma 轻量级向量库", "向量数据库用于语义搜索" ], metadatas=[{"topic": "AI"}, {"topic": "DB"}, {"topic": "Search"}], ids=["doc1", "doc2", "doc3"] # 必须唯一 ) # 方式2：手动传向量（自定义模型） collection.add( embeddings=[[0.1,0.2,...], [0.3,0.4,...]], # 与文本一一对应 documents=["文本1", "文本2"], ids=["id1", "id2"] ) # upsert：存在则更新，不存在则插入 collection.upsert(...)

4. 查（query/get）

语义检索（核心）

python

运行

results = collection.query( query_texts=["什么是向量数据库？"], # 查询文本（自动转向量） n_results=2, # 返回 top2 where={"topic": "DB"}, # 元数据过滤 where_document={"$contains": "向量"} # 文本内容过滤 ) # 结果结构 # results = { # "ids": [["doc2", "doc3"]], # "distances": [[0.12, 0.34]], # 距离越小越相似 # "documents": [["Chroma 轻量级向量库", "向量数据库用于语义搜索"]], # "metadatas": [[{"topic":"DB"}, {"topic":"Search"}]] # }

精确获取（按 ID / 过滤）

python

运行

# 按 ID 获取 items = collection.get(ids=["doc1", "doc2"]) # 过滤+分页 items = collection.get( where={"topic": "AI"}, limit=10, offset=0, include=["documents", "metadatas"] # 只返回指定字段 )

5. 改（update）

python

运行

collection.update( ids=["doc1"], documents=["更新：RAG 检索增强生成技术"], metadatas=[{"topic": "AI", "updated": True}] )

6. 删（delete）

python

运行

# 按 ID 删除 collection.delete(ids=["doc3"]) # 按条件删除 collection.delete(where={"topic": "old"}) # 清空集合 collection.delete(where={})

7. 其他常用

python

运行

# 集合总数 collection.count() # 预览前 5 条 collection.peek(limit=5)

五、完整代码示例（RAG 最小 Demo）

python

运行

import chromadb # 1. 初始化客户端（持久化） client = chromadb.PersistentClient(path="./chroma_rag") # 2. 创建集合 collection = client.get_or_create_collection( name="rag_demo", metadata={"hnsw:space": "cosine"} ) # 3. 准备知识库文本 docs = [ "Chroma 是轻量级开源向量数据库，专为 LLM 应用设计。", "RAG 通过检索外部知识库，让大模型回答更准确、时效性更强。", "向量数据库将文本转为高维向量，支持语义相似度搜索。" ] ids = ["rag1", "rag2", "rag3"] metas = [{"source": "intro"}, {"source": "tech"}, {"source": "concept"}] # 4. 存入数据库（自动嵌入） collection.add(documents=docs, ids=ids, metadatas=metas) # 5. 语义查询 query = "RAG 如何提升大模型回答准确性？" results = collection.query(query_texts=[query], n_results=2) # 6. 打印结果 print("=== 最相似文档 ===") for i, (doc, dist) in enumerate(zip(results["documents"][0], results["distances"][0])): print(f"{i+1}. 距离：{dist:.4f} | 内容：{doc}")

输出示例

plaintext

=== 最相似文档 === 1. 距离：0.1823 | 内容：RAG 通过检索外部知识库，让大模型回答更准确、时效性更强。 2. 距离：0.4567 | 内容：向量数据库将文本转为高维向量，支持语义相似度搜索。

六、LangChain 集成（常用）

python

运行

from langchain_community.vectorstores import Chroma from langchain_core.documents import Document # 1. 从 Document 列表创建向量库 documents = [Document(page_content="文本1", metadata={"source": "test"})] vectorstore = Chroma.from_documents( documents=documents, persist_directory="./chroma_langchain" # 持久化 ) # 2. 加载已有向量库 vectorstore = Chroma(persist_directory="./chroma_langchain") # 3. 转为检索器 retriever = vectorstore.as_retriever(k=3) docs = retriever.invoke("你的问题")