启动一个持久的Chroma客户端#
您可以配置Chroma以从本地计算机保存和加载数据库。数据将自动持久化并在启动时加载（如果存在）。
path是Chroma将在磁盘上存储其数据库文件的位置，并在启动时加载它们。
客户端对象有一些有用的便捷方法。
在客户端-服务器模式下运行Chroma#
Chroma也可以配置为在客户端/服务器模式下运行。在这种模式下，Chroma客户端连接到一个在单独进程中运行的Chroma服务器。
要在本地启动Chroma服务器，请运行以下命令：
然后使用Chroma HTTP客户端连接到服务器：
就是这样！只需进行此更改，Chroma的API就会在客户端-服务器模式下运行。
Chroma还提供了一个异步HTTP客户端。其行为和方法签名与同步客户端相同，但所有会阻塞的方法现在都是异步的。要使用它，请调用AsyncHttpClient：
使用Python HTTP-only客户端#
如果您在客户端-服务器模式下运行Chroma，您可能不需要完整的Chroma库。相反，您可以使用轻量级的仅客户端库。 在这种情况下，您可以安装chromadb-client包。此包是一个轻量级的服务器HTTP客户端，具有最小的依赖关系。
请注意，chromadb-client包是完整Chroma库的一个子集，不包括所有依赖项。如果您想使用完整的Chroma库，可以安装chromadb包。 最重要的是，没有默认的嵌入函数。如果你在没有嵌入的情况下添加文档，你必须手动指定一个嵌入函数并安装其依赖项。
使用集合#
Chroma允许你使用collection原语管理嵌入集合。
创建、检查和删除集合#
Chroma在URL中使用集合名称，因此对命名有一些限制：
- 名称长度必须在3到63个字符之间。
- 名称必须以小写字母或数字开头和结尾，中间可以包含点、破折号和下划线。
- 名称不能包含两个连续的点。
- 名称不能是有效的IP地址。
Chroma集合通过名称和可选的嵌入函数创建。如果你提供了一个嵌入函数，每次获取集合时都必须提供它。
如果你之后希望get_collection，你必须使用创建集合时提供的嵌入函数
嵌入函数接受文本作为输入，并执行分词和嵌入。如果没有提供嵌入函数，Chroma将使用sentence transformer作为默认值。
你可以了解更多关于🧬 嵌入函数的信息，以及如何创建你自己的嵌入函数。
可以通过名称使用.get_collection检索现有集合，并使用.delete_collection删除集合。你也可以使用.get_or_create_collection来获取集合（如果存在），或者如果不存在则创建它。
集合有一些有用的便捷方法。
更改距离函数#
create_collection 还接受一个可选的 metadata 参数，可以通过设置 hnsw:space 的值来自定义嵌入空间的距离方法。
hnsw:space 的有效选项是 "l2"、"ip" 或 "cosine"。默认值是 "l2"，即平方 L2 范数。
| 距离 | 参数 | 公式 |
|---|---|---|
| 平方 L2 | l2 | |
| 内积 | ip | |
| 余弦相似度 | cosine |
向集合中添加数据#
使用 .add 向 Chroma 添加数据。
原始文档：
如果 Chroma 接收到一个 documents 列表，它将自动使用集合的嵌入函数（如果没有在集合创建时提供，则使用默认值）对其进行分词和嵌入。Chroma 还会存储 documents 本身。如果文档太大，无法使用所选的嵌入函数进行嵌入，则会引发异常。
每个文档必须有一个唯一的关联 id。尝试两次 .add 相同的 ID 将导致仅存储初始值。可以为每个文档提供一个可选的 metadata 字典列表，以存储额外信息并启用过滤。
或者，您可以直接提供与文档关联的 embeddings 列表，Chroma 将存储关联的文档而不自行嵌入它们。
如果提供的 embeddings 与集合的维度不一致，则会引发异常。
您还可以将文档存储在其他地方，只向 Chroma 提供 embeddings 和 metadata 列表。您可以使用 ids 将嵌入与存储在其他地方的文档关联起来。
查询集合#
你可以通过一组 query_embeddings 进行查询。
Chroma 集合可以通过 .query 方法以多种方式进行查询。
查询将返回每个 query_embedding 最接近的 n_results 个匹配项，按顺序排列。 可以提供一个可选的 where 过滤字典来根据每个文档关联的 metadata 进行过滤。 此外，可以提供一个可选的 where_document 过滤字典来根据文档内容进行过滤。
如果提供的 query_embeddings 的维度与集合不同，将引发异常。
你也可以通过一组 query_texts 进行查询。Chroma 将首先使用集合的嵌入函数嵌入每个 query_text，然后使用生成的嵌入进行查询。
你也可以通过 .get 使用 id 从集合中检索项目。
.get 也支持 where 和 where_document 过滤器。如果没有提供 ids，它将返回所有匹配 where 和 where_document 过滤器的集合中的项目。
选择返回的数据#
在使用 get 或 query 时，你可以使用 include 参数来指定你想要返回的数据——可以是 embeddings、documents、metadatas，对于 query，还可以是 distances。默认情况下，Chroma 将返回 documents、metadatas，并且在 query 的情况下，返回结果的 distances。embeddings 默认不返回以提高性能，ids 总是返回。你可以通过将包含的字段名称数组传递给 query 或 get 方法的 includes 参数来指定你想要返回的字段。请注意，embeddings 将在 .get 中作为二维 numpy 数组返回，在 .query 中作为二维 numpy 数组的 Python 列表返回。
使用 Where 过滤器#
Chroma 支持通过 metadata 和 document 内容进行查询过滤。where 过滤器用于通过 metadata 进行过滤，where_document 过滤器用于通过 document 内容进行过滤。
通过 metadata 过滤#
为了通过 metadata 进行过滤，你必须向查询提供一个 where 过滤字典。该字典必须具有以下结构：
过滤 metadata 支持以下操作符：
$eq- 等于（字符串、整数、浮点数）$ne- 不等于（字符串、整数、浮点数）$gt- 大于（整数、浮点数）$gte- 大于或等于（整数、浮点数）$lt- 小于（整数、浮点数）$lte- 小于或等于（整数，浮点数）
使用 $eq 运算符相当于使用 where 过滤器。
where 过滤器仅搜索存在键的嵌入。如果你搜索 collection.get(where={"version": {"$ne": 1}})，没有 version 键的元数据将不会被返回。
按文档内容过滤#
为了按文档内容过滤，你必须向查询提供一个 where_document 过滤器字典。我们支持两个过滤键：$contains 和 $not_contains。字典必须具有以下结构：
使用逻辑运算符#
你还可以使用逻辑运算符 $and 和 $or 来组合多个过滤器。
$and 运算符将返回匹配列表中所有过滤器的结果。
$or 运算符将返回匹配列表中任意过滤器的结果。
使用包含运算符（$in 和 $nin）#
支持以下包含运算符：
$in- 值在预定义列表中（字符串，整数，浮点数，布尔值）$nin- 值不在预定义列表中（字符串，整数，浮点数，布尔值）
$in 运算符将返回元数据属性是提供列表中一部分的结果：
$nin 运算符将返回元数据属性不是提供列表中一部分的结果：
实用示例
有关更多示例和如何使用包含运算符的演示，请参见提供的笔记本 这里
更新集合中的数据#
可以使用 .update 更新集合中记录的任何属性。
如果集合中找不到 id，将记录错误并忽略更新。如果提供了 documents 而没有相应的 embeddings，将使用集合的嵌入函数重新计算嵌入。
如果提供的 embeddings 与集合的维度不一致，将引发异常。
Chroma 还支持 upsert 操作，该操作更新现有项目，或在项目尚不存在时添加它们。
如果集合中不存在某个 id，则将根据 add 创建相应的项目。具有现有 id 的项目将根据 update 进行更新。
从集合中删除数据#
Chroma 支持通过 .delete 使用 id 从集合中删除项目。与每个项目关联的嵌入、文档和元数据将被删除。 ⚠️ 自然地，这是一个破坏性操作，且无法撤销。
.delete 还支持 where 过滤器。如果没有提供 ids，它将删除集合中所有匹配 where 过滤器的项目。