tao-run-platform

TAO 执行 SDK

对于需要作业句柄、S3 I/O 封装或特定平台功能（Lepton 多节点、SLURM/Lustre 队列、Kubernetes Jobs、本地 Docker 调试、Brev 实例复用）的用户，SDK 是一个可选的 Python 层。大多数 TAO 技能只需运行 docker run，不需要 SDK。以下情况适合使用 SDK：

• 你希望使用 Job 句柄轮询状态并持续获取日志。
• 平台仅提供 API（Lepton 没有与 docker run 等效的方式）。
• 你需要在入口点中集成 S3 输入下载／输出上传。
• 你要串联多个作业，并希望保存状态。

运行前检查

使用此平台前，请安装 nvidia-tao-sdk[all]——[all] 扩展会引入所有特定于平台的依赖项（Lepton、Brev、S3 工具等）：

python -c "import tao_sdk" 2>/dev/null || {
  echo "MISSING: nvidia-tao-sdk not installed. Run:"
  echo "  pip install nvidia-tao-sdk[all]"
  exit 1
}

软件包索引因环境而异——预期运行器／容器已配置可用的 pip（例如 ~/.pip/pip.conf、PIP_INDEX_URL、PIP_EXTRA_INDEX_URL 或代理）。如果因索引／网络问题导致安装失败，这是运行器配置问题；此技能不绑定任何软件源。

如果未安装，Agent 会提示用户通过 Bash 授权安装，然后重新运行运行前检查。绝不静默自动安装。

设置

凭据来自环境变量——从 ~/.config/tao/.env 加载（由技能库的 SessionStart hook 自动加载）。

from tao_sdk.platforms.lepton import LeptonSDK   # DGX Cloud
from tao_sdk.platforms.brev   import BrevSDK     # Brev GPU instances

sdk = LeptonSDK()    # reads LEPTON_WORKSPACE_ID, LEPTON_AUTH_TOKEN
# or
sdk = BrevSDK()      # reads BREV_API_TOKEN (optional — falls back to brev login)

两个 SDK 都会在首次使用时延迟验证凭据；如果缺少必需的环境变量，会抛出 CredentialError 并显示清晰的错误消息。必需的环境变量：

平台	必需	可选
Lepton	LEPTON_WORKSPACE_ID、LEPTON_AUTH_TOKEN	—
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

Agent 绝不会读取凭据值——只会使用 [ -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

询问：

1. 此工作流应在哪个支持的平台上运行？
2. 是否应保持启用长时间运行监控？默认：启用。这意味着 Agent 会持续连接并发布状态，直至进入终止状态，包括在 PENDING 队列中长时间等待的情况。
3. 状态更新之间间隔多少分钟？默认：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: 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，不需要 Lepton 凭据。Kubernetes 和本地 Docker 不需要 Lepton 或 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]

仅限 Lepton：

• sdk.get_job_replicas(job_id) — 为卡在待处理状态的作业提供副本级诊断信息。

仅限 Brev：

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

提交作业

Agent 在调用 create_job 之前，始终会通过 build_entrypoint 构建容器命令。Agent 会从 skill_info.yaml 读取操作的架构（command、config_format、inputs、outputs、upload_excludes），并将这些字段作为 kwargs 传入。build_entrypoint 会内置容器中的 script_runner 运行时（以 base64 heredoc 形式内联）以及 CLI 调用。运行时会下载声明的输入，将远程 URI 重写为本地路径后，把规格文件写入 {config_path}，运行用户命令并上传输出。平台 SDK 的 create_job 会原样运行生成的命令，不会隐式添加包装。

build_entrypoint 会根据你传入的内容推断模式（config / args / passthrough）——无需显式传入 mode。完整的入口点约定、每种操作 mode 对应的规格/参数构建策略、模式推断表以及 resolve_container_image()，请参阅 references/job-construction.md。关于输出的存放位置（运行时目标表和各平台注入策略）以及重要规则“规格是嵌套字典，而不是扁平的点分键”，请参阅 references/outputs.md。完整的规格驱动和路径键控 build_entrypoint + create_job 示例，请参阅 references/examples.md。

监控

status = sdk.get_job_status(job.id)
print(status.status)   # Pending, Running, Complete, Error, Canceled
print(status.message)  # platform-specific detail

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

对于卡在 Pending 状态的 Lepton 作业，副本诊断信息可以揭示原因（镜像拉取、调度、挂载错误）：

for r in sdk.get_job_replicas(job.id):
    issue = r["status"].get("readiness_issue")
    if issue:
        print(issue["reason"], issue["message"])
        # e.g. "InProgress" / "Pulling image"  (normal for big images)
        #      "Failed"     / "ImagePullBackOff" (NGC_KEY problem)
        #      "ConfigError" / "Mount point not found" (bad node)

发生故障时，get_failure_analysis() 会对根本原因进行分类：

analysis = sdk.get_failure_analysis(job.id)
if analysis:
    print(analysis["err_class"])   # ERR_PROGRAM, ERR_INFRA, etc.
    print(analysis["suggestion"])  # human-readable fix
    for event in analysis.get("job_failure_by_node_event", []):
        print(event["node_event_name"], event["message"])  # OOM, GPU error, etc.

轮询模式

对于用户希望查看进度的交互式运行：

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/")
# Use the actual paths to set spec fields.

对于 S3 路径，拼接时请移除末尾斜杠，以避免出现 //：

base = dataset_uri.rstrip("/")
specs["dataset"]["train_csv"] = f"{base}/train.csv"   # nested — see "spec is nested dicts"

平台特定说明

每种后端（Lepton、Brev、SLURM、Kubernetes、本地 Docker）都有各自的导入路径、存储模型、分布式训练选项、凭证范围和 create_job kwargs。为特定后端生成或启动运行器工件之前，请参阅 references/platform-notes.md 了解各平台的详细信息。

错误模式

SDK 错误 → 根本原因 → 修复方法的映射见 references/error-patterns.md。遇到 CredentialError、镜像拉取失败、作业卡在 Pending 状态或类似问题时，请阅读此文档——其中的条目会将异常文本映射到根本原因。

SDK 不会做什么

关于范围限制（不读取技能、不执行 HPO、不对规格发表意见、不自动选择平台、不编排工作流），请参阅 references/scope.md。