Quant Agent V7.0 - ETF 量化投资多智能体框架

🚀 基于 LangGraph 的多智能体协作量化投资系统

---

📋 系统现状总览

✅ 已验证可用的功能

功能模块	状态	入口文件	说明
ETF 投资顾问	✅ 可用	run_etf_advisor.py	LLM 对话式配置 + 策略回测
多智能体工作流	✅ 可用	run_agent_workflow.py	LangGraph 流水线 (DataFusion→Factor→Debate→Risk→Execution)
策略回测	✅ 可用	run_etf_backtest.py	独立回测脚本，支持多种风险指标
LLM 对话	✅ 可用	DeepSeek API	投资需求收集、策略辩论
ClickHouse 数据	✅ 可用	ETF 日频数据库	需内网访问，数据从 2025-03 开始
模拟数据模式	✅ 可用	--demo 参数	无需数据库也能运行

⚠️ 需要条件才能使用的功能

功能模块	条件	说明
真实 ETF 数据	需要 ClickHouse 内网访问	数据库 10.13.66.5:20108
TradeMemory 向量存储	需要 Qdrant 运行	可选，关闭不影响主流程
Prometheus 监控	需要开启端口 9090	可选功能
Guardrails-AI 校验	需安装 guardrails-ai	已有 fallback，可选

❌ 暂不可用/受限的功能

功能模块	原因	备注
yfinance 美股数据	频繁被限流	短期内多次调用会触发 RateLimit
实盘交易	broker 仅支持 mock	需要自行对接券商 API
历史回测（2025年前）	数据库数据从2025-03开始	旧日期自动回退模拟数据

---

🚀 快速开始

1. 环境准备

# 创建 conda 环境
conda create -n agent1205 python=3.12
conda activate agent1205

# 安装依赖
pip install -r requirements.txt

# 必需的额外依赖
pip install langchain-openai yfinance scipy tushare

2. 配置 API Keys

编辑 quant_agent/.env：

# LLM API (必需)
DEEPSEEK_API_KEY=sk-your-key        # 主力推理模型
ARK_API_KEY=your-key                # 豆包/火山引擎（可选）
DASHSCOPE_API_KEY=your-key          # 千问（可选 fallback）
OPENROUTER_API_KEY=your-key         # 国际模型代理（可选）

# 数据库 (可选，使用 --demo 可跳过)
DB_HOST_Server=0.0.0.0
DB_POST_Server=9000
DB_USER_Server=etf
DB_PASSWORD_Server=your-db-password-here

3. 运行示例

# 最简单：全自动模式 + 模拟数据
python run_etf_advisor.py --auto --demo

# 指定日期和风险等级
python run_etf_advisor.py --auto --start 2024-06-01 --end 2024-12-01 --risk moderate

# LLM 对话式配置
python run_etf_advisor.py

# 多智能体工作流（LangGraph）
python run_agent_workflow.py --mode quick --tickers AAPL,MSFT
python run_agent_workflow.py --mode standard --tickers 510300.SS,159915.SZ

# ETF 选基 LangGraph 版本（完整继承主线能力）
python run_etf_agent_workflow_v2.py --mode standard --start 2024-01-01 --end 2024-06-01

---

🏗️ 系统架构

三条使用路径

┌─────────────────────────────────────────────────────────────────┐
│                      路径 1: ETF 投资顾问                        │
│                     (run_etf_advisor.py)                        │
├─────────────────────────────────────────────────────────────────┤
│  LLM 对话 → 配置生成 → ETFResearcher → Backtester → 报告       │
│     ↓           ↓            ↓             ↓           ↓        │
│  DeepSeek   参数映射    情绪因子选基    净值曲线    回测指标    │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                   路径 2: 多智能体工作流                         │
│                   (run_agent_workflow.py)                       │
├─────────────────────────────────────────────────────────────────┤
│  DataFusion → FactorCompute → StrategyDebate → RiskGuard → Exec │
│      ↓            ↓               ↓              ↓          ↓   │
│  数据清洗     因子计算        LLM多角色辩论    风控校验    模拟执行│
│  (yfinance/   (RSI/MACD/      (Bull/Bear/      (VaR/        (Mock│
│   ClickHouse)  Momentum)        Judge)         Exposure)   Broker)│
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│             路径 3: ETF 选基 LangGraph 版 (NEW!)                 │
│             (run_etf_agent_workflow_v2.py)                      │
├─────────────────────────────────────────────────────────────────┤
│  ETFDataFusion → [data_quality_router] → ETFSentiment           │
│       ↓                                        ↓                │
│  ETF数据加载    质量路由/回退          情绪+舆情分析            │
│       ↓                                        ↓                │
│  ETFSelection → FactorCompute → StrategyDebate → RiskGuard      │
│       ↓              ↓              ↓              ↓            │
│  因子选基       因子计算      多角色辩论     风控+幻觉检测       │
│                                                    ↓            │
│                 [risk_router] → StressTest → Execution          │
│                      ↓              ↓            ↓              │
│                 重试/结束      压力测试    模拟执行+熔断         │
│                                                    ↓            │
│                          ETFFinalDecision → PostTrade → END     │
└─────────────────────────────────────────────────────────────────┘

