Alibabacloud Pai Eas Service Deploy

PAI-EAS Service Deployment

⚠️ TOP RULES (read first)

1. 🔴 NO DUPLICATE SERVICE NAMES 🔴

If a service with the target name already exists: STOP and inform the user. Do NOT delete and recreate. Do NOT reuse it either.

2. Mandatory API Calls — Execute ALL of these in order:

| # | API | CLI | Purpose | |---|-----|-----|---------| | 1 | ListImages | aliyun aiworkspace list-images | Validate image | | 2 | describe-machine-spec | aliyun eas describe-machine-spec | Validate GPU type | | 3 | create-service | aliyun eas create-service | Create service | | 4 | describe-service | aliyun eas describe-service | Check status (once) | | 5 | describe-service-endpoints | aliyun eas describe-service-endpoints | Get endpoints |

Execute #1 and #2 ALWAYS, even if user provided the info. describe-machine-spec ≠ list-resources. describe-service ≠ ListServices.

3. Prohibited — ❌ Reuse existing service ❌ Write bash scripts (run CLI directly) ❌ CPU+vLLM/SGLang ❌ file:// in create-service ❌ Skip mandatory APIs ❌ Change the service name the user specified ❌ Poll describe-service in a loop (call once only)

4. Autonomous Execution — Do NOT ask user for info discoverable via APIs. Do NOT ask "should I proceed?" Execute directly. Timeout? Retry with --read-timeout 60. Error? Inform user and CONTINUE. Missing param? Pick reasonable default. If any pre-check or resource discovery step fails, log the failure and continue to the next step. Only STOP for the specific conditions listed in Self-Verify Checkpoints (duplicate service name, missing NLB/GW/dedicated resource group).

5. Self-Verify Checkpoints:

Before Step 2: Did Step 1.5 confirm no duplicate service name?
  If duplicate → STOP, inform user, do NOT proceed.
Before Step 5: Have I run list-images AND describe-machine-spec?
  If NO → STOP and run them NOW.
Before Step 6: Did Step 1.5 confirm no duplicate service name?
  If duplicate exists → STOP, inform user, do NOT proceed.
Step 4 resources: If NLB/GW/Resource Group not found → inform user and STOP.
  Do NOT block or attempt workarounds.
After Step 7: Did I call describe-service once and report the status?

6. Run CLI commands DIRECTLY — Use execute_shell_command to run each aliyun CLI command one at a time. Do NOT write bash scripts, deployment scripts, or shell files. Do NOT use retry_command() or any wrapper functions. Each command = one direct execution.

Pre-checks

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-deploy"
aliyun plugin update
aliyun configure set --auto-plugin-install true

⚠️ MANDATORY: Install and update required plugins BEFORE proceeding:

aliyun plugin update
aliyun plugin install aiworkspace --force
aliyun plugin install eas --force

Verify plugins are installed:

aliyun plugin list 2>/dev/null | grep -E "aiworkspace|eas"

If either plugin is missing after install, retry with:

aliyun plugin install  --force

See CLI Guide. Never read/echo AK/SK. Timeout? Retry with --read-timeout 60.

**⚠️ MANDATORY CHECKPOINT: After pre-checks, you MUST proceed to Step 1 regardless of any warnings during plugin installation. Plugin install failures are non-blocking — the plugins may already be installed. NEVER stop execution at the pre-check stage.**

Step 1: Collect Parameters

| Param | Required | Default | |-------|----------|---------| | RegionId | Yes | - | | Service Name | Yes | - | | Workspace ID | No | Auto-select | | Image URI | Yes | - | | Instance Type | Yes | - | | Replicas | No | 1 | | Port | No | 8000 | | OSS Path | No | - |

Service name: lowercase/digits/underscores only. No hyphens. 3-63 chars. IMPORTANT: Use the EXACT service name the user specifies. Do NOT rename. If the user specifies a prefix (e.g. "skill_qwen_开头"), generate a random suffix of 6 digits (e.g. skill_qwen_482917).

