feat: implement ERP AI Assistant Phase 1
Backend (FastAPI + SQLAlchemy + Claude API + RAG): - Config management with Pydantic v2 - Database engine with connection pooling and SQL injection prevention - AI engine with Claude API integration (support custom base URL) - RAG engine with ChromaDB and sentence-transformers - Requirement analysis service - Config generation service - Executor engine with SQL validation - REST API endpoints: /analyze, /generate, /execute Frontend (Vue 3 + Element Plus + Pinia): - Complete 3-step workflow: analyze → generate → execute - Step indicator with progress visualization - Analysis result display with field table - SQL preview with monospace font - Execute confirmation dialog with safety warning - Execution result display - State management with Pinia - API service integration Security: - SQL injection prevention with parameterized queries - Dangerous SQL operation blocking - Database password URL encoding - Transaction auto-rollback - Pydantic config validation Features: - Natural language requirement analysis - Automated SQL configuration generation - Safe execution with human review - LAN access support - Custom Claude API endpoint support Documentation: - README with quick start guide - Quick start guide - LAN access configuration - Dependency fixes guide - Claude API configuration - Git operation guide - Implementation report Dependencies fixed: - numpy<2.0.0 for chromadb compatibility - sentence-transformers==2.7.0 for huggingface_hub compatibility Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
288
docs/DEPENDENCY_FIXES.md
Normal file
288
docs/DEPENDENCY_FIXES.md
Normal file
@@ -0,0 +1,288 @@
|
||||
# 依赖问题修复指南
|
||||
|
||||
## 🐛 已知问题及解决方案
|
||||
|
||||
### 问题 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+
|
||||
Reference in New Issue
Block a user