alibabacloud-pai-dlc-job

PAI-DLC 深度学习作业管理

在 Alibaba Cloud PAI-DLC（Platform for AI - Deep Learning Containers）服务上管理深度学习训练作业。

场景说明

PAI-DLC 是 Alibaba Cloud AI Platform PAI 提供的分布式训练服务，支持：

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

架构：PAI Workspace + DLC Job + 计算资源（ECS 公共按量付费或 Lingjun 专属配额）+ 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 的说明：**此技能中每条调用 API 的 aliyun 命令都必须包含 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job/${SESSION_ID}（统一的 User-Agent + 会话 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

可观测性

**原因：**此技能发出的每次 PAI-DLC API 调用都必须携带统一的 User-Agent，以便平台侧跟踪能够将请求归因于此技能，并关联单个 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. 在技能会话开始时、首次 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
# every API-invoking command then appends:
#   --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。该模式已不再适用于技能。始终在每条命令中显式传入 --user-agent，并使用会话 ID 模板，以便独立跟踪每个会话。

## Environment Variables

This skill does not require any custom environment variables. Credentials are handled
by the Alibaba Cloud CLI configuration (see Authentication below). Optionally:

| Variable | Required | Purpose |
|----------|----------|---------|
| `ALIBABA_CLOUD_PROFILE` | Optional | Selects a non-default `aliyun configure` profile |
| `ALIBABA_CLOUD_REGION_ID` | Optional | Default region when `--region` is omitted (still recommended to pass `--region` explicitly) |

Do NOT export `ALIBABA_CLOUD_ACCESS_KEY_ID` / `ALIBABA_CLOUD_ACCESS_KEY_SECRET` from
within this session; configure them outside (`aliyun configure` or shell profile).

## Authentication Configuration

