tao-run-automl

TAO AutoML

单独安装？ 如果此会话并非由 TAO 技能库插件初始化，请先运行 tao-setup（主机预检、凭据、跨技能发现）。

结合以下内容，为 TAO 模型运行自动超参数优化：

1. skills/models/<model_skill>/ 下选定的模型技能。
2. skills/platform/<platform>/ 下选定的平台技能。
3. AutoMLRunner，它会生成建议、启动选定的操作任务、提取指标，并将结果反馈给优化器。

只有在确认模型元数据、平台预检、数据可见性、凭据、镜像选择和计算资源规格均无误后，才能启动。

执行运行时 — 硬性门槛

默认情况下，每项建议、基线评估、逐项建议评估和最终评估，都会在所选模型操作解析出的 container_image 中运行。任何训练环境设置之前，都要先从模型技能中解析该镜像。本地检查点或 Hugging Face 模型 ID 不会改变此规则。

仅在明确要求时，才使用基于 venv 的模型执行。绝不能根据 local-docker、本地 GPU、Python 或 pyproject.toml 推断 venv 模式。若未明确要求，执行方式即为容器支持。用于 tao_automl、TAO SDK 或平台适配器的主机端/控制器 venv 仅限控制平面使用；子模型操作仍须在已解析的容器镜像中运行。

参考索引

• references/skill_info.yaml：此工作流的结构化元数据。
• 详细参考文档拆分如下：automl-preflight-concepts.md 介绍前置条件和支持情况检查；automl-intent-algorithms.md 介绍搜索策略；automl-compression-literature.md 介绍蒸馏/剪枝/量化算法的充分性及未来压缩搜索路线图；automl-runner-configuration.md 介绍运行器/API/WandB 详情；automl-advanced-monitoring.md 介绍钩子、恢复和注意事项；automl-examples.md 提供对话示例；automl-common-pitfalls.md 介绍反复出现的安全检查。detailed-guide.md 仅作索引。
• skills/models/<network>/SKILL.md：模型特定的数据集要求、指标、HPO 注意事项、检查点交接和已知故障。
• skills/models/<network>/references/skill_info.yaml：操作约定、容器镜像、输入、输出、上传排除项和 mode。
• skills/platform/<platform>/SKILL.md：所选平台的预检、凭据、资源规格、监控和取消操作。
• skills/core/tao-launch-workflow/SKILL.md：用于平台、凭据、数据集可见性、镜像确认和用户确认的通用信息收集模式。

预检

1. 运行通用启动信息收集流程。如果用户尚未选择平台，请询问；Brev、SLURM、Kubernetes 和 Docker 地位相同。
2. 生成运行器文件之前，运行所选平台技能的预检。
3. 验证 nvidia-tao-automl 可导入：

python -c "import tao_automl; from tao_automl.runner import AutoMLRunner; print('OK')"

然后验证所选平台的 SDK 是否可用——导入 tao_automl 并不能证明平台后端已安装（例如，没有 docker 包时，DockerSDK() 会引发 CredentialError）。请参阅 automl-preflight-concepts.md。

如果缺少依赖，请显示 versions.yaml 中的确切安装命令，并在安装前征求用户同意：

SB="${TAO_SKILL_BANK_PATH:-~/tao-skill-bank}"
pip install "$($SB/scripts/resolve_versions_key.py wheels.tao_automl_<platform>)"

有效的平台 wheel 键为 tao_automl_brev、tao_automl_slurm、tao_automl_kubernetes、tao_automl_docker 和 tao_automl_all。仅在需要所有后端的开发机器上使用 all。仅当用户要求由 LLM 指导的算法时，才添加 ,llm。

模型支持门槛

每次运行前：

1. 阅读模型的 SKILL.md 和 references/skill_info.yaml。
2. 确认模型的 automl_enabled: true，或模型技能明确将所选操作路由到 AutoML。
3. 确认 <skill_dir>/schemas/<action>.schema.json 存在且能正常解析。这是 AutoML 搜索空间门槛。
4. 对于 Cosmos-RL 和 CLIP 等非 TAO-Core 模型，还必须具备 references/spec_template_<action>.yaml；否则，运行器就没有完整的操作默认值。
5. 如果任何门槛未通过，请勿自行编造搜索空间。报告缺失的包产物。

输入

构建运行器前收集以下内容：

