alibabacloud-pai-dsw-manage

PAI DSW インスタンス管理

Alibaba Cloud PAI DSW（Data Science Workshop）インスタンスのライフサイクル全体を管理します。プロビジョニングから、設定変更、ステータスの監視、起動・停止操作まで対応します。利用可能な ECS コンピューティング仕様の照会にも対応しています。

アーキテクチャ: PAI Workspace + DSW Instance + ECS Spec + Image + VPC + Dataset

API バージョン: pai-dsw/2022-01-01

---

インストール

事前確認：Aliyun CLI >= 3.3.3 が必要です

aliyun version を実行して、バージョンが >= 3.3.3 であることを確認してください。インストールされていない場合、またはバージョンが古い場合は、 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash を実行して更新してください。 インストール方法については、references/cli-installation-guide.md を参照してください。

事前確認：Aliyun CLI プラグインの更新が必要です [必須] aliyun configure set --auto-plugin-install true を実行して、自動プラグインインストールを有効にしてください。 [必須] aliyun plugin update を実行して、既存のプラグインを常に最新の状態にしてください。

# macOS (recommended)
brew install aliyun-cli

# Verify version (>= 3.3.3)
aliyun version

# Enable automatic plugin installation
aliyun configure set --auto-plugin-install true

# Update existing plugins
aliyun plugin update

# Install pai-dsw plugin
aliyun plugin install --names pai-dsw

[必須] CLI User-Agent — すべての aliyun CLI コマンドの実行には、次を含める必要があります。 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dsw-manage

---

認証

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

セキュリティルール：

• AK/SK の値を読み取ったり、エコーしたり、表示したりすることは絶対に避けてください（例：echo $ALIBABA_CLOUD_ACCESS_KEY_ID は禁止です）
• 会話やコマンドラインで、ユーザーに AK/SK を直接入力するよう求めることは絶対に避けてください
• aliyun configure set で認証情報を直接指定することは絶対に避けてください
• 認証情報の状態確認には、aliyun configure list のみを使用してください

aliyun configure list

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

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

1. Alibaba Cloud Console から認証情報を取得します
2. このセッション外で認証情報を設定します（ターミナルで aliyun configure を実行するか、シェルプロファイルに環境変数を設定します）
3. aliyun configure list に有効なプロファイルが表示されてから、戻って再試行します

---

RAM 権限

必要な権限の一覧と最小権限ポリシーについては、references/ram-policies.md を参照してください。

[必須] 権限エラーへの対応： 実行中のいずれかの時点で、コマンドまたは API 呼び出しが権限エラーにより失敗した場合は、次の手順に従ってください。

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

---

パラメーターの確認

重要：パラメーターの確認 — コマンドまたは API 呼び出しを実行する前に、ユーザーが変更可能なすべてのパラメーター（例：RegionId、インスタンス名、CIDR ブロック、パスワード、ドメイン名、リソース仕様など）を必ずユーザーに確認してください。明示的な承認なしに、値を推測したりデフォルト値を使用したりしないでください。

パラメーター	必須	説明	デフォルト
WorkspaceId	必須	PAI ワークスペース ID	なし — ユーザーが指定する必要があります
InstanceName	必須	インスタンス名（英字、数字、アンダースコアのみ、最大 27 文字）	なし — ユーザーが指定する必要があります
EcsSpec	必須（従量課金）	ECS コンピューティング仕様。例：ecs.c6.large。list-ecs-specs で照会します	なし
ImageId	ImageUrl と相互排他	PAI コンソールのイメージ ID	なし
ImageUrl	ImageId と相互排他	コンテナーイメージ URL。一般的な公式イメージについては、references/common-images.md を参照してください	なし
RegionId	必須	リージョン。例：cn-hangzhou、cn-shanghai	なし — ユーザーの確認が必要です
Accessibility	任意	公開範囲：PUBLIC（ワークスペース内の全ユーザー）または PRIVATE	PRIVATE
InstanceId	必須（更新／取得／起動／停止）	インスタンス ID（dsw-xxxxx 形式）	なし
VpcId	任意	プライベートネットワークアクセス用の VPC ID	なし
VSwitchId	任意	VPC 内の VSwitch ID	なし
SecurityGroupId	任意	セキュリティグループ ID	なし
AcceleratorType	必須（仕様の照会）	アクセラレーターの種類：CPU または GPU	なし — ユーザーの確認が必要です
Datasets	任意	CLI リスト形式のデータセットマウント：`DatasetId=<> MountPath=<> MountAccess=RO	RW`
--read-timeout	任意	CLI の読み取りタイムアウト（秒単位、長時間実行される操作用）	10
--connect-timeout	任意	CLI の接続タイムアウト（秒単位）	10

