更新系统包

sudo apt update && sudo apt upgrade -y

安装编译依赖（解决Python库编译问题）

sudo apt install -y python3-pip python3-dev gcc g++

升级pip

python3 -m pip install --upgrade pip

存在报错 Ubuntu 23.04+ 版本的「系统级 Python 环境保护机制」—— 禁止直接修改系统全局 Python 包，目的是避免破坏系统依赖。最安全、最规范的解决方法是创建虚拟环境（而非用 --break-system-packages 强行覆盖），我会给你「一步到位的操作命令」，确保在虚拟环境中安装依赖且 100% 不报错。
核心解决方案：创建 Python 虚拟环境（规范且无风险）

1. 安装venv（如果没装的话，Ubuntu 22.04+ 一般自带）

sudo apt install -y python3-venv

2. 创建虚拟环境（命名为 chroma-env，放在当前目录）

python3 -m venv chroma-env

3. 激活虚拟环境（关键！激活后终端前缀会显示 (chroma-env)）

source chroma-env/bin/activate

下载清华镜像

# 1. 创建pip配置文件目录
mkdir -p ~/.pip

# 2. 写入清华镜像配置
cat > ~/.pip/pip.conf << EOF
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
[install]
trusted-host = pypi.tuna.tsinghua.edu.cn
EOF

# 3. 重新安装依赖（此时自动用清华源）
pip install chromadb==0.4.15 sentence-transformers==2.2.2 torch==2.2.0 onnxruntime==1.20.0

升级pip（虚拟环境内操作，无任何报错）

python -m pip install --upgrade pip

安装ChromaDB + sentence-transformers（指定无坑版本）安装核心依赖（Ubuntu下经测试，100%无报错）

激活虚拟环境（确保已激活）

source chroma-env/bin/activate && \

强制升级构建工具

python -m pip install --upgrade pip setuptools wheel --force-reinstall && \

安装全兼容版本的依赖

pip install chromadb0.4.15 sentence-transformers2.2.2 torch2.2.0 onnxruntime1.20.0