如何端到端运行 machine-learning-for-trading 的 ETF 案例研究流水线

如何端到端运行 machine-learning-for-trading 的 ETF 案例研究流水线

【免费下载链接】machine-learning-for-tradingCode for Machine Learning for Trading, 3rd edition — from data sourcing to live execution.项目地址: https://gitcode.com/GitHub_Trending/ma/machine-learning-for-trading

这篇文章面向想要完整跑通 machine-learning-for-trading（ML4T，第 3 版）仓库中 ETF 案例研究的读者。案例研究对 100 只跨资产 ETF（股票、固收、商品、货币、房地产，9 个类别，2006–2025 年日线数据）执行一条 20 个阶段的流水线：从可行性分析、标签与特征工程，到 6 个模型家族的训练、回测、组合构建、成本与风险叠加，最后落到 holdout 验证与策略综合。目标结果是：每个阶段的产物（labels/、features/、run_log/下的训练与回测工件）按顺序落盘，最终在run_log/registry.db中得到完整的运行记录，并产出策略综合结果。

流水线各阶段与产出的对应关系见 case_studies/etfs/README.md 的 Pipeline 表，下面先列出你运行完成后应该能在案例研究目录里看到的东西，后面按顺序给出操作。

一、准备环境

两条路径任选其一，所有命令都在仓库根目录（git clone产生的文件夹）下执行：

• Docker（官方推荐）：拉取预构建镜像，跨平台环境一致，覆盖全部 27 章和 9 个案例研究。
• 本地 uv：uv sync安装约 300 个包（约 11 GB）。有 12 个包需要从源码编译，因此必须先装好 C/C++ 编译器和 Python 头文件（例如 Ubuntu/WSL2 下sudo apt install build-essential python3-dev），否则会停在error: command 'c++' failed。macOS 还需brew install libomp。本地路径要求 Python 3.14+，Windows 下必须在 WSL2 Ubuntu 终端里操作。

# 克隆仓库并复制环境模板（默认值即可使用，无需编辑） git clone https://github.com/stefan-jansen/machine-learning-for-trading.git cd machine-learning-for-trading cp .env.example .env # Docker 路径：拉取镜像（x86 约 12 GB，ARM64 约 3 GB） docker compose pull ml4t # 本地 uv 路径：安装依赖 uv sync

安装完成后的必做验证——两个路径各有一条 PASS/FAIL 检查命令，确认所有必需库可导入、运行时接线正确：

# Docker docker compose run --rm ml4t python scripts/verify_installation.py # 本地 uv uv run python scripts/verify_installation.py

每一行组件输出PASS/FAIL，全部 PASS 再继续。详细平台步骤（Windows WSL2、macOS Intel/Apple Silicon、GPU）见 docs/installation.md。

二、下载 ETF 数据

案例研究的数据集是 ETF 日线行情，来源 Yahoo Finance，免费、无需 API key。从仓库根目录运行：

# 本地 uv 路径 uv run python data/etfs/market/download.py # 文档估算约 30 秒 # Docker 路径：在 Jupyter Lab 终端（File → New → Terminal）或宿主机终端去掉 uv run 前缀 python data/etfs/market/download.py

如果某个阶段报DataNotFoundError，异常信息本身会带上该数据集对应的下载命令，从仓库根目录执行即可。数据指南见 data/README.md。

三、按顺序运行 20 个阶段

各阶段会检查自己需要的上游产物，缺失时会明确告诉你先跑哪个阶段，所以可以中途停下再从断点续跑。下面是 case_studies/etfs/README.md Running 一节给出的完整顺序（本地 uv 路径，从仓库根目录执行）：

uv run python case_studies/etfs/01_feasibility_analysis.py uv run python case_studies/etfs/02_labels.py uv run python case_studies/etfs/03_financial_features.py uv run python case_studies/etfs/04_model_based_features.py uv run python case_studies/etfs/05_evaluation.py uv run python case_studies/etfs/06_linear.py uv run python case_studies/etfs/07_gbm.py uv run python case_studies/etfs/08_tabular_dl.py uv run python case_studies/etfs/09_dl_lstm.py uv run python case_studies/etfs/10_dl_tsmixer.py uv run python case_studies/etfs/11a_pca.py uv run python case_studies/etfs/11b_ipca.py uv run python case_studies/etfs/11c_conditional_autoencoder.py uv run python case_studies/etfs/11d_stochastic_discount_factor.py uv run python case_studies/etfs/11e_supervised_autoencoder.py uv run python case_studies/etfs/11_latent_factors.py # summarizes 11a-11e uv run python case_studies/etfs/12_causal_dml.py uv run python case_studies/etfs/13_model_analysis.py uv run python case_studies/etfs/14_backtest.py uv run python case_studies/etfs/15_portfolio_management.py uv run python case_studies/etfs/16_risk_management.py uv run python case_studies/etfs/17_costs.py uv run python case_studies/etfs/18_holdout_predictions.py uv run python case_studies/etfs/19_holdout_backtest.py uv run python case_studies/etfs/20_strategy_analysis.py