Set profile region — Set the CLI profile region to match the deployment region. This avoids "Region mismatch" errors when --cluster-id differs from the profile's default region:

aliyun configure set --region 

Workspace ID: Required in metadata.workspace_id. If user does not specify a workspace, query available workspaces and pick one:

aliyun aiworkspace list-workspaces --region  \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-deploy | \
  jq '.Workspaces[] | select(.Status == "ENABLED") | {WorkspaceId, WorkspaceName}'

Step 1.5: Check for Duplicate Service Name

aliyun eas list-services --region  --cluster-id  \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-deploy | \
  jq '.ServiceList[] | select(.ServiceName == "") | {ServiceName, Status}'

**If a service with the same name already exists → STOP and inform the user: "A service named already exists (Status: ). Please choose a different name." Do NOT delete or reuse it.**

If no duplicate → proceed to Step 2.

Step 2: ListImages (🚧 BLOCKING GATE — NEVER SKIP)

Execute even if user provided image URI. Purpose = VALIDATION.

**⚠️ If you see "parse error" or "Exit Code 4", the plugin failed to install. You MUST retry with explicit install:**

aliyun plugin install aiworkspace --force

aliyun aiworkspace list-images --region  --verbose true \
  --labels 'system.official=true,system.supported.eas=true' \
  --page-size 50 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-deploy | \
  jq '.Images[] | {ImageId, ImageUri, ImageCategory}' > /tmp/eas_images.json
echo "Saved $(jq length /tmp/eas_images.json) images"

If still fails after plugin reinstall, retry with timeout:

aliyun aiworkspace list-images --region  --verbose true \
  --labels 'system.official=true,system.supported.eas=true' \
  --page-size 50 --read-timeout 60 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-deploy | \
  jq '.Images[] | {ImageId, ImageUri, ImageCategory}' > /tmp/eas_images.json
echo "Saved $(jq length /tmp/eas_images.json) images"

Step 3: describe-machine-spec (🚧 BLOCKING GATE — NEVER SKIP)

Execute even if user specified instance type. NOT list-resources.

**⚠️ If this command fails, retry with --read-timeout 60. NEVER proceed to Step 5 without /tmp/eas_specs.json existing.**

aliyun eas describe-machine-spec --region  \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-deploy | \
  jq '.InstanceTypes[] | select(.GPU > 0) | {InstanceType, CPU, GPU, Memory}' \
  > /tmp/eas_specs.json
echo "Available GPU specs:"; cat /tmp/eas_specs.json

Step 4: Network & Resource Config

| Type | VPC | Config | |------|-----|--------| | Shared | No | (default, no networking fields) | | Dedicated GW | Yes | networking.gateway + cloud.networking | | NLB | Yes | networking.nlb + cloud.networking |

**⚠️ If a required resource does not exist → STOP and inform the user. Do NOT block or attempt workarounds. This is a valid outcome.**

Dedicated Gateway — Call list-gateway. If no gateway exists → inform user and STOP. Otherwise call describe-gateway to get VPC/VSwitch, then query security group under that VPC. If no security group found → inform user and STOP.

aliyun eas list-gateway --region  \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-deploy

aliyun eas describe-gateway --region  --cluster-id  \
  --gateway-id  \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-deploy

aliyun eas describe-gateway --region  --cluster-id  \
  --gateway-id  \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-deploy | \
  jq '{vpc_id: .LoadBalancerList[0].VpcId, vswitch_id: (.LoadBalancerList[0].VSwitchIds | join(","))}'