> **Pre-check: Alibaba Cloud Credentials Required**
>
> **Security Rules:**
> - **NEVER** read, echo, or print AK/SK values (e.g., `echo $ALIBABA_CLOUD_ACCESS_KEY_ID` is FORBIDDEN)
> - **NEVER** ask the user to input AK/SK directly in the conversation or command line
> - **NEVER** use `aliyun configure set` with literal credential values
> - **ONLY** use `aliyun configure list` to check credential status
>
> ```bash
> aliyun configure list
> ```
> Check the output for a valid profile (AK, STS, or OAuth identity).
>
> **If no valid profile exists, STOP here.**
> 1. Obtain credentials from [Alibaba Cloud Console](https://ram.console.aliyun.com/manage/ak)
> 2. Configure credentials **outside of this session** (via `aliyun configure` in terminal
>    or environment variables in shell profile)
> 3. Return and re-run after `aliyun configure list` shows a valid profile

## RAM Permissions

> **[MUST] Permission Failure Handling:** When any command or API call fails due to
> permission errors at any point during execution, follow this process:
> 1. Read `references/ram-policies.md` to get the full list of permissions required by this SKILL
> 2. Use `ram-permission-diagnose` skill to guide the user through requesting the necessary permissions
> 3. Pause and wait until the user confirms that the required permissions have been granted

For detailed permission list, see [references/ram-policies.md](references/ram-policies.md).

**Required Permissions Overview:**

| Operation | Required Permission |
|-----------|---------------------|
| Create Job | `pai:CreateJob` |
| List Jobs | `pai:ListJobs` |
| Get Job Details | `pai:GetJob` |
| Get Pod Logs | `pai:GetPodLogs` |
| Get Job Events | `pai:GetJobEvents` |
| Update Job | `pai:UpdateJob` |
| Stop Job | `pai:StopJob` |
| AIWorkSpace Resource Discovery | `paiworkspace:ListWorkspaces` / `paiimage:ListImages,GetImage` / `paidataset:ListDatasets,GetDataset` / `paicodesource:ListCodeSources,GetCodeSource` |

> **AIWorkSpace authorization note:** `Image` / `DataSourceId` / `CodeSourceId` /
> `WorkspaceId` field values for `create-job` come from the
> AIWorkSpace resource-discovery APIs. `--resource-id` (QuotaId) is manually provided by the user.
> RAM users MUST hold the corresponding
> AIWorkSpace-namespaced permissions listed above (do not abbreviate as `aiworkspace:*`).

## Parameter Confirmation

> **Authoritative parameter reference is `aliyun pai-dlc <cmd> --help`** (must-read
> before every call). This skill only documents what `--help` does **not** tell
> you: cross-field rules, cross-product dependencies, hidden behaviors, business
> labels, and reject patterns. Whenever a rule below contradicts `--help`, the
> reason is stated inline.
>
> **Confirm before call:** all user-customizable values (region, names, CIDR,
> specs, etc.) MUST be confirmed with the user — never assume defaults.

### Hard rules that override `--help`

| Rule | Why this skill overrides `--help` |
|------|-----------------------------------|
| `--workspace-id` is **always required** | `--help` marks it optional, but server silently falls back to the user's **default workspace** if omitted → job often lands in the wrong workspace. Always confirm with user. |
| `--job-specs[].Image` MUST be a verbatim `ImageUri` from `aiworkspace list-images` | Cross-product contract; `--help` only describes the field type. See §7.6 red line. |
| `--data-sources[].DataSourceId` from `aiworkspace list-datasets`; `--code-source.CodeSourceId` from `list-code-sources` | Cross-product discovery; `--help` cannot point you to the source product. |
| `--resource-id` (QuotaId) is **manually supplied** | No CLI discovery step. |

### Cross-field mutual exclusion (`--help` cannot catch these)

- `EcsSpec` ⇄ `ResourceConfig` — within a single TaskSpec, pick exactly one.
- `Uri` ⇄ `DataSourceId` — within `--data-sources[]`.
- `Uri` ⇄ `CodeSourceId` — within `--code-source`.

### `--job-type` — Worker `Type` hints per framework

`--help` lists the 9 legal enum values verbatim. What `--help` doesn't tell you
is which `JobSpecs[].Type` roles each framework expects:

| `--job-type` | Valid `JobSpecs[].Type` roles |
|---|---|
| `TFJob` | `Chief` / `PS` / `Worker` / `Evaluator` / `GraphLearn` |
| `PyTorchJob` | `Worker` (+ optional `Master`, auto-promoted) |
| `MPIJob` | `Worker` + `Master` |
| `XGBoostJob` / `OneFlowJob` / `ElasticBatchJob` | `Worker` + optional `Master` |
| `RayJob` | `Worker` |
| `SlurmJob` / `DataJuicerJob` | framework-specific roles |

> **Case-sensitive, no aliases.** `tensorflow`, `pytorch`, `tf-job`, `Pytorch`,
> `PYTORCH_JOB`, `Custom`, `CustomJob` — all rejected.
>
> **No `Custom` enum.** For single-container custom workloads, map to
> `PyTorchJob` (most permissive role set).
>
> **Locked after create:** `JobType` cannot be changed via `update-job`.

Full field reference: see [references/related-apis.md](references/related-apis.md).

## Core Workflows

### 7.1 Resource Selection Decision Guide

Before calling `create-job`, determine the resource path:

- **Public pay-as-you-go** → Use `EcsSpec` in TaskSpec; do NOT pass `--resource-id`.
  - Use cases: quick start, testing, no dedicated quota.
  - Example: `"EcsSpec": "ecs.gn6i-c4g1.xlarge"`
- **Dedicated quota** (Lingjun / enterprise quota) → Use `ResourceConfig` in TaskSpec
  AND pass `--resource-id <QuotaId>`.
  - Use cases: dedicated resource group, Lingjun smart compute, Spot bidding.
  - Example: `--resource-id quotaXXX` + `"ResourceConfig": {"CPU": "4", "Memory": "8Gi", "GPU": "1"}`

> **EcsSpec and ResourceConfig MUST NOT both appear in the same TaskSpec.**

> **Also required before `create-job`:** `--job-specs[].Image` MUST come from
> `aliyun aiworkspace list-images`; `--data-sources[].DataSourceId` from
> `list-datasets`; `--code-source.CodeSourceId` from `list-code-sources`.
> Full discovery flow → see §7.6.

**Distributed architecture choices:**

| Topology | `JobSpecs` shape |
|---|---|
| Single-node | One `Worker` only |
| TFJob PS-Worker | Both `PS` (CPU) and `Worker` (GPU) roles |
| PyTorch multi-node | One `Worker` with `PodCount > 1` |

Optional flags: `--enable-gang-scheduling true` (all-or-nothing scheduling),
`Settings.EnableRDMA: true` (high-performance network for multi-node GPU),
`Settings.EnableSanityCheck: true` (GPU health verification).

> **All commands below require `--user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job/${SESSION_ID}`** (omitted in snippets for brevity — see [Observability](#observability)).

### 7.2 Create Training Job

Minimal single-node PyTorch job (public pay-as-you-go) parameter combination:

```bash
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>                        # → valid label Key=Value pairs
aliyun aiworkspace list-images         --region <r> --labels "K1=V1,K2=V2" # → --job-specs[].Image (use ImageUri verbatim)
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，也不要添加空格。值 MUST 来自 list-image-labels，绝不可自行编造。 发现官方公共镜像时，不要向 list-images 传入 --workspace-id（这些镜像是全局的）。 仅在筛选特定工作空间范围内的自定义／私有镜像时，才传入 --workspace-id。

红线： --job-specs[].Image MUST 是原样的 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 规格发现

发现可用的实例类型；返回的 EcsSpec 值应原样传入 --job-specs[].EcsSpec。

aliyun pai-dlc list-ecs-specs --region <r> --accelerator-type GPU --resource-type ECS --page-size 20
# Lingjun dedicated: --quota-id <id> (whitelisted users only)

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 使用抢占式实例可以降低成本，但存在被抢占的风险。
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>，检查是否已有 部分提交的先前尝试。

参考链接

参考文档	说明
references/related-apis.md	命令索引、跨产品字段映射、生命周期、红线、错误目录
references/ram-policies.md	RAM 权限策略详情
references/verification-method.md	端到端验证脚本
references/job-management.md	高风险停止／删除／更新流程 + Web Terminal
references/acceptance-criteria.md	技能测试验收标准
references/cli-installation-guide.md	CLI 安装指南