# 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 访问权限。