输入	要求
model_skill	skills/models/ 下已解析的模型技能目录。先将 network_arch 等用户别名解析为打包的技能目录。
network_arch	从已解析的模型技能元数据中读取。
action	要优化的操作——train、evaluate、inference、distill、prune 或 quantize，且须有打包的 schema/template。
platform	支持的 TAO 平台技能之一。
train_dataset / eval_dataset / 操作输入	使用模型专属的 spec 键和布局。非训练操作可能还需要父模型/教师模型检查点、校准数据或剪枝产物。
results_root	适合该平台的本地、Lustre 或 S3 路径。
gpu_count、num_nodes	遵守模型和平台限制。
container_image	通过模型元数据和 versions.yaml 解析；向用户展示。
automl_algorithm	默认使用 bayesian，除非用户要求其他算法或模型技能另有建议。
metric、direction	优先采用模型技能指定的验证/任务指标。
automl_budget	根据算法要求设置推荐数量、最大轮数/阶段数、并发数或种群规模。

切勿索要机密值。使用 [ -n "$VAR_NAME" ] && echo SET || echo UNSET 验证必需的环境变量。

启动前审核门槛

启动任何推荐任务前，展示具体的启动审核内容并获得用户确认。此门槛适用于每个 AutoML 支持的模型/网络的每次 AutoML 运行；它并非 Cosmos 专属，也不得限定于单个模型技能。即使平台和镜像预检已通过，也必须执行此审核。审核内容必须包括：

• 模型/网络、平台、镜像、GPU/节点配置，以及结果/工作区根目录
• 数据集模式和具体 spec 键；如果能以较低成本读取，还要包括训练/评估样本数
• 算法、预算、最大并发任务数、指标和方向
• 可搜索参数及其范围；用户未提供明确搜索空间时，还要包括默认值
• 初始启动批次的确切生成推荐配置；须在提交任何推荐任务前通过仅审核步骤生成
• 每条推荐的预计运行时间和预计总耗时，以及所用假设
• 预检后评估任务的自动基线评估任务 ID、指标值和结果路径；如果模型没有可运行的 evaluate 操作或验证数据，则明确说明阻碍
• AutoML 完成后的最终评估计划，针对选定的最佳检查点/模型，包括指标、数据集和记录路径

如果预计耗时超过用户说明的时限，或明显长于一般交互式运行，请在启动前询问是否缩减推荐数量、训练轮数、数据集规模、验证频率或搜索空间。不要在日志中隐去数天的预计耗时。

自动基线评估任务

平台、镜像、凭证、数据和模型预检通过后，在提交任何 AutoML 推荐任务之前，先对选定的验证/评估数据运行一次模型的评估操作。这是 AutoML 必需的设置步骤，不是让用户选择是否进行“预训练评估”的可选问题。使用 AutoML 训练任务的起始基础模型或检查点、模型技能中的评估规范/模板，以及所选平台的常规任务提交路径。如果模型技能建议评估时使用比训练更小的配置，请使用该配置，并在启动审查中说明。

在请求确认之前，先在启动审查中提供评估指标数值。如果存在起始检查点，但无法生成基线——没有打包的评估操作、缺少评估数据集或评估任务失败——请停止并报告阻碍，不要悄悄退回到仅使用训练损失的运行方式。

对于从头开始训练，请将基线记录为不可用，然后继续；不要评估空检查点。

最终评估由运行器负责。如果评估可运行，请将 final_eval_fn(best_rec, train_job_id) 传递给 AutoMLRunner.run；随后结果会包含 result["final_evaluation"]。有关回调、检查点、基线和从头开始训练的规则，请参阅 automl-preflight-concepts.md。

依赖项和数据预检

如果所选工作流需要对象存储或平台 CLI，但缺少相应工具，请报告缺失的依赖项，并在继续之前提供准确的安装命令。获得用户批准后，使用 --install-missing-tools 重新运行 scripts/check_tao_launch_preflight.py，以安装所需的最小软件包，并立即重试路径验证。对于 S3 路径，请在创建运行器产物之前，从启动平台验证凭证和路径可读性。

对于每次训练试验都会读取大型媒体存档或目录的模型，请将数据集暂存或解压一次到执行平台可见的存储中，然后让所有推荐规范都指向该暂存路径。在 <workspace>/evaluations/data_staging.json 中记录源 URI、暂存路径、可用时的字节数/文件数证据以及时间戳。如果无法暂存，请在启动前审查中说明反复进行 S3 I/O 的风险，并在为耗时较长的 AutoML 运行投入预算之前征求用户意见。

