模式和数据格式的变化是软件演进中不可避免的恶。我们认真对待这些变化，并尽量减少其频率，只在必要时进行。

Chroma 的承诺是，每当模式或数据格式发生变化时，我们将提供一个无缝且易于使用的迁移工具，以便迁移到新的模式/格式。

具体来说，我们将在以下渠道宣布模式变化：

• Discord（#migrations 频道）
• Github（此处）
• 邮件列表服务 注册

我们将努力提供：

• 对变化的描述及其背后的理由。
• 您可以运行的 CLI 迁移工具。
• 使用该工具的视频演示。

迁移日志#

v0.5.12#

where 子句中的操作符 $ne（不等于）和 $nin（不在）已更新：

• 之前：它们仅匹配具有指定键的记录。
• 现在：它们还匹配完全没有指定键的记录。

换句话说，$ne 和 $nin 现在分别匹配 $eq（等于）和 $in（在）所匹配记录的补集（完全相反）。

where_document 子句中的 $not_contains 操作符也已更新：

• 之前：它仅匹配具有文档字段的记录。
• 现在：它还匹配完全没有文档字段的记录。

换句话说，$not_contains 现在匹配 $contains 所匹配记录的完全相反的集合。

RateLimitingProvider 现已弃用，并被 RateLimitEnforcer 取代。这个新接口允许您用速率限制逻辑包装服务器调用。默认的 SimpleRateLimitEnforcer 实现允许所有请求，但您可以创建自定义实现以实现更高级的速率限制策略。

v0.5.11#

collection.get() 返回的结果现在按内部 ID 排序。而之前，结果按用户提供的 ID 排序，尽管这种行为并未明确记录。我们希望进行此更改，因为使用用户提供的 ID 可能对托管 Chroma 的性能不理想，并且我们希望将此更改传播到本地 Chroma，以保持行为的一致性。通常，Chroma 中较新的文档具有较大的内部 ID。

后续的行为变化是 limit 和 offset，它们取决于返回结果的顺序。例如，如果您有一个名为 coll 的集合，其中文档的 ID 按此顺序插入 ["3", "2", "1", "0"]，那么之前 coll.get(limit=2, offset=2)["ids"] 会返回 ["2", "3"]，而现在这将返回 ["1", "0"]。

我们还修改了 client.get_or_create 的行为。之前，如果集合已存在且提供了 metadata 参数，现有集合的元数据将被新值覆盖。现在已更改。如果集合已存在，get_or_create 将简单地返回具有指定名称的现有集合，任何额外的参数——包括 metadata——都将被忽略。

最后，从 collection.get()、collection.query() 和 collection.peek() 返回的嵌入现在表示为二维 NumPy 数组，而不是 Python 列表。在添加嵌入时，您仍然可以使用 Python 列表或 NumPy 数组。如果您的请求返回多个嵌入，结果将是一个包含二维 NumPy 数组的 Python 列表。这一更改是我们通过使用 NumPy 数组来增强本地 Chroma 中嵌入的内部表示性能的一部分。

v0.5.6#

Chroma 内部使用预写日志。在 v0.5.6 之前的所有版本中，此日志从未被修剪。这导致数据目录比实际需要的要大得多，并且在删除集合后，目录大小并未按预期减少。

在 v0.5.6 中，预写日志会自动修剪。但是，对于现有数据库，默认情况下不会启用此功能。升级后，您应该运行一次 chroma utils vacuum 以减小数据库大小并启用持续修剪。有关更多详细信息，请参阅 CLI 参考。

这不需要定期运行，也不需要在新创建的 v0.5.6 或更高版本的数据库上运行。

v0.5.1#

在 Python 客户端上，max_batch_size 属性已被移除。它之前未被记录，但如果您之前读取过它，现在应使用 get_max_batch_size()。

首次运行时，它会发出 HTTP 请求。我们将其设为方法，以更清楚地表明它可能是一个阻塞操作。

认证系统大改 - 2024年4月20日#

如果您没有使用 Chroma 的 内置认证系统，则无需采取任何行动。

此版本彻底改革并简化了我们的认证和授权系统。 如果你使用的是Chroma的内置认证系统，你需要更新你的配置以及任何你编写的用于实现自己的认证或授权提供者的代码。这一更改主要是为了偿还Chroma的一些技术债务，并使未来的更改更加容易，但它也改变了并简化了用户配置。如果你没有使用Chroma的内置认证系统，你不需要采取任何行动。

以前，Chroma的认证和授权依赖于许多具有多种配置选项的对象，包括：

• chroma_server_auth_provider
• chroma_server_auth_configuration_provider
• chroma_server_auth_credentials_provider
• chroma_client_auth_credentials_provider
• chroma_client_auth_protocol_adapter

以及其他。

我们已经将这些整合为三个类：

• ClientAuthProvider
• ServerAuthenticationProvider
• ServerAuthorizationProvider

ClientAuthProvider现在负责自己的配置和凭证管理。凭证可以通过chroma_client_auth_credentials设置提供给他们。chroma_client_auth_credentials的值取决于ServerAuthenticationProvider；对于TokenAuthenticationServerProvider，它应该只是令牌，而对于BasicAuthenticationServerProvider，它应该是username:password。

