mcpField
C
chroma

chroma

github.com/orchestra-research数据与数据库14.1k962 次安装19 周前更新
代码仓库

关于 chroma

Chroma 是面向 LLM 应用的开源嵌入数据库，适用于构建 RAG、语义搜索和本地或自托管应用。它提供向量查询、元数据筛选及持久化存储。

主要功能

  1. 01存储文档、嵌入和元数据
  2. 02相似度查询与元数据筛选
  3. 03增删改查集合内容
  4. 04本地持久化与服务器模式
  5. 05支持多种嵌入函数

适用场景

  1. 01构建 RAG 应用
  2. 02对文档进行语义搜索
  3. 03在笔记本中快速原型验证
  4. 04保存带元数据的嵌入

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/orchestra-research/ai-research-skills --skill chroma

安装后在 Claude Code 中输入/chroma确认已加载。

附带文件references/integration.md

详细介绍

Chroma - 开源嵌入数据库

用于构建带记忆的大模型应用的 AI 原生数据库。

何时使用 Chroma

在以下情况使用 Chroma：

  • 构建 RAG（检索增强生成）应用
  • 需要本地/可自托管的向量数据库
  • 想要开源解决方案（Apache 2.0）
  • 在 notebook 中进行原型开发
  • 对文档进行语义搜索
  • 存储带元数据的嵌入

指标：

  • 24,300+ GitHub stars
  • 1,900+ forks
  • v1.3.3（稳定版，每周发布）
  • Apache 2.0 许可证

改用以下替代方案：

  • Pinecone：托管云服务，自动扩缩容
  • FAISS：纯相似度搜索，无元数据
  • Weaviate：生产级 ML 原生数据库
  • Qdrant：高性能，基于 Rust

快速开始

安装
# Python
pip install chromadb

# JavaScript/TypeScript
npm install chromadb @chroma-core/default-embed
基本用法（Python）
import chromadb

# Create client
client = chromadb.Client()

# Create collection
collection = client.create_collection(name="my_collection")

# Add documents
collection.add(
    documents=["This is document 1", "This is document 2"],
    metadatas=[{"source": "doc1"}, {"source": "doc2"}],
    ids=["id1", "id2"]
)

# Query
results = collection.query(
    query_texts=["document about topic"],
    n_results=2
)

print(results)

核心操作

1. 创建 collection
# Simple collection
collection = client.create_collection("my_docs")

# With custom embedding function
from chromadb.utils import embedding_functions

openai_ef = embedding_functions.OpenAIEmbeddingFunction(
    api_key="your-key",
    model_name="text-embedding-3-small"
)

collection = client.create_collection(
    name="my_docs",
    embedding_function=openai_ef
)

# Get existing collection
collection = client.get_collection("my_docs")

# Delete collection
client.delete_collection("my_docs")
2. 添加文档
# Add with auto-generated IDs
collection.add(
    documents=["Doc 1", "Doc 2", "Doc 3"],
    metadatas=[
        {"source": "web", "category": "tutorial"},
        {"source": "pdf", "page": 5},
        {"source": "api", "timestamp": "2025-01-01"}
    ],
    ids=["id1", "id2", "id3"]
)

# Add with custom embeddings
collection.add(
    embeddings=[[0.1, 0.2, ...], [0.3, 0.4, ...]],
    documents=["Doc 1", "Doc 2"],
    ids=["id1", "id2"]
)
3. 查询（相似度搜索）
# Basic query
results = collection.query(
    query_texts=["machine learning tutorial"],
    n_results=5
)

# Query with filters
results = collection.query(
    query_texts=["Python programming"],
    n_results=3,
    where={"source": "web"}
)

# Query with metadata filters
results = collection.query(
    query_texts=["advanced topics"],
    where={
        "$and": [
            {"category": "tutorial"},
            {"difficulty": {"$gte": 3}}
        ]
    }
)

# Access results
print(results["documents"])      # List of matching documents
print(results["metadatas"])      # Metadata for each doc
print(results["distances"])      # Similarity scores
print(results["ids"])            # Document IDs
4. 获取文档
# Get by IDs
docs = collection.get(
    ids=["id1", "id2"]
)

# Get with filters
docs = collection.get(
    where={"category": "tutorial"},
    limit=10
)

# Get all documents
docs = collection.get()
5. 更新文档
# Update document content
collection.update(
    ids=["id1"],
    documents=["Updated content"],
    metadatas=[{"source": "updated"}]
)
6. 删除文档
# Delete by IDs
collection.delete(ids=["id1", "id2"])

# Delete with filter
collection.delete(
    where={"source": "outdated"}
)