NLB — Requires VPC/VSwitch/SecurityGroup. If user does not provide them, query via APIs. If any required resource not found → inform user and STOP. ⚠️ NLB requires ≥2 VSwitches across different availability zones. Use comma-separated format: "vswitch_id": "vsw-zone-a,vsw-zone-b". ⚠️ NLB Plugin Bug (aliyun-cli-eas v0.2.0): If create-service with NLB config returns 400 with 'vswitch can not be null' or 'vpcId, vswId and securityGroupId are required', this is a known CLI plugin bug (not a resource issue). Fallback strategy: 1. Retry create-service with NLB config once more (max 2 attempts). 2. If both fail → Remove networking.nlb and cloud.networking from service.json, redeploy with shared gateway. 3. Inform user: "NLB config failed due to CLI plugin limitation. Deployed with shared gateway instead."

EAS Dedicated Resource Group — Call list-resources. Filter for ResourceType == "Dedicated" and Status == "ResourceReady".

aliyun eas list-resources --region  \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-deploy | \
  jq '.Resources[] | select(.ResourceType == "Dedicated" and .Status == "ResourceReady") | {ResourceId, ResourceType, Status}'

Step 5: Build Service JSON

⚠️ BEFORE building JSON, you MUST read these reference files:

**⚠️ HARD GATE: Before writing service.json, VERIFY these files exist and have content. If either is missing → STOP and run that Step NOW.**

test -s /tmp/eas_images.json || echo "MISSING: Run Step 2 NOW"
test -s /tmp/eas_specs.json || echo "MISSING: Run Step 3 NOW"

⚠️ JSON format rules:

Quick Reference — JSON Skeletons

Below are minimal skeletons. **Read references/config-patterns.md for complete templates with all fields and examples.**

Base (Shared Gateway):

{"metadata":{"name":"","instance":1,"workspace_id":""},
 "containers":[{"image":"","port":
,"command":""}],
 "cloud":{"computing":{"instance_type":""}}}

+ OSS → add "storage":[{"mount_path":"/dir","oss":{"path":"oss:///

/","readOnly":true}}] + Autoscaling → add "autoscaler":{"min":1,"max":4,"scaleStrategies":[{"metricName":"qps","threshold":20}]} + Health Check → add startup_check to containers[] (see config-patterns.md Pattern 4)

NLB — full template (read references/network-config.md for details):

{"metadata":{"name":"","instance":1,"workspace_id":""},
 "containers":[{"image":"","port":
,"command":""}],
 "cloud":{"computing":{"instance_type":""},
          "networking":{"vpc_id":"","vswitch_id":",","security_group_id":""}},
 "networking":{"nlb":[{"id":"default","listener_port":
,"netType":"intranet"}]}}

{"metadata":{"name":"","instance":1,"resource":"","workspace_id":""},
 "containers":[{"image":"","port":
,"command":""}]}

{"metadata":{"name":"","instance":1,"workspace_id":""},
 "containers":[{"image":"","port":
,"command":""}],
 "networking":{"gateway":""},
 "cloud":{"computing":{"instance_type":""},
          "networking":{"vpc_id":"","vswitch_id":",","security_group_id":""}}}

jq -r '.[] | select(.ImageUri | contains("vllm")) | .ImageUri' /tmp/eas_images.json
jq -r '.[] | select(.InstanceType == "") | .InstanceType' /tmp/eas_specs.json

aliyun eas create-service --region  \
  --body "$(cat service.json)" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-deploy

aliyun eas describe-service --region  --cluster-id  \
  --service-name  \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-deploy | \
  jq '{Status, ServiceName, ServiceId}'

aliyun eas describe-service-endpoints --region  --cluster-id  \
  --service-name  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-deploy | \
  jq '{AccessToken, Endpoints: [.Endpoints[] | {
    Type: .EndpointType, Port: .Port,
    InternetEndpoints: .InternetEndpoints,
    IntranetEndpoints: .IntranetEndpoints
  }]}'

Deployment Summary
==================
Service Name: 
Status: 
Endpoints:
:
    InternetEndpoint: 
    IntranetEndpoint: 
    Port: 
Service Invocation Examples:
  curl /api/predict/ \
    -H "Authorization: "
  curl /api/predict/ \
    -H "Authorization: "
  curl :/api/predict/ \
    -H "Authorization: "