如果模型技能定义了依赖样本数量的约束，请在启动前强制执行。拒绝或限制所有会导致所选数据集和 GPU 分片数量对应的训练步数为零的批量大小推荐。对每个生成的推荐，在提交前使用 scripts/check_tao_launch_preflight.py --effective-batch-limit train_annotation=<batch_size>,<shard_count> 进行检查。如果某项推荐之后因有效批量大小相对于数据规模过大而失败，请将其归类为无效配置；仅在预算有余时替换或调整，并在最终摘要中报告所作修正。 如果可以通过标注文件或低成本清单读取获知训练样本数，请将其作为 automl_settings["train_sample_count"] 传递给 AutoMLRunner.run，这样运行器就能在提交任务前限制不可行的推荐，并将调整记录在 result["history"][i]["adjustments"] 中。

算法策略

算法	适用场景	必需参数
bayesian	预算较小或中等、参数较少时的默认选择。	num_recommendations、指标、方向
hyperband、asha	配置较多、早期阶段成本较低；ASHA 适合并行执行。	max_epochs、reduction_factor、可选的 max_concurrent
bohb、dehb	使用多保真预算进行贝叶斯/进化混合搜索。	与 Hyperband 相同的阶段预算字段
pbt	训练时间较长，且需要在训练期间调整计划时。	种群和迭代预算
llm、hybrid、autoresearch	用户明确要求使用已配置端点进行 LLM 引导搜索时。	LLM 端点配置和预算

对于 evaluate 或 inference，默认使用贝叶斯/BFBO 风格搜索，调整所选操作的提示词、解码、预处理或运行时配置参数。 使用操作输出/日志中的任务指标；如果指标名称含义不明确，请显式设置 direction。对于不会更新权重的操作，不要套用训练损失假设。

对于 distill，如果蒸馏操作执行基于轮次的优化并写入检查点，则采用与训练类似的策略。对于单次执行的 prune 和 quantize，默认使用 bayesian 或 bfbo，除非操作架构/model skill 声明了基于轮次或校准预算的字段，使 hyperband/asha/bohb/dehb 有意义。如果所选指标必须在压缩操作完成后，通过后续的 evaluate/inference 操作计算，请使用 eval_fn。

优先采用 model skill 的建议，而不是通用默认设置。如果 model skill 指出启动、验证或检查点成本在短试验中占主导地位，则避免使用 ASHA 或 Hyperband。

规格与搜索空间

将规格构建为嵌套字典。如果 model skill 为便于阅读而以点分隔的形式列出路径，请逐层访问路径并为嵌套叶节点赋值；不要将点分隔的字符串存储为规格键。

对于以下内容，请使用已打包的所选操作架构：

• automl_default_parameters
• automl_disabled_parameters
• 有效的最小/最大范围
• 枚举、选项权重、条件、依赖关系和常用参数

用户提供的搜索空间必须符合架构约束。对于具有离散选项的整数参数，如果 model skill 特别指出这一点，请使用架构要求的整数选项格式，而不是简单的列表。

除非 model skill 指出启动器可以推导数据源，否则必须覆盖数据源。如果数据集使用直接的标注/媒体路径，请保留用户提供的确切规格键。

指标策略

训练损失计算成本低，但可能产生误导。优先采用 model skill 指定的任务指标。使用以下任一方式：

• 日志指标：metric=<name>、direction=maximize|minimize。
• metric_extractor(logs, metric_name)：当默认解析器含义不明确时，解析模型日志。
• eval_fn(rec, train_job_id)：当用户需要下游任务指标时，在每条建议之后运行模型的 evaluate 操作。

除非 model skill 明确定义了这种映射，否则不要将 kpi 映射为指标。

最终报告必须比较基线指标、每条建议的指标以及选出的最佳指标，以便用户了解调优效果。对于需要使用 eval_fn 才能计算真实任务指标的 model skill，除非用户明确接受代理指标，否则应使用该评估器，而不要优化方便获取的训练损失。

Runner 构建

只有在所选平台 SDK 通过预检后，才使用它。构建 SDK 时，不要在代码中嵌入凭据。

