expflow Pipeline HPO — expflow 流水线 HPO

使用 expflow 管理 AI4S PDE 竞赛实验工作流。expflow 有三种模式，分别对应竞赛的三个阶段。

用户可以通过以下命令触发 expflow：

• "运行 HPO"
• "提交 pipeline"
• "分布式实验"
• "竞赛冲刺" 或 "快速迭代"
• "自动化 train→eval→submit 循环"
• "寻找最佳超参数"

安装 expflow-pde[pipeline]：

pip install "expflow-pde[pipeline]"

expflow 有三种 pipeline 模式，每种模式对应一个 CLI 命令：

• 模式 A — 全部（HPO → Train → Eval）：用于竞赛的探索阶段。Optuna 通过分布式 clearml-agent 试验找到最佳参数，训练并评估。

expflow pipeline submit-full train_task1.py \
  --queue default \
  --trials 50 --parallel 4 \
  --eval-script eval_task1.py \
  --metric seg_total --direction maximize

- 标志： - --trials N：总 HPO 试验次数 - --parallel M：最大并发试验次数（使用 GPU 节点数） - --metric：目标 metric 名称（在脚本 stdout 中以 METRIC: 开头） - --pruner：早停不佳试验的策略（hyperband、median、percentile） - --study-name：Optuna 研究名称（如果省略，会自动生成并存储到 SQLite） - --skip hpo --skip eval：仅运行 train

• 模式 B — 快速（Train → Eval）：用于竞赛的冲刺阶段。已知最佳参数，跳过 HPO，直接运行。

expflow pipeline submit train_task1.py \
  --queue default \
  --train-param lr=0.001 --train-param epochs=80 \
  --eval-script eval_task1.py \
  --eval-param sub_step=5

- 标志： - --skip eval：仅训练（提交 checkpoint） - --train-param key=val：注入训练脚本的参数 - --eval-param key=val：注入评估脚本的参数

• 模式 C — 灵活：跳过某个步骤。

expflow pipeline submit-full train_task1.py \
  --skip hpo --skip eval  # 仅训练
expflow pipeline submit-full train_task1.py \
  --skip train --skip eval  # 仅 HPO

HPO 有三种执行模式：

• 本地（默认）： subprocess serial 在 CPU 上运行，适合 ≤20 次试验，快速测试
• 分布式：使用 clearml-agent 进行任务克隆，适合多 GPU、自定义控制
• 优化器：使用 Clearml HyperParameterOptimizer，适合生产环境，50-200+ 次试验

- 关键标志： - --pruner：早停不佳试验的策略（hyperband、median、percentile、none） - --metric ：从脚本 stdout 中读取 METRIC:= - --direction：最大化或最小化 - --timeout ：安全截止时间

脚本要求：

• 训练/评估脚本必须接受超参数作为 --key=value CLI 参数
• 输出 METRIC:= 到 stdout 以捕获目标（本地模式）
• 报告 clearml 标量用于分布式/优化器模式：Task.current_task().report_scalar("Score", "seg_total", value, iteration=epoch)

常见问题：

• 剪枝器需要试验报告调用。至少每 10 个 epoch 调用一次 trial.report(val_loss, epoch)。
• HyperParameterOptimizer 需要 metric 名称在 Title/Series 格式。如果 metric 名称是 seg_total，则成为 title=seg_total, series=seg_total。
• clearml-agent 必须在 GPU 节点上运行，然后才能提交。使用 expflow clearml workers 或检查 Web UI 进行验证。

expflow_pde/ 中的关键文件：

• hpo.py：3 模式 HPO 运行器（本地/分布式/优化器）
• pipeline.py：ExperimentPipeline 类（快速/全部模式）
• cli_pipeline.py：pipeline 提交 + pipeline 提交全部 cli
• cli_optuna.py：optuna 运行所有三个后端

相关内容：

• experiment-lifecycle-governance：PIN、metrics 注册、比较分数、竞赛规则审计
• pde-experiment-hyperparameters：PDEBench 特定超参数参考
• multi-agent-distributed-experiment-workflow：Hermes → OpenCode → clearml