跳转到主要内容
针对生产环境，Chroma 提供了 Chroma 云 —— 一种快速、可扩展且无服务器的数据库即服务（DBaaS）。30 秒即可开启使用，包含 5 美元的免费额度。

​
通过 AI 安装

将以下提示词发送给 Claude Code、Cursor、Codex 或您喜爱的 AI 智能体。它将帮助您快速搭建 Chroma 环境。
In this directory create a new Python project with Chroma set up.
Use a virtual environment.

Write a small example that adds some data to a collection and queries it.
Do not delete the data from the collection when it's complete.
Run the script when you are done setting up the environment and writing the
script. The output should show what data was ingested, what was the query,
and the results.
Your own summary should include this output so the user can see it.

First, install `chromadb`.

The project should be set up with Chroma Cloud. When you install `chromadb`,
you get access to the Chroma CLI. You can run `chroma login` to authenticate.
This will open a browser for authentication and save a connection profile
locally.

You can also use `chroma profile show` to see if the user already has an
active profile saved locally. If so, you can skip the login step.

Then create a DB using the CLI with `chroma db create chroma-getting-started`.
This will create a DB with this name.

Then use the CLI command `chroma db connect chroma-getting-started --env-file`.
This will create a .env file in the current directory with the connection
variables for this DB and account, so the CloudClient can be instantiated
with chromadb.CloudClient(api_key=os.getenv("CHROMA_API_KEY"), ...).

​
手动安装

1

安装

pip install chromadb
2

创建 Chroma 客户端

Python
import chromadb
chroma_client = chromadb.Client()
3

创建集合 (Collection)

集合是您存储嵌入（embeddings）、文档和任何附加元数据的地方。集合会对您的嵌入和文档进行索引，从而实现高效的检索和过滤。您可以通过指定名称来创建集合。
Python
collection = chroma_client.create_collection(name="my_collection")
4

向集合中添加文本文档

Chroma 会存储您的文本并自动处理嵌入和索引工作。您也可以自定义嵌入模型。您必须为每个文档提供唯一的字符串 ID。
Python
collection.add(
    ids=["id1", "id2"],
    documents=[
        "This is a document about pineapple",
        "This is a document about oranges"
    ]
)
5

查询集合

您可以使用一系列查询文本来查询集合，Chroma 将返回 n 个最相似的结果。就是这么简单！
Python
results = collection.query(
    query_texts=["This is a query document about hawaii"], # Chroma will embed this for you
    n_results=2 # how many results to return
)
print(results)
如果未提供 n_results，Chroma 默认返回 10 个结果。在此示例中我们仅添加了 2 个文档，因此设置 n_results=2。
6

检查结果

从上述结果中，您可以看到关于“hawaii”（夏威夷）的查询在语义上与关于“pineapple”（菠萝）的文档最相似。
Python
{
  'documents': [[
      'This is a document about pineapple',
      'This is a document about oranges'
  ]],
  'ids': [['id1', 'id2']],
  'distances': [[1.0404009819030762, 1.243080496788025]],
  'uris': None,
  'data': None,
  'metadatas': [[None, None]],
  'embeddings': None,
}
7

亲自尝试一下

如果我们尝试查询 “This is a document about florida”（这是一篇关于佛罗里达的文档）会怎样？这是一个完整的示例。
Python
import chromadb
chroma_client = chromadb.Client()

# switch \`create_collection\` to \`get_or_create_collection\` to avoid creating a new collection every time
collection = chroma_client.get_or_create_collection(name="my_collection")

# switch \`add\` to \`upsert\` to avoid adding the same documents every time
collection.upsert(
    documents=[
        "This is a document about pineapple",
        "This is a document about oranges"
    ],
    ids=["id1", "id2"]
)

results = collection.query(
    query_texts=["This is a query document about florida"], # Chroma will embed this for you
    n_results=2 # how many results to return
)

print(results)

​
后续步骤

为了简单起见，本指南使用了 Chroma 的内存客户端。它在内存中启动 Chroma 服务，因此当程序终止时，任何摄入的数据都会丢失。如果您需要数据持久化，可以使用持久化客户端或以客户端-服务器模式运行 Chroma。