alibabacloud-pai-dlc-job：分布式训练 DLC（Deep Learning Containers）任务 API 相关能力。包括任务的创建、查询、更新和删除，以及任务相关事件、日志的查询等操作。

PAI-DLC 深度学习任务管理

在阿里云 PAI-DLC（人工智能平台 - 深度学习容器）服务上管理深度学习训练任务。

场景说明

PAI-DLC 是阿里云人工智能平台 PAI 提供的分布式训练服务，支持：

• 任务创建与执行 —— 为 TensorFlow、PyTorch、XGBoost 等框架创建分布式训练任务
• 任务监控 —— 获取任务状态、日志、事件和监控指标
• 计算健康检查 —— 检查 GPU 及其他计算设备的健康状态
• 任务管理 —— 更新和停止任务

架构：PAI 工作空间 + DLC 任务 + 计算资源（ECS 公共按量付费或灵骏专属配额）+ AIWorkSpace 目录（镜像 / 数据集 / 代码源 / 配额 / 工作空间）。

安装要求

前置检查：需要 Aliyun CLI >= 3.3.1
运行 aliyun version 确认版本 >= 3.3.1。若未安装或版本过低，
见 references/cli-installation-guide.md 获取安装说明。
然后 [必须] 运行 aliyun configure set --auto-plugin-install true 启用插件自动安装。

关于 --user-agent： 本 Skill 中每条调用 API 的 aliyun 命令都必须包含 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job/${SESSION_ID}（统一 User-Agent + session-id 模板——生成规则见可观测性）。客户端辅助命令（aliyun version、aliyun configure ...、aliyun plugin ...、aliyun <product> --help）不调用远程 API，因此不需要该标志。

网络超时与重试（--help 不强制执行的规则）： aliyun CLI 默认 10 秒连接 / 10 秒读取且无重试。对于长时间运行的流程（大型列表、慢地域），通过全局标志显式提高 --connect-timeout 15 --read-timeout 30 --retry-count 2。对于用户确认的高风险调用（stop-job / delete-*），绝不依赖默认值。

aliyun version
aliyun configure set --auto-plugin-install true
aliyun pai-dlc --help
aliyun aiworkspace --help >/dev/null 2>&1 || aliyun plugin install --names aliyun-cli-aiworkspace
aliyun plugin update

可观测性

原因： 本 Skill 发出的每次 PAI-DLC API 调用都必须携带统一 User-Agent，以便平台侧追踪可将请求归属到本 Skill，并关联单个 agent 会话内的所有调用。

User-Agent 模板

每条调用 API 的 aliyun 命令都必须传：

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job/{session-id}

• 前缀 AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job 固定——绝不要改动。
• {session-id} 是按下方规则生成的每会话标识符。
• 客户端辅助命令（aliyun version、aliyun configure ...、aliyun plugin ...、aliyun <product> --help）不调用远程 API，因此不需要该标志。

session-id 生成规则

1. 在 Skill 会话开始时、第一次 API 调用之前，生成 session-id 一次。
2. 格式：小写、无空格、无斜杠。推荐 uuidgen | tr 'A-Z' 'a-z' 或 $(date +%s)-$RANDOM。
3. 会话中每条命令都复用同一 session-id —— 绝不逐调用重新生成。这让追踪能把一次会话的所有调用归为一组。
4. 导出一次，并在每次 API 调用中引用该 shell 变量：

SESSION_ID=$(uuidgen | tr 'A-Z' 'a-z')
export SESSION_ID

之后每条调用 API 的命令都追加：

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job/${SESSION_ID}

aliyun pai-dlc list-jobs --region <r> \

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job/${SESSION_ID}

> **不要使用 `aliyun configure ai-mode`** 设置 User-Agent。该模式对 skills 已废弃。始终按命令显式传 `--user-agent` 配 session-id 模板，使每个会话可独立追踪。

环境变量

