tao-run-automl

TAO AutoML 技能

为任意 TAO 网络运行自动超参数优化（HPO）。Agent 使用 AutoMLRunner——一个统一接口，可管理完整流程：生成建议、启动训练作业、提取指标，并将结果反馈给优化器。

运行器不受平台限制——它接受任何实现了标准 SDK 结构（create_job、get_job_status、get_job_logs、get_failure_analysis）的对象，并调用这些方法。根据你希望作业运行的位置，选择相应的 SDK：

SDK	最适用于 AutoML 的场景
LeptonSDK	在 DGX Cloud 上进行多节点搜索；托管式调度
BrevSDK	在 Brev 实例上进行成本优化的搜索（每条建议对应一个实例，支持多 GPU）。使用多个凭证或工作区的账户必须向 create_job 传入 cloud_cred_id= 和 workspace_group_id=——参见 skills/platform/tao-run-on-brev/SKILL.md。
SlurmSDK	在具有队列／配额的共享 HPC 集群上进行大规模搜索
KubernetesSDK	在配备 NVIDIA GPU Operator 的 EKS／GKE／AKS／本地集群上进行搜索
DockerSDK	本地调试或单主机搜索

Lepton、SLURM 和 K8s 支持每条建议使用多节点（每条建议都是一个 N 节点分布式训练作业）。Brev 和本地 Docker 每条建议仅支持单主机——单台主机内仍支持多 GPU（gpu_count > 1），但一条建议不能跨多台主机。

工作流：（1）解析用户意图并执行预检，（2）选择算法，（3）配置并运行，（4）监控／恢复／查询状态，（5）解读结果。下方每个步骤都链接到包含完整详情的参考资料。故障模式：references/pitfalls.md。示例对话：references/examples.md。设置详情：references/prerequisites.md。

预检

此技能需要 nvidia-tao-automl（该包会传递依赖 nvidia-tao-sdk）。两者都在公共 PyPI 上；固定版本位于 versions.yaml（wheels.tao_automl_*），通过 scripts/resolve_versions_key.py 解析。选择所需的平台额外依赖项：

python -c "import tao_automl" 2>/dev/null || {
  SB="${TAO_SKILL_BANK_PATH:?}"
  echo "MISSING: nvidia-tao-automl not installed. Pick the platform extra you need:"
  echo "  pip install \"$($SB/scripts/resolve_versions_key.py wheels.tao_automl_lepton)\"      # DGX Cloud / Lepton"
  echo "  pip install \"$($SB/scripts/resolve_versions_key.py wheels.tao_automl_slurm)\"       # on-prem SLURM cluster"
  echo "  pip install \"$($SB/scripts/resolve_versions_key.py wheels.tao_automl_kubernetes)\"  # K8s (EKS / GKE / on-prem)"
  echo "  pip install \"$($SB/scripts/resolve_versions_key.py wheels.tao_automl_docker)\"      # local Docker daemon"
  echo "  pip install \"$($SB/scripts/resolve_versions_key.py wheels.tao_automl_brev)\"        # Brev GPU instances"
  echo "  pip install \"$($SB/scripts/resolve_versions_key.py wheels.tao_automl_all)\"         # all 5 platforms"
  echo "  (append ,llm or ,wandb to the extra for agentic-search or experiment-tracking deps)"
  exit 1
}

（针对本地检出版本进行开发：pip install -e '~/tao-run-automl[lepton]'。）如果缺少依赖项，Agent 会提示用户通过 Bash 授权安装，然后重新执行预检再继续。

前置条件

运行 AutoML 前，请满足以下所有条件——各平台凭据筛选、数据集 URI 格式、银行结构树和安装命令的完整详情见 references/prerequisites.md：

