Manage the full lifecycle of Alibaba Cloud PAI DSW (Data Science Workshop) instances — from provisioning through configuration changes, status monitoring, and start/stop operations. Also supports querying available ECS compute specs.
Run aliyun version to verify >= 3.3.3. If not installed or version too low,
run curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash to update,
or see references/cli-installation-guide.md for installation instructions.
Pre-check: Aliyun CLI plugin update required
[MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation.
[MUST] run aliyun plugin update to ensure that any existing plugins are always up-to-date.
[MUST] Permission Failure Handling: When any command or API call fails due to permission errors at any point during execution, follow this process:
Read references/ram-policies.md to get the full list of permissions required by this skill
Use the ram-permission-diagnose skill to guide the user through requesting the necessary permissions
Pause and wait until the user confirms that the required permissions have been granted
Parameter Confirmation
IMPORTANT: Parameter Confirmation — Before executing any command or API call, ALL user-customizable parameters (e.g., RegionId, instance names, CIDR blocks, passwords, domain names, resource specifications, etc.) MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.
Parameter
Required
Description
Default
WorkspaceId
Required
PAI workspace ID
None — user must provide
InstanceName
Required
Instance name (letters, digits, underscores only; max 27 chars)
None — user must provide
EcsSpec
Required (post-paid)
ECS compute spec, e.g., ecs.c6.large. Query via list-ecs-specs
Run aliyun pai-dsw list-ecs-specs --accelerator-type <CPU|GPU> --region <region> to list available compute specs.
[MUST] Region confirmation: The --region parameter is required. Spec availability varies by region — always confirm the region with the user before querying.
[MUST] Determine accelerator type correctly:
User mentions a spec name (e.g., ecs.hfc6.10xlarge): Query BOTH CPU and GPU types, then match InstanceType in results. Use the returned AcceleratorType field to confirm the classification.
User specifies image type: GPU image URL (contains -gpu- or cu) → query GPU specs; CPU image URL → query CPU specs.
User describes use case only: GPU for 大模型训练/深度学习, CPU for 数据分析/轻量任务. Always confirm with user if ambiguous.
[IMPORTANT] Do NOT guess from spec name prefix — the naming convention is unreliable. Always verify via API response.
[MUST] Choose accelerator type based on user requirements:
Default recommendation: GPU for 大模型训练/深度学习, CPU for 数据分析/轻量任务
Match image type (strong indicator): If user specifies a GPU image URL (contains -gpu- or cu), query GPU specs. If CPU image, query CPU specs.
Spec name requires verification: If user mentions a spec name, query both types and find the match in results
Always confirm with user before querying if the use case is ambiguous and no spec name is provided
Key response fields:
InstanceType: Spec name (e.g., ecs.hfc6.10xlarge)
AcceleratorType: CPU or GPU — the actual classification from API
IsAvailable: PRIMARY indicator — true means the spec is available for pay-as-you-go/subscription
SpotStockStatus: SECONDARY indicator — only for spot instances: WithStock (available) or NoStock (unavailable)
CPU / Memory / GPU / GPUType: Hardware details
Price: Hourly price in CNY
[MUST] Availability check logic:
For pay-as-you-go/subscription: Check IsAvailable == true
For spot instances: Check IsAvailable == true AND SpotStockStatus == "WithStock"
DO NOT use SpotStockStatus alone to judge availability — many specs have IsAvailable: true but SpotStockStatus: "NoStock"
Example: ecs.hfc6.10xlarge with IsAvailable: true, SpotStockStatus: "NoStock" → Available for pay-as-you-go
2. Create Instance (check-then-act)
[MUST] Idempotency guarantee: The CreateInstance API does not support ClientToken, so idempotency is ensured via a check-then-act pattern. Before creating, you must call list-instances --instance-name <name> to check if the name already exists.
Match → Return the existing InstanceId, do not recreate
Mismatch → Ask user to choose a different name
No exact match found (no instance has InstanceName === targetName) → Name is available, proceed to Step 2.2 to create
[WARNING] Critical: Exact name match required
The --instance-name filter may return partial matches. For example:
Query: --instance-name llm_train_001
Response may include: llm_train_001, llm_train_001_v2, llm_train_001_backup
You MUST verify exact match by checking:
text
for instance in response.Instances:
if instance.InstanceName == targetName: # EXACT string equality
# Name already exists - DO NOT create
Do NOT assume name is available just because TotalCount > 0 but you "think" no exact match. If TotalCount >= 1, carefully check each instance's InstanceName field.
Step 2.2 — Provision
Run aliyun pai-dsw create-instance with required args: --workspace-id, --instance-name, --ecs-spec, --region, and either --image-url or --image-id.
[MUST] Region confirmation: The --region parameter is required and must be confirmed with the user. Do NOT use CLI default region without explicit user approval. Spec availability and pricing vary by region.
[MUST] Match EcsSpec with image type:
GPU image URL (contains -gpu- or cu) → Must select a GPU spec (e.g., ecs.gn6v-c4g1.xlarge)
CPU image URL (contains -cpu-) → Must select a CPU spec (e.g., ecs.c6.large)
The spec type MUST match the image type, otherwise the instance will fail to start
Use case (大模型训练/数据分析) is only a recommendation, image type is the definitive indicator
Dataset mounting (optional): If the user specifies a dataset to mount, use the --datasets parameter in CLI list format:
Inform the user that instance startup typically takes 2–5 minutes
Why this matters: Blocking polling prevents the agent from responding to other user requests. DSW instance creation is a long-running operation; the agent should return control to the user promptly.
3. List Instances
Run aliyun pai-dsw list-instances. Filter by --workspace-id or --status; paginate with --page-number / --page-size.
4. Get Instance Details
Run aliyun pai-dsw get-instance --instance-id <id> to check instance status and details.
When to poll: Only poll when the user explicitly asks to wait for a status change (e.g., "wait until it's running"). Otherwise, return the current status immediately.
Timeout limits: Maximum 60 polls (30 minutes total). If exceeded, stop and prompt user to check manually.
Polling interval: 10–30 seconds between calls.
CLI timeout: For long-running operations, increase read timeout:
Run aliyun pai-dsw stop-instance --instance-id <id>.
Status transition: Running → Stopping → Stopped
Save environment image: To save the environment as a custom image before stopping, use the PAI Console. See Create a DSW Instance Image for instructions.
6. Update Instance
Run aliyun pai-dsw update-instance --instance-id <id> to modify --instance-name, --ecs-spec, --image-id, --accessibility, --datasets, etc.
[MUST] Before updating:
Call get-instance to check current status and configuration
Check if update is needed:
For --ecs-spec: Compare current EcsSpec with target spec. If already equal, skip update and inform user
For --image-id/--image-url: Compare current ImageId/ImageUrl with target
For --instance-name: Compare current InstanceName with target
If already at target configuration, return current instance info — do not call update-instance
If update is needed, use --start-instance true to auto-start after update
[IMPORTANT] Always update the specified instance by its InstanceId. Do NOT substitute with another instance that already has the target spec — the user's request is to upgrade the specific instance, not to find an alternative.
7. Start Instance
Run aliyun pai-dsw start-instance --instance-id <id>, then poll (Step 4) until Running.
Prerequisite: Instance must be in Stopped or Failed state. Call get-instance to confirm before starting.
