内容
# CompassFXPulse
> 多币种外汇风险管理平台 — Function Calling Agent + RAG + MCP Server + LoRA 微调 + TimeXer 时序预测，端到端 LLM 应用工程实战。
---
## 这是什么
把 2025 年花旗杯参赛项目（Vue + Flask + LoRA 微调 + 多源爬虫）从"各模块脱节、demo 跑不起来"重构升级成 **生产级 LLM 应用栈**：
- 🤖 **Function Calling Agent**（LangGraph 状态机 + Reflector 反思纠错闭环）
- 📚 **RAG 检索栈**（bge-m3 嵌入 + bge-reranker-v2-m3 重排 + ChromaDB + 30 篇策展金融语料）
- 🔌 **MCP Server**（FastMCP，5 工具同步暴露给 Cursor / Claude Desktop）
- 🎯 **LoRA SFT**（Qwen3-1.7B + 自合成 200 条中文金融 Q&A，eval loss 4.85→1.30）
- 📈 **TimeXer 时序预测**（Transformer，25 年 ECB 长数据 + 4 套外生特征实验）
- 🔍 **Langfuse 全链路 Trace**（plan / tool / latency / token，可优雅降级）
- 💬 **异构 LLM 路由**（DeepSeek 云端处理 Agent，本地 LoRA 处理慧聚答疑，一行 `.env` 切换）
---
## 系统架构
> **架构图（含 Phase 4 加固）**: 见 `docs/diagrams/architecture.png`（高清完整图），下方 mermaid 是简化版。
```mermaid
graph TB
subgraph "用户入口"
Browser["浏览器 :8081<br/>(Vue 2 + ECharts)"]
IDE["Cursor / Claude Desktop"]
BenchClient["Bench client<br/>(httpx async)"]
end
subgraph "边缘防御 (Phase 4.1+4.3)"
RateLimit["rate_limit.py<br/>token bucket per-IP<br/>10 rps + 20 burst"]
Guard["security/injection_guard.py<br/>5 层防御<br/>96.8% 拦截率"]
end
subgraph "Backend Flask :8080 (sync, WSGI)"
Routes["routes_chat / routes_agent / routes_rates / routes_health<br/>+ /api/cache/stats"]
Agent["agent/core.py<br/>Plan→Execute→Synth→Reflect<br/>MAX_TOOL_ROUNDS=2"]
Tools["agent/tools.py<br/>5 工具 + validate_tool_args"]
Cache["cache.py (Phase 4.1)<br/>TTLCache / Redis<br/>~6500× 提速"]
RAG["rag/pipeline.py<br/>bge-m3 + reranker"]
Obs["observability.py<br/>Langfuse"]
end
subgraph "Backend FastAPI :8082 (async, ASGI, Phase 4.4)"
FA["main_fastapi.py + routes_async.py<br/>200 并发 2.81× QPS"]
end
subgraph "评测框架 (Phase 4.2)"
Eval["eval/run_eval.py<br/>30 黄金集 + 31 对抗集<br/>pass 93.5% / judge 9.7"]
end
subgraph "MCP Server (stdio)"
MCP["mcp_server/server.py<br/>FastMCP"]
end
subgraph "LLM 路由"
DeepSeek["DeepSeek 云端<br/>(Agent 工具决策 + Judge)"]
LocalLoRA["本地 Qwen3-1.7B-Finance :8001<br/>(慧聚答疑)"]
end
subgraph "数据层"
MySQL[("MySQL pool=20<br/>17K 行汇率<br/>900 行预测")]
Chroma[("ChromaDB<br/>251 chunks")]
Corpus["30 篇策展<br/>markdown 语料"]
end
Browser -->|HTTP/SSE| RateLimit
BenchClient --> FA
RateLimit --> Guard
Guard --> Routes
IDE -->|MCP/JSON-RPC| MCP
Routes --> Agent
FA -.async wrap.-> Agent
Agent --> Tools
Agent --> Obs
Tools --> Cache
Cache -.miss.-> RAG
Cache -.miss.-> MySQL
Tools --> RAG
Tools --> MySQL
RAG --> Chroma
RAG -.离线 ingest.-> Corpus
Agent -.tools API.-> DeepSeek
Routes -.chat 路径.-> LocalLoRA
MCP -.复用同一组工具.-> Tools
Eval -.持续验证.-> Agent
style Cache fill:#fff8e1
style Guard fill:#ffebee
style RateLimit fill:#ffebee
style FA fill:#e8f5e9
style Eval fill:#f3e5f5
```
## Agent 状态机（LangGraph）
```mermaid
graph LR
START([START]) --> Planner
Planner -->|tool_calls| Executor
Planner -->|no tools| Synthesizer
Executor -->|< 2 rounds| Planner
Executor -->|≥ 2 rounds| Synthesizer
Synthesizer --> Reflector
Reflector -->|score ≥ 7| Finalize
Reflector -->|score < 7, retry < 1| Synthesizer
Reflector -->|retry exhausted| Finalize
Finalize --> END([END])
style Planner fill:#fff8e1
style Executor fill:#e8f4fd
style Synthesizer fill:#f5f5f5
style Reflector fill:#f3e5f5
style Finalize fill:#c8e6c9
```
---
## 关键交付指标
| 维度 | 数字 |
|---|---|
| **LoRA 微调** | Qwen3-1.7B QLoRA r=16，eval loss **4.85 → 1.30**（−73%），token 准确率 0.43→0.70 |
| **TimeXer backtest** | USD/GBP **MAE −10.23%** vs ARIMA（25 年 ECB + vol+mom+VIX+DXY） |
| **Agent 评测** | **30 题黄金集 pass 29/31=93.5%，LLM-as-Judge 平均 9.7/9.7/9.8（accuracy/faithfulness/helpfulness）** |
| **MCP Server** | 5 工具 + 1 resource，stdio + HTTP 双协议，3 PASS smoke test |
| **RAG 检索** | 30 篇策展语料 → 251 chunks，端到端检索 < 2s（含 reranker） |
| **数据规模** | 6 货币 × 25 年 = 7126 工作日，17,760 行汇率，900 行 SARIMAX 预测 |
| **代码规模** | ~189 文件 / 16 MB，覆盖 4 个工程方向（Web / Agent / 微调 / 时序） |
---
## 快速启动
> 假设已装 Python 3.12 + Node 16 + MySQL 8.x + 4 GB 显存的 GPU（CPU 也能跑，慢些）
### 1. 安装环境
```bash
conda create -n compass-fx python=3.12 -y
conda activate compass-fx
cd backend && pip install -r requirements.txt
```
### 2. 配置 `.env`
```bash
cd backend && cp .env.example .env
# 编辑 .env，至少填：
# MYSQL_PASSWORD = 你的 MySQL root 密码
# LLM_API_KEY = 在 https://platform.deepseek.com/ 申请（充值 ¥10 够用一个月）
```
### 3. 初始化数据 + 索引
```bash
cd backend
mysql -u root -p < scripts/init_db.sql # 建库 + 表
python scripts/refresh.py # 拉真实汇率 + 生成 SARIMAX 预测
python scripts/synthesize_corpus.py # （可选）合成 30 篇 RAG 语料
python scripts/rebuild_rag.py --rebuild # （可选）建向量库（需先下载 bge-m3）
```
### 4. 启动后端 + 前端
```bash
# 终端 1: 后端
python main.py
# 终端 2: 前端
cd frontend && npm install && npm run dev
# 浏览器 http://localhost:8081
```
### 5. （可选）接入 Claude Desktop / Cursor 的 MCP
参考 [`backend/mcp_server/README.md`](backend/mcp_server/README.md)，复制 [`claude_desktop_config.example.json`](backend/mcp_server/claude_desktop_config.example.json) 到 `%APPDATA%\Claude\claude_desktop_config.json`。
---
## 文档地图
每一个 phase 都有独立工程笔记 + 面试 Q&A：
| 阶段 | 文档 | 一句话总结 |
|---|---|---|
| 总览 | [docs/Phase3_总览.md](docs/Phase3_总览.md) | 5 个子阶段 + JD 覆盖矩阵 + 10 分钟 demo 路径 |
| 维护升级方案 | [docs/维护升级方案.md](docs/维护升级方案.md) | Phase 0-5 全规划（重启项目时的总图） |
| Phase 2 LoRA | [docs/Phase2_工程笔记.md](docs/Phase2_工程笔记.md) / [Phase2_完成报告.md](docs/Phase2_完成报告.md) | QLoRA 训练 + 自合成数据 + vLLM-style 部署 |
| Phase 2 三方对比 | [docs/LoRA_3way_comparison.md](docs/LoRA_3way_comparison.md) | DeepSeek vs Base Qwen3 vs LoRA 微调，8 题对比 |
| Phase 3.1+3.2 RAG | [docs/Phase3_RAG.md](docs/Phase3_RAG.md) | bge-m3 + reranker + ChromaDB + Agent 集成 |
| Phase 3.3 MCP | [docs/Phase3_3_MCP.md](docs/Phase3_3_MCP.md) | FastMCP + Cursor / Claude Desktop 接入 |
| Phase 3.4 Langfuse | [docs/Phase3_4_Langfuse.md](docs/Phase3_4_Langfuse.md) | 全链路 Trace + 优雅降级 |
| Phase 3.5 LangGraph | [docs/Phase3_5_LangGraph.md](docs/Phase3_5_LangGraph.md) | 多 Agent 状态机 + Reflector 反思 |
| **TimeXer backtest** | [docs/TimeXer_BacktestActuals.md](docs/TimeXer_BacktestActuals.md) | **8 个实验 + scaling experiment + 5 层面试 Q&A** |
| **Phase 4.1 缓存与并发** | [docs/Phase4_1_缓存与并发.md](docs/Phase4_1_缓存与并发.md) | **缓存层 + 连接池 + 限流，实测 ~6500× 提速** |
| **Phase 4.2 评测集** | [docs/Phase4_2_评测集.md](docs/Phase4_2_评测集.md) | **30 题 + LLM-as-Judge + 消融对照，pass 93.5% / judge 9.7** |
| **Phase 4.3 注入防御** | [docs/Phase4_3_注入防御.md](docs/Phase4_3_注入防御.md) | **5 层纵深防御 + 31 对抗样本，拦截率 96.8%** |
| **Phase 4.4 FastAPI 异步** | [docs/Phase4_4_FastAPI异步.md](docs/Phase4_4_FastAPI异步.md) | **ASGI parallel deploy + 实测 200 并发 2.81× QPS** |
---
## 切换 LLM Provider
只改 `.env` 4 行，无需改代码：
| Provider | LLM_BASE_URL | LLM_MODEL |
|---|---|---|
| **DeepSeek**（默认） | `https://api.deepseek.com/v1` | `deepseek-chat` |
| 阿里云百炼（Qwen） | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `qwen-plus` |
| 本地 Ollama | `http://127.0.0.1:11434/v1` | `qwen3:8b` |
| OpenAI | `https://api.openai.com/v1` | `gpt-4o-mini` |
| **本地 LoRA**（自训） | `http://127.0.0.1:8001/v1` | `qwen3-1.7b-finance` |
异构路由（Agent 走 DeepSeek，慧聚答疑走本地 LoRA）：分别填 `LLM_AGENT_*` 和 `LLM_CHAT_*`。
---
## 技术栈
```
后端 Flask 3.0 · MySQL 8 · OpenAI Python SDK · Langfuse 4.5
RAG ChromaDB · bge-m3 · bge-reranker-v2-m3 · transformers 5.6
Agent LangGraph 1.1 · LangChain Core 1.3 · DeepSeek tools API
MCP mcp 1.27 (FastMCP)
微调 PyTorch 2.6 + cu124 · peft 0.19 · trl 1.3 · bitsandbytes 0.49
时序 statsmodels 0.14 (SARIMAX) · TimeXer (清华原版)
前端 Vue 2.5 · ElementUI 2.15 · ECharts 5 · Webpack 3 · Marked + DOMPurify
观测 Langfuse cloud / self-hosted
```
## 路线图
```
Phase 0 ✅ Web 应用救火 + DeepSeek 对接 + 真实数据回填
Phase 2 ✅ LoRA Qwen3-1.7B 金融领域 SFT + FastAPI 推理服务
Phase 3.1 ✅ RAG 检索栈（bge-m3 + reranker + ChromaDB + 30 策展语料）
Phase 3.2 ✅ Function Calling Agent（5 工具 + 三层防御 + Trace 可视化）
Phase 3.3 ✅ MCP Server（暴露给 Cursor / Claude Desktop）
Phase 3.4 ✅ Langfuse 全链路 Trace
Phase 3.5 ✅ LangGraph 多 Agent + Reflector 反思纠错闭环
Phase 4.1 ✅ 缓存层（TTL/Redis 可切）+ 连接池 + 限流（QPS 5→50-100，缓存命中 ~6500× 提速）
Phase 4.2 ✅ 30 题黄金集 + LLM-as-Judge + 消融对照（pass 29/31=93.5%，judge 平均 9.7/10）
Phase 4.3 ✅ Prompt 注入 5 层纵深防御 + 31 对抗样本（拦截率 30/31=96.8%）
Phase 4.4 ✅ FastAPI ASGI parallel deployment（实测 50/100/200 并发下 QPS 提升 2.24×/2.61×/2.81×）
Phase 4.5 📅 vLLM 部署本地 LoRA
Phase 4.6 📅 Skill 打包 (forex-pulse.skill)
```
---
## 致谢
- Phase 0 重构基于 2025 年花旗杯（CompassFXPulse）参赛项目源码
- 原项目设计：花旗杯参赛队
- 重构、Agent / RAG / MCP / LoRA 改造、TimeXer 实验：[xzzzzc217](https://github.com/xzzzzc217)（东南大学网络空间安全 / 2027 届）
## License
MIT — see [LICENSE](LICENSE).
连接信息
猜你喜欢
暂无推荐服务器