ML-Alpha-Research-System
基于 Qlib 的量化研究系统：因子接入（GP / QuantaAlpha / 自定义面板）+ 可插拔策略框架 + Qlib 原生实验 + 研究报告。
架构
已挖掘因子 (GP/QuantaAlpha/Parquet) 策略层 回测 & 报告
───────────────────────────────── ────────── ─────────────
factor_panel / JSON library ──► 6+ 内置策略 (TopK/多空/加权...) ──► qlib SimulatorExecutor
QuantaAlpha API + LLM ──► LLM 策略规划 (选因子+选策略) ──► outputs/backtest/
qlib expression / pred.pkl ──► 策略套件对比 (suite)
与你之前版本的关系
| 旧脚本 | 问题 | 新方案 |
|---|---|---|
factor_engine/legacy/3.因子挖掘.py |
硬编码 parquet 路径 | QlibTensorDataEngine + config/settings.py |
factor_engine/legacy/因子挖掘2.0.py |
相关性惩罚、分块读取 | 合并到 factor_engine/gp/fitness.py |
factor_engine/legacy/因子挖掘06_17.py |
严格防重复 | 合并到 factor_engine/gp/ |
scripts/run_model_train.py |
自定义 LightGBM，非 qlib 实验 | scripts/run_qrun.py + workflow YAML |
| 无 bin 转换 | 无法接入自建数据 | data_pipeline/convert_to_qlib_bin.py + scripts/dump_bin.py |
快速开始
1. 安装依赖
pip install -r requirements.txt
export MLFLOW_ALLOW_FILE_STORE=true # mlflow 文件后端
2. 准备 Qlib 数据
方式 A：官方样例（最快）
python -m qlib.cli.data qlib_data --target_dir data/qlib_data/cn_data --region cn
官方样例覆盖约 2000-01-04 ~ 2020-09-25。
config/base.yaml切分已对齐。
方式 B：自建 Parquet/CSV → qlib .bin
# 1) 把你的 parquet 列名映射写在 config/base.yaml dump.column_aliases
# 2) 转换并 dump
python data_pipeline/convert_to_qlib_bin.py --parquet /path/to/your_data.parquet
# 或仅对已有 per-symbol CSV 目录 dump
python data_pipeline/convert_to_qlib_bin.py
dump_bin.py 来自 qlib 官方脚本，支持 dump_all / dump_update 增量更新。
策略回测（核心 — 因子接入 + 多策略）
前提：已有挖掘好的因子（GP parquet、QuantaAlpha JSON、pred.pkl 均可），无需在本项目里再跑挖掘。
# 列出所有内置策略
python scripts/run_backtest.py --list-strategies
# 单策略：GP 因子面板 → TopK Dropout
python scripts/run_backtest.py \
--strategy topk_dropout \
--signal-path outputs/gp_mining/qlib_gp_run_0/ML_Features_qlib.parquet \
--start 2019-04-01 --end 2020-09-24
# 策略套件对比（一次跑 4 个策略）
python scripts/run_backtest.py \
--suite long_only_core \
--signal-source gp_panel
# QuantaAlpha 因子库 JSON → IC 加权合成信号
python scripts/run_backtest.py \
--strategy score_weighted_topk \
--signal-source quantaalpha_library
内置策略（config/strategies.yaml）：
| 策略 | 说明 |
|---|---|
topk_dropout |
Qlib TopK 逐步换仓（默认基线） |
long_short_quantile |
多空分位组合 |
score_weighted_topk |
Softmax 分数加权 TopK |
rank_weighted |
排名衰减加权 |
dynamic_risk_topk |
动态风险预算 TopK |
enhanced_indexing |
增强指数化（需 risk model） |
QuantaAlpha LLM 策略（OpenAI 兼容 API）：
export OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=https://your-provider/v1
export CHAT_MODEL=deepseek-v3
# LLM 自动选因子 + 选策略 + 回测
python scripts/run_llm_strategy.py \
--library data/factors/all_factors_library.json
# 仅生成 LLM 策略计划（不回测）
python scripts/run_llm_strategy.py --factor-panel outputs/gp_mining/.../ML_Features_qlib.parquet --dry-run
配置见 config/quantaalpha.yaml。
列出已注册因子
python scripts/run_factor.py list
计算单个因子（qlib 自动算）
python scripts/run_factor.py compute --name momentum_5d
计算全部 enabled 因子
python scripts/run_factor.py compute --all
单因子 IC 分析
python scripts/run_factor.py analyze --name momentum_5d --segment test
单因子回测（IC + TopK 策略）
python scripts/run_factor.py backtest --name momentum_5d
批量单因子回测
python scripts/run_factor.py backtest --all
命令行追加新因子到 config/factor_registry.yaml
python scripts/run_factor.py add
--name my_alpha
--expression "Rank($close) - Rank($volume)"
--description "价量排名差"
多因子合并面板 → 策略回测
python scripts/run_factor.py export-panel python scripts/run_backtest.py --signal-source registry_all --strategy topk_dropout
因子公式记录在 **`config/factor_registry.yaml`**，想到新因子直接加进去即可。
### 3. GP 因子挖掘（可选）
```bash
python scripts/run_gp_mining.py
# 或自定义参数
RUN_ID=my_run POPULATION_SIZE=200 GENERATIONS_PER_RUN=20 python scripts/run_gp_mining.py
输出：outputs/gp_mining/<RUN_ID>/
factor_zoo.csv/top_factors.csv— 候选因子库ML_Features_qlib.parquet— GP 特征矩阵factor_formulas.csv— 因子公式
4. 导出 GP → Qlib DatasetH
python scripts/build_gp_dataset.py --run-id my_run
生成：
gp_qlib_handler.pkl— 供 workflow 加载gp_qlib_dataset.pkl— DatasetH 快照gp_qlib_features.parquet— 特征面板
5. 运行 Qlib 实验（核心）
Alpha158 Baseline（官方风格对照组）
python scripts/run_qrun.py --config config/workflows/workflow_alpha158_baseline.yaml
GP 因子 + LightGBM
python scripts/run_qrun.py \
--config config/workflows/workflow_gp_lightgbm.yaml \
--run-id my_run
实验产物写入 mlruns/，包含：
pred.pkl/label.pkl— 预测与标签sig_analysis.pkl— IC / Rank IC 分析report_normal_1day.pkl— 回测绩效port_analysis_1day.pkl— 组合分析
6. 生成研究报告
# GP 因子诊断（ICIR 排名、相关性热力图、进化曲线）
python scripts/generate_report.py --run-id my_run
# 含 qlib 实验结果（需 recorder id）
python scripts/generate_report.py \
--run-id my_run \
--experiment-name ml_alpha_gp \
--recorder-id <RECORDER_ID>
报告输出：outputs/reports/，包含 IC 时序、IC 分布、分位数收益、累计收益/回撤、因子相关性热力图、GP 进化曲线等。
7. 一键全流程
python scripts/run_full_pipeline.py --run-id my_run
# 从 parquet 开始（含 bin dump）
python scripts/run_full_pipeline.py --run-id my_run --parquet /path/to/data.parquet
# 仅跑 baseline 对照
python scripts/run_full_pipeline.py --baseline-only
配置体系（不再硬编码）
| 文件 | 用途 |
|---|---|
config/base.yaml |
Qlib 路径、时间切分、dump 映射、回测参数、实验 URI |
config/gp_mining.yaml |
GP 种群/代数/惩罚参数 |
config/settings.py |
统一加载 YAML + 环境变量覆盖 |
config/factor_registry.yaml |
你的因子公式库（qlib expression，自动计算/单因子回测） |
config/strategies.yaml |
策略注册表、预设套件、信号源模板 |
config/quantaalpha.yaml |
LLM API / QuantaAlpha 因子库配置 |
环境变量：
QLIB_PROVIDER_URI=data/qlib_data/cn_data
QLIB_MARKET=csi300
RUN_ID=my_experiment
POPULATION_SIZE=300
GENERATIONS_PER_RUN=50
MLFLOW_ALLOW_FILE_STORE=true
Web 可视化平台 (web_development/)
期货仿真交易 UI + 按功能模块在线启动 + Qlib 因子研究桥接。
# 一键启动后端 + 前端，并加载 Qlib 研究模块
python scripts/launch_platform.py --enable-research
# 或分别启动
cd web_development/backend && uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
cd web_development/frontend && npm install && npm run dev
| 页面 | 路径 | 说明 |
|---|---|---|
| 服务控制台 | /services |
按模块启动/停止：行情、期货策略、Qlib 研究、前端 |
| 因子研究 | /research |
查看因子注册表、算子库、A 股策略列表 |
| 仪表盘/交易 | /, /trading 等 |
期货仿真（wenjie 原功能） |
API 桥接：/api/platform/*（模块控制）、/api/research/*（因子/策略研究）。
核心模块
| 模块 | 说明 |
|---|---|
config/settings.py |
集中配置，路径/ RUN_ID 从 env 读取 |
data_pipeline/convert_to_qlib_bin.py |
Parquet → per-symbol CSV → .bin |
scripts/dump_bin.py |
qlib 官方 bin dump 工具 |
data_pipeline/gp_dataset_builder.py |
GP 特征 → StaticDataLoader → DataHandlerLP |
factor_engine/gp/ |
GP 算子、适应度、进化、QlibTensorDataEngine |
factor_engine/gp_handler.py |
GPFactorHandler（workflow YAML 加载 pickle） |
experiments/workflow_runner.py |
task_train + Recorder 封装 |
scripts/run_qrun.py |
实验入口 |
reports/analysis.py |
IC/回测/因子/GP 可视化 |
factor_engine/formula_registry.py |
因子公式注册表：加载/计算/缓存/合并 |
scripts/run_factor.py |
因子公式 CLI（compute/analyze/backtest/add） |
strategies/ |
策略注册表、内置策略、统一回测 runner |
integrations/quantaalpha/ |
LLM client、因子库解析、LLM 策略规划 |
data_pipeline/factor_loader.py |
统一因子/信号加载（GP/QuantaAlpha/qlib expr） |
scripts/run_backtest.py |
策略回测 CLI |
scripts/run_llm_strategy.py |
QuantaAlpha LLM 策略 |
面试亮点
- 因子与策略解耦：挖掘在外部完成，本项目专注因子接入 + 策略回测
- 可插拔策略框架：6+ 内置策略 + YAML 注册表 + 策略套件对比
- QuantaAlpha LLM 集成：OpenAI 兼容 API 自动选因子、选策略、跑回测
- Qlib 原生回测：SimulatorExecutor + Exchange 完整仿真
- 配置驱动：
settings.py+ YAML + 环境变量
QuantaAlpha 集成
QuantaAlpha 因子库 JSON 可直接接入：
# 1. 把 QuantaAlpha 产出的 all_factors_library*.json 放到 data/factors/
# 2. 配置 OPENAI_API_KEY（LLM 策略模式）或直接 IC 加权合成信号
python scripts/run_backtest.py --signal-source quantaalpha_library --strategy topk_dropout
目录结构
ML-Alpha-Research-System/
├── config/
│ ├── base.yaml
│ ├── gp_mining.yaml
│ ├── settings.py
│ └── workflows/ # qlib 实验 YAML
├── data_pipeline/
│ ├── convert_to_qlib_bin.py
│ └── gp_dataset_builder.py
├── experiments/
│ └── workflow_runner.py
├── factor_engine/
│ ├── gp/ # GP 因子挖掘
│ ├── gp_handler.py # Qlib handler
│ └── legacy/ # 原始脚本
├── strategies/ # 策略框架
│ ├── registry.py
│ ├── runner.py
│ └── builtins/
├── integrations/
│ └── quantaalpha/ # LLM API + 因子库
├── scripts/
│ ├── run_backtest.py # 策略回测
│ ├── run_llm_strategy.py # LLM 策略
│ ├── run_qrun.py # qlib 实验
│ ├── run_full_pipeline.py
│ └── launch_platform.py # Web 平台一键启动
├── web_development/ # 期货 UI + 服务控制台 + 研究桥接
│ ├── backend/ # FastAPI + platform/research API
│ └── frontend/ # Vue3 仪表盘 / 服务控制台 / 因子研究
├── reports/
│ └── analysis.py
├── mlruns/
└── outputs/
├── backtest/
├── gp_mining/
└── reports/