【数据库、向量、python】Chroma向量数据库：使用指南与实践案例

时间：2025-03-04 07:53:05

在这篇文章中，我们将一起探索如何使用这个强大的向量数据库。

什么是 Chroma？

Chroma 是一种高效的、基于 Python 的、用于大规模相似性搜索的数据库。它的设计初衷是为了解决在大规模数据集中进行相似性搜索的问题，特别是在需要处理高维度数据时。Chroma 的核心是 HNSW（Hierarchical Navigable Small World）算法，这是一种高效的近似最近邻搜索算法，可以在大规模数据集中实现快速的相似性搜索。

Chroma 的发展历程可以追溯到 2018 年，当时一组研究人员开始寻找一种能够处理大规模数据集的相似性搜索工具。他们发现，虽然市场上有许多相似性搜索工具，但大多数都无法有效处理高维度数据。因此，他们开始开发 Chroma，目标是创建一种能够处理大规模、高维度数据的相似性搜索工具。

在开发过程中，Chroma 的设计者们对其进行了多次迭代和改进，以提高其性能和可用性。他们引入了 HNSW 算法，使得 Chroma 能够在大规模数据集中实现快速的相似性搜索。此外，他们还添加了许多功能，如数据持久化、客户端/服务器模式、集合操作、嵌入函数修改、数据添加、查询、过滤、更新和删除等，使得 Chroma 更加强大和灵活。

到 2020 年，Chroma 已经成为一种成熟的相似性搜索工具，被广泛应用于各种需要处理大规模、高维度数据的场景，如推荐系统、图像搜索、文本搜索等。未来，Chroma 的开发者们计划继续改进和优化 Chroma，以满足用户不断增长的需求。

Chroma 的特性

Chroma 是一种强大的数据库技术，它的主要特性和关键技术包括：

  1. 持久化客户端：Chroma 可以配置为保存和从本地机器加载数据，这使得数据在启动时自动持久化并加载。
  2. 客户端/服务器模式：Chroma 可以运行为独立的服务器进程，并允许 HTTP 客户端连接。
  3. Python HTTP-only 客户端：Chroma 提供了一个轻量级的客户端库，使得用户无需安装完整的 Chroma 库就可以连接到 Chroma 服务器。
  4. 使用集合（Collections）：Chroma 使用集合名称在 URL 中，对命名有限制，用户可以创建、检查和删除集合。
  5. 修改集合的嵌入函数：Chroma 允许用户在创建集合时通过 metadata 参数自定义嵌入空间的距离方法。
  6. 向集合添加数据：Chroma 提供了 .add 方法，使得用户可以方便地向集合添加数据。
  7. 查询集合：Chroma 提供了 .query 方法，用户可以以多种方式查询集合。
  8. 选择返回的数据：Chroma 允许用户使用 include 参数指定想要返回的数据类型。
  9. 使用过滤器：Chroma 支持通过元数据和文档内容过滤查询，提供了强大的查询功能。
  10. 更新集合中的数据：Chroma 提供了 .update 方法，使得用户可以方便地更新集合中的数据。
  11. 从集合中删除数据：Chroma 提供了 .delete 方法，使得用户可以方便地从集合中删除数据。
  12. 认证：Chroma 支持基本认证和静态 API 令牌，提供了强大的安全性。

以上是 Chroma 的主要特性和关键技术，它的强大功能和灵活性使得用户可以方便地管理和查询数据。

如何安装 Chroma？

在开始使用 Chroma 之前，我们需要首先安装它。Chroma 可以通过 Python 的包管理器 pip 进行安装。打开你的命令行工具，输入以下命令：

pip install chromadb

如果你正在使用特定的 Python 环境，如 conda，你可能需要使用对应的安装命令，如： 

conda install chromadb

安装完成后，你可以通过在 Python 环境中输入以下命令来验证安装是否成功： 

import chromadb

如果没有出现错误，那么恭喜你，Chroma 已经成功安装并可以使用了。

如果你只需要使用 Chroma 的客户端功能，你可以选择安装轻量级的客户端库 chromadb-client。这个库的安装过程与 Chroma 的安装过程相同，只是包名不同。在命令行工具中输入以下命令进行安装：

pip install chromadb-client

同样，你可以通过在 Python 环境中输入以下命令来验证安装是否成功： 

import chromadb

如果没有出现错误，那么恭喜你，Chroma 客户端库已经成功安装并可以使用了。

如何使用 Chroma？

接下来，我们将一起探索如何使用 Chroma。我将会以一个简单的例子来说明如何使用 Chroma 的各种功能。

初始化 Chroma 客户端

