Readme.md

# 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. 安装依赖

```bash
pip install -r requirements.txt
export MLFLOW_ALLOW_FILE_STORE=true   # mlflow 文件后端
```

### 2. 准备 Qlib 数据

**方式 A：官方样例（最快）**

```bash
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**

```bash
# 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 官方脚本](https://github.com/microsoft/qlib/blob/main/scripts/dump_bin.py)，支持 `dump_all` / `dump_update` 增量更新。

### 策略回测（核心 — 因子接入 + 多策略）

**前提**：已有挖掘好的因子（GP parquet、QuantaAlpha JSON、pred.pkl 均可），无需在本项目里再跑挖掘。

```bash
# 列出所有内置策略
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）：

```bash
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

```bash
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（官方风格对照组）**

```bash
python scripts/run_qrun.py --config config/workflows/workflow_alpha158_baseline.yaml
```

**GP 因子 + LightGBM**

```bash
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. 生成研究报告

```bash
# 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. 一键全流程

```bash
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 因子库配置 |

环境变量：

```bash
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 因子研究桥接。

```bash
# 一键启动后端 + 前端，并加载 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 策略 |

## 面试亮点

1. **因子与策略解耦**：挖掘在外部完成，本项目专注因子接入 + 策略回测
2. **可插拔策略框架**：6+ 内置策略 + YAML 注册表 + 策略套件对比
3. **QuantaAlpha LLM 集成**：OpenAI 兼容 API 自动选因子、选策略、跑回测
4. **Qlib 原生回测**：SimulatorExecutor + Exchange 完整仿真
5. **配置驱动**：`settings.py` + YAML + 环境变量

## QuantaAlpha 集成

[QuantaAlpha](https://github.com/QuantaAlpha/QuantaAlpha) 因子库 JSON 可直接接入：

```bash
# 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/
```