Chroma是一款功能强大的开源 AI 应用数据库，专为高效数据存储与检索而设计。它不仅支持 Embedding 和 Metadata 的存储，还集成了多项核心功能，包括向量搜索、全文搜索、Document 存储、Metadata 过滤以及多模态检索。此外，Chroma 还提供了便捷的客户端-服务器（CS）模式，满足多样化的应用场景需求。

安装

# 在服务器上安装
pip install chromadb

# 在客户端上安装，仅支持 HTTP 的客户端
pip install chromadb-client

使用

# 导入chromadb
import chromadb

# 导入embedding_functions，它可以自定义嵌入模型
from chromadb.utils import embedding_functions

my_embedding_func = embedding_functions.OpenAIEmbeddingFunction(
    api_key="YOUR_API_KEY",
    model_name="<嵌入模型的名称>"
)

# 下面三选一就行
# 创建一个临时客户端，存在内存中
chroma_client = chromadb.EphemeralClient()
chroma_client = chromadb.Client()  # 默认使用内存存储模式（非持久化）

# 创建一个持久客户端，若不指定则存默认路径为 .chroma
chroma_client = chromadb.PersistantClient(path="<本地存储路径>")


# 创建一个集合
"""
集合是您存储嵌入、文档和任何附加元数据的地方。集合索引您的嵌入和文档，并实现高效的检索和过滤。您可以使用名称创建一个集合。
"""
collection = chroma_client.create_collection(
    name="my_collection",
    "embedding_function": my_embedding_func  # 指定向量模型

)
collection = chroma_client.get_or_create_collection(name="my_collection")  # 该方法可以避免重复创建集合

# collection的几个属性
print(collection.peek())  # 返回集合中前10项的列表
print(collection.count())  # 返回集合中项目的数量


# 增：向集合中添加一些文本文件
"""
Chroma 将存储您的文本并自动处理嵌入和索引。您还可以自定义嵌入模型。您必须为您的文档提供唯一的字符串 ID
"""
collection.add(
    documents=[
        "This is a document about pineapple",
        "This is a document about oranges"
    ],
    metadatas=[{"source": "pineapple"}, {"source": "oranges"}]
    ids=["id1", "id2"]
)

# 查：查询集合
"""
您可以使用查询文本列表查询集合，Chroma 将返回 n 个最相似的结果。就是这么简单！如果未提供 n_results，Chroma 默认将返回 10 个结果。默认情况下，Chroma 使用 DefaultEmbeddingFunction，它是基于 Sentence Transformers 的 MiniLM-L6-v2 模型
"""
results = collection.query(
    query_texts=["This is a query document about hawaii"],  # Chroma会自动嵌入
    n_results=2  # 返回多少结果
    # where = {"source": "hawaii"}, # 按元数据过滤
    # where_document = {"$contains": "about hawaii"} # 按文档内容过滤
)

# 改：如果重复执行，相同 ID 的文档会被更新
collection.upsert(
    documents=[
        "This is a document about pineapple",
        "This is a document about oranges"
    ],
    ids=["id1", "id2"]
)

# 删：删除某个文档，删除整个集合
collection.delete(ids=["id2"])  # 删除某个文档
client.delete_collection(name="my_collection")  # 删除整个集合

CS模式

服务器上运行这个命令：

# 运行chroma服务器
chroma run --path <本地持久化数据库的路径>

# 单独设置地址和端口
chroma run --path /db_path --host localhost --port 8000

客户端上运行这个代码：

import chromadb

# 下面二选一就行
# 同步客户端连接方式（阻塞式）
client = chromadb.HttpClient(host='localhost', port=8000)

# 异步客户端连接方式（非阻塞式）
async def main():
    client = await chromadb.AsyncHttpClient(host='localhost', port=8000)


# 运行异步主函数
asyncio.run(main())