tao-launch-workflow

TAO 工作流启动信息收集

启动任何 TAO 工作流或模型操作前，请使用此技能。

快速开始

运行平台辅助工具，询问用户的平台和监控偏好，然后在询问凭据前运行所选平台的详情辅助工具。

不可妥协的启动门槛

在启动前检查通过之前，请勿创建运行器脚本、启动脚本、兼容性垫片、工作区文件夹、状态文件、日志，也不要产生依赖安装副作用。

只有满足以下所有条件，启动前检查才算通过：

1. 已通过打包的平台辅助工具选择执行平台。
2. 平台凭据和必需的凭据组均已满足要求。
3. 模型专属凭据已满足要求。
4. 已从打包的模型／操作元数据中解析出默认容器镜像，向用户展示，并由用户确认或通过明确的 image=<override> 替换。
5. 从启动主机执行的平台访问检查成功。
6. 已将数据集输入映射到具体的规范键，并从所选平台的视角完成验证。
7. 已知模型／工作流技能要求的计算资源规格字段。

如果缺少任何一项，请询问缺失的信息，并在生成任何产物前停止。此要求适用于 AutoML、常规的 train/eval/infer/export/TRT，以及 DEFT／应用工作流。

初始问题

用户确认想要执行的操作后，使用打包的辅助工具询问执行平台。请勿扫描平台文档、技能文件夹或配置文件夹来整理可选项。

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

然后询问：

• 哪个受支持的平台应运行此工作流？
• 要我在此聊天中监控运行吗？监控表示启动后，我会持续轮询后端／作业日志并报告进度，直到作业完成、失败或你要求我停止，即使作业排队数小时或数天也一样。如果禁用监控，我会启动作业、提供作业 ID／日志路径，然后停止轮询。默认值：在聊天中监控。
• 我应多久报告一次状态？默认值：每 5 分钟一次。冒烟测试可设为 1-2 分钟，常规训练可设为 5 分钟，长时间运行则可设为 10-15 分钟。

用户接受默认值时，使用 long_running_enabled=true 和 status_interval_minutes=5。

启用监控后，即使已经轮询多次或作业仍为 PENDING，也不要发送最终摘要。请保持当前轮次持续进行，并每隔 status_interval_minutes 报告状态，直到进入终止状态，或用户明确要求停止／分离监控。如果运行环境无法保持聊天轮次开启，请明确说明，并留下持久的监控程序／日志路径；不要暗示轮次结束后聊天更新仍会继续。

最终答复规则：发送 final 响应会结束聊天端的监控。当 long_running_enabled=true 且任何已启动的作业仍未进入终止状态时，必须发送进行中的状态更新，并由 Agent 继续轮询。只有在工作流进入终止状态、用户明确要求分离／停止监控，或运行环境确实无法保持轮次开启时，才能发送最终答复；在最后一种情况下，请说明这是运行环境限制，并提供准确的持久状态命令／日志路径。

缺少输入时的提问格式

询问启动输入时，请提供具体示例并涵盖两种数据集输入模式。不要只询问“数据集根目录”。

使用以下结构，并根据所选模型／操作调整规范键：

I need these launch inputs before I can create specs or runner files:

1. Execution platform: lepton, brev, slurm, local-docker, or kubernetes.

2. Dataset inputs. You can provide either mode:
   A) Root mode: give train/eval roots and I map required files automatically.
      Example Cosmos-RL:
      train_root=/lustre/fsw/.../cosmos/train
      -> custom.train_dataset.annotation_path=train_root/annotations.json
      -> custom.train_dataset.media_path=train_root
   B) Direct spec mode: give the exact config/spec parameters yourself.
      Example:
      custom.train_dataset.annotation_path=/lustre/fsw/.../train_annotations.json
      custom.train_dataset.media_path=/lustre/fsw/.../videos_train.tar.gz
      custom.val_dataset.annotation_path=/lustre/fsw/.../eval_annotations.json
      custom.val_dataset.media_path=/lustre/fsw/.../eval_videos/

   Platform examples:
   - SLURM/Lustre: /lustre/fsw/.../data/train or lustre:///lustre/fsw/.../data/train
   - Lepton/Brev/Kubernetes: s3://bucket/path/train and s3://bucket/path/eval
   - local-docker: /data/tao/<model>/train or file:///data/tao/<model>/eval

