alibabacloud-pai-dlc-job-diagnostics

PAI-DLC ジョブの診断と健全性検査

PAI-DLC 分散トレーニングジョブを読み取り専用で診断します。対象となるシナリオは次の 3 つです。

• キュー待ちで停滞している原因の分析 — クォータの確認、ノードスケジューリングの診断、ハイパーノードの利用可能性
• 失敗したジョブの原因特定 — 失敗の分類、ログ／イベントの証拠チェーン、根本原因の特定
• クラスターの健全性検査 — トレーニングのスループット、ハングの検出、SanityCheck、再起動の安定性

アーキテクチャ：PAI-DLC ジョブ（読み取り専用クエリ）＋ PAI Studio リソース診断 API（キュー待ちシナリオ）。

0. 依存関係

このスキルで実行するのは読み取り専用の診断のみです。ジョブの作成／更新／停止、リソースの検出などの書き込み操作は、関連スキルの alibabacloud-pai-dlc-job が担当します。この 2 つのスキルは役割を補完し合い、共通のフィールド契約を共有します。

前提スキル	役割	切り替えが必要な場合
alibabacloud-pai-dlc-job	書き込み操作（作成／更新／停止）＋ AIWorkSpace リソースの検出	ジョブの作成／変更／停止、または Image／Dataset／CodeSource の検出
このスキル	読み取り専用の診断（ログ／イベント／sanity-check／キュー待ちの根本原因）	ジョブがすでに存在し、トラブルシューティングまたは健全性検査を行う場合

前提スキルの検出とインストール：

# Discover available skills
npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-find-skills
# Install the alibabacloud-pai-dlc-job skill itself
npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-pai-dlc-job

スキル間のフィールド契約： このスキルが使用する --job-id／--pod-id の値は、alibabacloud-pai-dlc-job が list-jobs／get-job --cli-query "Pods[0].PodId" を通じてそのまま出力したものです。変換は不要です。--region／--workspace-id の解決ルールは、どちらのスキルでも同じです。

インストール要件

事前確認：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-diagnostics を必ず指定してください。クライアント側のヘルパー（aliyun version、aliyun configure ...、aliyun plugin ...、aliyun <product> --help）はリモート API を呼び出さないため、このフラグは不要です。

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

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job-diagnostics"
# After session: aliyun configure ai-mode disable

認証

事前確認：Alibaba Cloud の認証情報が必要です

セキュリティルール：

• AK／SK の値を読み取ったり、エコーしたり、表示したりすることは絶対にしないでください
• AK／SK を直接入力するようユーザーに求めることは絶対にしないでください
• 認証情報の状態確認には aliyun configure list のみを使用してください

aliyun configure list

出力を確認し、有効なプロファイル（AK、STS、または OAuth ID）があることを確認してください。

有効なプロファイルがない場合は、ここで必ず停止してください。

1. Alibaba Cloud Console から認証情報を取得します
2. このセッションの外部で認証情報を設定します
3. aliyun configure list に有効なプロファイルが表示された後、戻って再実行します

RAM 権限

[必須] 権限エラーへの対応： コマンドが権限エラーで失敗した場合：

1. references/ram-policies.md を読み、必要な権限をすべて確認します
2. ram-permission-diagnose スキルを使用してユーザーを案内します
3. ユーザーが権限を付与したことを確認するまで、一時停止して待ちます

製品	権限	目的
pai-dlc	pai:GetJob、pai:GetPodLogs、pai:GetJobEvents、pai:GetPodEvents、pai:ListJobSanityCheckResults	ジョブ情報の収集
paistudio	paistudio:GetQuotaWorkloadDiagnosis	キュー待ちリソースの診断

パラメーターの確認

重要：パラメーターの確認 — コマンドを実行する前に、ユーザーが変更可能なパラメーター（RegionId、JobId など）をすべてユーザーに確認してください。

パラメーター	必須	説明
region	はい	ジョブが実行されるリージョン
job_id	はい	DLC ジョブ ID（例：dlcXXX）

---

エントリールーティング

診断リクエストを受け取ったら、まず get-job を呼び出してジョブのステータスを取得し、 ステータスに応じてルーティングします。

