多因子量化研究栈 initial-d/ml-quant-trading

ml-quant-trading

Languages: English | 简体中文 | 繁體中文

机器学习增强的多因子量化交易——采用偏差修正的横截面投资组合优化方法。

arXiv:2507.07107 |
Hugging Face Papers | Yimin Du，2025

先跑起来

python -m pip install mlquantx
mlquant demo

无需行情账号或 API Key。30–90 秒内，Demo 会依次运行 数据 → 因子 → 模型 → 组合 → 回测，并在 artifacts/small/ 生成可分享的 Markdown/JSON 报告。

旧版本用户：先运行 python -m pip install --upgrade mlquantx。
v0.4.1
将涨跌停观测在滚动因子计算前屏蔽，并从最近可交易收盘价计算跨停牌收益； v0.4.0 已将 Demo 评估改为按时间留出的样本外区间。公开数据加载器需要 python -m pip install --upgrade 'mlquantx[data]'；旧版 A 股或含停牌报告需要重跑。
这些是工程正确性改进，不是新增收益证据。

Demo 跑通后，可以继续查看 benchmark或提交一次复现报告。
如果这个基线对你有用，点个 Star 也能帮助其他研究者找到它。

| 213 个因子 | 4 条数据路径 | 100+ 个测试 | 可复现 benchmark |
| Mask-aware PyTorch 张量 | Synthetic、AkShare、Baostock、yfinance | 确定性工程检查 | 查看完整基准 |

这是一个面向研究和教学的工程参考实现，不是实盘交易系统，也不构成投资建议。

ml-quant-trading 项目预览

Colab 在线运行
· 查看公开验证结果
· 审计六项管线不变量
· 量化 Jev 决策面
· 体验数据集与模型
· 阅读论文
· 提交一次复现报告

参与复现：打开零行情账号 Colab 跑一次，把自动生成的报告、运行环境和 commit SHA 填入结构化报告表单。
成功和失败结果都欢迎；Agent、DSH 和脱敏私有评估可参加当前的 Agent Quant Benchmark Challenge。

项目概述

ml-quant-trading 是一个简洁、便于 fork 的端到端 A 股量化研究系统。仓库集成了张量因子引擎、213 维因子库、偏差修正、ML baseline、Markowitz 投资组合优化、向量化回测、synthetic 与公开数据演示，以及 CI、测试与 benchmark 工具，适合复现和扩展多因子量化研究。

v0.3.1 还新增了 System-One/Jev-style portfolio decision surface：不是把外部模型塞进策略 pipeline，而是把 pipeline 产出的因子、预测、mask、持仓、流动性、风险和成本封装成结构化 state，再回答 asset_action、target_weight、trade_allowed、risk_bucket 等 typed questions。它输出研究型 portfolio intent，不做券商、订单、账户或实盘执行。

快速入口

| 你的目标 | 从这里开始 | 能得到什么 |
| 先看项目能否跑通 | mlquant demo | 30–90 秒、无需行情数据的端到端冒烟测试 |
| 不安装直接体验 | Google Colab | 无需账号或行情 API 的浏览器内完整 Demo |
| 使用量化 Jev-style 决策接口 | System-One Adapter · 中文长文 | 从 pipeline artifacts 生成 decision state，并输出可评估的 portfolio intent |
| 审计实现语义 | 六项可复现管线不变量 | 确定性检查因子、mask、标签边界、执行时序与成本计算 |
| 检查可下载产物 | Hugging Face 数据集 · MLP 模型 | 由确定性 Quick Start 导出的 10 万行 synthetic 数据和 213 输入模型；不含真实或专有行情 |
| 查看真实公开数据结果 | CSI 300 验证看板 | 成本敏感性、换手率、基线与复现命令 |
| 理解研究结论边界 | Research Card | 适用范围、非目标、数据假设与已知限制 |
| 贡献一次运行结果 | 复现报告表单 | 跑 Colab、结构化提交报告并获得 README 署名 |

归档公开验证（2026-07-29）

以下数字生成于 v0.4.1 修复前，尚未用修正后的 mask-first 与停牌收益口径重新验证。 保留原始报告便于审计；不能把这些数字当作当前版本的验证结果。
10 月 17 日审计还发现 v0.4.1 及之前的公开验证用次日可用性决定当天选股，重跑也需要包含该修复。

归档结果采用 AkShare 的当前沪深 300 公开数据，在日频 213 因子近似流程中显式计入换手和交易成本。缓冲因子组合在 7 bps 有效成本假设下得到 22.20% 年化收益、0.919 Sharpe；同区间等权基线为 17.75% 和 0.882。完整口径、成本敏感性图和复现命令见验证看板。

这些结果是公开数据上的研究近似，不是论文的精确复现，不代表样本外收益，也不构成投资建议。

社区验证与贡献

| 外部贡献 | 内容 |
| PR #18 | ETF 跨资产公开数据复现 |
| PR #34 | Windows/Baostock 25 只 A 股验证 |
| PR #35 | 中性化与 Baostock 稳健性修复 |
| PR #36 | 全因子族英文手册 |
| PR #42 | 支撑 CSI 300 验证的零账号 AkShare 加载器 |
| PR #47 | 澄清累计交易成本的时间口径，并补充兼容层、测试和文档 |

这些结果链接到原始 PR，便于检查环境、命令、限制和评审过程。你也可以 打开零账号 Colab，运行并提交生成的报告。
运行结果请用结构化复现报告表单提交；Agent、DSH 和脱敏私有评估请参阅 Agent Quant Benchmark Challenge。

