目录

• 一、环境准备
• 二、安装方式
  • 1、本地持久化模式
  • 2、客户端-服务端模式
• 三、验证安装

---

参考

• 向量数据库技术系列三-Chroma介绍 (opens new window)
• 向量数据库Chroma的介绍 (opens new window)
• 【AI基础】从零开始：Chroma向量数据库构建高效AI应用全攻略 (opens new window)
• 向量数据库Chroma极简教程 (opens new window)
• 向量数据库：Chroma (opens new window)

---

Chroma：安装指南

一、环境准备

1. Python 版本：Chroma 要求 ​Python 3.8 及以上版本​。

2. 包管理工具：使用 pip 安装依赖。

3. 虚拟环境：在虚拟环境中安装，以隔离项目依赖，避免依赖冲突。

   # 使用 Conda
   conda create -n chroma_env python=3.11
   conda activate chroma_env
   

   # 使用 venv
   python -m venv chroma_env
   source chroma_env/bin/activate  # Linux/macOS
   chroma_env\Scripts\activate      # Windows
   

---

二、安装方式

1、本地持久化模式

适用场景：本地开发、小型项目（数据存储在内存或本地文件）。

• 安装chromadb

  pip install chromadb
  

  • 包含默认依赖：轻量级 SQLite 存储、HTTP 客户端。

• 持久化的客户端

  import chromadb
  client = chromadb.PersistentClient(path="/path/to/data")
  

  • 自定义本地的存储路径：path="/path/to/data"

• 非持久化客户端

  import chromadb
  client = chromadb.Client()
  

  • 运行在内存中，一般用在对于数据不需要持久化的场景。比如调试，实验的场景。

---

2、客户端-服务端模式

适用场景：生产环境（数据存储在独立服务器中）。

1. Python环境部署

• 安装chromadb

  pip install chromadb
  

  • 包含默认依赖：轻量级 SQLite 存储、HTTP 客户端。

• 启动服务端

  chroma run --path "/path/to/data" --host 0.0.0.0 --port 8000
  

  • --path "/path/to/data"： 指定数据库文件的存储路径，用于数据持久化。如果路径不存在会自动创建。
  • --host 0.0.0.0： 允许服务监听所有网络接口，支持远程访问（默认仅限本地）。
  • --port 8000： 设置服务运行端口为8000，可通过http://localhost:8000/docs访问API文档。

• 远程访问客户端

  启动成功后，客户端可通过以下代码连接：

  import chromadb
  client = chromadb.HttpClient(host='localhost', port=8000)
  

2. Docker环境部署

• 安装chromadb

  docker run -d --name chroma \
    -p 8000:8000 \
    -v /path/to/data:/chroma/chroma \
    -e IS_PERSISTENT=TRUE \
    chromadb/chroma:latest
  

  • 参数说明：
    • -p 8000:8000：映射容器端口到宿主机。
    • -v /path/to/data:/chroma/chroma：挂载持久化数据目录。
    • -e IS_PERSISTENT=TRUE：启用数据持久化。
  • 访问API：http://localhost:8000/docs

• 远程访问客户端

  启动成功后，客户端可通过以下代码连接：

  import chromadb
  client = chromadb.HttpClient(host='localhost', port=8000)、
  

---

注意： 自定义存储路径，相对路径 vs 绝对路径示例：

类型	代码示例	实际路径（假设工作目录为 C:\project）
相对路径	path="chroma/data"	C:\project\chroma\data
绝对路径	path="C:/chroma/data"	C:\chroma\data

---

三、验证安装

import chromadb
print(chromadb.__version__)  # 输出版本号

# ==测试客户端================================================================
# 初始化Chroma客户端，建立与向量数据库的连接
client = chromadb.Client()
# 创建一个名为"test"的集合(collection)，用于存储向量数据。集合类似于传统数据库中的表，包含文档、ID和元数据等要素
collection = client.create_collection("test")
# 向集合添加文档数据：
# - ids: 唯一标识符列表（此处添加单个文档ID为"id1"）
# - documents: 要存储的文本内容列表（此处添加单个文档"Hello Chroma!"）
collection.add(ids=["id1"], documents=["Hello Chroma!"])
# 执行查询操作：
# - query_texts: 查询文本列表（此处查询"Hi"）
# - n_results: 返回最相似的结果数量（此处设为1）
results = collection.query(query_texts=["Hi"], n_results=1)
# 打印查询结果中的文档内容：返回格式为二维列表，外层列表对应query_texts，内层列表对应n_results
print(results["documents"])  # 输出 [['Hello Chroma!']]

---