1. 共享启动前检查 — 首先运行 tao-launch-workflow 接入模式。在所选平台的凭据、访问检查、数据集可见性、模型凭据、容器镜像确认和计算规格均满足之前，AutoML 不得创建运行器文件、工作区、状态文件、日志、兼容性垫片或安装依赖项。这样可以避免因 SSH、存储、镜像或凭据设置问题导致虚假的推荐失败，浪费预算。
2. SDK 凭据 — 环境变量从 ~/.config/tao/.env 加载（由技能库的 SessionStart hook 自动加载）。使用 scripts/list_tao_platforms.py --platform <platform> --format text 按平台筛选必需变量，并且只询问列出的变量（仅当 URI 使用 s3:// 时需要 S3；拉取容器时需要 NGC_KEY）。Agent 绝不读取变量值——只用 [ -n "$VAR_NAME" ] 检查变量是否存在。构建 SDK 时不传入任何参数，例如 LeptonSDK()。
3. 数据集 — 数据集必须能从计算后端访问；URI 格式取决于平台（Lepton 使用 s3://...，SLURM 使用绝对共享路径，Azure 使用 azure://...，Docker 使用本地路径；绝不生成 aws://...）。接受数据集根目录或精确的 spec 键路径，并保留用户提供的键，例如 custom.train_dataset.annotation_path=，而不强制文件共用父目录。
4. 技能库可用 — 运行器需要显式指定 skill_dir（<bank-root>/models/<network> 的绝对路径，不使用环境变量回退）。使用 Agent 加载工作流时所用的同一技能库根目录。重要：AutoML 要求存在经过打包且有效的 <bank-root>/models/<network>/schemas/train.schema.json——它是启用 AutoML 支持的门槛（定义 automl_enabled 参数、默认值、范围、选项、权重和热门元数据）。运行时不得假设 ~/tao-core 存在；如果缺少打包的训练 schema，则不要为该模型运行 AutoML。对于非 TAO-Core 模型（cosmos-rl、clip），必须提供 references/spec_template_<action>.yaml；对于 TAO Core / 基于 Hydra 的模型（DINO、BEVFusion），该文件为可选项。
5. 已安装 nvidia-tao-automl，并包含所需平台的 extra（公共 PyPI；在 versions.yaml 中固定版本）。使用上方 Preflight 区块或 references/prerequisites.md 中的安装命令；对于 agentic 算法，在 extra 后追加 ,llm。

验证设置：

python3 -c "from tao_automl.runner import AutoMLRunner; print('OK')"
python3 -c "from tao_automl.brain.llm_brain import LLMBrain; print('LLM OK')"   # optional, LLM features
python3 -c "import wandb; print('WandB OK')"                                    # optional, WandB

---

概念：什么是 TAO AutoML？

TAO AutoML 可自动执行“尝试不同的超参数值 → 训练 → 比较结果 → 重复”这一循环。你需要告诉它使用什么网络（network_arch）、搜索哪些超参数（从模型技能和 schema 中选取）、优化什么指标（来自模型技能或用户请求）以及进行多少次试验（预算）。随后，它会使用搜索算法（贝叶斯、Hyperband、LLM 等）选择超参数值，在 SDK 指向的后端上启动实际训练作业，从训练日志中读取结果指标，并将其反馈给算法以学习哪些配置有效。此过程会重复执行，直到预算耗尽，最后返回找到的最佳配置。

每次“试验”称为一条推荐（rec）。一条 rec = 使用一组特定超参数进行的一次完整训练运行。

---

快速查询支持情况

当用户询问 AutoML 支持哪些模型／网络时，以 AutoML 模式运行打包的模型列表辅助工具。AutoML 的启用状态是模型级元数据（skills/models/<network>/references/skill_info.yaml 中包含 automl_enabled: true），而非工作流级。辅助工具会读取这些元数据，然后验证模型是否也有已打包且可解析的训练数据类架构：

${TAO_SKILL_BANK_PATH:-~/tao-skills-external}/scripts/list_tao_models.py \
  --skill-bank ${TAO_SKILL_BANK_PATH:-~/tao-skills-external} --scope automl --format text

下面的兼容性封装也有效，并会委托给相同的逻辑：

${TAO_SKILL_BANK_PATH:-~/tao-skills-external}/scripts/list_automl_support.py \
  --skill-bank ${TAO_SKILL_BANK_PATH:-~/tao-skills-external} --format text

返回该输出中的两个部分：可运行 AutoML 的模型，以及已启用 AutoML、但仍受架构打包限制的模型。支持规则：AutoML 在模型级启用；要让 AutoML 可运行，还要求已打包且有效的 skills/models/<network>/schemas/train.schema.json。

---

第 1 步：解析用户意图

默认进行快速启动运行，除非用户明确要求自定义 AutoML，或同意接受自定义选项。对于普通的“运行 AutoML”请求，不要将算法、预算或搜索空间选项说成必填项。

