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 を付ける必要があります。これにより、プラットフォーム側のトレースでリクエストをこのスキルに帰属させ、単一のエージェントセッション内のすべての呼び出しを関連付けられます。

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 を 再利用 してください。呼び出しごとに再生成しないでください。これにより、1 つのセッションのすべての呼び出しをトレースでグループ化できます。
4. 一度エクスポートし、すべての API 呼び出しでシェル変数を参照します。

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 を設定しないでください。 このモードはスキルでは非推奨です。各セッションを個別にトレースできるよう、session-id テンプレートを使って、各コマンドに --user-agent を明示的に指定してください。

## 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 や空白は使用できません。値は必ず 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 EcsSpec の検出

利用可能なインスタンスタイプを検出します。返された 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 を省略し、JSON の出力を jq でクライアント側で並べ替えてください。例： ... | 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）。
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	リスクの高い Stop／Delete／Update のフローと Web Terminal
references/acceptance-criteria.md	スキルのテスト受け入れ基準
references/cli-installation-guide.md	CLI のインストールガイド