huawei-cloud-modelarts-training-diagnosis

ModelArts トレーニングジョブの障害診断

概要

このスキルは、Huawei Cloud ModelArts のトレーニングジョブを自動で障害診断します。hcloud CLI を介して ModelArts のログ API とイベント API を呼び出して実行時情報を収集し、トレーニングジョブの失敗、タイムアウト、停止状態を分析して、修正案と確信度を含む診断結果を出力します。

アーキテクチャ

User Input
    ↓
Phase 1: Task Discovery (ListTrainingJobs)
    ↓
Phase 2: Status Assessment (ShowTrainingJobDetails)
    ↓
[Early Exit if traceback found in status.task_statuses[].message]
    ↓ (if no traceback)
Phase 3: Information Collection
    ├─ Main Path: ListTrainingJobEvents, ListTrainingJobStages
    └─ Extended Path: ShowTrainingJobLogsPreview, ShowObsUrlOfTrainingJobLogs
    ↓
Phase 4: Analysis (confidence-based inference)
    ↓
Phase 5: Output (diagnosis report + fix suggestions)

対象シナリオ

• トレーニングジョブの失敗（status.phase = "Failed"）
• トレーニングジョブのタイムアウト（status.phase = "Timeout"）
• トレーニングジョブの異常（status.phase = "Abnormal"）
• トレーニングジョブの停止（長時間実行されているが進捗がない）
• リソース不足によるトレーニングの失敗

代表的なユースケース

• 「トレーニングジョブが失敗しました。原因を診断してください」
• 「トレーニングジョブが停止していて、何時間も進捗がありません」
• 「トレーニングジョブがタイムアウトしました。何が起きたのでしょうか？」
• 「アカウント内の失敗したトレーニングジョブをすべてスキャンしてください」
• 「トレーニングジョブのエラーコード 1.015 は何を意味しますか？」

前提条件

hcloud CLI のインストール

• バージョン：7.2.2 以降
• 確認：hcloud version の実行結果がバージョン >= 7.2.2 であること
• インストールガイド：references/cli-installation-guide.md を参照してください

認証設定

• AK/SK が ~/.hcloud/config.json に設定されていること
• デフォルトのリージョン：cn-north-4
• project_id がプロファイルに設定されていること
• skipSecureVerify=true（WSL 環境用）

確認コマンド：

hcloud configure list

IAM 権限

このスキルには、ModelArts トレーニング API に対する読み取り専用権限が必要です。

必要な権限：references/iam-policies.md を参照してください

権限エラーへの対応：

1. いずれかの API が 403/401 を返した場合は、references/iam-policies.md を読みます
2. 必要な権限の一覧とポリシー JSON をユーザーに表示します
3. IAM コンソールでカスタムポリシーを作成するようユーザーを案内します
4. ユーザーが権限付与を確認するまで実行を一時停止します

KooCLI コマンド形式の標準

すべてのコマンドは、標準的な hcloud 形式に従います。

hcloud ModelArts <Operation> --param1=value1 --param2=value2 --cli-region=<region>

主な規約：

• サービス名：ModelArts（パスカルケース）
• 操作名：パスカルケース（例：ShowTrainingJobDetails）
• リージョンパラメーター：--cli-region=<value>（デフォルト：cn-north-4）
• 出力形式：--cli-output=json（エージェントによる処理用）
• JMESPath フィルタリング：--cli-query="<expression>"（出力を削減するため）

例：

hcloud ModelArts ShowTrainingJobDetails \
  --cli-region=cn-north-4 \
  --cli-output=json \
  --training_job_id="<TRAINING_JOB_ID>"

ワークフロー

このスキルでは、5 段階の診断ワークフローに従います。

フェーズ 1：タスクの検出

• ユーザーが完全なジョブ ID を指定した場合 → フェーズ 2 に進みます
• ユーザーが名前を指定した場合 → ListTrainingJobs を使って ID と status.phase を取得します
• ユーザーが何も指定しない場合 → すべての異常ジョブをスキャンします（status.phase = "Failed"/"Timeout"/"Abnormal"）

フェーズ 2：ステータスの評価

• ShowTrainingJobDetails を呼び出してジョブのステータスを取得します
• status.phase を確認します："Failed"/"Timeout"/"Abnormal" は実際の障害、"Running"/"Success" は誤検知、"Initializing" は観察待ちです
• 後続のログ API 用に status.task_statuses[].task_id を抽出します
• 早期終了：status.task_statuses[].message に完全な Python のトレースバックが含まれている場合は、フェーズ 3 の API を呼び出さずに HIGH の確信度で診断を完了できます

フェーズ 3：情報の収集（早期終了が適用される場合はスキップ）

主な経路（常に実行）：

1. ShowTrainingJobDetails → status.phase、status.task_statuses[].message、status.task_statuses[].task_id、status.failureAnalysisResult
2. ListTrainingJobEvents(level=Error) → エラーイベントの一覧
3. ListTrainingJobStages → 停止しているステージを確認

