通过Langchain初始化ChromaDB时出现zstd C API版本不匹配错误

问题场景 #

在Python 3.10的conda环境中，跟随Langchain的RAG应用教程初始化ChromaDB向量存储时，触发以下版本不匹配错误：

Traceback (most recent call last):

  File ~\anaconda3\envs\unstructured\lib\site-packages\spyder_kernels\py3compat.py:356 in compat_exec
    exec(code, globals, locals)

  File c:\users\nicol\onedrive\documents\uni\masterarbeit\giz\code\unstructured_preprocessing\semi-structured-rag_exmpl.py:335
    vectorstore = Chroma(collection_name="summaries", embedding_function=OpenAIEmbeddings())

  File ~\anaconda3\envs\unstructured\lib\site-packages\langchain_community\vectorstores\chroma.py:120 in __init__
    self._client = chromadb.Client(_client_settings)

  File ~\anaconda3\envs\unstructured\lib\site-packages\chromadb\__init__.py:35 in Client
    return system.get_api()

  File ~\anaconda3\envs\unstructured\lib\site-packages\chromadb\config.py:97 in get_api
    self.api = self._instantiate("chroma_api_impl")

  File ~\anaconda3\envs\unstructured\lib\site-packages\chromadb\config.py:87 in _instantiate
    impl = cls(self)

  File ~\anaconda3\envs\unstructured\lib\site-packages\chromadb\api\local.py:57 in __init__
    self._db = system.get_db()

  File ~\anaconda3\envs\unstructured\lib\site-packages\chromadb\config.py:92 in get_db
    self.db = self._instantiate("chroma_db_impl")

  File ~\anaconda3\envs\unstructured\lib\site-packages\chromadb\config.py:85 in _instantiate
    module = importlib.import_module(module_name)

  File ~\anaconda3\envs\unstructured\lib\importlib\__init__.py:126 in import_module
    return _bootstrap._gcd_import(name[level:], package, level)

  File <frozen importlib._bootstrap>:1050 in _gcd_import

  File <frozen importlib._bootstrap>:1027 in _find_and_load

  File <frozen importlib._bootstrap>:1006 in _find_and_load_unlocked

  File <frozen importlib._bootstrap>:688 in _load_unlocked

  File <frozen importlib._bootstrap_external>:883 in exec_module

  File <frozen importlib._bootstrap>:241 in _call_with_frames_removed

  File ~\anaconda3\envs\unstructured\lib\site-packages\chromadb\db\duckdb.py:4
    from chromadb.db.clickhouse import (

  File ~\anaconda3\envs\unstructured\lib\site-packages\chromadb\db\clickhouse.py:15
    import clickhouse_connect

  File ~\anaconda3\envs\unstructured\lib\site-packages\clickhouse_connect\__init__.py:1
    from clickhouse_connect.driver import create_client

  File ~\anaconda3\envs\unstructured\lib\site-packages\clickhouse_connect\driver\__init__.py:9
    from clickhouse_connect.driver.httpclient import HttpClient

  File ~\anaconda3\envs\unstructured\lib\site-packages\clickhouse_connect\driver\httpclient.py:21
    from clickhouse_connect.driver.compression import available_compression

  File ~\anaconda3\envs\unstructured\lib\site-packages\clickhouse_connect\driver\compression.py:7
    import zstandard

  File ~\anaconda3\envs\unstructured\lib\site-packages\zstandard\__init__.py:39
    from .backend_c import *  # type: ignore

ImportError: zstd C API versions mismatch; Python bindings were not compiled/linked against expected zstd version (10409 returned by the lib, 10505 hardcoded in zstd headers, 10505 hardcoded in the cext)

解决思路 #

• 重装zstandard包，对齐版本
  先彻底卸载现有版本：

  pip uninstall -y zstandard
  

  优先用conda安装适配环境的版本：

  conda install -c conda-forge zstandard
  

  若conda安装无效，再用pip强制重装：

  pip install zstandard --force-reinstall
  

• 显式指定ChromaDB使用DuckDB存储，绕开ClickHouse依赖
  初始化Chroma时直接指定数据库实现为DuckDB+Parquet，避免加载ClickHouse相关模块（正是它触发了zstandard的版本检查）：

  from chromadb.config import Settings
  from langchain_community.vectorstores import Chroma
  from langchain_openai import OpenAIEmbeddings
  
  vectorstore = Chroma(
      collection_name="summaries",
      embedding_function=OpenAIEmbeddings(),
      client_settings=Settings(
          chroma_db_impl="duckdb+parquet",
          persist_directory="./chroma_db"  # 可选，指定持久化路径
      )
  )
  

• 检查系统zstd库版本，必要时更新
  查看当前系统zstd版本：

  zstd --version
  

  如果系统库版本与Python绑定的版本差异过大，通过conda更新系统级zstd：

  conda install -c conda-forge zstd
  

• 重建干净的conda环境
  若以上方法均无效，创建全新环境隔离冲突：

  conda create -n rag_env python=3.10
  conda activate rag_env
  pip install langchain langchain_community chromadb openai
  

内容的提问来源于stack exchange，提问作者NicoBar