chroma db 向量数据库 使用指南（二）

使用指南

选择语言

• Python
• JavaScript

---

启动 Chroma 客户端

import chromadb


默认情况下，Chroma 使用内存数据库，该数据库在退出时持久化并在启动时加载（如果存在）。这适用于受机器内存限制的许多实验/原型设计工作负载。
from chromadb.config import Settings
client = chromadb.Client(Settings(
chroma_db_impl="duckdb+parquet",
persist_directory="/path/to/persist/directory" # Optional, defaults to .chromadb/ in the current directory
))


这 persist_directory 是 Chroma 将其数据库文件存储在磁盘上并在启动时加载它们的地方。
木星笔记本
在普通的 python 程序中， .persist() 如果您设置它，它将自动发生。但在 Jupyter Notebook 中，您需要 手动 调用 client.persist() .

客户端对象有一些有用的便捷方法。
client.heartbeat() # returns a nanosecond heartbeat. Useful for making sure the client remains connected.
client.reset() # Empties and completely resets the database. ⚠️ This is destructive and not reversible.

以客户端/服务器 模式

Chroma 还可以配置为使用磁盘上的数据库，这对于无法放入内存的较大数据很有用。要在客户端服务器模式下运行 Chroma，请运行 docker 容器：
docker-compose up -d --build


然后更新您的色度客户端以指向 docker 容器。默认： localhost:8000
import chromadb
from chromadb.config import Settings
chroma_client = chromadb.Client(Settings(chroma_api_impl="rest",
chroma_server_host="localhost",
chroma_server_http_port="8000"
))


就是这样！ client-server Chroma 的 API 将以仅此更改的模式运行。

使用 集合

Chroma 允许您使用原语管理嵌入集合 collection 。

创建、检查和删除 集合

Chroma 在 url 中使用集合名称，因此命名它们有一些限制：

• 名称的长度必须介于 3 到 63 个字符之间。
• 名称必须以小写字母或数字开头和结尾，中间可以包含点、破折号和下划线。
• 名称不得包含两个连续的点。
• 该名称不能是有效的 IP 地址。

Chroma 集合是使用名称和可选的嵌入函数创建的。如果您提供嵌入函数，则必须在每次获取集合时提供它。

collection = client.create_collection(name="my_collection", embedding_function=emb_fn)
collection = client.get_collection(name="my_collection", embedding_function=emb_fn)


警告
如果您以后希望这样做 get_collection ，则必须使用您在创建集合时提供的嵌入函数来这样做
嵌入函数以文本为输入，进行标记化和嵌入。如果没有提供嵌入函数，Chroma 将默认使用 句子变换器。

您可以了解有关 嵌入函数的 更多信息，以及如何创建您自己的嵌入函数。

可以使用 检索现有集合 .get_collection ，使用 删除现有集合 .delete_collection 。如果集合存在，您也可以使用 .get_or_create_collection 它来获取它，如果不存在，则创建它。
collection = client.get_collection(name="test") # Get a collection object from an existing collection, by name. Will raise an exception if it's not found.
collection = client.get_or_create_collection(name="test") # Get a collection object from an existing collection, by name. If it doesn't exist, create it.
client.delete_collection(name="my_collection") # Delete a collection and all associated embeddings, documents, and metadata. ⚠️ This is destructive and not reversible

集合有一些有用的便捷方法。

collection.peek() # returns a list of the first 10 items in the collection
collection.count() # returns the number of items in the collection
collection.modify(name="new_name") # Rename the collection

改变距离 函数

create_collection 还带有一个可选 metadata 参数，可用于通过设置值来自定义嵌入空间的距离方法 hnsw:space
collection = client.create_collection(
name="collection_name",
metadata={"hnsw:space": "cosine"}
)

的有效选项 hnsw:space 是“l2”、“ip”或“cosine”。 可以在此处 的 Hnswlib 文档中找到每个方程式。

向 集合

将数据添加到 Chroma 中 .add 。

原始文件：

collection.add(
documents=["lorem ipsum...", "doc2", "doc3", ...],
metadatas=[{"chapter": "3", "verse": "16"}, {"chapter": "3", "verse": "5"}, {"chapter": "29", "verse": "11"}, ...],
ids=["id1", "id2", "id3", ...]
)

如果 Chroma 传递了一个列表 documents ，它将自动标记化并将它们嵌入到集合的嵌入函数中（如果在创建集合时没有提供，则将使用默认值）。Chroma 也会存储它们 documents 自己。如果文档太大而无法使用所选的嵌入函数进行嵌入，则会引发异常。

每个文档必须有一个唯一的关联 id 。Chroma 不会为您跟踪 ID 的唯一性，由调用者决定是否添加相同的 ID 两次。 metadata 可以为每个文档提供可选的字典列表，以存储附加信息并启用过滤。

或者，您可以直接提供文档关联列表 embeddings ，Chroma 将存储关联文档而不嵌入它们本身。

collection.add(
documents=["doc1", "doc2", "doc3", ...],
embeddings=[[1.1, 2.3, 3.2], [4.5, 6.9, 4.4], [1.1, 2.3, 3.2], ...],
metadatas=[{"chapter": "3", "verse": "16"}, {"chapter": "3", "verse": "5"}, {"chapter": "29", "verse": "11"}, ...],
ids=["id1", "id2", "id3", ...]
)

如果提供的 embeddings 维度与集合不同，则会引发异常。

您还可以将文档存储在别处，只需向 Chroma 提供一个列表 embeddings 即可 metadata 。您可以使用 将 ids 嵌入与存储在别处的文档相关联。