ジョブのステータス	シナリオへのルート
Queuing / Creating	→ キュー待ち停滞の根本原因分析
Failed	→ 失敗したジョブの原因特定
Running	→ ヘルスチェック
Stopped	ユーザーに「ジョブは明示的に停止されました」と伝え、診断は行いません
Succeeded	→ 過去のレビュー（シナリオ 3 の実行手順に従います）

エッジケース — キュー待ちだったジョブが現在は Stopped / Succeeded：ユーザーがジョブについて「キューで止まったまま」と説明していても、get-job の結果が Stopped または Succeeded の場合は、シナリオ 1（キュー待ち分析）にルーティングします。ただし、リソース診断 API は HTTP 400 を返すことが想定されます。シナリオ 1 の「API エラー時のフォールバック」手順に従ってください。

ユーザーが特定のシナリオを直接リクエストする場合もあります（例：ステータスが Running でなくても、「ヘルスチェックを実行して」と依頼する場合）。

---

診断ツールボックス

PAI-DLC の読み取り専用コマンド

aliyun pai-dlc get-job --region <r> --job-id <id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job-diagnostics
aliyun pai-dlc get-job-events --region <r> --job-id <id> --max-events-num 50 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job-diagnostics
aliyun pai-dlc get-pod-events --region <r> --job-id <id> --pod-id <pod> --max-events-num 20 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job-diagnostics
aliyun pai-dlc get-pod-logs --region <r> --job-id <id> --pod-id <pod> --max-lines 100 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job-diagnostics
aliyun pai-dlc list-job-sanity-check-results --region <r> --job-id <id> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job-diagnostics
aliyun pai-dlc get-job-sanity-check-result --region <r> --job-id <id> --sanity-check-number 1 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job-diagnostics

PAI Studio のリソース診断（キュー待ちシナリオのみ）

aliyun paistudio GET /api/v1/quotas/{quota_id}/workloads/{job_id}/diagnosis \
  --region <r> --header "Content-Type=application/json" --force \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dlc-job-diagnostics

厳守事項：quota_id は必ず get-job の ResourceId フィールドから取得してください。 ResourceId が空（パブリック従量課金）の場合、この API は利用できません。

API の完全な構造については、references/resource-diagnosis-api.md を参照してください。

---

シナリオ 1：キュー待ち停滞の根本原因分析

トリガー：ジョブのステータスが Queuing / Creating で、ユーザーがスケジュールされないと報告しています。

ツール：get-job → paistudio resource diagnosis →（任意）get-job-events。

厳守事項：

• ResourceId が空 → リソース診断は利用できません。手がかりを探すためにイベントを調べてください
• ResourceId が空でない → リソース診断 API を主な手段として使用してください

重要：pai-dlc と paistudio は異なる 2 つの製品です

製品	対象範囲	コマンド
pai-dlc	ジョブ／Pod のライフサイクル（GetJob、GetJobEvents、ListJobs、GetPodLogs）	aliyun pai-dlc get-job ...
paistudio	リソース診断を含むプラットフォームレベルのサービス	aliyun paistudio GET /api/v1/quotas/...

リソース診断 API は paistudio に属しており、pai-dlc には属していません。 pai-dlc GetResourceQuota、pai-dlc ListResourceQuotas、 または pai-dlc GET /api/v1/resourcequotas/... は、誤った API であり 失敗するため、呼び出さないでください。正しいコマンドは次のとおりです。

aliyun paistudio GET /api/v1/quotas/{quota_id}/workloads/{job_id}/diagnosis ...

パターンに関する知識：リソース診断では 4 つのチェック （self_quota / ancestor_quota / user_limit / queue_strategy）に加え、ノードの スケジューリングとハイパーノード分析が返されます。一般的なパターン： references/diagnostic-patterns.md §1。

エージェントの裁量：クォータの不足分を計算するか、裏付けを得るためにイベントを取得するか、レポートの詳しさをどうするかは、エージェントが判断できます。

API エラー時のフォールバック

ジョブがアクティブなキュー待ち状態ではなくなっている場合（例：すでにユーザーによって Stopped にされている場合）、PAI Studio のリソース診断 API が HTTP 400/404 で失敗することがあります。この場合：

1. レポート内で API の失敗を明示してください： "Resource diagnosis API unavailable: HTTP {code} — {error message}"
2. 次のデータソースのみを使用して定性的な分析を行ってください：
   • get-job → ResourceRequest（Pod ごとの GPU/CPU/メモリ要求量）
   • get-job → PodCount × Pod ごとのリソース = 合計要求量
   • get-job → EcsSpec（インスタンスタイプとノードあたりの容量）
   • get-job-events → スケジューリングイベントのタイムラインとキュー待ち時間