研究与教学用途声明

仅用于研究和教学。 本项目不构成金融或投资建议，也不是可直接用于实盘交易的生产系统。回测结果不代表真实交易表现，并会受到数据质量、交易成本、滑点及建模假设等因素影响。所有结果都应视为研究验证，而非已经证实的样本外收益或可部署 alpha。已知限制请参阅 Reality Check。

核心模块

| 模块 | 功能 |
| features.tensor_factors | 带 mask 的 GPU 向量化基础算子（rank、corr、ewma、ts_*） |
| features.legacy_factors | 204 个手工构建的 alpha 因子（参阅因子手册） |
| features.alpha101 | Alpha101 风格的公式化因子 |
| features.neutralize | 横截面与行业中性化 |
| features.bias | 涨停、跌停与停牌偏差修正 |
| training.augment | GBM 数据增强 |
| models.nets | MLP / Transformer |
| models.losses | AdjMSE、IC、RankIC loss |
| portfolio.markowitz | 横截面 Markowitz 优化（收缩协方差、禁止卖空） |
| backtest.engine | 向量化回测，输出 Sharpe / IC / IR / DD 等指标 |
| systemone | System-One/Jev-style typed portfolio decision adapter |

因子库共包含 213 个因子：9 个精选 Alpha101 公式和 204 个手工构建的 legacy 因子。完整说明请参阅因子手册。

数据源

| 数据源 | 市场 | 访问方式 | 说明 |
| AkShare | A 股 | 公开、无需 API Key | 零鉴权加载器；上游接口可能变化或限流 |
| Baostock | A 股 | 免费注册 | 项目支持的 A 股数据加载器，需要账号 |
| yfinance | 美股 / ETF | 公开访问，有速率限制 | 用于公开数据验证和跨市场示例 |
| Synthetic | 不适用 | 零配置 | 使用固定 seed 确定性生成的 GBM panel，用于 pipeline 冒烟测试 |

本仓库不重新分发市场数据。AkShare、Baostock 与 yfinance 数据由加载脚本按需下载；Synthetic 数据则根据固定 seed 确定性生成。

源码安装与开发

python -m pip install mlquantx

一条命令跑通（Synthetic 数据，无需 API Key） mlquant demo

命令会显示每个运行阶段，并在 artifacts/small/ 中生成便于分享的 summary.md 与 summary.json，同时保留模型和回测产物。该 Demo 是确定性的工程冒烟测试，不是收益展示。

准备修改因子、模型、数据源或回测假设时，请切换到源码模式：

git clone https://github.com/initial-d/ml-quant-trading.git
cd ml-quant-trading
python -m pip install -e '.[dev]'

如需 CUDA 或 MOSEK，可在开发依赖中分别添加 gpu 或 mosek extra。

公开数据验证（可选）

轻量示例请打开 notebooks/public_factor_ic.ipynb。如需运行规模更大的 yfinance walk-forward 验证：

python scripts/public_data_validation.py \
--source yfinance \
--preset us-large-100 \
--max-tickers 100

运行方式和输出说明请参阅 Public-Data Validation。这些结果仅用于验证诊断，不是交易建议。

Portfolio Decision / 量化 Jev-style 接口

如果已经跑过 mlquant demo，可以把本地 artifacts 转成 decision state，再生成结构化 portfolio intent：

mlquant systemone build-state \
--artifacts-dir artifacts/small \
--as-of-index -2 \
--output artifacts/systemone/decision_state.json

mlquant systemone decide \
--state artifacts/systemone/decision_state.json \
--output artifacts/systemone/portfolio_decision.json

这条路径的定位是：

pipeline state + typed portfolio questions -> typed portfolio-intent answers

完整 state/question/output contract 见 System-One Adapter。中文解释见量化 Jev 不一定要接入模型：把多因子 Pipeline 封装成 Portfolio Decision Surface。

为什么值得 Star 或 Fork？

- 你需要一套能运行的 ML 多因子研究参考实现，而不是只有截图的策略介绍。
- 你希望直接复用带 mask 的 PyTorch 因子引擎、213 维因子库和 A 股涨跌停/停牌处理。
- 你想在公开数据、交易成本和基线对照下复现或挑战论文结论。
- 你正在寻找一个可扩展的数据 → 因子 → 模型 → 组合 → 回测工程模板。

如果这个仓库帮你节省了搭建研究管线的时间，欢迎点 Star、引用论文，或提交一份 benchmark / 复现报告。真实反馈比单纯的数字更有价值。

关键文档

- 英文 README
- CSI 300 公开验证看板
- AkShare CSI 300 日频 213 因子报告
- 中文技术长文：213 因子与含成本验证
- 中文技术长文：可信 Sharpe 之前的六项管线不变量
- 中文技术长文：量化 Jev-style Portfolio Decision Surface
- System-One Adapter 文档
- 维护者发布与推广材料
- Reality Check and Validation Status
- Public-Data Validation
- Public-Data Mini Reproduction
- Architecture Overview
- Factor Handbook（因子手册）
- FAQ
- Contributing Guide

引用

如果本项目对你的研究有帮助，请引用：

@article{du2025mlquant,
title = {Machine Learning Enhanced Multi-Factor Quantitative Trading:
A Cross-Sectional Portfolio Optimization Approach with Bias Correction},
author = {Du, Yimin},
journal= {arXiv preprint arXiv:2507.07107},
year = {2025},
url = {https://arxiv.org/abs/2507.07107}
}

License

本项目采用 MIT License，详见 LICENSE。