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

引言

Chroma DB是一个开源的向量数据库，特别适合存储和查询嵌入向量，广泛应用于AI、机器学习和大语言模型(LLM)领域。本教程将详细指导Windows 11用户完成Chroma DB的安装过程，即使是完全没有经验的新手也能轻松上手。

准备工作

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

Windows 11操作系统（版本22H2或更新）
Python 3.8或更高版本（推荐3.10+）
pip包管理工具（通常随Python一起安装）
至少4GB可用内存
稳定的网络连接（用于下载依赖包）

检查Python环境

首先打开命令提示符(CMD)或PowerShell，输入以下命令检查Python版本：

代码片段

python --version

如果显示版本低于3.8，请先升级Python。可以到Python官网下载最新版本。

安装步骤

1. 创建虚拟环境（推荐）

为了避免与其他Python项目冲突，我们首先创建一个虚拟环境：

代码片段

python -m venv chroma_env

激活虚拟环境：

代码片段

.\chroma_env\Scripts\activate

激活后，你的命令行提示符前会显示(chroma_env)，表示已进入虚拟环境。

注意：每次重新打开终端后都需要重新激活虚拟环境

2. 安装Chroma DB核心包

在激活的虚拟环境中运行以下命令：

代码片段

pip install chromadb

这个命令会安装：
– Chroma DB核心功能
– HTTP客户端/服务器组件
– SQLite作为默认存储后端

实践经验：如果下载速度慢，可以使用国内镜像源

代码片段

pip install chromadb -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 安装可选依赖项（推荐）

为了获得完整功能，建议安装以下额外依赖：

代码片段

pip install sentence-transformers pypdf tiktoken openai

这些包提供了：
– sentence-transformers：文本嵌入模型
– pypdf：PDF文档处理能力
– tiktoken：OpenAI令牌计数工具

4. 验证安装

创建一个简单的Python脚本来测试Chroma DB是否正常工作：

代码片段

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=2
)

print("查询结果:", results)

将上述代码保存为test_chroma.py并运行：

代码片段

python test_chroma.py

如果看到类似以下的输出，说明安装成功：

代码片段

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

Chroma DB服务器模式（可选）

如果你需要将Chroma DB作为服务运行供其他应用访问：

1. 启动服务器

代码片段

chroma run --path .\chroma_data --port 8000

参数说明：
– --path: 指定数据存储路径（默认为./chromadb）
– --port: HTTP服务端口（默认为8000）

2. Python客户端连接示例

代码片段

import chromadb

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

# ...其余代码与本地模式相同...

Windows系统常见问题解决

错误: Microsoft Visual C++ Build Tools缺失

解决方案：
代码片段
```
pip install chromadb --only-binary=:all:
```
或者从Microsoft官网下载Visual Studio Build Tools
SQLite版本不兼容

更新SQLite:
代码片段
```
pip install pysqlite3-binary --upgrade
```
端口冲突

如果8000端口被占用，可以指定其他端口：
代码片段
```
chroma run --port 8001
```

Chroma DB基本使用示例

下面是一个完整的示例，展示如何使用Chroma DB存储和查询PDF文档内容：

代码片段

import chromadb
from sentence_transformers import SentenceTransformer 
from pypdf import PdfReader 

# 初始化模型和客户端 
model = SentenceTransformer('paraphrase-multilingual-MiniLM-L12-v2')
client = chromadb.Client()

# PDF处理函数 
def process_pdf(file_path):
    reader = PdfReader(file_path)
    text = ""
    for page in reader.pages:
        text += page.extract_text()
    return text 

# PDF文件路径 
pdf_path = "sample.pdf" # <--替换为你的PDF文件路径 

# PDF文本提取和处理 
pdf_text = process_pdf(pdf_path)
chunks = [pdf_text[i:i+500] for i in range(0, len(pdf_text), 500)] #分割成500字符的块 

#生成嵌入向量 
embeddings = model.encode(chunks).tolist() 

#创建集合并添加数据 
collection = client.create_collection("pdf_documents")
ids = [f"chunk_{i}" for i in range(len(chunks))]

collection.add(
    documents=chunks,
    embeddings=embeddings,
    ids=ids,
    metadatas=[{"type": "pdf_chunk"}]*len(chunks)
)

#查询示例 
query_text = "文档中的关键概念是什么？"
query_embedding = model.encode([query_text]).tolist()[0]

results = collection.query(
    query_embeddings=[query_embedding],
    n_results=3 #返回最相关的3个结果 
)

print("最相关的段落:")
for doc in results['documents'][0]:
    print("\n---\n")
    print(doc[:200] + "...") #只打印前200字符避免输出过长

Chroma DB数据持久化

默认情况下，Chroma DB使用临时存储。要持久化数据：

代码片段

client = chromadb.PersistentClient(path="./chroma_data") #数据将保存在当前目录下的chroma_data文件夹中 

#后续使用方式与之前相同...
collection = client.get_or_create_collection("my_collection")

Windows系统优化建议

