AI Stock Recommendation System - MVP
一个基于 OpenBB + TuShare + Machine Learning + Claude API 的实时智能股票推荐系统。
🎯 项目特色
✅ 完整的数据流 - 从数据采集到模型预测再到自然语言解释 ✅ AI 驱动推荐 - XGBoost 模型 + Claude 自然语言解释 ✅ 实时推送 - WebSocket 支持实时推荐更新 ✅ 可视化仪表板 - Vue 3 + ECharts 展示推荐和分析 ✅ 一键部署 - Docker Compose 快速启动 ✅ 可扩展架构 - 预留本地 DeepSeek 推理接口
🏗️ 系统架构
┌─────────────────────────────────────┐
│ 浏览器 Dashboard 前端 │
│ (Vue 3 + ECharts) │
└──────────────┬──────────────────────┘
│ HTTP / WebSocket
┌──────────────▼──────────────────────┐
│ FastAPI 后端服务 │
│ (RESTful API + WebSocket) │
└──────────────┬──────────────────────┘
│
┌──────────┼──────────┐
│ │ │
┌───▼─┐ ┌────▼────┐ ┌──▼───────┐
│ 缓存 │ │ 数据库 │ │ Claude │
│Redis│ │PostgreSQL│ │ API │
└─────┘ └─────────┘ └──────────┘
📋 技术栈
| 组件 | 技术 |
|---|---|
| 后端 | FastAPI + SQLAlchemy |
| 数据源 | OpenBB + TuShare |
| 模型 | XGBoost / LightGBM |
| LLM | OpenRouter Claude 4.5 API |
| 前端 | Vue 3 + ECharts |
| 缓存 | Redis |
| 数据库 | PostgreSQL |
| 部署 | Docker + Docker Compose |
🚀 快速开始
前置要求
- Docker & Docker Compose
- Python 3.11+ (本地开发)
- Node.js 18+ (前端开发)
1. 克隆项目
git clone <repo-url> stock-recommendation
cd stock-recommendation
2. 配置环境变量
cp .env.example .env
# 编辑 .env，填入以下必需的 API Key：
# OPENROUTER_KEY=sk-or-v1-xxxxxx
# TUSHARE_TOKEN=xxxxxx
3. 启动服务
# 使用 Docker Compose 启动所有服务
docker-compose up -d
# 查看日志
docker-compose logs -f backend
4. 访问应用
- 📊 Dashboard: http://localhost:8080
- 🔌 API 文档: http://localhost:8000/docs
- 📡 WebSocket: ws://localhost:8000/ws/recommendations
📚 文档
- 系统架构 - 详细的系统设计和整体架构
- 模块规范 - 各个模块的接口和实现细节
- 执行计划 - 项目分阶段实施计划
- 部署指南 - 部署到生产环境的步骤
- API 文档 - REST API 和 WebSocket 接口定义
- 开发指南 - 本地开发和调试说明
🔑 API Key 配置
OpenRouter (Claude API)
- 访问 https://openrouter.ai/
- 获取 API Key
- 配置到
.env文件的OPENROUTER_KEY
TuShare (中国 A 股数据)
- 访问 https://tushare.pro/
- 注册并获取 API Token
- 配置到
.env文件的TUSHARE_TOKEN
OpenBB (可选)
- 访问 https://www.openbb.co/
- 获取 API Token (可选，系统会自动使用免费数据源)
- 配置到
.env文件的OPENBB_TOKEN
📊 API 端点
推荐接口
# 获取最新推荐
GET /api/recommendations
# 获取单个股票详情
GET /api/recommendations/{symbol}
# 实时推送（WebSocket）
WS /ws/recommendations
分析接口
# 行业分布分析
GET /api/analysis/sectors
# 技术信号分析
GET /api/analysis/signals/{symbol}
# 整体市场分析
GET /api/analysis/market
回测接口
# 运行回测
POST /api/backtest/run
📈 推荐逻辑
- 数据采集 → 从 OpenBB 和 TuShare 获取实时行情和基本面数据
- 特征工程 → 计算技术指标 (MA, RSI, MACD, ATR) 和基本面指标 (PE, PB, ROE)
- 模型预测 → XGBoost 评分每只股票 (0-100)
- 推荐选择 → 选择评分最高的 Top 10 股票
- LLM 解释 → 调用 Claude API 生成自然语言推荐理由
- 实时推送 → 通过 WebSocket 发送到前端展示
🧪 测试
后端测试
cd backend
pip install -r requirements.txt
pytest tests/ -v
前端测试
cd frontend
npm install
npm run build
🐳 Docker 命令
# 启动所有服务
docker-compose up -d
# 查看容器状态
docker-compose ps
# 查看日志
docker-compose logs -f backend
docker-compose logs -f frontend
# 停止服务
docker-compose down
# 清除所有数据（包括数据库）
docker-compose down -v
🌐 部署到生产环境
部署到美国节点 (VPS)
# 1. SSH 连接到服务器
ssh [email protected]
# 2. 克隆项目
git clone <repo-url> /opt/stock-recommendation
cd /opt/stock-recommendation
# 3. 配置环境
cp .env.example .env
# 编辑 .env，设置生产环境变量
# 4. 启动服务
docker-compose up -d
# 5. 配置 Nginx (可选)
# 参考 docs/DEPLOYMENT.md
# 6. 验证
curl http://85.239.237.116:8000/api/recommendations
# 浏览器访问 http://85.239.237.116:8080
📦 项目结构
stock-recommendation/
├── backend/ # 后端服务
│ ├── main.py # FastAPI 入口
│ ├── requirements.txt # Python 依赖
│ ├── Dockerfile # Docker 配置
│ └── app/
│ ├── config.py # 配置管理
│ ├── database.py # 数据库连接
│ ├── routes/ # API 路由
│ └── modules/ # 业务逻辑模块
│
├── frontend/ # 前端应用
│ ├── package.json # NPM 依赖
│ ├── vite.config.js # Vite 配置
│ ├── Dockerfile # Docker 配置
│ └── src/
│ ├── components/ # Vue 组件
│ ├── views/ # 页面组件
│ └── services/ # API 服务
│
├── docs/ # 项目文档
│ ├── SYSTEM_OVERVIEW.md # 系统架构
│ ├── MODULE_SPEC.md # 模块规范
│ ├── EXECUTION_PLAN.md # 执行计划
│ ├── DEPLOYMENT.md # 部署指南
│ ├── API_REFERENCE.md # API 文档
│ └── DEVELOPMENT.md # 开发指南
│
├── docker-compose.yml # 容器编排
├── .env.example # 环境配置模板
├── .gitignore # Git 忽略文件
└── README.md # 本文件
🤝 贡献
欢迎提交 Issue 和 Pull Request！
📝 许可
MIT License
📞 支持
- 📖 查看 文档
- 🐛 提交 Issue
- 💬 讨论 Discussions
🎓 学习资源
最后更新: 2025-11-10 状态: MVP 实施中 🚀