sdk 是平台 SDK 对象；无容器的 venv 模型使用 VirtualEnvSDK(venv_path=..., work_dir=...)。务必传入 work_dir——默认值 ~/.tao_sdk/virtualenv 会让主目录充满试验检查点。请参阅 automl-runner-configuration.md。

import sys
from pathlib import Path
from tao_automl.runner import AutoMLRunner

skill_bank = Path("<absolute-tao-skill-bank>")
model_skill = "<resolved-model-skill-directory>"
skill_dir = skill_bank / "skills" / "models" / model_skill
sys.path.insert(
    0, str(skill_bank / "skills/applications/tao-run-automl/scripts")
)
from resolve_automl_session import validate_session_settings

runner = AutoMLRunner(
    sdk=sdk,
    skill_dir=str(skill_dir),
    action=action,                      # train, distill, prune, quantize, ...
)

workspace_path = Path("<automl_workspace>")
resume = False
# Mandatory fail-closed gate from this skill's bundled scripts directory.
validate_session_settings(
    automl_settings,
    resume=resume,
    workspace=workspace_path if resume else None,
)
result = runner.run(
    workspace_path=str(workspace_path),    # timestamp it to avoid collisions
    automl_settings=automl_settings,       # must contain an explicit session_id
    spec_overrides=spec_overrides,
    automl_hyperparameters=automl_hyperparameters,
    custom_param_ranges=custom_param_ranges,
    metric_extractor=metric_extractor,  # optional
    eval_fn=eval_fn,                    # optional
    final_eval_fn=final_eval_fn,        # optional but required when final eval is runnable
    resume=resume,
)

明确设置 automl_settings["session_id"]，并在每次运行前调用 validate_session_settings。使用 scripts/resolve_automl_session.py new 生成一个新的 ID。仅在明确要求时恢复；使用 scripts/resolve_automl_session.py resolve --workspace <full-run-path> 解析其控制器。 状态缺失或不明确时应阻止运行。完整的全新运行／恢复流程请参阅 references/automl-advanced-monitoring.md 中的恢复部分。

监控

使用 runner 状态输出，以及平台 SDK 的 get_job_status、 get_job_logs 和 get_failure_analysis。对于正在运行的任务，请报告：

• 推荐 ID／试验 ID
• 平台任务 ID
• 状态
• 当前指标
• 目前为止的最佳指标
• 当前／最佳推荐所选的超参数
• 已用时间，以及有足够计时数据时更新后的预计剩余时间

发生失败时，请判断原因属于基础设施、数据可见性、镜像、凭据、规范／架构还是模型代码。只修复最小范围的原因，不要在未告知用户的情况下，将额外预算用于反复无效的推荐。 如果在运行设置期间解决了阻塞问题，请展示更新后的预检／启动审核，然后继续原任务，而不是让用户重新说明请求。

对于基于 LLM 的算法，在判定运行有效之前，请先检查 brain 日志。确认 LLM 调用成功、已生成提案、后续参数调整使用了先前的指标，并且日志显示了保留／丢弃或等效的算法决策。如果 brain 回退到随机采样，应将 LLM 工作流判定为失败或受阻，而不是将其视为有效的 LLM 引导运行。

结果交接

完成时：

1. 根据所选指标及其方向，确定最佳推荐。
2. 返回最佳子任务 ID 及其结果路径。
3. 使用模型技能的检查点／制品元数据和 SDK 辅助工具解析模型检查点或动作制品；不要猜测 latest 之类的文件名。
4. 报告确切的搜索空间、算法、预算、指标和平台。
5. 报告自动基线评估任务 ID／结果路径／指标、所有推荐的指标、最终评估状态／结果路径／指标、失败的推荐及根本原因、已用时间和最终运行说明。
6. 如果结果将用于 AutoML + DEFT 等工作流，请通过工作流声明的交接字段传递获胜的规范覆盖项和检查点。
7. 使用默认保留策略时，请确认已删除受清理支持且可安全修剪的终止试验制品，并保留获胜训练制品。明确报告受保护的晋升／恢复父项或保守 Hybrid 结果。SDK 无法回收的远程绑定、命名卷或其他输出路径必须在首次试验前未通过保留预检，而不能静默保留。

常见陷阱

启动或恢复 AutoML 运行前，请参阅 references/automl-common-pitfalls.md。