性能优化：
- Chroma在SSD上的性能比HDD好很多倍。
- Windows Defender可能会影响性能，可以将工作目录添加到排除列表。
内存管理：
- Chroma会缓存部分数据在内存中。
- Windows上可以通过任务管理器监控内存使用情况。

定期备份：

代码片段

Compress-Archive -Path .\chroma_data -DestinationPath .\chroma_backup.zip

开机自启（如果需要）：

代码片段

schtasks /create /tn "ChromaDBServer" /tr "cmd /c 'cd C:\path\to\project && .\chroma_env\Scripts\activate && chroma run'" /sc onstart /ru System

Chrome浏览器集成开发技巧

虽然名字相似但无关，但可以在Chrome开发者工具中调试HTTP API:

F12打开开发者工具 -> Network标签页
Chrome地址栏访问: http://localhost:8000/api/v1/collections
Chrome会自动生成API请求预览

Docker方式运行（高级选项）

如果你熟悉Docker, Windows上也可以这样运行:

代码片段

docker pull ghcr.io/chroma-core/chroma:latest  
docker run -p 8000:8000 ghcr.io/chroma-core/chroma

注意：需要先安装Docker Desktop for Windows

Chroma DB GUI工具推荐

虽然官方没有提供GUI,但可以尝试这些开源工具:

Chromaroid – Electron-based GUI (GitHub搜索)
Jupyter Notebook – Python交互式界面

代码片段

pip install jupyterlab  
jupyter lab

然后在Notebook中导入和使用Chroma。

AI集成示例：结合OpenAI使用

下面是一个结合OpenAI和Chroma的完整工作流:

代码片段

import openai  
import chromadb  

openai.api_key = "your-api-key" # <--替换为你的OpenAI密钥  

def get_embedding(text):  
    response = openai.Embedding.create(  
        input=[text],  
        model="text-embedding-ada-002"  
    )  
    return response['data'][0]['embedding']  

client = chromadb.PersistentClient()  
collection = client.get_or_create_collection("openai_docs")  

docs = ["机器学习简介", "深度学习基础", "神经网络架构"]  

collection.add(  
    documents=docs,  
    ids=[f"doc{i}" for i in range(len(docs))],  
    embeddings=[get_embedding(doc) for doc in docs]  
)  

query_embedding = get_embedding("什么是神经网络?")  

results = collection.query(  
    query_embeddings=[query_embedding],  
    n_results=1  
)  

print("最相关文档:", results['documents'][0][0])

Windows服务监控脚本（PowerShell）

创建一个监控脚本monitor_chroma.ps1:

代码片段

while($true) {   
 $status=(Get-NetTCPConnection -LocalPort 8000 -ErrorAction SilentlyContinue)   
 if(!$status) { Start-Process cmd "/c .\chroma_env\Scripts\activate && chroma run" }   
 Start-Sleep -Seconds x10   
}

按Ctrl+C停止监控。

WSL2用户特别提示

如果你使用WSL2:

代码片段

sudo apt-get update && sudo apt-get install python3-pip   
pip install chromadb --user   
export PATH=$PATH:$HOME/.local/bin   
chroma run --path ~/chromadata

然后在Windows中访问: http://localhost:8000

ChromaDB与常见LLM框架集成表

LLM框架	PyPI包名	GitHub地址
LangChain	langchain-chroma	github.com/langchain-ai
LlamaIndex	llama-index	github.com/jerryjliu/llama_index
Haystack	farm-haystack	github.com/deepset-ai/haystack

Windows计划任务设置方法

让Chroma每天凌晨重启以释放内存:

代码片段

schtasks /create /tn "RestartChroma" /tr "taskkill /im python.exe /f & cd C:\path\to\project && start cmd /k .\\chroma_env\\Scripts\\activate && chroma run" /sc daily /st xx03:00:00 /ru System

替换xx03:00为你希望的时间。

ChromaDB与SQL数据库对比

Feature	ChromaDB	SQL数据库
数据类型	向量+元数据	结构化数据
查询方式	相似度搜索	精确匹配
最佳场景	语义搜索	事务处理

Windows防火墙设置

允许端口8000入站规则:

代码片段

New-NetFirewallRule -DisplayName "Allow Chroma Port" -Direction Inbound -LocalPort x8000 -Protocol TCP -Action Allow    
netsh advfirewall firewall add rule name="Allow Chroma Port" dir=in action=allow protocol=TCP localport=x8000

Python性能优化技巧

对于大型数据集处理时加速方法:

批量插入:

代码片段

batch_size=x10000     
for i in range(0, len(data), batch_size):     
 collection.add(...)

2.多线程:

代码片段

from multiprocessing.dummy import Pool as ThreadPool     
pool.xThreadPool(x4)     
pool.map(lambda x:xcollection.add(...), chunks)     
pool.close()      
pool.join()

通过本教程的学习，你应该已经掌握了在Windows11上安装和使用ChromeDB的全部基础知识。无论是本地开发还是生产部署都能游刃有余。