263 lines
5.0 KiB
Markdown
263 lines
5.0 KiB
Markdown
# 安装问题解决指南
|
||
|
||
## 问题：Python 3.13 兼容性问题
|
||
|
||
如果您在安装依赖时遇到 numpy/pandas 编译错误，这是因为 Python 3.13 是最新版本，部分科学计算库还未完全适配。
|
||
|
||
### 错误信息示例
|
||
```
|
||
fatal error: 'type_traits' file not found
|
||
ERROR: Failed to build 'pandas' when installing build dependencies
|
||
```
|
||
|
||
## 解决方案
|
||
|
||
### 方案1：使用 Python 3.11 或 3.12（强烈推荐）
|
||
|
||
这是最简单可靠的方法。
|
||
|
||
#### macOS (使用 Homebrew)
|
||
|
||
```bash
|
||
# 1. 安装 Python 3.11
|
||
brew install python@3.11
|
||
|
||
# 2. 进入项目目录
|
||
cd /Users/aaron/source_code/Stock_Agent/backend
|
||
|
||
# 3. 删除旧的虚拟环境（如果存在）
|
||
rm -rf venv
|
||
|
||
# 4. 使用 Python 3.11 创建新的虚拟环境
|
||
python3.11 -m venv venv
|
||
|
||
# 5. 激活虚拟环境
|
||
source venv/bin/activate
|
||
|
||
# 6. 升级 pip
|
||
pip install --upgrade pip
|
||
|
||
# 7. 安装依赖
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
#### Linux (Ubuntu/Debian)
|
||
|
||
```bash
|
||
# 1. 安装 Python 3.11
|
||
sudo apt update
|
||
sudo apt install python3.11 python3.11-venv python3.11-dev
|
||
|
||
# 2. 创建虚拟环境
|
||
python3.11 -m venv venv
|
||
source venv/bin/activate
|
||
|
||
# 3. 安装依赖
|
||
pip install --upgrade pip
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
#### Windows
|
||
|
||
```powershell
|
||
# 1. 从 python.org 下载并安装 Python 3.11
|
||
# https://www.python.org/downloads/
|
||
|
||
# 2. 创建虚拟环境
|
||
py -3.11 -m venv venv
|
||
|
||
# 3. 激活虚拟环境
|
||
venv\Scripts\activate
|
||
|
||
# 4. 安装依赖
|
||
pip install --upgrade pip
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 方案2：使用预编译的 wheel 包（Python 3.13）
|
||
|
||
如果必须使用 Python 3.13，可以尝试安装预编译的包：
|
||
|
||
```bash
|
||
# 激活虚拟环境
|
||
source venv/bin/activate # macOS/Linux
|
||
# 或
|
||
venv\Scripts\activate # Windows
|
||
|
||
# 先单独安装 numpy 和 pandas
|
||
pip install --upgrade pip
|
||
pip install numpy --only-binary :all:
|
||
pip install pandas --only-binary :all:
|
||
|
||
# 然后安装其他依赖
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 方案3：使用 Conda（推荐用于数据科学项目）
|
||
|
||
Conda 提供预编译的包，避免编译问题：
|
||
|
||
```bash
|
||
# 1. 安装 Miniconda 或 Anaconda
|
||
# https://docs.conda.io/en/latest/miniconda.html
|
||
|
||
# 2. 创建环境
|
||
conda create -n stock_agent python=3.11
|
||
|
||
# 3. 激活环境
|
||
conda activate stock_agent
|
||
|
||
# 4. 安装依赖
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
## 验证安装
|
||
|
||
安装完成后，验证是否成功：
|
||
|
||
```bash
|
||
# 检查 Python 版本
|
||
python --version
|
||
# 应该显示 Python 3.11.x 或 3.12.x
|
||
|
||
# 检查关键包
|
||
python -c "import numpy; print('numpy:', numpy.__version__)"
|
||
python -c "import pandas; print('pandas:', pandas.__version__)"
|
||
python -c "import fastapi; print('fastapi:', fastapi.__version__)"
|
||
python -c "import tushare; print('tushare:', tushare.__version__)"
|
||
```
|
||
|
||
## 启动应用
|
||
|
||
安装成功后，按以下步骤启动：
|
||
|
||
```bash
|
||
# 1. 确保在虚拟环境中
|
||
source venv/bin/activate # macOS/Linux
|
||
# 或
|
||
venv\Scripts\activate # Windows
|
||
|
||
# 2. 配置环境变量
|
||
cd /Users/aaron/source_code/Stock_Agent
|
||
cp .env.example .env
|
||
# 编辑 .env 文件，填写 API 密钥
|
||
|
||
# 3. 启动应用
|
||
cd backend
|
||
python -m app.main
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### Q1: 如何检查当前 Python 版本？
|
||
|
||
```bash
|
||
python --version
|
||
python3 --version
|
||
python3.11 --version
|
||
```
|
||
|
||
### Q2: 如何切换 Python 版本？
|
||
|
||
macOS/Linux:
|
||
```bash
|
||
# 使用特定版本创建虚拟环境
|
||
python3.11 -m venv venv
|
||
```
|
||
|
||
Windows:
|
||
```powershell
|
||
py -3.11 -m venv venv
|
||
```
|
||
|
||
### Q3: 虚拟环境激活失败？
|
||
|
||
确保在正确的目录：
|
||
```bash
|
||
cd /Users/aaron/source_code/Stock_Agent/backend
|
||
ls venv # 应该能看到 bin 或 Scripts 目录
|
||
```
|
||
|
||
### Q4: pip 安装很慢？
|
||
|
||
使用国内镜像源：
|
||
```bash
|
||
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
|
||
```
|
||
|
||
### Q5: 权限错误？
|
||
|
||
不要使用 sudo，确保在虚拟环境中：
|
||
```bash
|
||
which python # 应该显示虚拟环境路径
|
||
```
|
||
|
||
## 推荐的完整安装流程
|
||
|
||
```bash
|
||
# 1. 安装 Python 3.11
|
||
brew install python@3.11 # macOS
|
||
|
||
# 2. 进入项目目录
|
||
cd /Users/aaron/source_code/Stock_Agent
|
||
|
||
# 3. 创建虚拟环境
|
||
python3.11 -m venv backend/venv
|
||
|
||
# 4. 激活虚拟环境
|
||
source backend/venv/bin/activate
|
||
|
||
# 5. 升级 pip
|
||
pip install --upgrade pip setuptools wheel
|
||
|
||
# 6. 安装依赖
|
||
cd backend
|
||
pip install -r requirements.txt
|
||
|
||
# 7. 配置环境变量
|
||
cd ..
|
||
cp .env.example .env
|
||
nano .env # 或使用其他编辑器
|
||
|
||
# 8. 启动应用
|
||
cd backend
|
||
python -m app.main
|
||
```
|
||
|
||
## 获取帮助
|
||
|
||
如果仍然遇到问题：
|
||
|
||
1. 检查 Python 版本：`python --version`
|
||
2. 检查虚拟环境：`which python`
|
||
3. 查看完整错误信息
|
||
4. 提交 Issue 到项目仓库
|
||
|
||
## 最小依赖版本
|
||
|
||
如果遇到版本冲突，可以尝试最小版本：
|
||
|
||
```txt
|
||
fastapi>=0.100.0
|
||
uvicorn>=0.23.0
|
||
langchain>=0.1.0
|
||
tushare>=1.3.0
|
||
sqlalchemy>=2.0.0
|
||
pydantic>=2.0.0
|
||
pandas>=2.0.0
|
||
numpy>=1.24.0
|
||
```
|
||
|
||
## 成功标志
|
||
|
||
当您看到以下输出时，说明安装成功：
|
||
|
||
```
|
||
INFO: Started server process [xxxxx]
|
||
INFO: Waiting for application startup.
|
||
INFO: Application startup complete.
|
||
INFO: Uvicorn running on http://0.0.0.0:8000
|
||
```
|
||
|
||
然后访问 http://localhost:8000 即可使用系统！
|