Skip to content

cli.md

Latest commit

 

History

History
132 lines (96 loc) · 7.14 KB

cli.md

File metadata and controls

132 lines (96 loc) · 7.14 KB
Raw

CLI 参考

产品镜像和源码安装环境均使用 turbo-physai。仅在尚未安装组件的源码开发目录中，可使用 PYTHONPATH=. python -m turbo_physai.cli 调用同一入口。

optimization init

创建空白的外部优化开发工程：

turbo-physai optimization init <name> [--output <directory>]
  • name：模型或优化项目名称，必须以字母开头，只包含字母、数字、-、_；
  • --output：输出目录；未指定时，框架将名称转为小写、将 - 转为 _，并使用 <normalized_name>_optimization；
  • 已存在路径不会覆盖。

optimization generate

turbo-physai optimization generate \
  --recipe <recipe.yaml> \
  --repo <model-repo> \
  --commit <validated-commit> \
  --output <generated-optimization-config.yaml> \
  [--force]
  • 模型仓库 HEAD 必须等于 --commit；
  • 模型仓库必须干净；
  • --commit 用于本次生成的基线确认，并作为非阻断的参考信息写入最终 YAML；
  • 展开 extends 和 Group 依赖，确定最终 Group 顺序；
  • 检查 Group 组合冲突和模型 Replacement 对公共 Replacement 的直接引用；
  • 从当前模型仓库提取 target source/AST Hash；
  • 同时输出配置和隐藏生成记录 .<配置文件名>.generation.json；
  • 配置或记录已存在时默认返回错误；
  • --force 同时更新配置和生成记录。

run

准备 RuntimeConfig，并在每个 Python 训练进程中应用 OptimizationConfig 后执行原训练入口：

turbo-physai run \
  [--model <model-name>] \
  [--optimization-config <model-optimization-config.yaml>] \
  [--runtime-config <runtime.yaml>] \
  [--log-report] \
  [--force-group GROUP_ID[,GROUP_ID...]] \
  [--disable-group GROUP_ID[,GROUP_ID...]] \
  [--set NAME=VALUE] \
  [--disable-numa] \
  <training-command>
参数 含义
--model 内置模型名称；自动选择该模型的 OptimizationConfig 和 RuntimeConfig
--optimization-config 显式 OptimizationConfig 路径；优先于 --model 选择结果
--runtime-config 显式 RuntimeConfig 路径；优先于 --model 选择结果
--log-report 将本次优化应用报告输出到训练日志；默认关闭
--force-group GROUP_ID[,GROUP_ID...] 对指定且已启用的一个或多个 Group 的可放行检查进行一次性覆盖
--disable-group GROUP_ID[,GROUP_ID...] 本次启动不应用指定的一个或多个 Group
--set NAME=VALUE 覆盖或增加非空环境变量，可重复
--disable-numa 关闭本次启动的 NUMA 绑定；默认开启

训练命令直接写在 TurboPhysAI 参数之后，框架逐字透传，不解析或改写启动器参数。可以使用 torchrun、torchpack dist-run、DeepSpeed、accelerate、mpirun、srun 或 Shell 启动脚本，TurboPhysAI 会在每个 Python 训练 rank 中自动应用 OptimizationConfig。

指定 --log-report 后，Rank 0 将完整 OptimizationReport 输出到训练日志，其他 rank 输出应用状态摘要。报告内容见优化应用报告。

例外是 python -E、-I、-S：这三个标志会使启动钩子不被加载，命令中出现它们时 turbo-physai run 直接报错，而不是让训练以未优化状态运行。

Shell 语法本身仍不由 turbo-physai run 解析。source、ulimit、管道和条件分支应保留在作业脚本中，由该脚本调用 turbo-physai run。完整字段和覆盖规则见 RuntimeConfig 使用指南。

配置选择顺序如下：

  1. 显式 --optimization-config 或 --runtime-config；
  2. --model 对应目录下的 configs/optimization.yaml 和可选的 configs/runtime.yaml；
  3. 未指定模型和 OptimizationConfig 时，使用内置 optimizations/common/configs/optimization.yaml，不加载 RuntimeConfig。

模型名称不区分大小写，- 会按 _ 处理。例如 --model BEVFormer 与 --model bevformer 等价。

turbo-physai run \
  --model bevformer \
  torchrun --nproc-per-node=8 tools/train.py path/to/config.py

TorchPack 示例：

turbo-physai run \
  --model bevfusion \
  torchpack dist-run -np 8 python tools/train.py path/to/config.py

--force-group 仅对本次启动有效，且 Group 必须已被当前 OptimizationConfig 启用。多个 Group ID 使用逗号分隔。该参数只能覆盖框架明确标记为可放行的证据类检查。目标不存在、Alias 身份冲突、签名不兼容和优化冲突等结构性问题仍会阻断。

--disable-group 仅对本次启动有效，不修改 OptimizationConfig。多个 Group ID 使用逗号分隔。依赖被禁用 Group 的其他 Group 同时跳过。报告分别使用 disabled_by_user 和 dependency_disabled 记录两类原因。同一 Group 不能同时强制放行和禁用。

run 用 exec 替换自身执行训练命令，进程树中不留中间进程。SIGINT、SIGTERM 等信号由训练进程直接接收，不经过转发。

optimization check

用于在不启动训练的情况下，排查配置加载、Group 依赖及目标代码匹配问题。检查通过不能代替实际运行验证。

turbo-physai optimization check <optimization-config.yaml> \
  [--repo <model-repo> | --generated-only]

默认检查已生成的 OptimizationConfig 与当前模型仓库是否一致。--repo 默认为当前目录。该模式要求模型工作区干净，并校验配置格式、字段类型和 Catalog 导入，检查 Group 依赖闭包、执行顺序、Group 组合以及已记录的 target Hash。模型仓库 commit 不同本身不会导致检查失败。默认模式不检查隐藏生成记录。

使用 --generated-only 检查生成记录，防止交付时遗漏 CLI 生成步骤或修改配套文件后未重新生成。该模式不需要模型环境，不能与 --repo 同时使用：

turbo-physai optimization check --generated-only <optimization-config.yaml>

该模式读取配置同目录的隐藏生成记录 .<配置文件名>.generation.json，核对 Config、Recipe、声明的 Catalog 文件和继承配置规范化后的 SHA-256。YAML 按解析后的数据计算，Python Catalog 按 AST 计算；不导入 Catalog 或模型，也不需要克隆模型仓库。

注释、空行及不改变解析结果的排版变化不会触发失败。配置值、列表顺序、Catalog 代码结构及字符串内容的变化仍会触发失败。记录缺失、格式错误、关联文件缺失、无法解析或指纹不匹配时返回 2，需要修正文件并重新执行 optimization generate。

返回码

返回码 含义
0 命令成功，或训练进程正常退出
2 训练进程执行前发生参数、OptimizationConfig、RuntimeConfig、生成检查或覆盖策略错误
91 某个 rank 无法应用 OptimizationConfig，主动终止而不是以未优化状态继续训练
训练进程返回码 run 执行训练后，退出码即训练进程自身的退出码，包括信号导致的 128 + signal

非 run 命令的具体错误原因写入标准错误输出。run 执行训练后，训练日志和异常由训练进程直接输出。