手把手教你在Windows WSL2上安装Chroma DB，新手必看教程 (2025年05月)

引言

Chroma DB是一个开源的向量数据库，专门为AI应用设计，特别适合存储和检索嵌入向量(embeddings)。本教程将带你从零开始，在Windows WSL2环境中安装和配置Chroma DB。即使你是完全的新手，也能跟着步骤顺利完成安装。

准备工作

在开始之前，请确保你的系统满足以下要求：

1. Windows 10版本2004或更高版本/Windows 11
2. 已启用WSL2功能
3. 已安装Ubuntu发行版（推荐20.04或22.04 LTS版本）

💡 如何检查WSL版本：在PowerShell中运行 wsl -l -v，确保VERSION列显示为2

第一步：设置WSL2环境

1. 打开Ubuntu终端：在Windows搜索栏输入”Ubuntu”并打开

2. 更新系统包列表：

   代码片段 复制代码

   sudo apt update && sudo apt upgrade -y
   

3. 安装Python环境：

   代码片段 复制代码

   sudo apt install python3 python3-pip python3-venv -y
   

⚠️ 注意：Chroma DB需要Python 3.7或更高版本。运行 python3 --version 确认你的Python版本

第二步：创建Python虚拟环境

为了避免与其他项目产生依赖冲突，我们创建一个专用虚拟环境：

# 创建项目目录并进入
mkdir chroma_project && cd chroma_project

# 创建虚拟环境
python3 -m venv chroma_env

# 激活虚拟环境
source chroma_env/bin/activate

激活后，你的命令行提示符前应该会显示 (chroma_env)。

🔄 小技巧：每次重新打开终端后都需要重新激活虚拟环境。如果忘记激活了，只需再次运行 source chroma_env/bin/activate

第三步：安装Chroma DB

现在我们可以安装Chroma DB及其依赖项：

pip install chromadb pysqlite3-binary --upgrade

这个命令会：
– chromadb：安装Chroma DB核心库
– pysqlite3-binary：提供SQLite后端支持（WSL2上需要）

🐞 常见问题：如果遇到SSL证书错误，可以尝试先运行：

代码片段 复制代码

pip install --upgrade certifi

第四步：验证安装

让我们写一个简单的脚本来测试Chroma DB是否正常工作：

1. 创建测试文件：

   代码片段 复制代码

   nano test_chroma.py
   

2. 粘贴以下代码：

   代码片段 复制代码

   import chromadb
   
   # 创建客户端实例
   client = chromadb.Client()
   
   # 创建一个集合（类似于表）
   collection = client.create_collection("test_collection")
   
   # 添加一些文档和嵌入向量（这里使用随机向量）
   collection.add(
       documents=["这是第一个文档", "这是第二个文档"],
       metadatas=[{"source": "doc1"}, {"source": "doc2"}],
       ids=["id1", "id2"]
   )
   
   # 查询相似文档（使用随机查询向量）
   results = collection.query(
       query_texts=["查找相似文档"],
       n_results=1
   )
   
   print("查询结果:", results)
   

3. 保存并退出（按Ctrl+X，然后按Y确认）

4. 运行测试脚本：

   代码片段 复制代码

   python test_chroma.py
   

如果一切正常，你应该看到类似这样的输出：

查询结果: {'ids': [['id1']], 'distances': [[0.123456]], 'metadatas': [[{'source': 'doc1'}]], 'embeddings': None, 'documents': [['这是第一个文档']]}

第五步：持久化存储配置（可选）

默认情况下，Chroma使用内存存储。要启用持久化存储：

# 修改之前的客户端创建代码为：
client = chromadb.PersistentClient(path="/path/to/store/data")

例如：

client = chromadb.PersistentClient(path="./chroma_data")

这会在当前目录下创建一个chroma_data文件夹来存储数据。

WSL2特定优化建议

1. 性能优化：
   将数据库文件存储在WSL文件系统中（如/home目录），而不是挂载的Windows驱动器上。

