5.0 KiB
5.0 KiB
安装问题解决指南
问题：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)
# 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)
# 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
# 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，可以尝试安装预编译的包：
# 激活虚拟环境
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 提供预编译的包，避免编译问题：
# 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
验证安装
安装完成后，验证是否成功：
# 检查 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__)"
启动应用
安装成功后，按以下步骤启动：
# 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 版本？
python --version
python3 --version
python3.11 --version
Q2: 如何切换 Python 版本？
macOS/Linux:
# 使用特定版本创建虚拟环境
python3.11 -m venv venv
Windows:
py -3.11 -m venv venv
Q3: 虚拟环境激活失败？
确保在正确的目录：
cd /Users/aaron/source_code/Stock_Agent/backend
ls venv # 应该能看到 bin 或 Scripts 目录
Q4: pip 安装很慢？
使用国内镜像源：
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
Q5: 权限错误？
不要使用 sudo，确保在虚拟环境中：
which python # 应该显示虚拟环境路径
推荐的完整安装流程
# 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
获取帮助
如果仍然遇到问题：
- 检查 Python 版本：
python --version - 检查虚拟环境：
which python - 查看完整错误信息
- 提交 Issue 到项目仓库
最小依赖版本
如果遇到版本冲突，可以尝试最小版本：
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 即可使用系统！