本 Skill 不需要任何自定义环境变量。凭证由阿里云 CLI 配置处理（见下方鉴权）。可选：

不要在本会话内导出 ALIBABA_CLOUD_ACCESS_KEY_ID / ALIBABA_CLOUD_ACCESS_KEY_SECRET；在会话之外配置它们（aliyun configure 或 shell profile）。

鉴权配置

前置检查：需要阿里云凭证
安全规则：
- 绝不读取、回显或打印 AK/SK 值（例如 echo $ALIBABA_CLOUD_ACCESS_KEY_ID 是禁止的）
- 绝不要求用户在对话或命令行中直接输入 AK/SK
- 绝不使用字面凭证值运行 aliyun configure set
- 只使用 aliyun configure list 检查凭证状态
```bash
aliyun configure list
```
检查输出中是否有有效 profile（AK、STS 或 OAuth 身份）。
如果不存在有效 profile，就此停止。
1. 从阿里云控制台获取凭证
2. 在本会话之外配置凭证（通过终端中的 aliyun configure 或 shell profile 中的环境变量）
3. 待 aliyun configure list 显示有效 profile 后再返回并重试

RAM 权限

[必须] 权限失败处理： 当任何命令或 API 调用在执行过程中因权限错误失败时，遵循以下流程：
1. 阅读 references/ram-policies.md 获取本 Skill 所需的完整权限列表
2. 使用 ram-permission-diagnose skill 引导用户申请必要权限
3. 暂停并等待用户确认所需权限已授予

详细权限列表见 references/ram-policies.md。

所需权限概览：

AIWorkSpace 授权说明： create-job 的 Image / DataSourceId / CodeSourceId / WorkspaceId 字段值来自 AIWorkSpace 资源发现 API。--resource-id（QuotaId）由用户手动提供。RAM 用户必须持有上方列出的相应 AIWorkSpace 命名空间权限（不要缩写为 aiworkspace:*）。

参数确认

权威参数参考是 aliyun pai-dlc <cmd> --help（每次调用前必读）。本 Skill 只记录 --help 不告诉你的内容：跨字段规则、跨产品依赖、隐藏行为、业务标签和拒绝模式。当下方规则与 --help 冲突时，原因已内联说明。
调用前确认： 所有用户可自定义的值（地域、名称、CIDR、规格等）都必须与用户确认——绝不假设默认值。

覆盖 --help 的硬性规则

跨字段互斥（--help 无法捕获）

• EcsSpec ⇄ ResourceConfig —— 在单个 TaskSpec 内，只能选其一。
• Uri ⇄ DataSourceId —— 在 --data-sources[] 内。
• Uri ⇄ CodeSourceId —— 在 --code-source 内。

--job-type —— 各框架的 Worker Type 提示

--help 逐字列出 9 个合法枚举值。--help 没告诉你的是各框架期望哪些 JobSpecs[].Type 角色：

大小写敏感，无别名。 tensorflow、pytorch、tf-job、Pytorch、PYTORCH_JOB、Custom、CustomJob —— 全部被拒绝。
无 Custom 枚举。 对于单容器自定义工作负载，映射到 PyTorchJob（角色集最宽松）。
创建后锁定： JobType 无法通过 update-job 更改。

完整字段参考：见 references/related-apis.md。

核心工作流

7.1 资源选择决策指南

调用 create-job 前，确定资源路径：

• 公共按量付费 → 在 TaskSpec 中使用 EcsSpec；不要传 --resource-id。
• 用例：快速开始、测试、无专属配额。
• 示例："EcsSpec": "ecs.gn6i-c4g1.xlarge"
• 专属配额（灵骏 / 企业配额） → 在 TaskSpec 中使用 ResourceConfig 并传 --resource-id <QuotaId>。
• 用例：专属资源组、灵骏智能计算、Spot 竞价。
• 示例：--resource-id quotaXXX + "ResourceConfig": {"CPU": "4", "Memory": "8Gi", "GPU": "1"}