2. 内存管理：
   如果你的数据集很大，考虑增加WSL的内存限制：
   在Windows用户目录下创建或修改.wslconfig文件（如C:\Users\你的用户名.wslconfig）:

   添加以下内容：

   代码片段 复制代码

   [wsl2]
   memory=4GB    # 根据你的系统调整大小  
   swap=8GB      # Swap空间大小  
   localhostForwarding=true  <br>
    

常见问题解决

Q1: Chroma启动时报错”Failed to create collection”

A:
– 确保使用的是最新版本的Chroma (pip install --upgrade chromadb)
– WSL上的SQLite有时会有问题，尝试指定不同的后端：

client = chromadb.HttpClient() 

Q2: Python找不到模块chromadb

A:
– 确认你激活了正确的虚拟环境 (source chroma_env/bin/activate)
– 检查是否在正确的环境中安装了Chroma (pip list | grep chroma)

Q3: WSL中磁盘空间不足

A:
– WSL默认会占用Windows磁盘空间。清理不需要的包:

sudo apt autoremove -y 
sudo apt clean 

Chroma DB基本使用示例

下面是一个更完整的示例代码：

import chromadb
from chromadb.utils import embedding_functions

# 初始化客户端和嵌入函数 (这里使用默认的all-MiniLM-L6-v2模型)
client = chromadb.PersistentClient(path="./chroma_data")
sentence_transformer_ef = embedding_functions.SentenceTransformerEmbeddingFunction(model_name="all-MiniLM-L6-v2")

# 创建或获取集合 (类似数据库表)
collection = client.get_or_create_collection(
    name="my_documents",
    embedding_function=sentence_transformer_ef,
)

# 添加文档到集合中 (自动生成嵌入)
collection.add(
    documents=[
        "机器学习是AI的一个分支",
        "深度学习使用神经网络",
        "Python是一种流行的编程语言"
    ],
    metadatas=[
        {"category": "AI"},
        {"category": "AI"},
        {"category": "programming"}
    ],
    ids=["doc1", "doc2", "doc3"]
)

# 查询相似的文档 (自动将查询文本转换为嵌入)
results = collection.query(
    query_texts=["什么是神经网络?"],
    n_results=2,
)

print("最相似的文档:", results['documents'])
print("对应的元数据:", results['metadatas'])

这个例子展示了如何:
1. 使用持久化存储客户端
2. 设置自定义嵌入函数(Sentence Transformer)
3. 添加带有元数据的文档到集合中
4.执行语义搜索查询

Chrome DB可视化工具(可选)

如果你想要一个图形界面来查看和管理你的数据:

pip install gradio 

然后创建一个新的Python文件:

import gradio as gr 
import chromadb 

def query_chroma(query_text, n_results):
    client = chromadb.PersistentClient(path="./chroma_data")
    collection = client.get_or_create_collection("my_documents")

    results = collection.query(
        query_texts=[query_text],
        n_results=int(n_results)
    )

    return {
        "Documents": results["documents"],
        "Metadata": results["metadatas"],
        "Distances": results["distances"]
    }

iface = gr.Interface(
    fn=query_chroma,
    inputs=[
        gr.Textbox(label="Query Text"),
        gr.Slider(1, 10, value=3, label="Number of Results")
    ],
    outputs=gr.JSON(label="Results"),
) 

iface.launch(server_name="0.0.0.0") 

运行后访问 http://localhost:7860 ，你会看到一个简单的Web界面来查询你的数据库。

总结

通过本教程,你已经学会了:

✅如何在WSL2上搭建Python环境
✅如何正确安装和配置ChromeDB
✅基础的使用方法和持久化存储配置
✅针对WSL环境的优化建议

现在你可以开始构建自己的向量搜索应用了! ChromeDB非常适合构建:

• AI助手记忆存储
• RAG(检索增强生成)应用
•语义搜索系统

如果有任何问题,欢迎在评论区留言讨论!