跳转到主要内容
模式和数据格式的更改是软件演进过程中不可避免的代价。我们非常慎重地对待这些更改，仅在必要时才进行且频率极低。 Chroma 承诺，每当模式或数据格式发生更改时，我们将提供一个无缝且易于使用的迁移工具，以帮助迁移到新的模式/格式。 具体而言，我们将在以下平台宣布模式更改： 我们的目标是提供：
  • 更改的描述及其理由。
  • 一个可运行的 CLI 迁移工具。
  • 使用该工具的视频演示。

​
迁移日志

​
v1.0.0 - 2025年3月1日

在此版本中，我们使用 Rust 重写了 Chroma 的大部分代码。整体性能得到了显著提升。 破坏性变更 Chroma 不再提供内置的身份验证实现。 list_collections 现在恢复为返回 Collection 对象。 Chroma 进程内变更 如果您通过以下方式使用 Chroma，本节内容适用于您：
import chromadb

client = chromadb.Client()
# or
client = chromadb.EphemeralClient()
# or
client = chromadb.PersistentClient()
新的 Rust 实现会忽略这些设置：
  • chroma_server_nofile
  • chroma_server_thread_pool_size
  • chroma_memory_limit_bytes
  • chroma_segment_cache_policy
Chroma CLI 变更 如果您使用 CLI (chroma run) 运行 Chroma 服务器，本节内容适用于您。 之前您可能通过环境变量提供给服务器的设置，例如 CHROMA_SERVER_CORS_ALLOW_ORIGINS 或 CHROMA_OTEL_COLLECTION_ENDPOINT，现在需通过配置文件提供。例如：
chroma run --config ./config.yaml
点击此处查看完整的配置文件示例。 Chroma Docker 变更 如果您使用 Docker 容器运行 Chroma，本节内容适用于您。 之前您通过环境变量提供给容器的设置（如 CHROMA_SERVER_CORS_ALLOW_ORIGINS），现在需通过配置文件提供。请参阅 Docker 文档了解更多信息。 容器中的默认数据存储位置已从 /chroma/chroma 更改为 /data。例如，如果您之前启动容器的方式是：
docker run -p 8000:8000 -v ./chroma:/chroma/chroma chroma-core/chroma
您现在应该使用以下方式启动： 
docker run -p 8000:8000 -v ./chroma:/data chroma-core/chroma

​
v0.6.0 - 2024年12月30日

此前，list_collections 返回 Collection 对象列表。如果您的某些集合是使用自定义嵌入函数（即非默认函数）创建的，这可能会导致错误。因此，从现在起 list_collections 将仅返回集合名称。 例如，如果您使用 OpenAIEmbeddingFunction 创建了所有集合，以下是正确使用 list_collections 和 get_collection 的方式：
collection_names = client.list_collections()
ef = OpenAIEmbeddingFunction(...)
collections = [
	client.get_collection(name=name, embedding_function=ef)
	for name in collection_names
]
未来，我们计划支持嵌入函数持久化，届时 list_collections 可以返回正确配置的 Collection 对象，您也不再需要在 get_collection 中提供对应的嵌入函数。 此外，我们已停止支持 Python 3.8。

​
v0.5.17 - 2024年10月30日

我们不再支持在元数据过滤、ID 过滤等操作中发送空列表或空字典。例如： 
collection.get(
	ids=["id1", "id2", "id3", ...],
	where={}
)
不再被支持。请改用： 
collection.get(ids=["id1", "id2", "id3", ...])

​
v0.5.12 - 2024年10月8日

where 子句中的运算符 $ne（不等于）和 $nin（不在...中）已更新：
  • 以前：它们仅匹配包含指定键的记录。
  • 现在：它们也会匹配根本不包含指定键的记录。
换句话说，$ne 和 $nin 现在分别匹配 $eq（等于）和 $in（在...中）所匹配记录的补集（完全相反的集合）。 where_document 子句中的 $not_contains 运算符也已更新：
  • 以前：它仅匹配具有文档字段的记录。
  • 现在：它也会匹配根本没有文档字段的记录。
换句话说，$not_contains 现在匹配与 $contains 所匹配集合完全相反的记录集。 RateLimitingProvider 现已弃用，由 RateLimitEnforcer 取代。这个新接口允许您使用限流逻辑封装服务器调用。默认的 SimpleRateLimitEnforcer 实现允许所有请求，但您可以创建自定义实现来实现更高级的限流策略。

​
v0.5.11 - 2024年9月26日

