
名称	tao-run-platform
描述	TAO执行SDK，用于在支持的平台（Brev、SLURM、本地Docker、Kubernetes）上提交和监控GPU训练任务。当用户想要通过SDK运行TAO任务、获取任务跟踪、S3 I/O包装、多节点分布式训练或docker-run无法提供的平台特定功能时使用。触发短语包括“use the TAO SDK”、“call tao_sdk”、“AutoMLRunner”、“ActionWorkflow”、“Job handles”、“S3 I/O wrapping”、“TAO platform run”。
开源协议	Apache-2.0 compatibility: 需要Python 3.10+和nvidia-tao-sdk包（pip install nvidia-tao-sdk[all]）。 metadata:
作者	NVIDIA Corporation
版本	“0.1.0” allowed-tools: Read Bash tags: - platform - tao - sdk

TAO执行SDK

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

SDK是可选的Python层，适用于需要任务句柄、S3 I/O包装或平台特定功能（SLURM/Lustre队列、Kubernetes作业、本地Docker调试、Brev实例重用）的用户。大多数TAO技能仅使用docker run即可运行，不需要它。在以下情况下使用SDK：

您希望获得Job句柄以随时间轮询状态和流式日志。
您需要将S3感知的输入下载/输出上传内置到入口点中。
您正在链接多个作业并希望持久化状态。

预检

在使用此平台之前安装nvidia-tao-sdk[all]——[all]附加组件会拉取每个平台特定的依赖项（Brev、S3工具等）。如果缺少，默认在活动Python环境中安装它并重新运行导入检查：

python -c "import tao_sdk" 2>/dev/null || {
  echo "正在安装缺失的Python要求：nvidia-tao-sdk[all]"
  python -m pip install "nvidia-tao-sdk[all]"
}
python -c "import tao_sdk"

包索引是环境特定的——运行器/容器应具有可用的pip配置（例如~/.pip/pip.conf、PIP_INDEX_URL、PIP_EXTRA_INDEX_URL或代理）。如果由于索引/网络原因安装失败，那是运行器设置问题；本技能对注册表保持不可知。

默认情况下，缺失的pip要求会自动安装并在运行日志中报告。非pip/系统先决条件仍然需要正常的预检失败和用户可见的修复。

设置

凭据来自环境变量——从会话环境读取（在启动前在shell中导出它们）。

from tao_sdk.platforms.brev   import BrevSDK     # Brev GPU实例

sdk = BrevSDK()      # 读取BREV_API_TOKEN（可选——回退到brev login）

SDK在首次使用时惰性验证凭据，如果缺少必需的环境变量，则引发CredentialError并带有清晰的消息。必需的环境变量：

平台	必需	可选
Brev	—（手动`brev login`可行）	`BREV_API_TOKEN`
S3 I/O（任何平台）	`S3_BUCKET_NAME`, `ACCESS_KEY`, `SECRET_KEY`	`S3_ENDPOINT_URL`, `CLOUD_REGION`
容器环境	`NGC_KEY`	`HF_TOKEN`

代理从不读取凭据值——它仅检查存在性，使用[ -n "$VAR_NAME" ]。

工作流启动输入

对于任何TAO工作流或操作启动，首先确认用户目标。然后在凭据或启动细节之前询问平台和监控偏好。从打包的辅助程序生成支持的平台选择，而不是扫描平台文档或文件夹：

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

询问：

哪个受支持的平台应运行此工作流？
是否应保持长期运行的监控？默认：启用。这意味着代理保持连接并发布状态直到终端状态，包括长时间的PENDING队列等待。
状态更新之间间隔多少分钟？默认：5分钟。

在模型/操作已知后，从打包的元数据解析默认容器镜像，并要求用户确认或提供image=<override>，然后再创建运行器文件：

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

对于可训练模型的模型工作流，在创建普通训练作业之前检查模型级别的AutoML元数据：

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

如果所选模型具有automl_enabled: true和有效的训练模式，则默认通过skills/applications/tao-run-automl路由训练，并使用automl_policy: on。仅当其运行设置包含automl_policy: off、用户明确要求普通运行或模型元数据显示AutoML已启用但训练模式尚未打包时，工作流才应绕过AutoML。

选择平台后，获取凭据过滤器：