collection.add(
embeddings=[[1.1, 2.3, 3.2], [4.5, 6.9, 4.4], [1.1, 2.3, 3.2], ...
metadatas=[{"chapter": "3", "verse": "16"}, {"chapter": "3", "verse": "5"}, {"chapter": "29", "verse": "11"}, ...],
ids=["id1", "id2", "id3", ...]
)

查询 集合

可以使用 方法以多种方式查询色度集合 .query 。

您可以通过一组查询 query_embeddings 。

collection.query(
query_embeddings=[[11.1, 12.1, 13.1],[1.1, 2.3, 3.2] ...]
n_results=10,
where={"metadata_field": "is_equal_to_this"},
where_document={"$contains":"search_string"}
)

查询将按顺序返回 n_results 与每个最接近的匹配项。 query_embedding 可以提供一个可选的 where 过滤器字典，以通过与每个文档相关联的方式过滤结果 metadata 。此外， where_document 可以提供一个可选的过滤器字典来按文档的内容过滤结果。

如果提供的 query_embeddings 维度与集合不同，则会引发异常。

您还可以通过一组查询 query_texts 。Chroma 将首先使用 query_text 集合的嵌入函数对每个进行嵌入，然后使用生成的嵌入执行查询。

collection.query(
query_texts=["doc10", "thus spake zarathustra", ...]
n_results=10,
where={"metadata_field": "is_equal_to_this"},
where_document={"$contains":"search_string"}
)


您还可以 id 使用 .get .
collection.get(
ids=["id1", "id2", "id3", ...],
where={"style": "style1"}
)

.get 还支持 where 和 where_document 过滤器。如果没有 ids 提供，它将返回集合中与 where 和 where_document 过滤器匹配的所有项目。

选择 返回

使用 get 或 query 时，您可以使用 include 参数指定要返回的数据 - embeddings 、 documents 、 metadatas 和 query 中的任何一个 distances 。默认情况下，Chroma 将返回 documents ， metadatas 在查询的情况下，返回 distances 结果的 。 embeddings 默认情况下被排除在性能之外并且 ids 总是被返回。您可以通过将包含字段名称的数组传递给查询或 get 方法的 includes 参数来指定要返回哪些。

# Only get documents and ids
collection.get(
include=["documents"]
)

collection.query(
query_embeddings=[[11.1, 12.1, 13.1],[1.1, 2.3, 3.2] ...],
include=["documents"]
)

使用 Where 过滤器

metadata Chroma 支持按内容过滤查询 document 。filter where 用于按 过滤 metadata ， where_document filter 用于按 document 内容过滤。

按 元数据

为了过滤元数据，您必须 where 为查询提供过滤字典。字典必须具有以下结构：

{
"metadata_field": {
<Operator>: <Value>
}
}

过滤元数据支持以下运算符：

• $eq - 等于（字符串，整数，浮点数）
• $ne - 不等于（字符串、整数、浮点数）
• $gt - 大于（整数，浮点数）
• $gte - 大于或等于（整数，浮点数）
• $lt - 小于（整数，浮点数）
• $lte - 小于或等于（整数，浮点数）

使用 $eq 运算符等同于使用 where 过滤器。

{
"metadata_field": "search_string"
}

# is equivalent to

{
"metadata_field": {
"$eq": "search_string"
}
}

按文档 内容

为了过滤文档内容，您必须 where_document 为查询提供过滤字典。字典必须具有以下结构：

# Filtering for a search_string
{
"$contains": "search_string"
}

使用逻辑 运算符

您还可以使用逻辑运算符 $and 和 $or 组合多个过滤器。

运算 $and 符将返回匹配列表中所有过滤器的结果。

{
"$and": [
{
"metadata_field": {
<Operator>: <Value>
}
},
{
"metadata_field": {
<Operator>: <Value>
}
}
]
}

运算 $or 符将返回与列表中的任何过滤器匹配的结果。

{
"$or": [
{
"metadata_field": {
<Operator>: <Value>
}
},
{
"metadata_field": {
<Operator>: <Value>
}
}
]
}

更新 集合
集合中项目的任何属性都可以使用 .update .
collection.update(
ids=["id1", "id2", "id3", ...],
embeddings=[[1.1, 2.3, 3.2], [4.5, 6.9, 4.4], [1.1, 2.3, 3.2], ...],
metadatas=[{"chapter": "3", "verse": "16"}, {"chapter": "3", "verse": "5"}, {"chapter": "29", "verse": "11"}, ...],
documents=["doc1", "doc2", "doc3", ...],
)

如果 id 在集合中找不到 an，将引发异常。如果 documents 提供时没有相应的 embeddings ，嵌入将使用集合的嵌入函数重新计算。

如果提供的 embeddings 维度与集合不同，则会引发异常。

Chroma 还支持 upsert 更新现有项目或添加它们（如果它们尚不存在）的操作。

collection.upsert(
ids=["id1", "id2", "id3", ...],
embeddings=[[1.1, 2.3, 3.2], [4.5, 6.9, 4.4], [1.1, 2.3, 3.2], ...],
metadatas=[{"chapter": "3", "verse": "16"}, {"chapter": "3", "verse": "5"}, {"chapter": "29", "verse": "11"}, ...],
documents=["doc1", "doc2", "doc3", ...],
)

如果 an id 不存在于集合中，则将根据创建相应的项目 add 。具有现有 id s 的项目将根据 更新 update 。

从 集合

Chroma 支持 id 使用 .delete . 与每个项目关联的嵌入、文档和元数据将被删除。⚠️当然，这是破坏性操作，无法撤销。

collection.delete(
ids=["id1", "id2", "id3",...],
where={"chapter": "20"}
)

.delete 还支持 where 过滤器。如果没有 ids 提供，它将删除集合中与 where 过滤器匹配的所有项目。