持久化存储

# Persist to disk
client = chromadb.PersistentClient(path="./chroma_db")

collection = client.create_collection("my_docs")
collection.add(documents=["Doc 1"], ids=["id1"])

# Data persisted automatically
# Reload later with same path
client = chromadb.PersistentClient(path="./chroma_db")
collection = client.get_collection("my_docs")

嵌入函数

默认（Sentence Transformers）
# Uses sentence-transformers by default
collection = client.create_collection("my_docs")
# Default model: all-MiniLM-L6-v2
OpenAI
from chromadb.utils import embedding_functions

openai_ef = embedding_functions.OpenAIEmbeddingFunction(
    api_key="your-key",
    model_name="text-embedding-3-small"
)

collection = client.create_collection(
    name="openai_docs",
    embedding_function=openai_ef
)
HuggingFace
huggingface_ef = embedding_functions.HuggingFaceEmbeddingFunction(
    api_key="your-key",
    model_name="sentence-transformers/all-mpnet-base-v2"
)

collection = client.create_collection(
    name="hf_docs",
    embedding_function=huggingface_ef
)
自定义嵌入函数
from chromadb import Documents, EmbeddingFunction, Embeddings

class MyEmbeddingFunction(EmbeddingFunction):
    def __call__(self, input: Documents) -> Embeddings:
        # Your embedding logic
        return embeddings

my_ef = MyEmbeddingFunction()
collection = client.create_collection(
    name="custom_docs",
    embedding_function=my_ef
)

元数据过滤

# Exact match
results = collection.query(
    query_texts=["query"],
    where={"category": "tutorial"}
)

# Comparison operators
results = collection.query(
    query_texts=["query"],
    where={"page": {"$gt": 10}}  # $gt, $gte, $lt, $lte, $ne
)

# Logical operators
results = collection.query(
    query_texts=["query"],
    where={
        "$and": [
            {"category": "tutorial"},
            {"difficulty": {"$lte": 3}}
        ]
    }  # Also: $or
)

# Contains
results = collection.query(
    query_texts=["query"],
    where={"tags": {"$in": ["python", "ml"]}}
)

LangChain 集成

from langchain_chroma import Chroma
from langchain_openai import OpenAIEmbeddings
from langchain.text_splitter import RecursiveCharacterTextSplitter

# Split documents
text_splitter = RecursiveCharacterTextSplitter(chunk_size=1000)
docs = text_splitter.split_documents(documents)

# Create Chroma vector store
vectorstore = Chroma.from_documents(
    documents=docs,
    embedding=OpenAIEmbeddings(),
    persist_directory="./chroma_db"
)

# Query
results = vectorstore.similarity_search("machine learning", k=3)

# As retriever
retriever = vectorstore.as_retriever(search_kwargs={"k": 5})

LlamaIndex 集成

from llama_index.vector_stores.chroma import ChromaVectorStore
from llama_index.core import VectorStoreIndex, StorageContext
import chromadb

# Initialize Chroma
db = chromadb.PersistentClient(path="./chroma_db")
collection = db.get_or_create_collection("my_collection")

# Create vector store
vector_store = ChromaVectorStore(chroma_collection=collection)
storage_context = StorageContext.from_defaults(vector_store=vector_store)

# Create index
index = VectorStoreIndex.from_documents(
    documents,
    storage_context=storage_context
)

# Query
query_engine = index.as_query_engine()
response = query_engine.query("What is machine learning?")

服务模式

# Run Chroma server
# Terminal: chroma run --path ./chroma_db --port 8000

# Connect to server
import chromadb
from chromadb.config import Settings

client = chromadb.HttpClient(
    host="localhost",
    port=8000,
    settings=Settings(anonymized_telemetry=False)
)

# Use as normal
collection = client.get_or_create_collection("my_docs")

最佳实践

  1. 使用持久化客户端 - 重启时不会丢失数据
  2. 添加元数据 - 支持过滤和跟踪
  3. 批量操作 - 一次性添加多个文档
  4. 选择合适的嵌入模型 - 平衡速度与质量
  5. 使用过滤器 - 缩小搜索范围
  6. 唯一 ID - 避免冲突
  7. 定期备份 - 复制 chroma_db 目录
  8. 监控 collection 大小 - 按需扩容
  9. 测试嵌入函数 - 确保质量
  10. 生产环境使用服务模式 - 更适合多用户

性能

操作延迟说明
添加 100 个文档约 1-3s含嵌入
查询（top 10）约 50-200ms取决于 collection 大小
元数据过滤约 10-50ms索引得当则很快

资源

评论

支持 Markdown