3. 使用禁止の表現：「おそらく」「かもしれない」「たぶん」「十分でない可能性がある」など、曖昧さを含む表現は絶対に使用しないでください。確認済みの事実のみを記載してください：
   • GPU の合計要求量 = PodCount × RequestGPU = {計算値}
   • インスタンスタイプ = {EcsSpec}
   • キュー待ち時間 = {計算した時間または分}
   • ジョブの最終ステータス = {Stopped/Succeeded など}
4. API を利用できない場合の必須出力構成：

## Resource Diagnosis (API Unavailable — Configuration-Based Analysis)

- Diagnosis API: unavailable (HTTP {code}: {message})
- Resource demand: {PodCount} pods × {GPU/pod} GPU = {total} GPU cards
- Instance type: {EcsSpec}
- Queuing duration: {hours}h {minutes}m
- Quota ID: {ResourceId}
- Job final status: {status} ({ReasonCode})
- Conclusion: The job requested {total} GPU cards which could not be
  fulfilled within the queuing window before the job was {stopped/completed}.

---

シナリオ 2：失敗したジョブの原因特定

トリガー：ジョブのステータス = Failed。

ツール：get-job →（必要に応じて）get-job-events / get-pod-events / get-pod-logs。

厳守事項：

• Stopped は失敗ではありません。原因を診断しないでください。
• ［出力ガード — 推奨事項は厳禁］ 失敗が以下のいずれかに該当する場合、診断レポートには「Recommendations」／「Suggested fixes」／「Next steps」／「Solution」のセクションを一切含めず、根本原因と客観的な事実のみを出力してください。
  • ResourceAllocateFailed（リソース不足）
  • ジョブのプリエンプション／退避（ReasonMessage に preempted または evicted が含まれる）
  • スポットインスタンスの回収
  • レポートは診断結果で終わらなければなりません。 出力内のどの文でも、設定の変更、クォータの追加申請、インスタンスタイプの切り替え、再試行ロジックの追加、またはジョブパラメーターの変更をユーザーに指示してはなりません。
  • 禁止される例（すべて禁止）：
    • 「従量課金インスタンスの使用を推奨します」
    • 「クォータの追加申請をご検討ください」
    • 「別のゾーンへの切り替えをお試しください」
    • 「EnablePreemptibleJob: false を設定して、プリエンプティブジョブを無効にしてください」
    • 「チェックポイント処理と再試行ロジックを実装してください」
    • 「解決策：オーバーセールされたクォータではなく、保証されたクォータを使用してください」
  • 許可される例：
    • 「根本原因：クラウドプラットフォームによってスポットインスタンスが回収され、ポッドの退避とジョブの失敗が発生しました。」
    • 「ポッドのプリエンプション／退避によりジョブが失敗しました。ReasonCode: JobFailed。」
  • ユーザーへの提案として許可されるもの：「クォータポリシーの調整については、プラットフォーム管理者にお問い合わせください。」

プリエンプション／退避／リソース不足による失敗に必須の出力テンプレート：

## Diagnosis Conclusion

- Failure reason: {classification} ({ReasonCode}: {ReasonMessage})
- Affected pods: {pod list with SubStatus}
- Timeline: {key timestamps from events}
- Evidence: {quoted ReasonMessage or event details}

For quota policy or resource allocation adjustments, please contact your
platform administrator.

パターンに関する知識：失敗分類の優先順位（ネットワーク > イメージ > ランタイム > リソース > 設定 > システム）、終了コードの意味、キーワード照合ルールについては、references/diagnostic-patterns.md §2 を参照してください。

エージェントの裁量：ReasonCode が明確な場合、ログは不要なことがあります。ログですでに問題が説明されている場合、イベントは不要なことがあります。情報が十分かどうかに応じて、調査の深さを判断してください。

シナリオ 3：ヘルスチェック

トリガー：ジョブのステータスが Running で、ユーザーが検査／ヘルスチェックを依頼した場合。

ツール：get-job + get-job-events + get-pod-logs

• list-job-sanity-check-results。

実行手順：