EcsSpec 和 ResourceConfig 不得同时出现在同一 TaskSpec 中。

create-job 前还需要： --job-specs[].Image 必须来自 aliyun aiworkspace list-images；--data-sources[].DataSourceId 来自 list-datasets；--code-source.CodeSourceId 来自 list-code-sources。完整发现流程 → 见 §7.6。

分布式架构选择：

可选标志：--enable-gang-scheduling true（全有或全无调度）、Settings.EnableRDMA: true（多节点 GPU 高性能网络）、Settings.EnableSanityCheck: true（GPU 健康验证）。

下方所有命令都需要 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job/${SESSION_ID}（为简洁在片段中省略——见可观测性）。

7.2 创建训练任务

最小单节点 PyTorch 任务（公共按量付费）参数组合：

aliyun pai-dlc create-job --region <region> --workspace-id <ws-id> \
  --display-name "my-pytorch-training" --job-type PyTorchJob \
  --job-specs '[{"Type":"Worker","PodCount":1,"Image":"<ImageUri>","EcsSpec":"ecs.gn6i-c4g1.xlarge"}]' \
  --user-command 'python train.py' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job/${SESSION_ID}

多节点 / Spot / RDMA / 数据挂载——用 create-job --help。后续片段为简洁省略 --user-agent——始终要包含它。

7.3 列出 / 获取任务

用 --cli-query 投影特定字段（对日志 / 事件流程至关重要）：

aliyun pai-dlc list-jobs --region <region> --status Running
aliyun pai-dlc get-job  --region <region> --job-id <id>
aliyun pai-dlc get-job  --region <region> --job-id <id> --cli-query "Pods[0].PodId"

7.4 日志与事件

始终限制返回大小： --max-lines 100（日志）、--max-events-num 50（事件）。

先获取 PodId，再查询日志 / 事件：

POD_ID=$(aliyun pai-dlc get-job --region <r> --job-id <id> --cli-query "Pods[0].PodId")
aliyun pai-dlc get-pod-logs    --region <r> --job-id <id> --pod-id $POD_ID --max-lines 100
aliyun pai-dlc get-pod-events  --region <r> --job-id <id> --pod-id $POD_ID --max-events-num 20
aliyun pai-dlc get-job-events  --region <r> --job-id <id> --max-events-num 50

诊断顺序： get-job（状态）→ get-job-events → get-pod-logs → get-pod-events。

7.5 计算健康检查

aliyun pai-dlc list-job-sanity-check-results --region <r> --job-id <id>
aliyun pai-dlc get-job-sanity-check-result   --region <r> --job-id <id> --sanity-check-number 1

7.6 创建前资源发现（AIWorkSpace）

发现流程： list-workspaces → list-image-labels → list-images → list-datasets → list-code-sources → pai-dlc create-job。

配额（--resource-id）： 用户提供。无 CLI 发现步骤。

aliyun aiworkspace list-workspaces     --region <r>                        # → --workspace-id
aliyun aiworkspace list-image-labels   --region <r>                        # → 合法 label Key=Value 对
aliyun aiworkspace list-images         --region <r> --labels "K1=V1,K2=V2" # → --job-specs[].Image（逐字使用 ImageUri）
aliyun aiworkspace list-datasets       --region <r> --workspace-id <ws>    # → DataSources[].DataSourceId
aliyun aiworkspace list-code-sources   --region <r> --workspace-id <ws>    # → CodeSource.CodeSourceId

标签规则（--help 中没有）：逗号分隔的 Key=Value 对，无 JSON / 无空格。值必须来自 list-image-labels——绝不臆造。发现官方公共镜像时（它们是全局的），不要给 list-images 传 --workspace-id。仅当过滤限定到特定工作空间的自定义 / 私有镜像时才传 --workspace-id。
红线： --job-specs[].Image 必须是逐字的 ImageUri（不是 Name / ImageId）。

字段映射、完整参数和错误码：见 references/related-apis.md 和 references/verification-method.md。