collection.get() 返回的结果现在按内部 ID 排序。此前，结果按用户提供的 ID 排序，尽管这一行为并未在文档中明确说明。我们决定做出此更改，因为在托管版 Chroma 中使用用户提供的 ID 可能不利于性能，且我们希望在本地 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 - 2024年9月16日

Chroma 内部使用预写日志（WAL）。在 v0.5.6 之前的所有版本中，此日志从未被清理。这导致数据目录远大于实际需要，且删除集合后目录大小并未按预期减少。 在 v0.5.6 中，预写日志会自动清理。但是，对于现有数据库，此功能默认不开启。升级后，您应运行一次 chroma utils vacuum 以减小数据库体积并启用持续清理。详见 CLI 参考。 此操作无需定期运行，也不需要在 v0.5.6 或更高版本创建的新数据库上运行。

​
v0.5.1 - 2024年6月7日

在 Python 客户端中，max_batch_size 属性已被移除。虽然之前未在文档中说明，但如果您正在使用它，现在应改用 get_max_batch_size()。 该方法在首次运行时会发起 HTTP 请求。我们将其改为方法形式，是为了更明确地表示这可能是一个阻塞操作。

​
身份验证系统大修 - 2024年4月20日

如果您未使用 Chroma 的内置身份验证系统，则无需执行任何操作。 此版本大修并简化了我们的身份验证（Authentication）和授权（Authorization）系统。如果您正在使用 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 也是如此。配置的值（或配置文件中的数据）将取决于您的 authn 和 authz 提供程序。更多信息请参阅 此处。 Chroma 附带的两种身份验证系统是 Basic 和 Token。我们为每种系统提供了简短的迁移指南。

​
Basic 认证

如果您使用 Token 认证，您的服务器配置可能如下所示： 
CHROMA_SERVER_AUTH_CREDENTIALS="admin:admin"
CHROMA_SERVER_AUTH_CREDENTIALS_FILE="./example_file"
CHROMA_SERVER_AUTH_CREDENTIALS_PROVIDER="chromadb.auth.providers.HtpasswdConfigurationServerAuthCredentialsProvider"
CHROMA_SERVER_AUTH_PROVIDER="chromadb.auth.basic.BasicAuthServerProvider"
注意：AUTH_CREDENTIALS 和 AUTH_CREDENTIALS_FILE 只能设置其中之一，但本指南展示了如何迁移两者。 以及对应的客户端配置：
CHROMA_CLIENT_AUTH_PROVIDER="chromadb.auth.token.TokenAuthClientProvider"
CHROMA_CLIENT_AUTH_CREDENTIALS="admin:admin"
要迁移到新的服务器配置，只需将其更改为： 
CHROMA_SERVER_AUTHN_PROVIDER="chromadb.auth.token_authn.TokenAuthenticationServerProvider"
CHROMA_SERVER_AUTHN_CREDENTIALS="test-token"
CHROMA_SERVER_AUTHN_CREDENTIALS_FILE="./example_file"
新的客户端配置： 
CHROMA_CLIENT_AUTH_CREDENTIALS="test-token"
CHROMA_CLIENT_AUTH_PROVIDER="chromadb.auth.basic_authn.BasicAuthClientProvider"

​
Token 认证

如果您使用 Token 认证，您的服务器配置可能如下所示： 
CHROMA_SERVER_AUTH_CREDENTIALS="test-token"
CHROMA_SERVER_AUTH_CREDENTIALS_FILE="./example_file"
CHROMA_SERVER_AUTH_CREDENTIALS_PROVIDER="chromadb.auth.token.TokenConfigServerAuthCredentialsProvider"
CHROMA_SERVER_AUTH_PROVIDER="chromadb.auth.token.TokenAuthServerProvider"
CHROMA_SERVER_AUTH_TOKEN_TRANSPORT_HEADER="AUTHORIZATION"
注意：AUTH_CREDENTIALS 和 AUTH_CREDENTIALS_FILE 只能设置其中之一，但本指南展示了如何迁移两者。 以及对应的客户端配置：
CHROMA_CLIENT_AUTH_PROVIDER="chromadb.auth.token.TokenAuthClientProvider"
CHROMA_CLIENT_AUTH_CREDENTIALS="test-token"
CHROMA_CLIENT_AUTH_TOKEN_TRANSPORT_HEADER="AUTHORIZATION"
要迁移到新的服务器配置，只需将其更改为： 
CHROMA_SERVER_AUTHN_PROVIDER="chromadb.auth.token_authn.TokenAuthenticationServerProvider"
CHROMA_SERVER_AUTHN_CREDENTIALS="test-token"
CHROMA_SERVER_AUTHN_CREDENTIALS_FILE="./example_file"
CHROMA_AUTH_TOKEN_TRANSPORT_HEADER="AUTHORIZATION"
新的客户端配置： 
CHROMA_CLIENT_AUTH_CREDENTIALS="test-token"
CHROMA_CLIENT_AUTH_PROVIDER="chromadb.auth.token_authn.TokenAuthClientProvider"
CHROMA_AUTH_TOKEN_TRANSPORT_HEADER="AUTHORIZATION"