首先，我们需要初始化 Chroma 客户端。这可以通过以下代码实现：

client = (path="/path/to/save/to")

这将配置 Chroma 以保存和从本地机器加载数据。数据将自动持久化并在启动时加载（如果存在）。

启动 Chroma 服务器

接下来，我们可以启动 Chroma 服务器。这可以通过运行以下命令实现：

chroma run --path /db_path
连接到服务器

然后，我们可以使用 Chroma HTTP 客户端连接到运行的服务器。这可以通过以下代码实现：

import chromadb
chroma_client = (host='localhost', port=8000)
安装客户端库

如果我们不需要完整的 Chroma 库，我们可以安装轻量级的客户端库 chromadb-client。这可以通过运行以下命令实现：

pip install chromadb-client
设置客户端

然后，我们可以使用 连接到 Chroma 服务器。这可以通过以下代码实现：

import chromadb
client = (host='localhost', port=8000)
使用集合（Collections）

接下来，我们可以开始使用集合（Collections）。我们可以创建、检查和删除集合。这可以通过以下代码实现：

collection = client.create_collection(name="my_collection", embedding_function=emb_fn)
collection = client.get_collection(name="my_collection", embedding_function=emb_fn)
修改集合的嵌入函数

我们还可以修改集合的嵌入函数。这可以通过以下代码实现：

collection = client.create_collection(
    name="collection_name",
    metadata={"hnsw:space": "cosine"}  # l2 是默认选项
)
向集合添加数据

然后，我们可以向集合添加数据。这可以通过以下代码实现：

(
    documents=["lorem ipsum...", "doc2", "doc3", ...],
    metadatas=[{"chapter": "3", "verse": "16"}, ...],
    ids=["id1", "id2", "id3", ...]
)
查询集合

我们还可以查询集合。这可以通过以下代码实现：

(
    query_embeddings=[[11.1, 12.1, 13.1], ...],
    n_results=10,
    where={"metadata_field": "is_equal_to_this"},
    where_document={"$contains": "search_string"}
)
指定返回数据

我们还可以指定返回的数据。这可以通过以下代码实现：

(include=["documents"])
(include=["documents"])
使用过滤器

我们还可以使用过滤器。这可以通过以下代码实现：

{"metadata_field": {"$eq": "search_string"}}
{"$contains": "search_string"}
更新集合中的数据

我们还可以更新集合中的数据。这可以通过以下代码实现：

(
    ids=["id1", "id2", "id3", ...],
    embeddings=[[1.1, 2.3, 3.2], ...],
    metadatas=[{"chapter": "3", "verse": "16"}, ...],
    documents=["doc1", "doc2", "doc3", ...],
)
从集合中删除数据

我们还可以从集合中删除数据。这可以通过以下代码实现：

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

最后，我们还可以进行认证。Chroma 支持基本认证和静态 API 令牌。具体的设置方法将在后续的文章中详细介绍。

以上就是使用 Chroma 的基本方法。希望这篇文章能帮助你更好地理解和使用 Chroma。

Chroma 的应用

假设我们正在开发一个新闻推荐系统，我们需要存储和检索大量的新闻文章。我们可以使用 Chroma 来创建一个集合，将每篇文章的内容作为文档，文章的元数据（如标题、作者、发布日期等）作为元数据，文章的 ID 作为 ID。然后我们可以使用 Chroma 的查询功能来根据用户的兴趣和行为来推荐相关的新闻文章。

以下是一个简单的示例代码：

import chromadb

# 初始化 Chroma 客户端
client = (path="/path/to/save/to")

# 创建集合
collection = client.create_collection(name="news_articles", embedding_function=emb_fn)

# 添加新闻文章
(
    documents=["Article content 1...", "Article content 2...", "Article content 3...", ...],
    metadatas=[{"title": "Title 1", "author": "Author 1", "date": "2021-01-01"}, ...],
    ids=["id1", "id2", "id3", ...]
)

# 查询相关的新闻文章
results = (
    query_embeddings=[[11.1, 12.1, 13.1], ...],
    n_results=10,
    where={"metadata_field": "is_equal_to_this"},
    where_document={"$contains": "search_string"}
)

# 打印查询结果
for result in results:
    print(result)

在这个示例中，我们首先初始化了一个 Chroma 客户端，并创建了一个名为 news_articles 的集合。然后我们添加了一些新闻文章到集合中。每篇文章都有一个文档（文章的内容）、一个元数据（文章的标题、作者和日期）和一个 ID。最后，我们使用 .query 方法查询了与给定嵌入向量相关的新闻文章，并打印了查询结果。

开源项目地址

/chroma-core/chroma

相关文章