ChromaDB

在 Clore.ai 的 GPU 上部署用于 AI 应用的开源向量数据库 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 — 一流的集成

所有示例都可以在通过以下方式租用的 GPU 服务器上运行 CLORE.AI 市场.

---

服务器要求

参数	最低要求	推荐配置
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

ChromaDB 本身不要求 GPU —— 它在 CPU 上也能高效运行。不过， 生成嵌入 （将文本转换为向量）在 GPU 加速下能显著受益。如果您计划使用本地嵌入模型（sentence-transformers 等），请选择带 GPU 的服务器。

---

在 CLORE.AI 上快速部署

1. 找到合适的服务器

前往 CLORE.AI 市场 并选择：

• 仅 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

启动命令：

uvicorn chromadb.app:app --host 0.0.0.0 --port 8000

3. 测试部署

curl http://<server-ip>:8000/api/v1/heartbeat
# 预期：{"nanosecond heartbeat": <timestamp>}

---

逐步设置

第一步：SSH 登录到您的服务器

ssh root@<your-clore-server-ip> -p <ssh-port>

第 2 步：创建数据目录

mkdir -p /workspace/chromadb/data
mkdir -p /workspace/chromadb/config

第 3 步：运行 ChromaDB 容器

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 步：验证是否正在运行

# 检查健康状态
curl http://localhost:8000/api/v1/heartbeat

# 检查版本
curl http://localhost:8000/api/v1/version

# 列出集合
curl http://localhost:8000/api/v1/collections

第 5 步：安装 Python 客户端

pip install chromadb
pip install sentence-transformers  # 用于本地 GPU 嵌入
pip install openai                  # 用于 OpenAI 嵌入

第 6 步：从 Python 测试连接性

import chromadb

client = chromadb.HttpClient(host="<server-ip>", port=8000)
print(f"ChromaDB 版本: {client.get_version()}")
print(f"心跳: {client.heartbeat()}")

第 7 步：（可选）启用身份验证

# 创建认证凭据
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：基本向量存储操作

import chromadb
from chromadb.utils import embedding_functions

# 连接到 Clore.ai 服务器上的 ChromaDB
client = chromadb.HttpClient(
    host="<your-clore-server-ip>",
    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：语义搜索

import chromadb
from chromadb.utils import embedding_functions

client = chromadb.HttpClient(host="<server-ip>", 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 流水线

import chromadb
from chromadb.utils import embedding_functions
from openai import OpenAI

# 初始化客户端
chroma_client = chromadb.HttpClient(host="<server-ip>", 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：多集合文档管理

import chromadb
from chromadb.utils import embedding_functions

client = chromadb.HttpClient(host="<server-ip>", 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：过滤和元数据查询

import chromadb

client = chromadb.HttpClient(host="<server-ip>", 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（生产）

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. 批量更新以提高速度

# 以 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 索引调优

collection = client.create_collection(
    name="optimized",
    metadata={
        "hnsw:space": "cosine",
        "hnsw:construction_ef": 200,  # 更高 = 更好的索引质量（构建更慢）
        "hnsw:search_ef": 100,        # 更高 = 更好的召回率（搜索更慢）
        "hnsw:M": 32,                 # 更高 = 更好的召回率（占用更多内存）
    }
)

4. 本地使用的持久化客户端

# 直接在 Clore.ai 服务器上进行开发时使用
import chromadb

client = chromadb.PersistentClient(path="/workspace/chromadb/data")
# 无需服务器，适合单进程使用且更快

---

故障排除

问题：无法连接到 ChromaDB

# 检查容器是否正在运行
docker ps | grep chromadb

# 检查日志
docker logs chromadb --tail 20

# 在容器内部测试
docker exec chromadb curl http://localhost:8000/api/v1/heartbeat

问题：容器重启后数据丢失

# 确保已挂载卷
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

问题：内存不足错误

# 限制内存缓存
docker run -d -p 8000:8000 \
  -e CHROMA_MEMORY_LIMIT_BYTES=1073741824 \
  -v /workspace/chromadb/data:/chroma/chroma \
  chromadb/chroma:latest

问题：嵌入生成缓慢

# 验证嵌入是否正在使用 GPU
python3 -c "
import torch
from sentence_transformers import SentenceTransformer
model = SentenceTransformer('all-MiniLM-L6-v2', device='cuda')
print(f'嵌入模型在: {model.device}')
"

问题：重启后未找到集合

# 验证是否启用了持久性
curl http://localhost:8000/api/v1/collections
# 如果为空，说明未设置 IS_PERSISTENT 或卷未挂载

---

文档

• GitHub: https://github.com/chroma-core/chroma

• 官方文档: https://docs.trychroma.com

• Docker Hub: https://hub.docker.com/r/chromadb/chroma

• PyPI: https://pypi.org/project/chromadb

• Discord: https://discord.gg/MMeYNTmh3x

• CLORE.AI 市场: https://clore.ai/marketplace

---

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 GPU 服务器。浏览可用 GPU 并按小时租用 — 无需承诺，提供完整的 root 访问权限。