​
已更改配置项的参考

  • 整体配置
    • 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 客户端。
  • 服务器身份验证 (authn)
    • 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。
  • 服务器授权 (authz)
    • chroma_server_authz_ignore_paths：已删除。功能现集成在 chroma_server_auth_ignore_paths 中。
查看完整更改，您可以阅读 PR 或在 Discord 上联系 Chroma 团队。

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

此版本增加了对多模态嵌入的支持，并相应更改了 EmbeddingFunction 的定义。此项更改主要影响那些实现了自定义 EmbeddingFunction 类的用户。如果您使用的是 Chroma 的内置嵌入函数，则无需采取任何操作。 EmbeddingFunction 此前，EmbeddingFunction 的定义为：
class EmbeddingFunction(Protocol):
    def __call__(self, texts: Documents) -> Embeddings:
        ...
更新后，EmbeddingFunction 的定义为： 
Embeddable = Union[Documents, Images]
D = TypeVar("D", bound=Embeddable, contravariant=True)

class EmbeddingFunction(Protocol[D]):
    def __call__(self, input: D) -> Embeddings:
        ...
主要区别在于：
  • EmbeddingFunction 现在是泛型的，接受一个类型参数 D，它是 Embeddable 的子类型。这允许我们定义可以嵌入多种模态的 EmbeddingFunction。
  • __call__ 现在只接受一个参数 input，以支持任何类型 D 的数据。texts 参数已被移除。

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

此版本有哪些新功能？
  • 创建客户端的新简便方式
  • 更改了存储方式
  • .persist() 已移除，.reset() 不再默认开启
新客户端 
### in-memory ephemeral client

# before
import chromadb
client = chromadb.Client()

# after
import chromadb
client = chromadb.EphemeralClient()


### persistent client

# before
import chromadb
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
))

# after
import chromadb
client = chromadb.PersistentClient(path="/path/to/persist/directory")


### http client (to talk to server backend)

# before
import chromadb
from chromadb.config import Settings
client = chromadb.Client(Settings(chroma_api_impl="rest",
                                        chroma_server_host="localhost",
                                        chroma_server_http_port="8000"
                                    ))

# after
import chromadb
client = chromadb.HttpClient(host="localhost", port="8000")
您仍然可以访问底层的 .Client() 方法。如果您想关闭遥测，所有客户端都支持自定义设置： 
import chromadb
from chromadb.config import Settings
client = chromadb.PersistentClient(
    path="/path/to/persist/directory",
    settings=Settings(anonymized_telemetry=False))
新数据布局 此版本的 Chroma 放弃了 duckdb 和 clickhouse，转而使用 sqlite 进行元数据存储。这意味着需要迁移数据。我们为此创建了一个迁移 CLI 工具。 如果您升级到 0.4.0 并尝试以旧方式访问存储的数据，您将看到以下错误消息：
您正在使用已弃用的 Chroma 配置。请运行 pip install chroma-migrate 并执行 chroma-migrate 来升级您的配置。更多信息请参阅 https://docs.chroma.org.cn/deployment/migration 或加入我们的 Discord https://discord.gg/MMeYNTmh3x 获取帮助！
以下是如何安装和使用该 CLI： 
pip install chroma-migrate
chroma-migrate
如果您在迁移过程中需要任何帮助，请联系我们！我们随时在 Discord 提供支持。 持久化 (Persist) 与重置 (Reset) .persist() 存在于旧版本 Chroma 中，因为当时写入操作只有在强制执行时才会刷新到磁盘。Chroma 0.4.0 会立即将所有写入保存到磁盘，因此不再需要 persist。 用于重置整个数据库的 .reset() 以前默认是开启的，这感觉不太安全。0.4.0 默认将其禁用。您可以通过向 Settings 对象传递 allow_reset=True 来重新启用它。例如：
import chromadb
from chromadb.config import Settings
client = chromadb.PersistentClient(path="./path/to/chroma", settings=Settings(allow_reset=True))