跳转到主要内容
本页面列出了常见的陷阱或问题及其解决方法。 如果您在此处未看到您的问题，请同时搜索 Github Issues。

​
Chroma JS-Client 在 NextJS 项目中失效

我们的默认嵌入函数使用 @huggingface/transformers，它依赖于 NextJS 无法打包的二进制文件。如果您遇到此问题，可以使用 withChroma 插件包裹您的 nextConfig（在 next.config.ts 中），这将添加克服打包问题所需的设置。 
import type { NextConfig } from "next";
import { withChroma } from "chromadb";

const nextConfig: NextConfig = {
  /* config options here */
};

export default withChroma(nextConfig);

​
无法在连续的 2D 数组中返回结果。可能是 ef 或 M 太小

当 HNSW 索引根据其结构和您的数据无法为查询检索到请求数量的结果时，就会出现此错误。解决方法是减少您从查询中请求的结果数量 (n_result)，或者增加 HNSW 参数 M、ef_construction 和 ef_search。您可以在此处阅读更多关于 HNSW 配置的信息。

​
使用 .get 或 .query 时，embeddings 显示为 None

这实际上不是错误。嵌入向量非常庞大，传回的开销很大。大多数应用程序并不使用底层的嵌入向量，因此默认情况下，Chroma 不会传回它们。 要传回它们：请在查询中添加 include=["embeddings", "documents", "metadatas", "distances"] 以返回所有信息。 例如：
results = collection.query(
    query_texts="hello",
    n_results=1,
    include=["embeddings", "documents", "metadatas", "distances"],
)
我们可能会将 None 更改为其他内容，以更清晰地说明未返回它们的原因。

​
运行 pip install chromadb 时出现构建错误

如果在设置过程中遇到类似的错误 
Failed to build hnswlib
ERROR: Could not build wheels for hnswlib, which is required to install pyproject.toml-based projects
请尝试社区提供的以下几点建议
  1. 如果遇到错误：clang: error: the clang compiler does not support '-march=native'，请设置此环境变量：export HNSWLIB_NO_NATIVE=1
  2. 如果是 Mac 系统，请安装/更新 xcode 开发者工具：xcode-select --install
  3. 如果是 Windows 系统，请尝试这些步骤

​
SQLite

Chroma 需要 SQLite > 3.35。如果您遇到 SQLite 版本过低的问题，请尝试以下操作。
  1. 安装最新版本的 Python 3.10，有时较低版本的 Python 会捆绑旧版本的 SQLite。
  2. 如果您使用的是 Linux 系统，可以安装 pysqlite3-binary：pip install pysqlite3-binary，然后在运行 Chroma 之前按照此处的步骤覆盖默认的 sqlite3 库。或者，您可以从头开始编译 SQLite，并用最新版本替换 Python 安装中的库，具体操作见此处的说明。
  3. 如果您使用的是 Windows，可以从 https://www.sqlite.org/download.html 手动下载最新版本的 SQLite，并用最新版本替换 Python 安装目录中 DLLs 文件夹下的 DLL。您可以通过在 Python 中运行 os.path.dirname(sys.executable) 来查找 Python 的安装路径。
  4. 如果您使用的是基于 Debian 的 Docker 容器，旧版本的 Debian 没有最新的 SQLite，请使用 bookworm 或更高版本。

​
非法指令 (核心已转储)

如果在设置过程中遇到此类错误且正在使用 Docker - 您可能是在与运行机器 CPU 架构不同的机器上构建了该库。请尝试在运行该镜像的机器上重新构建 Docker 镜像。

​
我的数据目录太大

如果您在 v0.5.6 之前就开始使用 Chroma，可以通过清理 (vacuuming) 来显著缩小数据库。清理一次后，将启用自动修剪（v0.5.6 中的新功能），它将控制您的数据库大小。