7.7 任务生命周期管理（停止 / 更新 / Web 终端）

停止是高风险操作。继续前，用 get-job 查询状态，向用户呈现结果，并要求明确确认。

--help 没告诉你的规则（update-job 静默无效家族）：
- 停止任务仅在状态为 Running 或 Queuing 时适用。
- update-job --priority 仅在 (a) 任务使用配额资源（--resource-id）且 (b) 状态为 Creating、Queuing 或 EnvPreparing 时生效。一旦任务进入 Running 或更后阶段，优先级无法修改——API 返回 200 OK 但变更静默未应用。始终用 get-job 预检状态。
- update-job --accessibility 在任何状态下立即生效。
- update-job 不暴露 --display-name（--help 只列出 --job-id、--accessibility、--description、--job-specs、--priority）。要重命名任务，需重建它。

完整的预检 + 确认 + 执行模板，以及 update-job 低风险路径和 get-web-terminal / get-token 分享命令，见 references/job-management.md。

7.8 Ecs Spec 发现

发现可用实例类型；返回的 EcsSpec 值逐字进入 --job-specs[].EcsSpec。

aliyun pai-dlc list-ecs-specs --region <r> --accelerator-type GPU --resource-type ECS --page-size 20

灵骏专属：--quota-id <id>（仅白名单用户）

> **`list-ecs-specs` 不支持 `--sort-by`** —— 即使 `--help` 中显示为合法的值（例如 `CPU` / `GPU` / `Memory` / `GmtCreateTime`）也会被服务端拒绝。在此始终省略 `--sort-by`，用 `jq` 在客户端对 JSON 输出排序——例如 `... | jq '.EcsSpecs | sort_by(-.AcceleratorNumber)'`。

成功验证方法

分步端到端验证脚本（资源发现 → CreateJob → 日志查询 → 清理），见 references/verification-method.md。

快速验证：

• get-job → create-job 返回后不久状态应为 Creating / Queuing / Running。
• list-jobs --status Running → 应返回刚创建的任务直到它完成或被停止。
• get-pod-logs → Pod 过了 EnvPreparing 后应返回非空日志内容。

命令表

完整命令索引（5 大类 × 约 40 条命令，含插件归属）合并于 references/related-apis.md §1。

最佳实践

以下条目是决策规则和操作习惯——不是参数值（那些在 --help 中）。

1. 任务命名 —— 使用有意义、可排序的名称：project-model-date（例如 resnet50-imagenet-20260320）。重建（而非 update-job）是重命名的唯一方式。
2. 资源规格 —— 按模型和数据集大小选 GPU 类型 / 数量。选定 EcsSpec 之前用 list-ecs-specs --accelerator-type GPU 验证可用性（见 §7.8）。
3. 尽早诊断 —— 遵循顺序 get-job → get-job-events → get-pod-logs → get-pod-events。限制响应（--max-lines 100、--max-events-num 50）以保持 agent 上下文精简。
4. 优先级调整 —— 优先在 create-job 时设置 --priority。创建后的 update-job --priority 仅对 Creating / Queuing / EnvPreparing 阶段的配额任务有效（§7.7）；一旦 Running，优先级无法修改。
5. 成本控制 —— 对每个长时间运行的实验用 --job-max-running-time-minutes 作为自动停止护栏。通过 SpotSpec 使用 Spot 可降低成本但有被抢占风险。
6. 健康检查 —— 对 GPU 训练启用 Settings.EnableSanityCheck: true，在训练开始前捕获故障设备。
7. 资源清理 —— 对已完成任务执行 stop-job 以释放配额。
8. 写入幂等性 —— PAI-DLC create-* API 不暴露 --client-token（已通过 aliyun pai-dlc create-job --help 验证）。因此网络重试可能创建重复任务。缓解措施：在重新发出失败的 create-* 之前，运行 list-jobs --display-name <name> 检测半提交的先前尝试。

参考链接