拡張経路（条件付き）： 4. ShowTrainingJobLogsPreview → ログのプレビュー（トレースバック／エラー行を検索） 5. ShowObsUrlOfTrainingJobLogs → OBS の全ログダウンロードリンク（有効期間は 5 分）

詳細なフロー：references/diagnosis-flow.md を参照してください

コアコマンド

タスク検出コマンド

ListTrainingJobs — 異常のあるトレーニングジョブをすべてスキャン

hcloud ModelArts ListTrainingJobs \
  --cli-region=cn-north-4 \
  --cli-output=json \
  --cli-query="items[?status.phase=='Failed' || status.phase=='Timeout' || status.phase=='Abnormal'].{job_id: metadata.id, name: metadata.name, phase: status.phase}"

ステータス確認コマンド

ShowTrainingJobDetails — ジョブのステータスとエラー情報を取得します

hcloud ModelArts ShowTrainingJobDetails \
  --cli-region=cn-north-4 \
  --cli-output=json \
  --training_job_id="<TRAINING_JOB_ID>"

主なレスポンスフィールド：

• metadata.id、metadata.name — ジョブ識別子
• status.phase — ジョブのステータス（「Failed」、「Running」、「Success」など）
• status.task_statuses[].message — Python の完全なトレースバックまたはエラーメッセージ（主な証拠）
• status.task_statuses[].exit_code — 整数の終了コード
• status.task_statuses[].task_id — ログ API 用のタスク ID
• status.failureAnalysisResult.analysis_results[] — プラットフォームによる自動診断

情報収集コマンド

ListTrainingJobEvents — エラーイベントを取得します

hcloud ModelArts ListTrainingJobEvents \
  --cli-region=cn-north-4 \
  --cli-output=json \
  --level=Error \
  --limit=100 \
  --training_job_id="<TRAINING_JOB_ID>"

ListTrainingJobStages — ステージのチェックポイントを確認します

hcloud ModelArts ListTrainingJobStages \
  --cli-region=cn-north-4 \
  --cli-output=json \
  --training_job_id="<TRAINING_JOB_ID>"

ShowTrainingJobLogsPreview — ログをプレビューします（トレースバックを検索）

hcloud ModelArts ShowTrainingJobLogsPreview \
  --cli-region=cn-north-4 \
  --cli-output=json \
  --training_job_id="<TRAINING_JOB_ID>" \
  --task_id="<TASK_ID>"

ShowObsUrlOfTrainingJobLogs — OBS の完全なログのダウンロードリンクを取得します（有効期間は 5 分）

hcloud ModelArts ShowObsUrlOfTrainingJobLogs \
  --cli-region=cn-north-4 \
  --cli-output=json \
  --training_job_id="<TRAINING_JOB_ID>" \
  --task_id="<TASK_ID>"

コマンドテンプレート一式：references/hcloud-command-templates.mdを参照してください

パラメーターの確認

トレーニング診断パラメーター

パラメーター	必須	型	説明	デフォルト
training_job_id	はい	文字列	トレーニングジョブ ID（例：ListTrainingJobs から取得）	なし
task_id	条件付き	文字列	トレーニングジョブ内のタスク ID（ShowTrainingJobDetails.status.task_statuses[].task_id から取得）	なし
--cli-region	いいえ	文字列	Huawei Cloud のリージョン	cn-north-4
--cli-output	いいえ	文字列	出力形式（json/table/tsv）	json
--cli-query	いいえ	文字列	出力をフィルタリングする JMESPath 式	なし

注：

• ログ API には task_id が必要です。ShowTrainingJobDetails.status.task_statuses[].task_id から取得してください。
• リージョンは切り替えられます（例：cn-north-9、cn-east-3）が、そのリージョンの project_id を設定する必要があります。
• ログには機密情報が含まれる場合があります。主要なエラー／トレースバック行のみを抽出し、ログ全体は表示しないでください。

出力形式

このスキルは、診断レポートをMarkdown 形式で出力します。

出力テンプレート

## 诊断结论

| 项目 | 值 |
|------|-----|
| 任务 | `<metadata.name>` (`<metadata.id>`) |
| 当前状态 | `<status.phase>` |
| 故障级别 | Fault / Abnormal / 疑似异常 / 正常 |

## 根因

<一句话描述什么导致了作业失败>（置信度：HIGH/MEDIUM/LOW）

## 修复建议

### 方案 1

1. <step 1>
2. <step 2>

> 注意：以上操作涉及 [只读查询 / 需要用户确认后手动执行的变更]

## 后续步骤

[信息不足时] 当前信息不足以确定根因，建议补充以下信息：
- 调用 `<API>` 获取 `<field>`
- 或手动检查 `<environment/configuration>`

厳守事項：上記のテンプレートに厳密に従ってレポートを生成してください。分析の推論は内部にとどめ、レポートには含めないでください。

確信度レベル

• 高：status.task_statuses[].message に原因を特定できる完全な Python トレースバックが含まれている、または status.failureAnalysisResult.analysis_results[].description に明確なエラーの説明がある、またはイベントに明確なエラーが含まれている
• 中：複数の間接的な手掛かりが同じ根本原因を示している、または status.task_statuses[].exit_code が 0 以外だが、message が空または曖昧
• 低：情報が不十分です。「情報不足」と出力し、必要な追加情報を列挙してください。