WorkspaceId の取得方法：ワークスペース ID がわからない場合は、次を実行します。

aliyun aiworkspace list-workspaces --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dsw-manage

アクセス可能なすべてのワークスペースが返されます。WorkspaceName に基づいて適切なものを選択するか、ユーザーに確認してください。

参考：ワークスペースの作成と管理

---

コアワークフロー

コマンドの完全な構文とパラメーターの詳細については、references/related-commands.md を参照してください。

1. 利用可能な ECS 仕様を照会する

aliyun pai-dsw list-ecs-specs --accelerator-type <CPU|GPU> --region <region> を実行して、利用可能なコンピュート仕様を一覧表示します。

[MUST] リージョンの確認：--region パラメーターは必須です。仕様の利用可否はリージョンによって異なるため、照会する前に必ずユーザーにリージョンを確認してください。

[MUST] アクセラレーターの種類を正しく判断する：

• ユーザーが仕様名を指定した場合（例：ecs.hfc6.10xlarge）：CPU と GPU の両方の種類を照会してから、結果の InstanceType を照合します。分類を確認するには、返された AcceleratorType フィールドを使用してください。
• ユーザーがイメージの種類を指定した場合：GPU イメージの URL（-gpu- または cu を含む）→ GPU 仕様を照会します。CPU イメージの URL → CPU 仕様を照会します。
• ユーザーがユースケースのみを説明した場合：大規模モデルのトレーニング／ディープラーニングには GPU、データ分析／軽量タスクには CPU を使用します。曖昧な場合は必ずユーザーに確認してください。
• [IMPORTANT] 仕様名のプレフィックスから推測しないでください。命名規則は信頼できません。必ず API の応答で確認してください。

[MUST] ユーザーの要件に基づいてアクセラレーターの種類を選択する：

• デフォルトの推奨：大規模モデルのトレーニング／ディープラーニングには GPU、データ分析／軽量タスクには CPU
• イメージの種類に合わせる（強い判断材料）：ユーザーが GPU イメージの URL（-gpu- または cu を含む）を指定した場合は、GPU 仕様を照会します。CPU イメージの場合は、CPU 仕様を照会します。
• 仕様名は確認が必要：ユーザーが仕様名を指定した場合は、両方の種類を照会し、結果から該当するものを探します。
• ユースケースが曖昧で仕様名が指定されていない場合は、照会する前に必ずユーザーに確認してください。

主な応答フィールド：

• InstanceType：仕様名（例：ecs.hfc6.10xlarge）
• AcceleratorType：CPU または GPU — API による実際の分類
• IsAvailable：最優先の指標 — true は、その仕様が従量課金またはサブスクリプションで利用可能であることを示します。
• SpotStockStatus：二次的な指標 — スポットインスタンスの場合のみ使用します：WithStock（利用可能）または NoStock（利用不可）
• CPU／Memory／GPU／GPUType：ハードウェアの詳細
• Price：1 時間あたりの価格（CNY）

[MUST] 利用可否の確認ロジック：

• 従量課金／サブスクリプションの場合：IsAvailable == true を確認します。
• スポットインスタンスの場合：IsAvailable == true かつ SpotStockStatus == "WithStock" を確認します。
• 利用可否の判断に SpotStockStatus のみを使用しないでください。多くの仕様では、IsAvailable: true でも SpotStockStatus: "NoStock" となります。
• 例：IsAvailable: true, SpotStockStatus: "NoStock" の ecs.hfc6.10xlarge → 従量課金で利用可能

2. インスタンスを作成する（確認してから実行）

[MUST] 冪等性の保証：CreateInstance API は ClientToken をサポートしていないため、確認してから実行するパターンで冪等性を確保します。作成前に、list-instances --instance-name <name> を呼び出して、同じ名前がすでに存在するかどうかを必ず確認してください。

ステップ 2.1 — 存在を確認する

aliyun pai-dsw list-instances \
  --instance-name <name> \
  --region <region> \
  --resource-id ALL \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dsw-manage

判断ロジック：

