ml-quant-trading

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

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 / 复现报告。真实反馈比单纯的数字更有价值。

关键文档

引用

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

@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。

initial-d/ml-quant-trading

实测星标增长

关于

README.zh-CN.md