任何会调用具备训练能力的模型技能的工作流／应用，都必须检查所选模型的 automl_enabled 元数据。如果其值为 true，则默认使用此 AutoML 工作流作为训练路径，除非运行／工作流设置包含 automl_policy: off，或用户明确要求进行一次普通的单次训练运行。这样一来，AutoML 启用机制便可扩展至 tao-train-single-step、DEFT 和未来的工作流，而无需在每个应用技能中重复维护允许列表。

提取默认运行所需的输入，并应用快速启动默认值。完整的必填字段表（network_arch、platform、数据集 URI／直接规格文件路径、image、metric、direction、skill_dir、long_running_enabled、status_interval_minutes、凭据、计算资源配置，以及 LLM 端点／模型／密钥三项）、快速启动默认值（bayesian、10 条建议、None 超参数／范围、每隔 5 分钟监控）、友好的启动信息收集提示清单、仅自定义时使用的字段、快速启动运行器结构，以及指标选择最佳实践，均见 references/intake-and-inputs.md。

始终适用的关键门控策略：

• 如果缺少任何必填字段，请询问用户。不要猜测数据集路径、技能库路径、凭据或模型技能标记为必需的硬件。
• image：解析默认值并告知用户；创建 AutoML 运行器前，必须获得用户确认或提供 image=<override>。
• direction：仅当指标名称与隐式规则“包含 'loss' → 最小化，否则最大化”不一致时才需要。
• llm_endpoint、llm_model、llm_api_key：对于 llm／hybrid／autoresearch，必须询问用户；代码默认值 https://integrate.api.nvidia.com/v1 会返回 404，因此必须始终显式传入 llm_endpoint。

生成 AutoML 脚本前，使用共享启动预检验证平台访问权限和数据集可见性。对于 SLURM，这意味着能够通过无密码 SSH 连接至少一台登录主机，并对每个必需的标注／媒体路径执行远程 test -e 检查。也必须以相同方式确认容器镜像——确认后的训练镜像必须传入 AutoMLRunner.run(..., image=chosen_image, ...) 或 SDK 适配器的 create_job(..., image=chosen_image, ...)；不要依赖隐式默认值。还要运行模型技能文档中说明的任何特定于模型的标注内容检查。如果预检失败，请停止并提供修复步骤，而不要创建会立即失败的运行器。缺少必需的标注字段属于预检失败，而不是 AutoML 推荐失败。

**自定义门控：**解决快速启动所需的必填字段后，可以简要提供自定义选项。如果用户拒绝，则使用默认值继续。如果用户选择自定义，则展示 references/intake-and-inputs.md 中仅自定义时使用的字段。 强制要求：配置 AutoML 前，先阅读生成的 dataclass schema。 对于选定的模型／操作，请阅读 ${TAO_SKILL_BANK_PATH:-~/tao-skills-external}/models/<network>/schemas/train.schema.json 和 .../schemas/manifest.json。只有在 train.schema.json 已打包且有效时，AutoML 才能运行。不得退回使用手写笔记、旧版 runner 脚本或本地的 ~/tao-core 检出目录。如果缺少 schema，请停止并报告：AutoML 已启用，但在生成并交付 schema 前无法运行。将 schema JSON 作为 automl_default_parameters、automl_disabled_parameters、各参数的默认值、范围、枚举、option_weights、math_cond、depends_on、parent_param 和 popular 的唯一准确信息来源。当 automl_hyperparameters=None 时，runner 会发现 schema 中所有标记为 automl_enabled=True 的参数；每个网络的参数集合各不相同，因此切勿在此处硬编码。

以下强制规则适用于每次运行——完整文本、代码模式和原因见 references/mandatory-rules.md：