两条容易踩坑的执行规则：

• 必须在仓库根目录运行。数据加载器按工作目录解析data/，从章节目录里跑会报数据集缺失（No module named 'utils'同理）。
• Docker 路径把命令改成docker compose run --rm ml4t python case_studies/etfs/01_feasibility_analysis.py（无uv）；无显示环境（服务器/CI）加MPLBACKEND=Agg PLOTLY_RENDERER=json前缀，避免plt.show()弹窗阻塞。

四、验证产物

1. 单阶段产物：每跑完一个阶段，对照上面第一节的表格检查对应文件是否出现。例如02_labels结束后应有labels/fwd_ret_21d.parquet及其.digest.jsonsidecar；14_backtest起每个预测集/入场方案在run_log/backtest/{hash}/下生成daily_returns.parquet、weights.parquet、trades.parquet、fills.parquet、equity.parquet、portfolio_state.parquet、spec.json。
2. 运行日志：所有训练、预测、回测都登记在内容寻址的 SQLite 目录run_log/registry.db中，它是书中全部指标（IC、Sharpe、回撤）的唯一来源。schema 与查询 API 见 case_studies/RUN_LOG.md。
3. 最终综合：20_strategy_analysis完成后应得到results/strategy_assessment.json与20_strategy_synthesis/output/etfs/etfs_tearsheet.html。该阶段只读 registry、不写入新行，它打印/落盘的结果就是整条流水线的收尾判定。

05_evaluation这类阶段的文档示例输出（IC 时间序列、triage 台账）只在预执行的.ipynb中展示，重跑时数值以你本地结果为准。

可选分支：缩短验证时间

• 先下载预计算产物再局部复跑：端到端全量重训文档估计需要数小时到数天。官方 artifact 发布提供九个案例研究的完整注册运行日志，etfs包约 33 MB：

  uv run python scripts/download_artifacts.py --cs etfs # 只下 etfs uv run python scripts/download_artifacts.py --list # 检查已安装

  下载器校验归档与每个文件后原子安装case_studies/etfs/run_log/，中断不会破坏已有运行日志。装好基线后，分析类 notebook（13_model_analysis、20_strategy_analysis）可直接加载指标与工件；改配置复训时，用scripts/create_experiment.py --cs etfs --output /tmp/ml4t-etf-experiment建一个可写实验副本，并以ML4T_OUTPUT_DIR=/tmp/ml4t-etf-experiment前缀运行阶段，不触碰下载的只读基线。

• Papermill 降参运行：每个 notebook 顶部有# %% tags=["parameters"]参数格，Papermill 可注入缩小范围的值（如MAX_SYMBOLS 15、N_EPOCHS 2），让 notebook 在分钟级完成，代码路径与生产一致。测试套件的做法是按tests/overrides.yaml里的覆盖参数逐本运行：

  uv run pytest tests/test_chapter_notebooks.py -v -k "etfs"

  注意设置ML4T_OUTPUT_DIR（pytest 会自动设置）后，输出和配置读取都被重定向，隔离目录必须包含案例研究的config/，手动运行时用create_experiment.py构建。

限制与已知差异

• 全量重跑不必等于发布数值。发布 artifact 是出版时点的快照；代码持续更新、GPU 训练非位级可复现、市场数据会被供应商修订，重跑通常只有小数级差异。docs/running-notebooks.md 的建议是把发布数值当作参考运行，若差异大到改变结论再作为 issue 报告。
• 配置三层分离：超参数网格不写在阶段文件里，而是运行时从case_studies/etfs/config/setup.yaml（交易问题定义）、config/training/{label}.yaml（该标签的训练菜单）、case_studies/config/{model_type}/{name}.yaml（共享 preset）三层读取。要改网格，编辑实验副本里对应的 preset 名清单和 preset 文件，而不是改 notebook。
• 部分条目来自仓库而非实验副本：labels.rebalance_step、labels.classification_eval_label等四个setup.yaml声明以及config/backtest/base.yaml始终读仓库副本，改实验副本无效；若确需改仓库副本，应从空的run_log/开始，避免新旧方法学混在一个 registry 里。
• holdout 结果本身：案例研究报告的已发布结果中，holdout 门（策略对比基准的双边置信区间）未通过——这是该案例研究有意保留的教学结论，不是流水线缺陷；重跑时不要把它当失败来“修复”。

完成 20 个阶段后，run_log/registry.db里应能按 hash 追溯到从可行性、标签、特征到 holdout 回测的完整链条；若某阶段提示缺前置产物，按提示回补对应阶段再往下跑即可。

【免费下载链接】machine-learning-for-tradingCode for Machine Learning for Trading, 3rd edition — from data sourcing to live execution.项目地址: https://gitcode.com/GitHub_Trending/ma/machine-learning-for-trading