特性: 条件路由 | 自动重试 | 压力测试 | 检查点 | Prometheus | 熔断

Agent 工作流模式

模式	说明	LLM 调用	适用场景
quick	最小化 LLM	仅 Bull/Bear	快速测试
standard	标准流程	Bull/Bear/Judge	日常使用
deep	完整流程	全部角色 + 反思	重要决策

---

📊 核心功能详解

ETF 情绪因子选基策略

因子	权重	说明
动量因子	35%	近期收益率趋势
成交量因子	25%	量价配合程度
溢折价因子	20%	ETF 折溢价率
波动率因子	20%	波动率变化趋势

风险等级参数

风险等级	theta	最大回撤	持仓数	适合人群
保守型	0.3	8%	15只	追求稳健
稳健型	0.5	15%	10只	平衡收益与风险
激进型	0.7	25%	5只	追求高收益

回测指标

• 收益: 总收益率、年化收益率、超额收益
• 风险: 年化波动率、最大回撤、VaR
• 风险调整: 夏普比率、索提诺比率、卡玛比率、信息比率
• 交易: 换手率、胜率、盈亏比

---

📁 项目结构

Quantitative Investment Agent Framework V7.0/
├── run_etf_advisor.py       # 🚀 ETF 投资顾问入口
├── run_agent_workflow.py    # 🚀 多智能体工作流入口
├── run_etf_backtest.py      # 📊 独立回测脚本
│
├── quant_agent/
│   ├── .env                 # API Keys 配置
│   ├── config.yaml          # 系统配置
│   │
│   ├── core/
│   │   ├── investment_advisor.py  # LLM 对话式顾问
│   │   ├── config.py              # Pydantic 配置
│   │   ├── llm_factory.py         # 统一 LLM 工厂（6种模型）
│   │   └── models.py              # 数据模型
│   │
│   ├── agents/
│   │   ├── data_fusion/           # 数据融合 Agent
│   │   ├── factor_compute/        # 因子计算 Agent
│   │   ├── strategy_debate/       # 策略辩论 Agent（多角色）
│   │   ├── risk_guard/            # 风险控制 Agent
│   │   ├── execution/             # 执行 Agent
│   │   └── etf_selection/         # ETF 选基 Agent
│   │
│   ├── researchers/
│   │   ├── etf_researcher.py      # ETF 研究员（情绪因子）
│   │   └── backtest.py            # 回测引擎
│   │
│   ├── workflows/
│   │   ├── main_graph.py          # LangGraph 工作流定义
│   │   ├── routers.py             # 条件路由
│   │   ├── modes/                 # quick/standard/deep 配置
│   │   └── nodes/                 # 重试/压测节点
│   │
│   └── infra/
│       ├── logging_conf.py        # 日志配置
│       ├── monitoring/            # Prometheus 监控
│       └── vector_store/          # TradeMemory 向量存储
│
├── output/                   # 回测图表输出
└── tests/                    # 单元测试

---

🔧 配置说明

LLM 模型分工

# quant_agent/core/llm_factory.py 中定义的角色分配
AGENT_LLM_MAPPING = {
    "bull": "doubao",        # 豆包 - 多头论点撰写
    "bear": "doubao",        # 豆包 - 空头论点撰写
    "judge": "deepseek",     # DeepSeek - 逻辑推理判断
    "macro": "gemini-flash", # Gemini - 宏观分析
    "risk_guard": "deepseek",# DeepSeek - 风控推理
}

配置优先级

环境变量 > .env 文件 > config.yaml > 默认值

---

🧪 测试

# 运行单元测试
pytest tests/unit/ -v

# 测试 LLM 连接
python test_llm_integration.py

---

📝 常见问题

Q: yfinance 报错 "Rate limited"?

A: Yahoo Finance 有请求频率限制。等待几分钟后重试，或使用 --demo 模式。

Q: LLM 对话失败?

A: 检查 quant_agent/.env 中的 DEEPSEEK_API_KEY 是否正确配置。

Q: 数据库连接失败?

A: 需要内网访问。使用 --demo 模式可跳过数据库依赖。

Q: TradeMemory 初始化失败?

A: 这是可选功能，需要运行 Qdrant 向量数据库。不影响主流程运行。

Q: 回测历史日期数据不足?

A: 数据库从 2025-03-10 开始。旧日期会优先尝试 TuShare（需 TUSHARE_API_KEY），再不行回退到模拟数据。

---

🔮 开发计划

• 接入更多券商 API（实盘交易）
• 补充历史 ETF 数据
• Web UI 界面
• 定时任务调度
• 多因子组合优化

---

📄 许可证

MIT License

---

Made with ❤️ for Quantitative Investment | 更新于 2024-12-07