在前面“四种客户端”介绍了 HttpClient 的基本用法，我们本地使用 Docker 安装了一个 Chroma 服务。下面将对 HttpClient 的参数进行详细介绍。
下面代码片段创建了一个用于连接 Chroma 服务端的客户端：
client = chromadb.HttpClient(
host="localhost",
port=8000,
ssl=False,
headers=None,
settings=None,
tenant="default_tenant",
database="default_database",
)参数说明：
host：Chroma 服务端主机名，默认是 localhost
port：Chroma 服务的 HTTP 端口，默认是 8000
ssl：连接是否启用 SSL 加密
headers：可选，每次请求附带的 HTTP 请求头
settings：可选配置，用于覆盖默认设置
tenant：请求所使用的租户名称
database：请求所使用的数据库名称
返回：
ClientAPI：配置完成的客户端实例
异常：
ValueError：当 settings 里面配置了和入参不一致的 host / port 时抛出
下面是 HttpClient 类的实现代码：
def HttpClient(
host: str = "localhost",
port: int = 8000,
ssl: bool = False,
headers: Optional[Dict[str, str]] = None,
settings: Optional[Settings] = None,
tenant: str = DEFAULT_TENANT,
database: str = DEFAULT_DATABASE,
) -> ClientAPI:
# 如果外部没有传入settings配置对象，则实例化一份默认Settings
if settings is None:
settings = Settings()
# 强制类型转换，防止用户传入非标准类型参数
host = str(host)
port = int(port)
ssl = bool(ssl)
tenant = str(tenant)
database = str(database)
# 指定底层API实现为FastAPI版本（http服务配套实现）
settings.chroma_api_impl = "chromadb.api.fastapi.FastAPI"
# 校验：settings内部如果已经存在host，并且和函数入参host不一致，抛出冲突异常
if settings.chroma_server_host and settings.chroma_server_host != host:
raise ValueError(
f"Chroma server host provided in settings[{settings.chroma_server_host}] is different to the one provided in HttpClient: [{host}]"
)
# 将入参host写入settings配置
settings.chroma_server_host = host
# 校验：settings内部如果已经存在端口，并且和函数入参port不一致，抛出冲突异常
if settings.chroma_server_http_port and settings.chroma_server_http_port != port:
raise ValueError(
f"Chroma server http port provided in settings[{settings.chroma_server_http_port}] is different to the one provided in HttpClient: [{port}]"
)
# 将入参port写入settings配置
settings.chroma_server_http_port = port
# 将ssl开关、自定义请求头写入settings
settings.chroma_server_ssl_enabled = ssl
settings.chroma_server_headers = headers
# 返回客户端创建器实例，后续由它生成真正的客户端
return ClientCreator(tenant=tenant, database=database, settings=settings)看见没有，即使你传递了自定义的 settings，chroma_server_host、chroma_server_http_port、chroma_server_ssl_enabled 和chroma_server_headers 四个参数也会被 HttpClient 函数指定的参数覆盖，但是在覆盖之前，如果你在自定义 settings 中指定了 chroma_server_host 或 chroma_server_http_port，必须和参数 host、port 保持一致，否则抛出 ValueError 错误。
如果你要传递自定义请求头，可以通过headers 参数，鉴权在反向代理层做的话（后续章节给方案），token 就是通过 headers 传，如下：
import chromadb
import os
headers = {}
# 获取 token 环境变量
token = os.getenv("CHROMA_TOKEN")
if token:
headers["Authorization"] = f"Bearer {token}"
client = chromadb.HttpClient(
host="localhost",
port=8000,
ssl=False,
headers=headers,
)
print(client)注意，不要使用 os.environ['CHROMA_TOKEN']，如果没有配置 CHROMA_TOKEN 环境变量会直接抛出错误 KeyError: 'CHROMA_TOKEN' 。
import chromadb
client = chromadb.EphemeralClient()
# 当前时间的纳秒时间戳，用来探活，1793688846556641816
print(client.heartbeat())
# 1.5.9
print(client.get_version())写健康检查的时候用 heartbeat() 就行，例如：
import chromadb
def healthy(client: chromadb.HttpClient) -> bool:
"""
检测 chroma 服务是否健康可用
:param client: Chroma HTTP客户端实例
:return: True 服务正常；False 连接失败/异常
"""
try:
# heartbeat 返回服务时间戳，正常情况下大于0
return client.heartbeat() > 0
except Exception:
# 网络、连接、服务未启动等所有异常统一返回不健康
return False
if __name__ == "__main__":
client = chromadb.HttpClient(
host="localhost",
port=8000
)
is_ok = healthy(client)
if is_ok:
print("✅ Chroma 服务健康")
else:
print("❌ Chroma 服务不可访问")HttpClient 模式下最常见的错误是连接超时和 payload 过大：
服务端默认最大 payload 40 MiB（环境变量 CHROMA_MAX_PAYLOAD_SIZE_BYTES）
一批写太多会超，报 413 之类
把批次降到几百条通常就好了
官方 SDK 参考手册：https://docs.trychroma.com/reference/python/client
川公网安备51010802032098