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` 中添加约束：
```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

**解决方案:**
已升级到兼容版本：
```txt
sentence-transformers==2.7.0  # 从 2.2.2 升级
```

**修复步骤:**
```bash
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. **安全性**: 便于安全审计和漏洞修复

---

## 🔄 更新依赖

### 更新单个包

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

### 更新所有包（谨慎）

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

### 安全更新

仅更新补丁版本（修复 bug 和安全漏洞）：
```bash
pip install --upgrade package-name==1.2.*  # 保持在 1.2.x
```

---

## ⚠️ 常见依赖问题

### 问题 1: pip 安装超时

**解决方案:**
```bash
# 使用国内镜像
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:**
```bash
sudo apt-get install unixodbc-dev
pip install pyodbc
```

**CentOS/RHEL:**
```bash
sudo yum install unixODBC-devel
pip install pyodbc
```

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

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

**原因:** HuggingFace 模型下载速度慢

**解决方案:**
```bash
# 使用镜像站
export HF_ENDPOINT=https://hf-mirror.com

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

### 问题 4: ChromaDB 初始化错误

**可能原因:**
- 权限问题
- SQLite 版本过低
- 磁盘空间不足

**解决方案:**
```bash
# 检查目录权限
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
```

---

## 🔍 依赖诊断命令

### 检查已安装版本

```bash
# 列出所有包
pip list

# 查看特定包信息
pip show numpy

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

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

### 依赖树分析

```bash
# 安装 pipdeptree
pip install pipdeptree

# 查看依赖树
pipdeptree

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

### 冲突检测

```bash
# 检查依赖冲突
pip check

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

---

## 📝 最佳实践

### 1. 使用虚拟环境

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

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

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

### 2. 定期更新依赖

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

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

### 3. 锁定依赖版本

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

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

### 4. 分离开发和生产依赖

创建 `requirements-dev.txt`:
```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 迁移指南](https://numpy.org/doc/stable/numpy_2_0_migration_guide.html)
- [ChromaDB 文档](https://docs.trychroma.com/)
- [Python 依赖管理最佳实践](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/)

---

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