• 基于 LLM 的算法必须先配置提示词（llm、hybrid、autoresearch）——生成脚本前，先确定 llm_endpoint、llm_model 和 llm_api_key（优先级链见参考文档）。没有有效的 LLM 设置时，brain 会静默回退到随机采样，浪费 GPU 预算。
• 强制要求：生成脚本前先阅读模型技能文档——阅读 <bank-root>/models/<network>/SKILL.md，并遵循其中的 训练要求、各操作的数据集要求、典型 Spec 覆盖项、AutoML／HPO 说明和错误模式。不要硬编码特定模型的知识。
• 强制要求：此 AutoML 技能中不得包含特定模型的常量——超参数名称、范围、默认值、指标名称、数据集布局、Spec 覆盖项键、图像和指标正则表达式应放在 schema 和模型技能文档中，而不是此处。
• 强制要求：工作区文件夹必须带时间戳——始终使用 datetime.now().strftime("%Y%m%d_%H%M%S") 为 workspace_path 添加后缀；切勿使用不带时间戳的路径。
• 强制要求：通过预检后，每个新的 AutoML 请求都必须创建全新的 runner——每个新请求都要创建新的 runner 脚本、日志、PID 文件、SDK state_file 和带唯一时间戳的 workspace_path；只有用户明确要求恢复、继续、找回或检查时，才可恢复运行。

指标选择最佳实践： 优先选择模型技能文档推荐的验证指标或任务指标，而不是廉价的训练损失（小规模微调数据集容易对其过拟合）；使用验证代理指标时，也要应用模型技能文档要求的验证相关 spec_overrides，以便输出该指标；通过 eval_fn 获取真实任务指标最为可靠，但会增加每次推荐的成本。详情见 references/intake-and-inputs.md。

---

第 2 步：选择算法

默认使用 bayesian。经典算法和 LLM／Agent 式算法的完整表格（适用场景、典型预算、工作原理）、默认规则与注意事项，以及决策树，均见 references/algorithms.md。仅在自定义模式下或用户指定算法时，才展示算法指南。

---

第 3 步：配置并运行

根据 references/automl-settings.md 中的通用结构构建 runner——其中包含最简示例、包含所有选项的完整示例、LLM 驱动示例、程序化 AutoML API、完整的 automl_settings 键表、kpi 指标解析、LLM 分析器环境开关以及 spec_overrides 规则。

• 使用 custom_param_ranges 限定搜索空间：见 references/custom-param-ranges.md（格式表、示例、特定模型的搜索空间规则）。
• 可选择启用 metric_extractor／eval_fn 钩子和 WandB 跟踪：见 references/hooks-and-wandb.md。
• LLM／Agent 式深入介绍——NLConfigGenerator、独立的 LLMAnalyzer、五个 autoresearch Agent 组件以及多阶段研究程序：见 references/nl-config-and-research.md。

所有特定模型的超参数、指标提取器和 spec_overrides 均来自模型技能文档。

---

步骤 4：监控进度

runner.run() 会一直阻塞，直到所有建议都完成；使用 on_recommendation / on_result 回调报告进度。每条建议耗时 10–90 分钟，长时间上传时不要假定运行失败。如果协调器在运行过程中退出，请使用完整的带后缀 workspace_path 和 resume=True 重新启动。使用 query_status() 在单独的进程中检查进度。有关回调、恢复行为以及完整的 query_status() / get_status() 用法，请参阅：references/monitoring-and-resume.md。

---

步骤 5：解读结果

runner.run() 会返回一个包含 best、progress 和 history 键的普通字典；指标值始终采用用户原始的量纲。报告最佳配置、排名对比表、见解、启用时的 WandB 链接，以及后续步骤。有关完整的结果字典结构、报告检查清单以及所有建议均失败时的排查方法，请参阅：references/results.md。

---

特定模型说明

这里不应包含特定模型说明。对于每个请求的 network_arch，请阅读 <bank-root>/models/<network>/SKILL.md，并以其中的 Training Requirements、Per-Action Dataset Requirements、Typical Spec Overrides、AutoML / HPO Notes 和 Error Patterns 部分为准。

---

常见陷阱

references/pitfalls.md 记录了 15 种反复出现的故障模式及其修复方法，包括 skill_dir 错误或缺失、LLM 端点错误（404）、特定模型训练失败、工作区冲突、代理指标较弱、隐式方向陷阱、spec 覆盖项拼写错误、扫描过程中协调器退出、静默随机 LLM 配置、缺少 openai、WandB 未记录，以及 conda run 缓冲。在任何运行之前和运行期间都应查看这些内容。

---

对话示例

有关优化网络、请求真实任务指标、LLM 引导搜索、全自动 autoresearch、恢复运行、切换到 ASHA 并使用 WandB，以及根据目标描述生成配置的代表性 Agent/用户对话，请参阅：references/examples.md。