搬瓦工 VPS 部署 ChromaDB 嵌入向量存储教程

ChromaDB 是一款轻量级的开源嵌入向量数据库，专为 AI 应用设计。它以简单易用著称，几行 Python 代码即可完成向量的存储和检索。ChromaDB 既可以作为嵌入式库在应用内运行，也可以部署为独立的服务端，是构建 RAG 应用最常用的向量存储之一。本教程将介绍在搬瓦工 VPS 上部署和使用 ChromaDB 的完整流程。

一、ChromaDB 特点

极简 API：API 设计简洁，学习成本极低。
内置向量化：默认集成 Sentence Transformers 嵌入模型。
灵活部署：支持嵌入式、客户端-服务端和 Docker 三种模式。
自动持久化：数据自动存储到磁盘，重启不丢失。
框架集成：与 LangChain、LlamaIndex 等框架深度集成。

二、环境准备

操作系统：Ubuntu 20.04 或更高版本。
内存：至少 1GB（嵌入式模式），2GB 以上更佳。
Python：Python 3.9 或更高版本。

apt update && apt upgrade -y
apt install python3 python3-pip python3-venv -y

mkdir -p /opt/chromadb && cd /opt/chromadb
python3 -m venv venv
source venv/bin/activate

三、安装 ChromaDB

pip install chromadb

四、嵌入式模式使用

最简单的使用方式，直接在 Python 应用中作为库使用：

cat > /opt/chromadb/embedded_demo.py <<'EOF'
import chromadb

# 创建持久化客户端
client = chromadb.PersistentClient(path="/opt/chromadb/data")

# 创建或获取集合
collection = client.get_or_create_collection(
    name="documents",
    metadata={"hnsw:space": "cosine"}  # 使用余弦相似度
)

# 添加文档（ChromaDB 会自动生成嵌入向量）
collection.add(
    documents=[
        "如何在 VPS 上安装 Docker 容器引擎",
        "Nginx 反向代理配置详解和最佳实践",
        "Linux 服务器安全加固和防火墙设置",
        "MySQL 数据库性能优化和索引调优",
        "使用 Let's Encrypt 配置免费 SSL 证书"
    ],
    ids=["doc1", "doc2", "doc3", "doc4", "doc5"],
    metadatas=[
        {"category": "容器"},
        {"category": "Web服务器"},
        {"category": "安全"},
        {"category": "数据库"},
        {"category": "SSL"}
    ]
)

# 查询相似文档
results = collection.query(
    query_texts=["服务器安全配置"],
    n_results=3
)

print("查询结果：")
for i, doc in enumerate(results["documents"][0]):
    distance = results["distances"][0][i]
    metadata = results["metadatas"][0][i]
    print(f"  {i+1}. [{metadata['category']}] {doc} (距离: {distance:.4f})")

print(f"\n集合总文档数: {collection.count()}")
EOF

python3 embedded_demo.py

五、服务端模式部署

将 ChromaDB 部署为独立服务，供多个应用共享：

# 方式一：直接运行
chroma run --host 0.0.0.0 --port 8000 --path /opt/chromadb/server-data

# 方式二：使用 Docker 部署（参考 Docker 安装教程）
docker run -d --name chromadb \
  -p 8000:8000 \
  -v /opt/chromadb/server-data:/chroma/chroma \
  chromadb/chroma:latest

5.1 客户端连接

cat > /opt/chromadb/client_demo.py <<'EOF'
import chromadb

# 连接远程 ChromaDB 服务
client = chromadb.HttpClient(host="localhost", port=8000)

# 操作方式与嵌入式模式完全一致
collection = client.get_or_create_collection("remote_docs")
collection.add(
    documents=["测试文档内容"],
    ids=["test1"]
)
print(f"远程集合文档数: {collection.count()}")
EOF

六、使用自定义嵌入模型

pip install sentence-transformers

cat > /opt/chromadb/custom_embedding.py <<'EOF'
import chromadb
from chromadb.utils.embedding_functions import SentenceTransformerEmbeddingFunction

# 使用指定的嵌入模型
embedding_fn = SentenceTransformerEmbeddingFunction(
    model_name="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
)

client = chromadb.PersistentClient(path="/opt/chromadb/custom-data")
collection = client.get_or_create_collection(
    name="multilingual_docs",
    embedding_function=embedding_fn
)

# 添加中文文档
collection.add(
    documents=[
        "搬瓦工 VPS 提供高性能的虚拟专用服务器",
        "Docker 容器技术简化了应用部署流程",
        "向量数据库是 AI 应用的重要基础组件"
    ],
    ids=["zh1", "zh2", "zh3"]
)

results = collection.query(query_texts=["虚拟服务器"], n_results=2)
for doc in results["documents"][0]:
    print(f"  - {doc}")
EOF

七、配置 Systemd 服务

cat > /etc/systemd/system/chromadb.service <<EOF
[Unit]
Description=ChromaDB Vector Database Server
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/chromadb
ExecStart=/opt/chromadb/venv/bin/chroma run --host 0.0.0.0 --port 8000 --path /opt/chromadb/server-data
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable chromadb
systemctl start chromadb

八、配置认证

生产环境建议启用认证保护：

# 使用 Token 认证启动
chroma run --host 0.0.0.0 --port 8000 \
  --path /opt/chromadb/server-data \
  --chroma-server-authn-provider chromadb.auth.token_authn.TokenAuthenticationServerProvider \
  --chroma-server-authn-credentials "your-secure-token"

# 客户端使用 Token 连接
import chromadb
from chromadb.config import Settings

client = chromadb.HttpClient(
    host="localhost",
    port=8000,
    settings=Settings(
        chroma_client_auth_provider="chromadb.auth.token_authn.TokenAuthClientProvider",
        chroma_client_auth_credentials="your-secure-token"
    )
)

九、与 RAG 框架集成

ChromaDB 可以无缝集成到 LangChain 和 LlamaIndex 中：

# LangChain 集成
from langchain_community.vectorstores import Chroma
from langchain_community.embeddings import HuggingFaceEmbeddings

embeddings = HuggingFaceEmbeddings(model_name="sentence-transformers/all-MiniLM-L6-v2")
vectorstore = Chroma(
    persist_directory="/opt/chromadb/langchain-data",
    embedding_function=embeddings,
    collection_name="langchain_docs"
)

# 添加文档
vectorstore.add_texts(["VPS 安全配置指南", "Docker 部署最佳实践"])

# 相似度搜索
results = vectorstore.similarity_search("安全配置", k=3)

十、数据管理

# 备份 ChromaDB 数据
tar -czf /opt/backups/chromadb-$(date +%Y%m%d).tar.gz /opt/chromadb/server-data/

# 集合管理
python3 -c "
import chromadb
client = chromadb.PersistentClient(path='/opt/chromadb/data')
# 列出所有集合
for c in client.list_collections():
    print(f'{c.name}: {c.count()} 条文档')
"

十一、常见问题

首次启动缓慢

ChromaDB 首次使用时会下载默认的嵌入模型（约 90MB），搬瓦工海外节点下载速度通常很好。也可以提前手动下载模型。

数据量限制

ChromaDB 适合中小规模的数据集（百万级以下）。如果数据量更大，建议使用 Milvus 或 Weaviate。

总结

ChromaDB 以其极简的 API 和轻量级部署成为 RAG 应用最受欢迎的向量存储选择。无论是快速原型开发还是中小规模的生产部署，ChromaDB 都能很好地胜任。选购搬瓦工 VPS 请查看全部方案，使用优惠码 NODESEEK2026 可享受 6.77% 的折扣，购买链接：bwh81.net。