erp-ass/docs/DEPENDENCY_FIXES.md

依赖问题修复指南

🐛 已知问题及解决方案

问题 1: NumPy 2.0 兼容性错误 ✅ 已修复

错误信息:

AttributeError: `np.float_` was removed in the NumPy 2.0 release. Use `np.float64` instead.

原因:

• ChromaDB 0.4.18 依赖旧版 NumPy API
• NumPy 2.0 移除了 np.float_ 等类型别名
• 版本冲突导致运行失败

解决方案: 已在 requirements.txt 中添加约束：

numpy<2.0.0

问题 2: Sentence-Transformers 与 HuggingFace Hub 不兼容 ✅ 已修复

错误信息:

ImportError: cannot import name 'cached_download' from 'huggingface_hub'

原因:

• sentence-transformers 2.2.2 使用了已弃用的 cached_download API
• 新版 huggingface_hub 移除了该 API

解决方案: 已升级到兼容版本：

sentence-transformers==2.7.0  # 从 2.2.2 升级

修复步骤:

cd backend
source venv/bin/activate  # Windows: venv\Scripts\activate

# 卸载当前 numpy
pip uninstall numpy -y

# 重新安装依赖（会安装 numpy 1.x）
pip install -r requirements.txt

# 验证 numpy 版本
python -c "import numpy; print(numpy.__version__)"
# 应输出: 1.x.x (小于 2.0)

---

📦 依赖版本说明

核心依赖版本

包名	版本	说明
numpy	< 2.0.0	降级以兼容 chromadb
chromadb	0.4.18	向量数据库
sentence-transformers	2.2.2	文本嵌入模型
fastapi	0.104.1	Web 框架
anthropic	0.18.1	Claude API SDK
pydantic	2.5.0	数据验证

为什么锁定版本？

1. 兼容性保证: 避免主版本升级引入破坏性更改
2. 可重现构建: 确保开发和生产环境一致
3. 安全性: 便于安全审计和漏洞修复

---

🔄 更新依赖

更新单个包

pip install --upgrade package-name
pip freeze > requirements.txt  # 更新版本

更新所有包（谨慎）

pip install --upgrade pip
pip-review --auto  # 需要 pip-review 工具

安全更新

仅更新补丁版本（修复 bug 和安全漏洞）：

pip install --upgrade package-name==1.2.*  # 保持在 1.2.x

---

⚠️ 常见依赖问题

问题 1: pip 安装超时

解决方案:

# 使用国内镜像
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 或配置全局镜像
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

问题 2: pyodbc 安装失败

原因: 缺少 ODBC 驱动开发包

解决方案:

Ubuntu/Debian:

sudo apt-get install unixodbc-dev
pip install pyodbc

CentOS/RHEL:

sudo yum install unixODBC-devel
pip install pyodbc

Windows: 无需额外操作，直接安装即可。

问题 3: sentence-transformers 下载模型慢

原因: HuggingFace 模型下载速度慢

解决方案:

# 使用镜像站
export HF_ENDPOINT=https://hf-mirror.com

# 或在 Python 代码中设置
import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'

问题 4: ChromaDB 初始化错误

可能原因:

• 权限问题
• SQLite 版本过低
• 磁盘空间不足

解决方案:

# 检查目录权限
chmod -R 755 backend/knowledge_base/

# 检查 SQLite 版本（需要 >= 3.35.0）
python -c "import sqlite3; print(sqlite3.sqlite_version)"

# 清理并重新初始化
rm -rf backend/knowledge_base/chroma_db

---

🔍 依赖诊断命令

检查已安装版本

# 列出所有包
pip list

# 查看特定包信息
pip show numpy

# 检查过时的包
pip list --outdated

# 检查安全漏洞
pip audit  # 需要 pip-audit 工具

依赖树分析

# 安装 pipdeptree
pip install pipdeptree

# 查看依赖树
pipdeptree

# 查看反向依赖（谁依赖了这个包）
pipdeptree -r -p numpy

冲突检测

# 检查依赖冲突
pip check

# 查看版本约束
pip-compile --dry-run requirements.txt

---

📝 最佳实践

1. 使用虚拟环境

# 创建虚拟环境
python3 -m venv venv

# 激活虚拟环境
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate      # Windows

# 确认使用虚拟环境
which python  # Linux/Mac
where python  # Windows

2. 定期更新依赖

# 每月检查更新
pip list --outdated

# 更新前查看变更日志
pip install --upgrade package-name --dry-run

3. 锁定依赖版本

# 生成精确版本
pip freeze > requirements.txt

# 或使用 pip-tools
pip-compile requirements.in

4. 分离开发和生产依赖

创建 requirements-dev.txt:

-r requirements.txt

pytest==7.4.3
pytest-asyncio==0.21.1
pytest-cov==4.1.0
pytest-mock==3.12.0
httpx==0.25.2

---

🆘 依赖问题排查流程

1. 确认错误信息 → 找到具体的包名和错误类型
2. 检查版本冲突 → pip check
3. 查看依赖关系 → pipdeptree -r -p package-name
4. 搜索已知问题 → GitHub Issues / Stack Overflow
5. 尝试降级/升级 → 调整版本约束
6. 清理重新安装 → pip cache purge && pip install -r requirements.txt

---

📚 相关资源

• NumPy 2.0 迁移指南
• ChromaDB 文档
• Python 依赖管理最佳实践

---

更新时间: 2026-03-21 适用版本: v1.0.0+