四种客户端 - Chroma 教程

四种客户端

🎉摘要：本文详细介绍了Chroma数据库的四种客户端：EphemeralClient（内存）、PersistentClient（本地磁盘）、HttpClient（远程服务）和CloudClient（托管云）的使用方法和区别。内容包括HttpClient的Docker部署与连接示例、CloudClient的注册说明、四种客户端的数据存储位置和适用场景对比，以及异步版本客户端AsyncHttpClient的使用方法。通过本文可以了解如何根据需求选择合适的Chroma客户端。

在前面章节我们已经学习和使用了 EphemeralClient（内存）和PersistentClient（本地磁盘）客户端，前者将数据保存到内存，程序退出数据就丢失。后者是将数据写入到磁盘文件，程序退出数据不会丢失。如果仅仅用于测试 Chroma 的某些特性使用前面两个客户端完全足够了。

除了它们，Chroma 还提供了 HttpClient 和 CloudClient 客户端。前者是将 Chroma 部署成一个单独的服务，通过“主机+端口”网络访问调用，二后者连接 Chroma 官方托管云（trychroma.com 的云服务），内置云鉴权、tenant/database 体系，走官方云端接口，不是连你自己搭的 chroma 服务

简单用法如下：

import chromadb

# 内存
client = chromadb.EphemeralClient()

# 本地磁盘
client = chromadb.PersistentClient(path="./chroma_data")

# 远程服务
client = chromadb.HttpClient(host="localhost", port=8000)

# 托管
client = chromadb.CloudClient(tenant="...", database="...", api_key="...")

HttpClient 用法

先安装 Chroma 服务，这里使用 Docker 进行安装：

# 拉取镜像
docker pull chromadb/chroma

# 启动容器
docker run -v ./chroma-data:/data -p 8000:8000 chromadb/chroma

# 查看容器启动情况，根据容器名称过滤
root@localhost:~# docker ps -f "name=reverent_lamport"
CONTAINER ID   IMAGE             COMMAND                  CREATED       STATUS         PORTS                                         NAMES
3b777707ec23   chromadb/chroma   "dumb-init -- chroma…"   6 weeks ago   Up 4 minutes   0.0.0.0:8000->8000/tcp, [::]:8000->8000/tcp   reverent_lamport

编写一段简易脚本使用 HttpClient 客户端连接 Chroma 服务，如下：

import chromadb

client = chromadb.HttpClient(host="localhost", port=8000)    # 远程服务
col = client.get_or_create_collection("client_demo", embedding_function=None)
col.add(
    ids=["q1", "q2", "q3", "q4"],
    documents=[
        "订单付款后多久发货？一般 48 小时内出库",
        "如何申请退款？在订单详情页点击申请退款",
        "发票怎么开？在个人中心-发票管理里申请电子发票",
        "快递丢了怎么办？联系客服补发或全额退款",
    ])
print(col.get(ids=["q1","q2"])["documents"])

运行代码，输出如下：

['订单付款后多久发货？一般 48 小时内出库', '如何申请退款？在订单详情页点击申请退款']

CloudClient 用法

CloudClient 仅能调用 Chroma 官方托管的云服务，我们需要到官网去注册一个账号（官网地址 https://www.trychroma.com/）：

很遗憾，编写该章节时注册功能没有开放，限制新用户注册，不能进行演示了，你可以尝试一下。

各个客户端区别

下面表格展示了各个客户端的区别，帮助你选择合适的客户端：

	Ephemeral	Persistent	HttpClient	CloudClient
数据落在哪	进程内存	本地目录	远程服务器	Chroma Cloud
进程退出后	数据全没	数据还在	数据还在	数据还在
多进程共享	不行	不行（有锁）	可以	可以
适合	调试、测试、notebook	单机应用、原型	生产	不想运维

异步版本

前面介绍的客户端都是同步版本客户端，发出调用请求后，代码会卡住，必须等接口处理完、拿到返回结果，才会继续往下执行后续代码，期间无法做别的事情。

Chroma 还提供了异步版本，发出调用请求后，异步客户端不会卡住，可以先去干别的任务，等结果回来再处理。

使用方式如下：

import asyncio
import chromadb


async def main():
    # 异步客户端，连接本地Docker启动的Chroma服务（HttpClient对应服务端模式）
    # 注意：AsyncHttpClient 是异步版本，和同步的 HttpClient 不能混用
    client = await chromadb.AsyncHttpClient(host="localhost", port=8000)

    # 创建向量集合
    col = await client.get_or_create_collection(name="my_collection", embedding_function=None)

    # 异步添加数据：文档文本、唯一id；不传embeddings时，会自动对documents做向量化
    await col.add(ids=["id1"], documents=["hello"])

    # 异步向量检索：传入查询文本，自动向量化后做相似度召回，只返回1条结果
    res = await col.query(query_texts=["hi"], n_results=1)

    # 打印召回结果的文档id列表
    print(res["ids"])

# 启动异步事件循环，执行main协程
asyncio.run(main())

注意，异步版本的方法签名跟同步版一模一样，只是都变成了协程。在 FastAPI 这种异步框架里用它，能避免阻塞事件循环。

说说我的看法

* 必填

全部评论（0）

没有评论

本网站专注于 Java、数据库（MySQL、Oracle）、Linux、软件架构及大数据等多领域技术知识分享。涵盖丰富的原创与精选技术文章，助力技术传播与交流。无论是技术新手渴望入门，还是资深开发者寻求进阶，这里都能为您提供深度见解与实用经验，让复杂编码变得轻松易懂，携手共赴技术提升新高度。如有侵权，请来信告知：hxstrive@outlook.com