AI向量数据库chromadb的swagger-ui的运行使用教程

🚀 Chroma v2 API 快速使用指南

你现在打开的是 ChromaDB v2 版本的 Swagger UI 文档 （localhost:8000/docs），这是新版多租户/多数据库架构的 API 接口。下面我一步步教你怎么用它来操作集合、插入和查询数据。

1. 先理解核心概念

Tenant（租户） ：默认是 default_tenant
Database（数据库） ：默认是 default_database
CRN（Chroma Resource Name） ：格式为 crn:{tenant}:{database}:{collection_name}，用来唯一标识一个集合

2. 常用接口操作示例（以 HTTP 请求为例）

🔐 1）查看当前用户身份

http 复制代码

GET /api/v2/auth/identity

作用：确认你当前连接的租户和数据库信息。
响应示例：

json 复制代码

{
  "user_id": "default_user",
  "tenant": "default_tenant",
  "database": "default_database"
}

📚 2）列出所有集合

http 复制代码

GET /api/v2/tenants/{tenant}/databases/{database}/collections

替换参数：

{tenant} → default_tenant
{database} → default_database

作用：获取当前数据库下的所有集合名称。

🆕 3）创建一个新集合

http 复制代码

POST /api/v2/tenants/{tenant}/databases/{database}/collections
Content-Type: application/json

{
  "name": "my_collection",
  "metadata": {"description": "测试集合"}
}

作用：创建名为 my_collection 的集合。
成功响应 ：会返回该集合的 CRN，比如 crn:default_tenant:default_database:my_collection。

📄 4）按 CRN 获取集合信息

http 复制代码

GET /api/v2/collections/{crn}

替换参数：

{crn} → 上一步得到的 crn:default_tenant:default_database:my_collection

作用：查看集合的元数据、配置等信息。

➕ 5）向集合中添加数据（核心操作）

接口路径：POST /api/v2/collections/{crn}/add

（在 Swagger 里往下翻就能找到）

请求体示例：

json 复制代码

{
  "ids": ["id1", "id2"],
  "documents": ["这是第一条文档", "这是第二条文档"],
  "embeddings": [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]],
  "metadatas": [{"source": "test"}, {"source": "test"}]
}

如果你用了自动 Embedding 模型，embeddings 字段可以省略，Chroma 会自动生成。

🔍 6）查询集合数据

接口路径：POST /api/v2/collections/{crn}/query

请求体示例：

json 复制代码

{
  "query_embeddings": [[1.1, 2.1, 3.1]],
  "n_results": 2,
  "include": ["documents", "distances"]
}

作用：根据向量相似度检索最相似的文档。
响应示例：

json 复制代码

{
  "ids": [["id1", "id2"]],
  "documents": [["这是第一条文档", "这是第二条文档"]],
  "distances": [[0.03, 0.15]]
}

3. 在 Swagger UI 里直接测试

打开 localhost:8000/docs
点击任意接口（比如 POST /api/v2/tenants/{tenant}/databases/{database}/collections）
点击 Try it out
填入 tenant 和 database 参数（默认都是 default_tenant 和 default_database）
在 Request body 里填入 JSON 数据
点击 Execute，直接看到响应结果

4. Python 客户端调用（推荐）

如果你不想写原生 HTTP，用新版 chromadb Python 客户端更方便：

python 复制代码

import chromadb
from chromadb.config import Settings

# 连接到本地 Chroma 服务
client = chromadb.HttpClient(host="localhost", port=8000)

# 直接操作默认租户/数据库
coll = client.get_or_create_collection(name="my_collection")

# 添加数据
coll.add(
    ids=["id1", "id2"],
    documents=["这是第一条文档", "这是第二条文档"],
    embeddings=[[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]
)

# 查询数据
results = coll.query(
    query_embeddings=[[1.1, 2.1, 3.1]],
    n_results=2
)
print(results)

5. 关键注意事项

默认租户/数据库 ：如果没特别配置，所有操作都用 default_tenant 和 default_database 即可。
CRN 格式 ：必须严格是 crn:{tenant}:{database}:{collection_name}，不能写错。
版本兼容 ：v2 API 和老版本（v1）不兼容，所以你之前的 PersistentClient 代码如果是本地文件模式，和这个 HTTP 服务是两套不同的运行方式。