1. get-job → ステータス、WorkspaceId、Pod リスト、EnableSanityCheck が設定されているかを取得します
2. get-job-events → イベントチェーンを分析します（スケジューリング、再起動など）
3. get-pod-logs → 最初にマスターポッド（rank=0）を対象にし、存在する場合は構造化されたトレーニングメトリクスを抽出します
4. list-job-sanity-check-results → ジョブ設定で EnableSanityCheck=true の場合にのみ実行します
5. コンソールリンクを生成します（必須 — 必ず両方のリンクを出力してください）：
   • ジョブの概要：https://pai.console.aliyun.com/?regionId={region}&workspaceId={workspace_id}#/dlc/jobs/{job_id}/overview
   • モニタリングダッシュボード：https://pai.console.aliyun.com/?regionId={region}&workspaceId={workspace_id}#/dlc/jobs/{job_id}/monitor
   • 必須の締めくくりの注意書き（すべての検査レポートにそのまま追記してください）：

     > GPU/memory real-time resource utilization metrics require the monitoring
     > dashboard above. This skill's CLI commands do not support fetching
     > runtime utilization data directly.
     

   この手順は、ジョブのステータス（Running、Succeeded、その他の状態）にかかわらず必須です。ジョブがすでに完了している場合でも、ユーザーが過去のリソース使用率を確認できるよう、モニタリングリンクが必要です。

評価項目のマトリックス（必須／任意）：

評価項目	必須／任意	備考
トレーニングスループット	任意	マスターポッドのログから抽出します
ハング検出	Running の場合のみ	Succeeded のジョブではスキップします
ハードウェアの状態	任意	EnableSanityCheck=true が必要です
再起動の安定性	必須	get-job から RestartCount を直接読み取ります

リソース使用率に関する注意：GPU／メモリのメトリクスは、このスキルの CLI コマンドでは取得できません。モニタリングダッシュボードのリンク（手順 5）と締めくくりの注意書きは、すべての検査レポートで必須です。省略しないでください。

評価項目ごとの解釈ルールについては、 references/healthcheck-dimensions.mdを参照してください。

エージェントの裁量：kilo-card ジョブではハングと SanityCheck を重視し、小規模なジョブではログからトレーニングスループットを確認します。規模とユーザーの意図に応じて、分析の深さとレポートの詳しさを判断してください。

---

ベストプラクティス

1. まず get-job を実行してから、次の処理に進みます — ステータスを決めつけず、照会してから処理を振り分けてください
2. 応答サイズを制限します — コンテキストの肥大化を避けるため、--max-lines 100／--max-events-num 50 を使用してください
3. 問題のあるポッドを特定します — get-job の Pod のうち、Status=Failed/Unknown または ReasonMessage があるものに注目してください
4. ログの末尾を読みます — エラーは通常、最後の数十行に含まれます。ログ全体を取得する必要はありません
5. 終了コードは手掛かりであり、結論ではありません — exit 137 は OOM または外部からの強制終了の可能性があります。状況と併せて判断してください
6. 過剰な診断は避けてください — ReasonCode に原因がすでに示されている場合は、ログ全体の取得を省略してください
7. コンソールリンク — ユーザーがコンソールで詳細やリソース使用率のメトリクスを確認できるよう、概要とモニタリングの両方のリンクを生成してください
8. 読み取り専用 — このスキルでは、stop／update／create を絶対に実行してはいけません
9. レポートの要約 — レポートの最後に、評価項目ごとの評価テーブルを表示してください：

評価項目	評価	主な所見
トレーニングスループット	✅/⚠️/❌/N/A	...
ハング検出	✅/⚠️/❌/N/A	...
ハードウェアの状態	✅/⚠️/❌/N/A	...
再起動の安定性	✅/⚠️/❌	...

参考リンク

ドキュメント	内容
references/resource-diagnosis-api.md	PAI Studio リソース診断 API の完全リファレンス
references/diagnostic-patterns.md	障害パターンのナレッジベース（キューイング／障害／ハング／再起動）
references/healthcheck-dimensions.md	ヘルスチェックの観点と解釈ルール
references/ram-policies.md	RAM 権限ポリシー
references/related-commands.md	CLI コマンドのクイックリファレンス
references/acceptance-criteria.md	受け入れ基準
references/verification-method.md	検証方法
references/cli-installation-guide.md	CLI インストールガイド