• TotalCount == 0 → 名前は使用可能です。作成するにはステップ 2.2 に進みます。
• TotalCount >= 1 → [MUST] 名前が完全一致するか確認します：
  1. 返された Instances 配列を順に確認します。
  2. 各インスタンスの InstanceName フィールドと対象の名前を1 文字ずつ比較します（大文字と小文字を区別し、文字列が完全一致すること）。
  3. 完全一致するものが見つかった場合（instance.InstanceName === targetName）→ 名前はすでに使用されています：
     • 一致したインスタンスの InstanceId を取得します。
     • get-instance --instance-id <id> を呼び出して、詳細情報を取得します。
     • 主要なパラメーター（EcsSpec、ImageUrl、Accessibility など）を比較します。
     • 一致する場合 → 既存の InstanceId を返し、再作成しないでください。
     • 一致しない場合 → 別の名前を選ぶようユーザーに依頼します。
  4. 完全一致するものが見つからない場合（InstanceName === targetName となるインスタンスがない場合）→ 名前は使用可能です。作成するにはステップ 2.2 に進みます。

[WARNING] 重要：名前の完全一致が必要です

--instance-name フィルターでは、部分一致する結果が返される場合があります。たとえば、次のようになります。

• クエリ：--instance-name llm_train_001
• 応答に含まれる可能性のある名前：llm_train_001、llm_train_001_v2、llm_train_001_backup

完全一致を必ず確認してください。次のように確認します。

for instance in response.Instances:
    if instance.InstanceName == targetName:  # EXACT string equality
        # Name already exists - DO NOT create

TotalCount > 0 でも完全一致するものはないと「思う」だけで、名前が使用可能だと判断しないでください。TotalCount >= 1 の場合は、各インスタンスの InstanceName フィールドを注意深く確認してください。

ステップ 2.2 — プロビジョニング

必要な引数 --workspace-id、--instance-name、--ecs-spec、--region と、--image-url または --image-id のいずれかを指定して、aliyun pai-dsw create-instance を実行します。

[MUST] リージョンの確認：--region パラメーターは必須で、ユーザーに確認する必要があります。ユーザーの明示的な承認なしに、CLI のデフォルトリージョンを使用しないでください。利用可能なスペックと料金はリージョンによって異なります。

[MUST] EcsSpec とイメージタイプを一致させる：

• GPU イメージ URL（-gpu- または cu を含む）→ GPU スペックを選択する必要があります（例：ecs.gn6v-c4g1.xlarge）
• CPU イメージ URL（-cpu- を含む）→ CPU スペックを選択する必要があります（例：ecs.c6.large）
• スペックの種類はイメージタイプと一致している必要があります。一致しない場合、インスタンスの起動に失敗します
• ユースケース（大規模モデルのトレーニング／データ分析）はあくまで推奨の参考であり、最終的な判断基準はイメージタイプです

データセットのマウント（任意）：ユーザーがマウントするデータセットを指定した場合は、CLI リスト形式の --datasets パラメーターを使用します。

--datasets DatasetId=<dataset-id> MountPath=<mount-path> MountAccess=RO

[MUST] データセットのパラメーターにはユーザーの明示的な確認が必要です。データセットの設定を推測したり、自動生成したりしないでください。

公式イメージ： references/common-images.md。

高度な使用方法（VPC、データセット）：references/related-commands.md。

応答：{"InstanceId": "dsw-xxxxx", ...}

[IMPORTANT] 作成後はすぐに応答する：create-instance が InstanceId を返したら、Running 状態になるまで待機しないでください。代わりに、次の手順を実行します。

1. InstanceId と現在の状態（Creating）をただちにユーザーに返します
2. 後で状態を確認するためのコマンドをユーザーに提示します。

   aliyun pai-dsw get-instance --instance-id <instance-id> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dsw-manage
   

3. インスタンスの起動には通常 2〜5 分かかることをユーザーに伝えます

重要な理由：ポーリング中に処理をブロックすると、エージェントがほかのユーザーリクエストに応答できなくなります。DSW インスタンスの作成は時間のかかる処理です。エージェントは速やかに制御をユーザーに返す必要があります。

3. インスタンスの一覧表示

aliyun pai-dsw list-instances を実行します。--workspace-id または --status で絞り込み、--page-number／--page-size でページネーションします。

4. インスタンスの詳細を取得