確信度の詳細なルール：references/confidence-rules.mdを参照してください

検証方法

このスキルでは、3 段階の検証アプローチに従います。

インストールの検証

hcloud version

成功条件：バージョン 7.2.2 以上が返されること

設定の検証

hcloud configure list

成功条件：region=cn-north-4 の有効な AK/SK 設定が表示されること

機能の検証

hcloud ModelArts ListTrainingJobs --cli-region=cn-north-4

成功条件：HTTP 200 とトレーニングジョブのリストが返されること

検証手順の詳細：references/verification-method.mdを参照してください

ベストプラクティス

早期終了の原則

• ShowTrainingJobDetails が status.task_statuses[].message に完全な Python トレースバックを返す場合は、フェーズ 3 の API（ListTrainingJobEvents、ListTrainingJobStages、ShowTrainingJobLogsPreview、ShowObsUrlOfTrainingJobLogs）をスキップしてください。
• 根本原因がすでに明らかな場合に、API 呼び出しを節約し、診断を迅速化できます。

段階的な診断

• 最小限の情報（ジョブ ID のみ）から開始します。
• まずフェーズ 2（ShowTrainingJobDetails）を実行します。
• フェーズ 2 の結果が不十分な場合（message にトレースバックがない場合）に限り、フェーズ 3 の API を実行します。
• すべての API を一度に実行せず、5 フェーズのワークフローに従ってください。

エビデンスに基づく分析

• すべての推論で、API レスポンスの具体的なフィールドを根拠として示す必要があります
• 1つのエビデンスは1つの推論を裏付けます。複数のエビデンスを相互検証することで、信頼度が高まります
• 返された情報が曖昧である場合、または明示的なエラーが含まれていない場合は、「現在の情報に基づいて根本原因を特定できません」と出力します
• 厳禁：エビデンスなしで根本原因を推測すること

ログの取り扱い

• ログには機密情報（IP アドレス、トークン、認証情報）が含まれる場合があります
• 診断には、主要なエラー行とトレースバック行のみを抽出してください
• 出力にログ全体を表示しないでください
• ログ全体を取得するには、ShowObsUrlOfTrainingJobLogs を使用し、ユーザーにダウンロードを促してください（リンクの有効期間は5分です）

リージョンの切り替え

• デフォルトのリージョンは cn-north-4 です
• リージョンを切り替える際は、そのリージョンに project_id が設定されていることを確認してください
• リージョンプロファイルに project_id がない場合は、hcloud configure init を使用するか、--project_id を明示的に指定してください

参考ドキュメント

ドキュメント	ファイル	説明
API カタログ	references/api-catalog.md	6つのトレーニング診断 API、ステータスのフェーズ、レスポンス構造、イベントレベル
診断フロー	references/diagnosis-flow.md	早期終了の原則を含む、5フェーズの詳細な診断ワークフロー
コマンドテンプレート	references/hcloud-command-templates.md	各 API 用の hcloud コマンドテンプレート一式
信頼度ルール	references/confidence-rules.md	信頼度レベルの定義、エビデンスの対応付け、出力仕様
CLI インストールガイド	references/cli-installation-guide.md	hcloud CLI のインストール、設定、検証
IAM ポリシー	references/iam-policies.md	必要な IAM 権限とポリシー JSON
検証方法	references/verification-method.md	3段階の検証手順
受け入れ基準	references/acceptance-criteria.md	スキルテストの合格／不合格基準

注意事項

セキュリティ上の制約

1. 一貫して読み取り専用：GET API のみを呼び出します（読み取り専用の一覧クエリに POST を使用する ListTrainingJobs を除く）。Create／Update／Delete／Stop は決して呼び出しません
2. 認証情報を漏えいさせない：AK／SK を決して出力しません
3. ユーザーの確認が必要：修正案に変更（再起動、仕様の変更など）が含まれる場合は、「手動で実行する前にユーザーの確認が必要です」と明確に促してください。自動実行は決して行いません
4. 機密情報のマスキング：ログには機密情報が含まれる場合があります。出力前に機密フィールドをマスキングしてください（例：IP アドレスをマスキングし、トークン全体を出力しない）

対象範囲の制限

• トレーニングジョブの診断のみ：Notebook、推論サービス、その他のシナリオは診断しません
• コードの変更なし：ビジネスコードやリソースは変更しません
• 捏造なし：エビデンスなしで根本原因を決して捏造せず、API の返却フィールドに基づいて判断する必要があります
• プライベートデータにアクセスしない：ユーザーのリポジトリ内のプライベートデータを直接読み取りません

既知の制限事項

• 一部の API にはレート制限がある場合があります。スロットリングされた場合は、待ってから再試行してください
• ログのプレビューは切り詰められる場合があります。ログ全体を取得するには OBS リンクを使用してください
• メトリクス API はスキルから削除されています（状態は表示できますが、根本原因は診断できません）
• status.task_statuses[].message は失敗時でも空の場合があります。その場合は Phase 3 の API が必要になります