Chroma 报 http-only client mode，PersistentClient 用的是哪份包

构造 PersistentClient 时出现：

Chroma is running in http-only client mode

这个错误要求先核对 Python 包。Chroma 的官方使用说明区分完整 chromadb 和精简 chromadb-client：后者用于连接远程服务。它们的导入名称都可能是 chromadb，所以“import 成功”不足以认定安装了完整本地组件。

下面的客户端形态按历史 0.5.7 核对，相关包用途仍需对照项目实际发行版本；没有精确版本的旧日志，不补造发生版本。

先查当前解释器和两个分发包

python -m pip show chromadb chromadb-client
python -m pip check
python -c 'import sys,chromadb; print(sys.executable); print(chromadb.__version__); print(chromadb.__file__)'

如果环境同时装了两者，它们可能覆盖同一导入目录。删除其中一个包也可能影响共享文件，因此优先在新虚拟环境重建，而不是反复修补当前 site-packages。

依赖管理器中明确选择本地嵌入式或远程服务方案，锁定相容版本。不要把完整包只安装到另一个终端解释器，然后继续用原 Notebook 内核验证。

本地数据，使用完整包和独立测试目录

完整环境准备好后，用两个先后退出的子进程检查写入与读取。父进程拥有临时目录，等两次调用都结束后再清理；不打开生产数据。将下面保存为 Python 脚本，使用目标项目的解释器运行：

import subprocess
import sys
from tempfile import TemporaryDirectory

CHILD = r"""
import sys
import chromadb
from chromadb.config import Settings

mode, directory = sys.argv[1:]
client = chromadb.PersistentClient(
    path=directory,
    settings=Settings(anonymized_telemetry=False),
)
if mode == "write":
    collection = client.create_collection(
        name="package-check",
        embedding_function=None,
    )
    collection.add(ids=["one"], embeddings=[[1.0, 0.0]])
else:
    collection = client.get_collection(
        name="package-check",
        embedding_function=None,
    )
    if collection.count() != 1:
        raise RuntimeError("unexpected persisted count")
    if collection.get(ids=["one"])["ids"] != ["one"]:
        raise RuntimeError("persisted ID was not found")
print(mode + " complete")
"""

def main():
    with TemporaryDirectory(prefix="chroma-package-check-") as directory:
        for mode in ("write", "read"):
            subprocess.run(
                [sys.executable, "-c", CHILD, mode, directory],
                check=True,
                timeout=60,
            )
    print("test directory removed")

if __name__ == "__main__":
    main()

示例采用 0.5.7 API，关闭产品遥测并显式提供向量，避免包检查额外下载 embedding 模型。它会写入专用临时目录；子进程出错会停止后续步骤，超时则由父进程结束并等待该子进程，再退出临时目录。二维向量只是测试数据，不能用于证明真实检索质量。固定版本客户端定义提供了对应构造接口。

0.5.7 的共享 System 实现按持久化目录缓存实例。同一进程创建第二个客户端可能复用原来的 System，因此不能靠它证明数据已从磁盘重载。这里让写入进程退出后，才启动读取进程；两次命令都成功并找到原 ID，再核对备份副本中的真实集合。

远程数据，保留精简包并使用 HttpClient

连接远程服务时，应采用 HttpClient，而不是把服务地址当本地路径。先用已有配置创建客户端，再调用 heartbeat() 检查连接；远程 HTTPS 和认证继续沿用正常配置。

精简包不包含默认 embedding 依赖。用 documents 添加或用文本查询时，还需要明确的 embedding function，或由应用提供已有向量。包冲突修复成功以后出现“需要 embedding function”，属于下一步配置，不应把所有依赖又混装回来。

验收看原应用选定的模式：本地测试集合能创建、保存并由新进程读取；远程服务则能通过正常身份访问目标集合。检查实际地址和集合后，再恢复业务流量。