4.1 环境搭建与客户端连接

在体系位置里，这一节是第四章动手篇的第一站：把环境装好、客户端连上。前面三章都是理论，从这一节开始每段都有可运行代码。

数字事实切入

Chroma 的 Python 包体积不大，pip install chromadb 通常几十秒装完，不依赖外部服务。这是它和"先起个集群"的向量库最直观的区别——你本地进程里就有一个完整可用的实例。

安装与两种客户端

## 安装: pip install chromadb
import chromadb

## 方式一: 内存客户端, 进程退出即丢, 适合原型/测试
client_mem = chromadb.Client()
print("内存客户端:", type(client_mem).__name__)
## 输出: 内存客户端: Client

## 方式二: 持久化客户端, 数据落盘到指定目录
client_per = chromadb.PersistentClient(path="./chroma_data")
print("持久客户端就绪, 路径存在:", __import__("os").path.exists("./chroma_data"))
## 输出: 持久客户端就绪, 路径存在: True
​

两种客户端的取舍：内存版零配置、重启干净，适合跑单测和经验证；持久版多一行 path，换来了重启不丢，生产基本都用它。

连接远端服务端

当数据规模超出单机，Chroma 也支持以 HTTP 服务端模式运行，客户端通过地址连：

## 服务端模式 (需先另起 chroma server)
client_http = chromadb.HttpClient(host="localhost", port=8000)
## 之后 API 与本地客户端一致, 只是请求走网络
try:
    print("服务端心跳:", client_http.heartbeat())
except Exception as e:
    print("未启动服务端, 报错:", type(e).__name__)
## 输出(若未起服务): 未启动服务端, 报错: ChromaServerError (或连接错)
​

版本与依赖坑

import chromadb
print("版本:", chromadb.__version__)
## 输出类似: 版本: 0.5.x
## 注意: 嵌入函数、服务端协议都随版本变, 锁定版本再写代码更稳
​

我们建议在项目里把 chromadb 写进 requirements.txt 并锁版本，避免下游升级导致默认嵌入模型变化、旧数据查不到。

案例：原型到持久的无痛切换

背景：开发期用内存客户端快速试，上线要落盘。

操作：只把 chromadb.Client() 换成 chromadb.PersistentClient(path=...)，其余 add/query 代码一行不改。

结果：切换零成本，历史数据从首次写入起就落盘。

解读：Chroma 刻意让两种客户端 API 一致，切换不在代码逻辑而在"连接方式"。这像建筑里"同样的插座，电池供电和市电供电切换不影响电器"。

变式：若担心写错路径，用绝对路径并先 os.makedirs 确保父目录存在。

我们看连接的取舍

嵌入式连接把"数据库"退化为"一个库调用"，认知负担极低；代价是你得自己管进程生命周期和文件落盘位置。服务端连接把管理外包给独立进程，换来并发与隔离，代价是多一处要运维的服务。选型见第六章，这里先会连就行。

深度对照：环境是"地基"不是"步骤"

搭环境最容易被当成照抄命令，但它其实决定了后续所有操作的稳定性。依赖冲突、Python 版本错位、虚拟环境缺失，都会让后面每一步都踩暗坑。这像盖楼先勘地基：地基歪了，上面砌得再漂亮也会裂。

Chroma 的客户端是纯 Python 包，安装即用，但它依赖的底层单机引擎和列存格式对 Python 版本有隐性要求。先确认运行环境干净，比事后排错省十倍时间。

## 安装前先确认运行环境(示意)
import sys, importlib.metadata as md
print("python 版本:", sys.version.split()[0])
try:
    v = md.version("chromadb")
    print("已安装 chromadb:", v, "(建议先升级到最新稳定版再开始)")
except md.PackageNotFoundError:
    print("尚未安装 chromadb, 需在干净虚拟环境中安装")
## python 版本: 3.11.x
## 已安装 chromadb: 0.5.x (建议先升级到最新稳定版再开始)
​

虚拟环境为什么不是"可选项"

很多报错来自"系统里装了三份 Python、两份 chromadb"，你以为在跑 A，实际跑的是 B。虚拟环境把依赖锁进一个独立盒子，谁也别串门。这像实验室的分区：试剂分开放，才不会交叉污染实验结果。

⚠️ 常见坑：在系统全局直接 pip install，之后另一个项目升级了 chromadb，你的脚本莫名行为变了。用虚拟环境隔离，是零成本的保险。

💡 关键直觉：搭环境的目标不是"装上"，而是"可复现"——换台机器按同一份依赖声明能跑出一模一样的结果，才算环境真正搭好。

实践中的常见坑与关键直觉

• ⚠️ 忽略 Python 版本下限：老版本 Python 跑新客户端会报语法或依赖错，先核对支持范围。
• ⚠️ 把临时试验装的包留进全局：久而久之全局环境变成" dependency 垃圾场"，新项目隐患不断。
• 💡 把依赖写进声明文件并随项目走，新人克隆即可重建环境，不靠口头传"我当初怎么装的"。
• 💡 客户端连不上时，先确认是环境问题还是代码问题：在干净环境重跑最小片段，能二分定位。

一个安装踩坑的小案例

背景：新手在系统全局直接装了 chromadb，之后另一个项目升级了版本，他的脚本突然报接口找不到。

操作：没用虚拟环境，两个项目共用一份全局包，版本互相踩。

结果：花了一下午才定位是"跑的是另一个版本的 chromadb"，不是代码错。

解读：环境问题伪装成代码问题，最费排查。虚拟环境是一次性投入、长期省心。这像每人用自己的水杯，不会喝错别人的水。

变式：若团队统一用容器，则连虚拟环境都可省，镜像里锁死依赖，复现更彻底。

本节要点回顾：Chroma 三种连接——内存、持久、Http；前两者 API 一致，切换只改连接方式；持久化用 path 落盘，生产多用；锁版本避免默认嵌入变化导致旧数据查不到。

⚠️ 不锁 chromadb 版本，升级后默认嵌入模型可能变，旧集合的向量空间对不上，查询静默失效。

💡 开发用内存客户端求快，上线换持久客户端，业务代码几乎不改——这个切换要尽早固化成习惯。