基础概念与安装 #
核心概念 #
在开始使用 Chroma 之前，让我们先了解几个核心概念。
向量嵌入（Vector Embedding） #
text
┌─────────────────────────────────────────────────────────────┐
│ 向量嵌入 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 定义： │
│ 将文本、图像等数据转换为高维向量表示 │
│ │
│ 示例： │
│ "苹果" → [0.1, 0.5, -0.3, 0.8, ...] │
│ "iPhone" → [0.12, 0.48, -0.28, 0.82, ...] │
│ │
│ 特点： │
│ - 语义相似的文本，向量也相似 │
│ - 可以计算向量之间的相似度 │
│ - 是 AI 理解文本的基础 │
│ │
│ 常见模型： │
│ - OpenAI text-embedding-ada-002 │
│ - Sentence Transformers │
│ - Cohere Embeddings │
│ │
└─────────────────────────────────────────────────────────────┘
集合（Collection） #
text
┌─────────────────────────────────────────────────────────────┐
│ 集合 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 定义： │
│ Chroma 中存储数据的基本单位，类似于数据库中的"表" │
│ │
│ 特点： │
│ - 每个集合有自己的嵌入函数 │
│ - 可以存储文档、向量、元数据 │
│ - 支持增删改查操作 │
│ │
│ 示例： │
│ ┌─────────────────────────────────────────┐ │
│ │ Collection: documents │ │
│ ├─────────────────────────────────────────┤ │
│ │ id: "doc1" │ │
│ │ document: "Python 是编程语言" │ │
│ │ embedding: [0.1, 0.2, ...] │ │
│ │ metadata: {"source": "web"} │ │
│ └─────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
文档（Document） #
text
┌─────────────────────────────────────────────────────────────┐
│ 文档 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 定义： │
│ 存储在集合中的基本数据单元 │
│ │
│ 组成部分： │
│ - id: 唯一标识符 │
│ - document: 文本内容（可选） │
│ - embedding: 向量嵌入（可选，可自动生成） │
│ - metadata: 元数据（可选） │
│ │
│ 示例： │
│ { │
│ "id": "doc1", │
│ "document": "Python 是一种流行的编程语言", │
│ "embedding": [0.1, 0.2, -0.3, ...], │
│ "metadata": { │
│ "source": "wikipedia", │
│ "category": "programming", │
│ "date": "2024-01-01" │
│ } │
│ } │
│ │
└─────────────────────────────────────────────────────────────┘
元数据（Metadata） #
text
┌─────────────────────────────────────────────────────────────┐
│ 元数据 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 定义： │
│ 附加在文档上的结构化信息，用于过滤和分类 │
│ │
│ 支持的类型： │
│ - 字符串 (string) │
│ - 整数 (int) │
│ - 浮点数 (float) │
│ - 布尔值 (bool) │
│ │
│ 用途： │
│ - 过滤查询结果 │
│ - 分类和组织文档 │
│ - 存储额外信息 │
│ │
│ 示例： │
│ { │
│ "source": "web", # 字符串 │
│ "page": 42, # 整数 │
│ "score": 0.95, # 浮点数 │
│ "published": true # 布尔值 │
│ } │
│ │
└─────────────────────────────────────────────────────────────┘
相似性搜索 #
text
┌─────────────────────────────────────────────────────────────┐
│ 相似性搜索 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 定义： │
│ 根据向量相似度找到最相关的文档 │
│ │
│ 常用距离度量： │
│ - 余弦相似度 (Cosine Similarity) - 默认 │
│ - 欧几里得距离 (L2) │
│ - 内积 (Inner Product) │
│ │
│ 工作原理： │
│ 1. 将查询文本转换为向量 │
│ 2. 计算与所有文档向量的相似度 │
│ 3. 返回相似度最高的 N 个结果 │
│ │
│ 示例： │
│ 查询: "编程语言" │
│ 结果: │
│ 1. "Python 是编程语言" (相似度: 0.95) │
│ 2. "JavaScript 用于网页" (相似度: 0.87) │
│ 3. "Java 是面向对象语言" (相似度: 0.82) │
│ │
└─────────────────────────────────────────────────────────────┘
系统要求 #
硬件要求 #
text
┌─────────────────────────────────────────────────────────────┐
│ 硬件要求 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 最低配置： │
│ - CPU: 双核处理器 │
│ - 内存: 4 GB RAM │
│ - 存储: 1 GB 可用空间 │
│ │
│ 推荐配置： │
│ - CPU: 四核或更多 │
│ - 内存: 8 GB RAM 或更多 │
│ - 存储: SSD，10 GB 可用空间 │
│ │
│ 生产环境： │
│ - CPU: 八核或更多 │
│ - 内存: 16 GB RAM 或更多 │
│ - 存储: SSD，100 GB 可用空间 │
│ │
└─────────────────────────────────────────────────────────────┘
软件要求 #
text
┌─────────────────────────────────────────────────────────────┐
│ 软件要求 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 操作系统： │
│ - macOS 10.15+ │
│ - Windows 10+ │
│ - Linux (Ubuntu 18.04+, CentOS 7+) │
│ │
│ Python 版本： │
│ - Python 3.8+ │
│ - 推荐 Python 3.10 或 3.11 │
│ │
│ 依赖项： │
│ - pip (Python 包管理器) │
│ - 虚拟环境工具 (venv, conda) │
│ │
└─────────────────────────────────────────────────────────────┘
安装方法 #
方法一：pip 安装（推荐） #
bash
# 基础安装
pip install chromadb
# 安装特定版本
pip install chromadb==0.4.22
# 升级到最新版本
pip install --upgrade chromadb
方法二：使用虚拟环境 #
bash
# 创建虚拟环境
python -m venv chroma-env
# 激活虚拟环境
# macOS/Linux
source chroma-env/bin/activate
# Windows
chroma-env\Scripts\activate
# 安装 Chroma
pip install chromadb
方法三：使用 conda #
bash
# 创建 conda 环境
conda create -n chroma-env python=3.10
# 激活环境
conda activate chroma-env
# 安装 Chroma
pip install chromadb
方法四：从源码安装 #
bash
# 克隆仓库
git clone https://github.com/chroma-core/chroma.git
cd chroma
# 安装依赖
pip install -e .
安装验证 #
验证安装 #
python
import chromadb
print(chromadb.__version__)
运行测试 #
python
import chromadb
client = chromadb.Client()
collection = client.create_collection("test")
collection.add(
documents=["测试文档"],
ids=["test1"]
)
results = collection.query(
query_texts=["测试"],
n_results=1
)
print(results)
print("Chroma 安装成功！")
可选依赖 #
嵌入函数依赖 #
bash
# Sentence Transformers
pip install chromadb sentence-transformers
# OpenAI Embeddings
pip install chromadb openai
# Cohere Embeddings
pip install chromadb cohere
# Google PaLM Embeddings
pip install chromadb google-generativeai
开发依赖 #
bash
# 安装开发工具
pip install chromadb[dev]
# 包含：
# - pytest (测试)
# - black (代码格式化)
# - mypy (类型检查)
# - pre-commit (Git hooks)
环境配置 #
配置环境变量 #
bash
# .env 文件
CHROMA_HOST=localhost
CHROMA_PORT=8000
OPENAI_API_KEY=your-api-key
COHERE_API_KEY=your-api-key
Python 代码配置 #
python
import os
from dotenv import load_dotenv
load_dotenv()
import chromadb
client = chromadb.HttpClient(
host=os.getenv("CHROMA_HOST", "localhost"),
port=int(os.getenv("CHROMA_PORT", 8000))
)
客户端模式 #
内存模式 #
python
import chromadb
client = chromadb.Client()
# 数据存储在内存中，程序结束后丢失
持久化模式 #
python
import chromadb
client = chromadb.PersistentClient(path="./chroma_db")
# 数据持久化到磁盘
服务器模式 #
python
import chromadb
client = chromadb.HttpClient(
host="localhost",
port=8000
)
# 连接到 Chroma 服务器
异步客户端 #
python
import chromadb
client = await chromadb.AsyncHttpClient(
host="localhost",
port=8000
)
# 异步操作
常见问题 #
问题 1：安装失败 #
bash
# 解决方案：升级 pip
pip install --upgrade pip
# 解决方案：使用国内镜像
pip install chromadb -i https://pypi.tuna.tsinghua.edu.cn/simple
问题 2：依赖冲突 #
bash
# 解决方案：使用虚拟环境
python -m venv fresh-env
source fresh-env/bin/activate
pip install chromadb
问题 3：SQLite 版本问题 #
bash
# Chroma 需要 SQLite 3.35+
# 检查 SQLite 版本
python -c "import sqlite3; print(sqlite3.sqlite_version)"
# 如果版本过低，升级 SQLite 或使用其他存储后端
问题 4：内存不足 #
python
# 解决方案：使用持久化存储
client = chromadb.PersistentClient(path="./chroma_db")
# 或使用服务器模式
client = chromadb.HttpClient(host="localhost", port=8000)
下一步 #
现在你已经完成了 Chroma 的安装和配置，接下来学习 快速开始，编写你的第一个 Chroma 程序！
最后更新：2026-04-04