3. Container image. I will resolve the default from packaged model metadata and
   show it before launch, for example:
   default image for <model>/<action>: <resolved container image>
   Use this image, or provide image=<override> to pin a different TAO build.

4. Compute shape required by the model, for example GPUs/nodes.

5. Required credentials from platform/model docs, for example HF_TOKEN for
   gated Hugging Face models.

6. Monitoring preference. By default I monitor in this chat and post progress
   every 5 minutes; choose 1-2 minutes for smoke tests or 10-15 minutes for
   long training.

容器镜像确认

在创建规格、运行脚本、工作区、日志、状态文件或提交作业之前，先解析所选模型／操作对应的镜像：

${TAO_SKILL_BANK_PATH:-~/tao-skills-external}/scripts/resolve_tao_image.py \
  --skill-bank ${TAO_SKILL_BANK_PATH:-~/tao-skills-external} \
  --model <network> --action <action> --format text

如果辅助工具不可用，请通过 SkillBank().get_model_config(network_arch) 读取 skills/models/<network>/config.json。按以下顺序解析镜像字段：

1. actions.<action>.container_image
2. actions.<action>.image
3. 顶层 container_image
4. 顶层 image

显示确切的镜像并询问：

Container image for <network>/<action>:
default=<resolved image>

Use this image, or provide image=<override>?

如果用户接受，将解析出的镜像作为作业的 image 传入。如果用户指定其他镜像，则要求提供非空的镜像引用，并改为传入该值。不得在未告知用户的情况下使用默认镜像启动。此确认适用于训练、AutoML 推荐、评估、推理、导出、TensorRT 引擎生成，以及会提交 TAO 容器的应用工作流。

凭据筛选

用户选择平台后，只获取该平台的凭据列表：

${TAO_SKILL_BANK_PATH:-~/tao-skills-external}/scripts/list_tao_platforms.py \
  --skill-bank ${TAO_SKILL_BANK_PATH:-~/tao-skills-external} \
  --platform <platform> --format text

只询问该命令返回的凭据，以及所选模型技能要求的特定模型凭据。在 SLURM、Kubernetes 或本地 Docker 上，不要询问 Lepton 凭据。在 Lepton、Brev、Kubernetes 或本地 Docker 上，不要询问 SLURM 凭据。只有当所选平台以及数据集／结果 URI 需要访问 s3:// 时，才询问 S3 凭据。

对于初始启动信息收集，只询问必需凭据和必需凭据组。将辅助工具输出中的可选凭据／设置部分作为参考资料；除非符合其 only_when 条件、所选工作流无法继续，或用户要求自定义该设置，否则不要索取这些值。

如果辅助工具输出中包含“必需凭据组”部分，则继续操作前，每组都必须满足一项凭据要求。根据辅助工具提供的说明和“获取方法”文本解释每项所需值。

对于 SLURM，面向用户的提示应先询问 SSH_KEY_PATH。只有当用户表示自己已在使用 SSH 代理时，才提及 SSH_AUTH_SOCK。

数据集信息收集

接受以下任一模式的数据集输入：

• 数据集根目录模式： 用户提供训练／评估／校准根目录，由模型技能按约定映射所需文件。例如，对于 Cosmos-RL 训练： custom.train_dataset.annotation_path=<root>/annotations.json 和 custom.train_dataset.media_path=<root>。
• 直接规格模式： 如果标注、媒体归档、视频或图像文件夹位于不同位置，用户提供确切的规格键路径。直接保留这些键，例如： custom.train_dataset.annotation_path=/lustre/.../train_annotations.json 和 custom.train_dataset.media_path=/lustre/.../videos.tar.gz。

请根据所选平台询问相应的数据集示例：