aliyun pai-dsw get-instance --instance-id <id> を実行して、インスタンスの状態と詳細を確認します。

ポーリングするタイミング：ユーザーが状態の変化まで待つことを明示的に依頼した場合（例：「起動するまで待って」）に限り、ポーリングしてください。それ以外の場合は、現在の状態をすぐに返してください。

タイムアウトの上限：最大 60 回のポーリング（合計 30 分）です。上限に達したら停止し、手動で確認するようユーザーに促してください。

ポーリング間隔：呼び出しの間隔を 10〜30 秒にします。

CLI のタイムアウト：時間のかかる処理では、読み取りタイムアウトを延長します。

aliyun pai-dsw get-instance --instance-id <id> --read-timeout 30 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-dsw-manage

Status == "Running" になったら、InstanceUrl を使ってインスタンスにアクセスします。

状態遷移の詳細については、references/related-commands.md の「インスタンスの状態値」を参照してください。

5. インスタンスの停止

aliyun pai-dsw stop-instance --instance-id <id> を実行します。

ステータス遷移：Running → Stopping → Stopped

環境イメージの保存：停止前に環境をカスタムイメージとして保存するには、PAI コンソールを使用してください。手順については、DSW インスタンスイメージの作成を参照してください。

6. インスタンスの更新

aliyun pai-dsw update-instance --instance-id <id> を実行して、--instance-name、--ecs-spec、--image-id、--accessibility、--datasets などを変更します。

[MUST] 更新前に：

1. get-instance を呼び出して、現在のステータスと構成を確認します
2. 更新が必要かどうかを確認します：
   • --ecs-spec の場合：現在の EcsSpec と対象のスペックを比較します。すでに同じ場合は、更新をスキップしてユーザーに知らせます
   • --image-id／--image-url の場合：現在の ImageId／ImageUrl と対象を比較します
   • --instance-name の場合：現在の InstanceName と対象を比較します
3. 対象の構成がすでに適用されている場合は、現在のインスタンス情報を返します。update-instance は呼び出さないでください
4. 更新が必要な場合は、更新後に自動で起動するよう --start-instance true を指定します

[IMPORTANT] 必ず InstanceId を指定して、指定されたインスタンスを更新してください。対象のスペックがすでに適用されている別のインスタンスに置き換えないでください。ユーザーのリクエストは特定のインスタンスのアップグレードであり、代替インスタンスの検索ではありません。

7. インスタンスの起動

aliyun pai-dsw start-instance --instance-id <id> を実行し、その後、Running になるまでポーリングします（ステップ 4）。

前提条件：インスタンスの状態が Stopped または Failed である必要があります。起動前に get-instance を呼び出して確認してください。

---

成功の確認

確認手順の詳細については、references/verification-method.mdを参照してください。

簡易チェック：get-instance が、空でない InstanceUrl と Status == "Running" を返すことを確認します。

---

クリーンアップ

このスキルではインスタンスの削除を提供しません（取り消せない操作のため、コンソールを使用してください）。

課金を停止するには、ステップ 5（stop-instance）でインスタンスを停止してください。

---

ベストプラクティス

1. 作成前に必ず確認してから操作します — インスタンスの重複エラーを避けるため、list-instances --instance-name <name> を使用します。
2. PRIVATE の可視性を推奨します — 他のワークスペースユーザーによる誤操作を防ぎます。
3. 更新前にインスタンスのステータスを確認します — まず get-instance を呼び出してください。一部のパラメーターは Stopped 状態が必要ですが、Running のまま更新できるものもあります。
4. list-instances では --resource-id ALL を使用します — デフォルトでは従量課金のインスタンスのみが返されます。
5. ポーリングのタイムアウト制限を守ります — タイムアウトと間隔のガイダンスについては、ステップ 4 を参照してください。
6. プロビジョニング前にスペックの利用可否を確認します — list-ecs-specs を実行して、対象リージョンでスペックが利用可能か確認します。
7. インスタンスに Labels を付けます — 一括クエリとライフサイクル管理が簡単になります。

---

参考資料

ドキュメント	パス
CLI のインストール	references/cli-installation-guide.md
RAM ポリシー	references/ram-policies.md
CLI コマンド	references/related-commands.md
確認	references/verification-method.md
受け入れ基準	references/acceptance-criteria.md
一般的なイメージ	references/common-images.md
PAI DSW API の概要	help.aliyun.com