ServerAuthenticationProvider负责将请求的授权信息转换为包含进行授权决策所需信息的UserIdentity。他们现在负责自己的配置和凭证管理。通过chroma_server_authn_credentials和chroma_server_authn_credentials_file设置进行配置。

ServerAuthorizationProvider负责将关于请求和发出请求的UserIdentity的信息转换为授权决策。通过chroma_server_authz_config和chroma_server_authz_config_file设置进行配置。

可以设置_authn_credentials或authn_credentials_file中的一个，但不能同时设置两者。对于authz_config和authz_config_file也是如此。配置的值（或配置文件中的数据）将取决于你的认证和授权提供者。更多信息请参见这里。

Chroma自带的两个认证系统是Basic和Token。我们为每个系统提供了一个小型迁移指南。

Basic#

如果你使用的是Token认证，你的服务器配置可能如下所示：

注意：只能设置AUTH_CREDENTIALS和AUTH_CREDENTIALS_FILE中的一个，但本指南展示了如何迁移两者。

以及相应的客户端配置：

要迁移到新的服务器配置，只需将其更改为：

新的客户端配置：

Token#

如果你使用的是Token认证，你的服务器配置可能如下所示：

注意：只能设置AUTH_CREDENTIALS和AUTH_CREDENTIALS_FILE中的一个，但本指南展示了如何迁移两者。

以及相应的客户端配置：

要迁移到新的服务器配置，只需将其更改为：

新的客户端配置：

更改的配置值参考#

• 整体配置
  • chroma_client_auth_token_transport_header: 重命名为 chroma_auth_token_transport_header。
  • chroma_server_auth_token_transport_header: 重命名为 chroma_auth_token_transport_header。
• 客户端配置
  • chroma_client_auth_credentials_provider: 已删除。功能现已移至 chroma_client_auth_provider。
  • chroma_client_auth_protocol_adapter: 已删除。功能现已移至 chroma_client_auth_provider。
  • chroma_client_auth_credentials_file: 已删除。功能现已移至 chroma_client_auth_credentials。
  • 这些更改也适用于 Typescript 客户端。
• 服务器认证
  • chroma_server_auth_provider: 重命名为 chroma_server_authn_provider。
  • chroma_server_auth_configuration_provider: 已删除。功能现已移至 chroma_server_authn_provider。
  • chroma_server_auth_credentials_provider: 已删除。功能现已移至 chroma_server_authn_provider。
  • chroma_server_auth_credentials_file: 重命名为 chroma_server_authn_credentials_file。
  • chroma_server_auth_credentials: 重命名为 chroma_server_authn_credentials。
  • chroma_server_auth_configuration_file: 重命名为 chroma_server_authn_configuration_file。
• 服务器授权
  • chroma_server_authz_ignore_paths: 已删除。功能现已移至 chroma_server_auth_ignore_paths。

要查看完整的更改，您可以阅读 PR 或在 Discord 上联系 Chroma 团队。

迁移至 0.4.16 - 2023年11月7日#

此版本增加了对多模态嵌入的支持，并随之更改了 EmbeddingFunction 的定义。 此更改主要影响那些已实现自己的 EmbeddingFunction 类的用户。如果您使用的是 Chroma 内置的嵌入函数，则无需采取任何行动。

EmbeddingFunction

之前，EmbeddingFunction 定义为：

在此更新后，EmbeddingFunction 定义为：

关键区别在于：

• EmbeddingFunction 现在是泛型的，并接受一个类型参数 D，它是 Embeddable 的子类型。这使我们能够定义可以嵌入多种模式的 EmbeddingFunction。
• __call__ 现在接受一个单一参数 input，以支持任何类型的数据 D。texts 参数已被移除。

从 >0.4.0 迁移至 0.4.0 - 2023年7月17日#

此版本的新功能是什么？

• 创建客户端的新简便方法
• 更改了存储方式
• .persist() 已移除，.reset() 不再默认开启

新客户端

您仍然可以访问底层的 .Client() 方法。如果您想关闭遥测功能，所有客户端都支持自定义设置：

新的数据布局

此版本的 Chroma 放弃了 duckdb 和 clickhouse，转而使用 sqlite 进行元数据存储。这意味着需要迁移数据。我们创建了一个迁移 CLI 工具来完成此操作。

如果您升级到 0.4.0 并尝试访问以旧方式存储的数据，您将看到此错误消息

您正在使用 Chroma 的过时配置。请 pip install chroma-migrate 并运行 chroma-migrate 以升级您的配置。有关更多信息，请参阅 https://docs.trychroma.com/deployment/migration 或加入我们的 Discord 寻求帮助：https://discord.gg/8g5FESbj！

以下是如何安装和使用 CLI：

如果你在迁移过程中需要任何帮助，请随时联系我们！我们随时在 Discord 上提供帮助。

持久化与重置

.persist() 在旧版本的 Chroma 中存在，因为写操作只有在强制执行时才会刷新。Chroma 0.4.0 会立即将所有写操作保存到磁盘，因此不再需要 .persist()。

.reset() 用于重置整个数据库，在旧版本中默认启用，这感觉不太对。0.4.0 版本默认禁用了它。你可以通过向 Settings 对象传递 allow_reset=True 来重新启用它。例如：