• SLURM：共享集群路径，例如 /lustre/fsw/portfolios/<team>/<your-dir>/data/<model>/train（其中 <your-dir> 是你在集群上的个人目录），或 /lustre/... 下的直接规格路径。
• Lepton、Brev、Kubernetes：通常使用 s3://bucket/path/train 和 s3://bucket/path/eval，除非平台配置文件挂载了共享存储。
• 本地 Docker：Docker 主机可见的本地路径，例如 /data/tao/<model>/train，或计划中的容器挂载内可见的直接规格路径。

不要假设“数据集根目录”是唯一可接受的输入。如果提供了直接规格路径，应验证确切的规格路径，而不是追加默认文件名。

平台预检

创建任何启动产物之前，先运行所选平台的预检。

所需输入可用时，优先使用打包的预检辅助工具：

${TAO_SKILL_BANK_PATH:-~/tao-skills-external}/scripts/check_tao_launch_preflight.py \
  --skill-bank ${TAO_SKILL_BANK_PATH:-~/tao-skills-external} \
  --platform <platform> \
  --path train_annotation=<path> \
  --path train_media=<path>

用户提供了确切的直接规范路径时，传入这些路径。对于根模式输入，先展开模型所需文件，再将具体的标注／媒体路径传给辅助工具。

当模型技能列出了标注级必填字段时，使用 --json-required-field <path-label>=<field>[,<field>...] 传入这些字段，以便在预检阶段发现架构／数据内容问题，而不是等到第一个训练容器启动后才发现。例如，Cosmos-RL train/AutoML 要求使用 --json-required-field train_annotation=video_fps 和 --json-required-field val_annotation=video_fps。

真实启动时，不要使用 --skip-platform-access。此标志仅用于干运行环境检查，或用户已提供平台和存储访问权限的明确手动证明时。如果辅助工具无法验证远程 API、CLI、集群或对象存储访问权限，则视为预检失败，不要生成启动产物。

对于 SLURM：

1. 必须提供 SLURM_USER、SLURM_HOSTNAME、SLURM_PARTITION，以及 SSH_KEY_PATH 或 SSH_AUTH_SOCK 其中之一。运行时值使用所选平台辅助工具的 Resource defaults。对于打包的 SLURM 默认值，生成启动器时使用 SLURM_TIME_HOURS=4 和 SLURM_TIMEOUT_HOURS=3.8；对于 4 小时的分区列表，绝不能擅自设置 12 小时的默认值。允许使用 nohup 或在后台启动编排器以确保其持续运行，但这本身不满足聊天监控要求。启动后，保持前台聊天侧轮询循环，直到任务进入终态或明确分离。
2. 拆分逗号分隔的 SLURM_HOSTNAME，尽可能解析主机，并要求至少有一台主机支持无密码 ssh -o BatchMode=yes。
3. 如果 SSH 失败，不要提供多个等效选项。要求用户提供 SSH_KEY_PATH=/path/to/private_key，并展示无密码设置步骤：如有需要，使用 ssh-keygen -t ed25519 -N "" -f ~/.ssh/id_ed25519 创建密钥；使用 ssh-copy-id -i ~/.ssh/id_ed25519.pub <SLURM_USER>@<login-host> 安装密钥；使用 ssh-keyscan -H <login-host> >> ~/.ssh/known_hosts 信任主机；设置 chmod 600 ~/.ssh/id_ed25519；使用 ssh -o BatchMode=yes -i ~/.ssh/id_ed25519 <SLURM_USER>@<login-host> 'hostname' 验证；然后使用 SSH_KEY_PATH=~/.ssh/id_ed25519 重新运行。
4. SSH 验证通过后，在远程登录主机上使用 test -e 或等效的只读命令验证数据集标注／媒体路径。
5. 只有完成上述步骤后，才能创建运行器脚本、规范、工作区或提交作业。

对于本地 Docker，在编写启动产物之前，先验证 Docker／GPU 访问权限和本地数据集路径。对于 Lepton、Brev 和 Kubernetes，在编写启动产物之前，先验证 API 或集群访问权限、对象存储凭据，以及 s3:// 输入的 aws s3 ls 可读性。对于这些远程平台上的已挂载共享存储或 PVC 路径，必须手动证明该路径已挂载到作业环境中；辅助工具会采取默认拒绝策略，不接受未经验证的远程挂载路径。