${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需要SLURM_USER和SLURM_HOSTNAME；它不需要Brev凭据。Kubernetes和本地Docker不需要Brev或SLURM凭据。仅当所选平台和数据/结果URI需要时，才询问存储凭据（如S3密钥）。

核心API

所有平台SDK实现相同的核心形状：

sdk.create_job(image, command, gpu_count=1, env_vars=None, inputs=None, outputs=None, **kwargs) -> Job
sdk.get_job_status(job_id) -> JobStatus
sdk.get_job_logs(job_id, tail=None) -> str
sdk.cancel_job(job_id) -> bool
sdk.get_failure_analysis(job_id) -> dict | None
sdk.get_job_results_dir(job_id) -> str
sdk.check_path(remote_path) -> bool
sdk.list_path(remote_path) -> list[str]

仅Brev：

sdk.delete_instance(instance_id) — 清理临时实例。
sdk.list_instances() — 列出活动实例。

提交作业

代理在调用create_job之前总是通过build_entrypoint构造容器命令。代理从skill_info.yaml读取操作的模式（command、mode、config_format、inputs、outputs、upload_excludes）并将这些字段作为kwargs传递。build_entrypoint然后烘焙：

容器内的script_runner运行时（内联为base64 heredoc——容器中无需安装tao_sdk）。
在容器运行时执行的CLI调用，它将：下载声明的输入（S3 / HF-Hub / NGC），在{config_path}处写入规范文件，并将远程URI重写为本地路径，运行用户命令，并上传输出。

输出目的地从SDK注入的环境变量在运行时解析（参见“输出去向”）。平台SDK的create_job原样运行生成的命令——没有inputs/outputs kwargs，没有隐式包装。数据流在代理的代码中可见。

输出去向（运行时解析——代理不管理）

SDK注入TAO_JOB_ID（匹配Job.id），当附加持久挂载时，注入TAO_RESULTS_ROOT到容器环境。在容器内部，script_runner解析输出目的地：

容器环境	结果
设置`TAO_RESULTS_ROOT`（Lustre / PVC / bind / NFS）	输出在`{TAO_RESULTS_ROOT}/<job_id>/<key>/`；不上传
设置`S3_BUCKET_NAME`（云，无挂载）	输出在`s3://{bucket}/results/<job_id>/<key>/`；运行结束时上传
两者都不	输出在`/results/<job_id>/<key>/`（容器临时）并带有响亮的结束警告

各平台策略：

SDK	注入的内容
`SlurmSDK`	`TAO_RESULTS_ROOT={SLURM_BASE_RESULTS_DIR}/results`（始终——Lustre，从不S3，避免GPU空闲调度程序杀死）
`KubernetesSDK` / `DockerSDK` / `BrevSDK`	如果挂载目标为`/results`，则`TAO_RESULTS_ROOT=/results`；否则回退到S3

希望自定义目的地的代理可以直接在输出规范键处放置s3://... URI或绝对路径——显式值覆盖自动填充。否则，像cosmos-rl的output_dir: "output"或DINO的空results_dir这样的模型自然默认值会被script_runner自动重写。

规范是嵌套字典，而不是扁平的点分隔键

这是构建规范时最常见的错误。skill_info.yaml的inputs: / outputs:块中出现的点符号（例如section.subsection.key）是进入嵌套规范的路径——script_runner在该路径查找值。它不是规范本身的形状。规范镜像模型容器期望的任何形状（通常是嵌套的TOML/YAML）。

# ✓ 正确——嵌套字典
specs = {
    "section": {
        "subsection": {"key": "value"},
    },
}

# ✗ 错误——带有点的扁平顶级键。TOML/YAML将其作为带引号的裸字符串键发出，模型看到空的`section`表，
# 并且任何在"section.subsection.key"声明的输入都会静默地无法下载，因为_get_nested(specs, "section.subsection.key") → None。
specs = {
    "section.subsection.key": "value",
}

这两种形状看起来相似但含义不同。如有疑问，请打开模型的references/目录（例如默认规范TOML或YAML）——这是规范字典需要镜像的字面嵌套结构。skill_info.yaml中的inputs: / outputs:声明是进入嵌套规范的路径，而不是键名。

构建规范 / 参数

技能的操作在skill_info.yaml的actions.<action>.mode字段中声明其配置机制。将缺失的mode视为无效元数据并修复技能，而不是推断默认值。首先读取actions.<action>.mode，然后将匹配的参数形状传递给build_entrypoint：

声明的模式	代理传递的内容
`config`	`specs=...`，带有规范键的`inputs` / `outputs`；辅助程序写入规范文件，重写URI，并运行命令
`args`	`args=...`，带有可选的规范键`inputs` / `outputs`；辅助程序将CLI参数替换到命令模板中
`passthrough`	路径键的`inputs=...`和/或`outputs=...`；辅助程序下载到列出的路径，运行命令，并上传列出的输出

不要从缺失的元数据推断模式。缺失mode意味着技能契约已过时。

参见references/spec-construction.md了解每种模式的构建策略、推荐的决策顺序以及针对规范驱动作业（配置文件）和路径键作业（无配置文件）的build_entrypoint示例。

解析容器镜像

技能通过键（tao_toolkit.pyt）或绝对URI（nvcr.io/...）声明镜像。使用resolve_container_image()来处理两者：

from tao_sdk.versions import resolve_container_image
image = resolve_container_image(skill_info["container_image"])

在幕后，它遍历versions.yaml以获取键；绝对URI原样返回。

监控

status = sdk.get_job_status(job.id)
print(status.status)   # Pending, Running, Complete, Error, Canceled
print(status.message)  # 平台特定细节

logs = sdk.get_job_logs(job.id, tail=200)
print(logs)

失败时，get_failure_analysis()对根本原因进行分类：

analysis = sdk.get_failure_analysis(job.id)
if analysis:
    print(analysis["err_class"])   # ERR_PROGRAM, ERR_INFRA等
    print(analysis["suggestion"])  # 人类可读的修复
    for event in analysis.get("job_failure_by_node_event", []):
        print(event["node_event_name"], event["message"])  # OOM, GPU错误等

轮询模式

对于用户想要观看的交互式运行：

import time
status_interval_minutes = status_interval_minutes or 5
while True:
    status = sdk.get_job_status(job.id)
    if status.status in ("Complete", "Error", "Canceled"):
        break
    print(f"  {status.status}")
    time.sleep(status_interval_minutes * 60)

if status.status == "Error":
    print(sdk.get_job_logs(job.id, tail=100))
    print(sdk.get_failure_analysis(job.id))

启用长期运行的监控后，不要在30分钟后或在几次未更改的轮询后停止。每status_interval_minutes持续发出更新，直到作业完成、失败、被取消或用户要求分离/停止。如果聊天/运行时不能保持那么久，请明确说明并提供持久的工作流/日志路径以进行手动状态刷新。

不要将最终响应用于非终态的监控作业。完成轮询回合会分离聊天观察者。保持非终态状态消息作为进行中更新，并继续轮询；仅在终态、用户明确分离/停止或阻止进一步轮询的实际运行时限制时才最终完成。

对于后台运行，持久化job.id和state_file路径，然后通过构建相同的SDK并调用get_job_status(job_id)稍后重新连接——作业状态从磁盘存储中读取。

编排模式

多步骤工作流、并行扫描和通过ActionWorkflow的文件夹耐久性位于references/orchestration-patterns.md。在链接create_job调用、扫描参数或跨上下文中断持久化运行状态之前，请阅读它。

数据集工具

当技能文档的文件名与用户的布局不匹配时，列出数据集以确认：

assert sdk.check_path("s3://my-bucket/coco/")
files = sdk.list_path("s3://my-bucket/coco/train/")
# 使用实际路径设置规范字段。

对于S3路径，连接时去除尾部斜杠以避免//：

base = dataset_uri.rstrip("/")
specs["dataset"]["train_csv"] = f"{base}/train.csv"   # 嵌套——参见"规范是嵌套字典"

平台特定说明

参见references/platform-notes.md了解各平台行为、kwargs和凭据范围：Brev（instance_id/gpu_type/cloud_cred_id/workspace_group_id、就绪等待超时）、SLURM（通过SSH的sbatch、Lustre路径、队列默认值）、Kubernetes（kubeconfig、GPU Operator）和本地Docker（单主机、多GPU）。

错误模式

SDK错误→根本原因→修复映射在references/error-patterns.md。当遇到CredentialError、镜像拉取失败、卡在Pending的作业或类似情况时阅读——条目将异常文本映射到根本原因。

SDK不做什么

SDK不读取/解释技能、不自行运行AutoML、不决定规范内容、不选择平台或不编排多步骤工作流——这些仍然是代理的责任。参见references/scope.md了解完整的范围护栏，包括模型级别的AutoML策略（automl_enabled: true → skills/applications/tao-run-automl，除非automl_policy: off或用户要求普通单次运行）。