# ChromaDB ChromaDB 是 **领先的开源向量数据库** 专为 AI 应用构建。它提供了一个简单直观的 API 用于存储、查询和管理高维嵌入向量 —— 这些是现代 RAG 系统、语义搜索、推荐引擎和大型语言模型记忆的核心。 ChromaDB 抽象化了向量相似性搜索的复杂性，让您可以专注于构建 AI 应用。它支持用于开发的内存模式和用于生产部署的持久化服务器模式，并提供 Docker 支持，以便在 Clore.ai GPU 服务器上轻松部署。 主要功能： * 🚀 **简单的 Python/JavaScript API** — 几分钟即可入门 * 💾 **持久化存储** — 数据在容器重启后仍然存在 * 🔍 **多种距离度量** — 余弦、L2、内积 * 📦 **集成的嵌入工具** — 内置支持 OpenAI、Cohere、sentence-transformers * 🏗️ **多租户** — 使用集合来组织不同的数据集 * 🔌 **REST API** — 与语言无关的 HTTP 接口 * ⚡ **通用使用** — 用于近似最近邻搜索的 HNSW 索引 * 🔗 **原生支持 LangChain/LlamaIndex** — 一流的集成 {% hint style="success" %} 所有示例都可以在通过以下方式租用的 GPU 服务器上运行 [CLORE.AI 市场](https://clore.ai/marketplace). {% endhint %} *** ## 服务器要求 | 参数 | 最低要求 | 推荐配置 | | -------- | ------------------ | --------------------------- | | GPU | 任何 NVIDIA GPU（可选） | NVIDIA RTX 3080 及以上（用于嵌入生成） | | 显存（VRAM） | ChromaDB 本身不需要 GPU | 8–16 GB（用于本地嵌入模型） | | 内存（RAM） | 4 GB | 16–32 GB | | CPU | 2 个核心 | 8 核 | | 磁盘 | 10 GB | 50–200 GB（用于大型数据集） | | 操作系统 | Ubuntu 20.04+ | Ubuntu 22.04 | | Docker | 需要 | Docker + Docker Compose | | 端口 | 22, 8000 | 22, 8000 | {% hint style="info" %} ChromaDB 本身不要求 GPU —— 它在 CPU 上也能高效运行。不过， **生成嵌入** （将文本转换为向量）在 GPU 加速下能显著受益。如果您计划使用本地嵌入模型（sentence-transformers 等），请选择带 GPU 的服务器。 {% endhint %} *** ## 在 CLORE.AI 上快速部署 ### 1. 找到合适的服务器 前往 [CLORE.AI 市场](https://clore.ai/marketplace) 并选择： * **仅 CPU** 用于 ChromaDB 服务器 + API（存储预先计算的嵌入） * **GPU 服务器** 如果您也希望本地生成嵌入 ### 2. 配置您的部署 **Docker 镜像：** ``` chromadb/chroma:latest ``` **端口映射：** ``` 22 → SSH 访问 8000 → ChromaDB HTTP API ``` **环境变量：** ``` IS_PERSISTENT=TRUE ANONYMIZED_TELEMETRY=FALSE CHROMA_SERVER_AUTH_CREDENTIALS_FILE=/chroma/auth.txt ``` **启动命令：** ```bash uvicorn chromadb.app:app --host 0.0.0.0 --port 8000 ``` ### 3. 测试部署 ```bash curl http://:8000/api/v1/heartbeat # 预期：{"nanosecond heartbeat": } ``` *** ## 逐步设置 ### 第一步：SSH 登录到您的服务器 ```bash ssh root@ -p ``` ### 第 2 步：创建数据目录 ```bash mkdir -p /workspace/chromadb/data mkdir -p /workspace/chromadb/config ``` ### 第 3 步：运行 ChromaDB 容器 ```bash docker run -d \ --name chromadb \ -p 8000:8000 \ -v /workspace/chromadb/data:/chroma/chroma \ -e IS_PERSISTENT=TRUE \ -e ANONYMIZED_TELEMETRY=FALSE \ -e CHROMA_SERVER_LOG_LEVEL=INFO \ chromadb/chroma:latest ``` ### 第 4 步：验证是否正在运行 ```bash # 检查健康状态 curl http://localhost:8000/api/v1/heartbeat # 检查版本 curl http://localhost:8000/api/v1/version # 列出集合 curl http://localhost:8000/api/v1/collections ``` ### 第 5 步：安装 Python 客户端 ```bash pip install chromadb pip install sentence-transformers # 用于本地 GPU 嵌入 pip install openai # 用于 OpenAI 嵌入 ``` ### 第 6 步：从 Python 测试连接性 ```python import chromadb client = chromadb.HttpClient(host="", port=8000) print(f"ChromaDB 版本: {client.get_version()}") print(f"心跳: {client.heartbeat()}") ``` ### 第 7 步：（可选）启用身份验证 ```bash # 创建认证凭据 echo "admin:$2y$12$$(openssl rand -hex 16)" > /workspace/chromadb/auth.txt # 启用身份验证运行 docker run -d \ --name chromadb-auth \ -p 8000:8000 \ -v /workspace/chromadb/data:/chroma/chroma \ -v /workspace/chromadb/auth.txt:/chroma/auth.txt \ -e IS_PERSISTENT=TRUE \ -e CHROMA_SERVER_AUTH_CREDENTIALS_FILE=/chroma/auth.txt \ -e CHROMA_SERVER_AUTH_CREDENTIALS_PROVIDER=chromadb.auth.providers.HtpasswdFileServerAuthCredentialsProvider \ -e CHROMA_SERVER_AUTH_PROVIDER=chromadb.auth.basic.BasicAuthServerProvider \ chromadb/chroma:latest ``` *** ## 使用示例 ### 示例 1：基本向量存储操作 ```python import chromadb from chromadb.utils import embedding_functions # 连接到 Clore.ai 服务器上的 ChromaDB client = chromadb.HttpClient( host="", port=8000 ) # 使用 sentence-transformers 生成嵌入（如果可用则在 GPU 上运行） embedding_fn = embedding_functions.SentenceTransformerEmbeddingFunction( model_name="all-MiniLM-L6-v2" ) # 创建集合 collection = client.get_or_create_collection( name="clore_ai_docs", embedding_function=embedding_fn, metadata={"hnsw:space": "cosine"} # 距离度量 ) # 添加文档 documents = [ "Clore.ai 是一个去中心化的 GPU 云市场，用于 AI 工作负载。", "您可以在 Clore.ai 上租用 NVIDIA RTX 4090、A100 和 H100 GPU。", "Clore.ai 支持基于 Docker 的任意 AI 框架部署。", "Clore.ai 的价格与 AWS 和 GCP 相比具有竞争力。", "Clore.ai 市场在全球拥有数千台 GPU 服务器。", "您可以部署 PyTorch、TensorFlow、JAX 和其他机器学习框架。", "Clore.ai 提供按点价的计费以实现更具成本效益的 GPU 计算。", ] ids = [f"doc_{i}" for i in range(len(documents))] collection.add( documents=documents, ids=ids, metadatas=[{"source": "docs", "index": i} for i in range(len(documents))] ) print(f"已向集合添加 {len(documents)} 个文档") print(f"集合大小: {collection.count()} 个文档") ``` *** ### 示例 2：语义搜索 ```python import chromadb from chromadb.utils import embedding_functions client = chromadb.HttpClient(host="", port=8000) embedding_fn = embedding_functions.SentenceTransformerEmbeddingFunction( model_name="all-MiniLM-L6-v2" ) collection = client.get_collection( name="clore_ai_docs", embedding_function=embedding_fn ) # 语义搜索查询 queries = [ "GPU 租赁费用是多少？", "有哪些机器学习工具可用？", "告诉我有关 GPU 硬件选项的信息", ] for query in queries: results = collection.query( query_texts=[query], n_results=3, include=["documents", "distances", "metadatas"] ) print(f"\n🔍 查询: {query}") for i, (doc, dist) in enumerate(zip( results["documents"][0], results["distances"][0] )): similarity = 1 - dist # 将距离转换为相似度 print(f" {i+1}. [{similarity:.3f}] {doc[:100]}...") ``` *** ### 示例 3：与 ChromaDB + OpenAI 的 RAG 流水线 ```python import chromadb from chromadb.utils import embedding_functions from openai import OpenAI # 初始化客户端 chroma_client = chromadb.HttpClient(host="", port=8000) openai_client = OpenAI(api_key="your-openai-api-key") # 使用 OpenAI 嵌入 openai_ef = embedding_functions.OpenAIEmbeddingFunction( api_key="your-openai-api-key", model_name="text-embedding-3-small" ) # 获取集合 collection = chroma_client.get_or_create_collection( name="knowledge_base", embedding_function=openai_ef ) def add_to_knowledge_base(texts, ids=None, metadatas=None): """将文档添加到 ChromaDB 知识库。""" if ids is None: ids = [f"doc_{i}" for i in range(len(texts))] collection.add(documents=texts, ids=ids, metadatas=metadatas or [{}]*len(texts)) print(f"✓ 已添加 {len(texts)} 个文档。总计: {collection.count()}") def rag_query(question, n_context=5): """检索相关上下文并使用 GPT-4 生成答案。""" # 1. 检索相关文档 results = collection.query( query_texts=[question], n_results=n_context, include=["documents", "distances"] ) context_docs = results["documents"][0] distances = results["distances"][0] # 2. 构建上下文字符串 context = "\n\n".join([ f"[来源 {i+1} (相关性: {1-d:.2f})]: {doc}" for i, (doc, d) in enumerate(zip(context_docs, distances)) ]) # 3. 使用 LLM 生成答案 messages = [ { "role": "system", "content": "你是一个乐于助人的助手。请根据提供的上下文回答问题。如果答案不在上下文中，请说明。" }, { "role": "user", "content": f"Context:\n{context}\n\nQuestion: {question}" } ] response = openai_client.chat.completions.create( model="gpt-4-turbo", messages=messages, temperature=0.1 ) answer = response.choices[0].message.content return { "question": question, "answer": answer, "sources": context_docs, "relevance_scores": [1 - d for d in distances] } # 示例用法 knowledge = [ "Clore.ai 是一个拥有超过 45,000 名用户的 GPU 云市场。", "Clore.ai 支持基于 Docker 的工作负载部署。", "Clore.ai 上的 GPU 服务器范围从 GTX 1080 到 H100。", "您可以使用 SSH 访问和自定义端口来部署 AI 应用。", ] add_to_knowledge_base(knowledge) result = rag_query("Clore.ai 有多少用户？") print(f"问: {result['question']}") print(f"答: {result['answer']}") ``` *** ### 示例 4：多集合文档管理 ```python import chromadb from chromadb.utils import embedding_functions client = chromadb.HttpClient(host="", port=8000) embedding_fn = embedding_functions.SentenceTransformerEmbeddingFunction( model_name="all-mpnet-base-v2" # 更高质量的嵌入 ) # 为不同类型的文档创建单独的集合 collections = { "technical_docs": client.get_or_create_collection("technical_docs", embedding_function=embedding_fn), "faq": client.get_or_create_collection("faq", embedding_function=embedding_fn), "blog_posts": client.get_or_create_collection("blog_posts", embedding_function=embedding_fn), } # 向各自集合添加文档 collections["technical_docs"].add( documents=["Clore.ai 的 Docker 部署指南", "GPU 服务器的 SSH 配置"], ids=["tech_001", "tech_002"], metadatas=[{"type": "guide", "version": "v2"}, {"type": "config"}] ) collections["faq"].add( documents=["问：我如何付款？答：通过加密货币。", "问：有哪些 GPU？答：从 RTX 到 H100。"], ids=["faq_001", "faq_002"], metadatas=[{"category": "payment"}, {"category": "hardware"}] ) # 在所有集合中搜索 def search_all_collections(query, n_results=2): all_results = [] for name, col in collections.items(): results = col.query(query_texts=[query], n_results=n_results) for doc, dist in zip(results["documents"][0], results["distances"][0]): all_results.append({ "collection": name, "document": doc, "similarity": 1 - dist }) # 按相关性排序 all_results.sort(key=lambda x: x["similarity"], reverse=True) return all_results[:n_results * 2] results = search_all_collections("我如何使用 Docker 部署？") for r in results: print(f"[{r['collection']}] ({r['similarity']:.3f}) {r['document'][:80]}...") ``` *** ### 示例 5：过滤和元数据查询 ```python import chromadb client = chromadb.HttpClient(host="", port=8000) collection = client.get_collection("technical_docs") # 添加带有丰富元数据的文档 collection.add( documents=[ "指南：在 NVIDIA A100 GPU 集群上运行 PyTorch", "指南：在 RTX 4090 上进行 TensorFlow 分布式训练", "教程：在 GPU 上使用 LoRA 对 LLM 进行微调", "参考：CUDA 12.1 兼容性矩阵", "指南：面向多 GPU 设置的 Docker 网络", ], ids=["d1", "d2", "d3", "d4", "d5"], metadatas=[ {"type": "guide", "gpu": "A100", "framework": "pytorch", "year": 2024}, {"type": "guide", "gpu": "RTX4090", "framework": "tensorflow", "year": 2024}, {"type": "tutorial", "gpu": "any", "framework": "transformers", "year": 2024}, {"type": "reference", "gpu": "any", "framework": "cuda", "year": 2023}, {"type": "guide", "gpu": "multi", "framework": "docker", "year": 2024}, ] ) # 使用元数据过滤进行查询 results = collection.query( query_texts=["GPU 培训指南"], n_results=3, where={"type": "guide"}, # 仅返回指南 include=["documents", "metadatas", "distances"] ) print("过滤后的结果（type=guide）：") for doc, meta, dist in zip( results["documents"][0], results["metadatas"][0], results["distances"][0] ): print(f" [{1-dist:.3f}] {doc}") print(f" 元数据: {meta}") ``` *** ## invokeai.yaml 配置文件 ### Docker Compose（生产） ```yaml version: '3.8' services: chromadb： image: chromadb/chroma:latest container_name: chromadb ports: - "8000:8000" volumes: - chromadb_data:/chroma/chroma environment: - IS_PERSISTENT=TRUE - ANONYMIZED_TELEMETRY=FALSE - CHROMA_SERVER_LOG_LEVEL=INFO - ALLOW_RESET=FALSE - CHROMA_SEGMENT_CACHE_POLICY=LRU - CHROMA_MEMORY_LIMIT_BYTES=2147483648 # 2 GB 缓存 restart: unless-stopped healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8000/api/v1/heartbeat"] interval: 30s timeout: 10s retries: 3 volumes: chromadb_data: driver: local ``` ### 环境变量参考 | 变量 | 默认 | 描述 | | ----------------------------- | ------- | --------------- | | `IS_PERSISTENT` | `FALSE` | 启用持久化存储 | | `ANONYMIZED_TELEMETRY` | `TRUE` | 禁用使用情况跟踪 | | `CHROMA_SERVER_LOG_LEVEL` | `INFO` | 日志详细级别 | | `CHROMA_MEMORY_LIMIT_BYTES` | 无 | 分段缓存的最大内存 | | `ALLOW_RESET` | `FALSE` | 允许通过 API 重置所有数据 | | `CHROMA_SERVER_AUTH_PROVIDER` | 无 | 身份验证提供者类 | *** ## 1. 使用 SDXL-Turbo 或 SDXL-Lightning 以实现快速生成 ### 1. 选择合适的嵌入模型 | 模型 | 维度 | 适用场景 | 速度 | 是否需要 GPU | | ------------------------ | ---- | ---- | ---- | -------- | | `all-MiniLM-L6-v2` | 384 | 通用使用 | 快速 | 否 | | `all-mpnet-base-v2` | 768 | 中等 | 更好 | 可选 | | `text-embedding-3-small` | 1536 | 通用使用 | 很好 | 仅 API | | `BAAI/bge-large-en-v1.5` | 1024 | 中等 | 最佳选择 | 是 | ### 2. 批量更新以提高速度 ```python # 以 100-1000 为批次添加以获得最佳性能 BATCH_SIZE = 500 for i in range(0, len(all_documents), BATCH_SIZE): batch = all_documents[i:i+BATCH_SIZE] collection.add( documents=[d["text"] for d in batch], ids=[d["id"] for d in batch], metadatas=[d["meta"] for d in batch] ) print(f"批次 {i//BATCH_SIZE + 1} 完成") ``` ### 3. HNSW 索引调优 ```python collection = client.create_collection( name="optimized", metadata={ "hnsw:space": "cosine", "hnsw:construction_ef": 200, # 更高 = 更好的索引质量（构建更慢） "hnsw:search_ef": 100, # 更高 = 更好的召回率（搜索更慢） "hnsw:M": 32, # 更高 = 更好的召回率（占用更多内存） } ) ``` ### 4. 本地使用的持久化客户端 ```python # 直接在 Clore.ai 服务器上进行开发时使用 import chromadb client = chromadb.PersistentClient(path="/workspace/chromadb/data") # 无需服务器，适合单进程使用且更快 ``` *** ## 故障排除 ### 问题：无法连接到 ChromaDB ```bash # 检查容器是否正在运行 docker ps | grep chromadb # 检查日志 docker logs chromadb --tail 20 # 在容器内部测试 docker exec chromadb curl http://localhost:8000/api/v1/heartbeat ``` ### 问题：容器重启后数据丢失 ```bash # 确保已挂载卷 docker inspect chromadb | grep Mounts -A 10 # 使用显式卷重新运行 docker run -d -p 8000:8000 \ -v /workspace/chromadb/data:/chroma/chroma \ -e IS_PERSISTENT=TRUE \ chromadb/chroma:latest ``` ### 问题：内存不足错误 ```bash # 限制内存缓存 docker run -d -p 8000:8000 \ -e CHROMA_MEMORY_LIMIT_BYTES=1073741824 \ -v /workspace/chromadb/data:/chroma/chroma \ chromadb/chroma:latest ``` ### 问题：嵌入生成缓慢 ```bash # 验证嵌入是否正在使用 GPU python3 -c " import torch from sentence_transformers import SentenceTransformer model = SentenceTransformer('all-MiniLM-L6-v2', device='cuda') print(f'嵌入模型在: {model.device}') " ``` ### 问题：重启后未找到集合 ```bash # 验证是否启用了持久性 curl http://localhost:8000/api/v1/collections # 如果为空，说明未设置 IS_PERSISTENT 或卷未挂载 ``` *** ## 文档 * **GitHub**: * **官方文档**: * **Docker Hub**: * **PyPI**: * **Discord**: * **CLORE.AI 市场**: *** ## Clore.ai 的 GPU 建议 | 在 Clore.ai 上的预估费用 | 开发/测试 | RTX 3090（24GB） | | ----------------- | ----- | -------------- | | \~$0.12/每 GPU/每小时 | 生产 | RTX 4090（24GB） | | 生产环境 RAG | 生产 | RTX 4090（24GB） | | 高吞吐量嵌入 | 大规模 | A100 80GB | > GPU 服务器上。浏览可用 GPU 并按小时租用 — 无需承诺，提供完整的 root 访问权限。 [Clore.ai](https://clore.ai/marketplace) GPU 服务器。浏览可用 GPU 并按小时租用 — 无需承诺，提供完整的 root 访问权限。 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.clore.ai/guides/guides_v2-zh/rag-yu-xiang-liang-shu-ju-ku/chromadb.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.