PAI DSW 实例管理

管理阿里云 PAI DSW（数据科学工作室）实例的全生命周期，涵盖资源预配、配置变更、状态监控和启动/停止操作。还支持查询可用的 ECS 计算规格。

架构：PAI Workspace + DSW Instance + ECS Spec + Image + VPC + Dataset

API 版本：pai-dsw/2022-01-01

---

安装

前置检查：阿里云 CLI 版本必须 >= 3.3.3

运行 aliyun version 验证版本是否 >= 3.3.3。如果尚未安装或版本过低，

运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 进行更新，

或参阅 [references/cli-installation-guide.md](references/cli-installation-guide.md) 了解安装说明。

前置检查：必须更新阿里云 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

---

身份认证

前置检查：必须提供阿里云凭证

安全规则：

- 严禁读取、回显或打印 AK/SK 值（例如，禁止执行 echo $ALIBABA_CLOUD_ACCESS_KEY_ID）

- 严禁要求用户直接在对话或命令行中输入 AK/SK

- 严禁将 aliyun configure set 与明文凭证值一起使用

- 仅可使用 aliyun configure list 检查凭证状态

```bash

aliyun configure list

```

检查输出中是否存在有效的配置文件（AK、STS 或 OAuth 身份）。

如果不存在有效的配置文件，请在此停止。

1. 从阿里云控制台获取凭证

2. 在此会话之外配置凭证（在终端中通过 aliyun configure，或通过 Shell 配置文件中的环境变量）

3. 待 aliyun configure list 显示有效的配置文件后返回并重试

---

RAM 权限

有关完整权限列表和最小权限策略，请参阅 [references/ram-policies.md](references/ram-policies.md)。

[必须] 权限错误处理：执行过程中的任何阶段，如果任何命令或 API 调用因权限错误而失败，请遵循以下流程：

1. 读取 references/ram-policies.md，获取此 skill 所需的完整权限列表

2. 使用 ram-permission-diagnose skill，指导用户申请必要权限

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](references/common-images.md) | 无 | | RegionId | 必填 | 地域，例如 cn-hangzhou、cn-shanghai | 无——必须由用户确认 | | Accessibility | 可选 | 可见性范围：PUBLIC（所有工作空间用户）或 PRIVATE | PRIVATE | | InstanceId | 必填（更新/获取/启动/停止） | 实例 ID（格式为 dsw-xxxxx） | 无 | | VpcId | 可选 | 用于私网访问的 VPC ID | 无 | | VSwitchId | 可选 | VPC 内的交换机 ID | 无 | | SecurityGroupId | 可选 | 安全组 ID | 无 | | AcceleratorType | 必须（规格查询） | 加速器类型：CPU 或 GPU | 无——用户必须确认 | | Datasets | 可选 | 采用 CLI 列表格式的数据集挂载：DatasetId=<> MountPath=<> MountAccess=RO|RW | 无——用户必须确认，无默认值 | | --read-timeout | 可选 | CLI 读取超时时间（秒，用于长时间运行的操作） | 10 | | --connect-timeout | 可选 | CLI 连接超时时间（秒） | 10 |

如何获取 WorkspaceId：如果用户不知道其工作空间 ID，请运行：

```bash

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

```

此命令会返回用户有权访问的所有工作空间。根据 WorkspaceName 选择合适的工作空间，或请用户确认。

参考：创建和管理工作空间

---

核心工作流

完整的命令语法和参数详情：[references/related-commands.md](references/related-commands.md)。

1. 查询可用的 ECS 规格

运行 aliyun pai-dsw list-ecs-specs --accelerator-type <CPU|GPU> --region <region> 以列出可用的计算规格。

[必须] 地域确认：--region 参数为必填项。规格可用性因地域而异——查询前必须始终与用户确认地域。

[必须] 正确确定加速器类型：

- 用户提及规格名称（例如 ecs.hfc6.10xlarge）：查询 CPU 和 GPU 两种类型，然后在结果中匹配 InstanceType。使用返回的 AcceleratorType 字段确认分类。

- 用户指定镜像类型：GPU 镜像 URL（包含 -gpu- 或 cu）→ 查询 GPU 规格；CPU 镜像 URL → 查询 CPU 规格。

- 用户仅描述使用场景：GPU 用于大模型训练/深度学习，CPU 用于数据分析/轻量任务。如有歧义，必须始终与用户确认。

- [重要] 不得根据规格名称前缀猜测——命名约定并不可靠。必须始终通过 API 响应进行验证。

[必须] 根据用户需求选择加速器类型：

- 默认推荐：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：以 CNY 计的每小时价格

[必须] 可用性检查逻辑：

- 对于按量付费/包年包月：检查 IsAvailable == true

- 对于抢占式实例：同时检查 IsAvailable == true 和 SpotStockStatus == "WithStock"

- 不得仅使用 SpotStockStatus 判断可用性——许多规格虽然显示 IsAvailable: true，但也显示 SpotStockStatus: "NoStock"

- 示例：ecs.hfc6.10xlarge 显示 IsAvailable: true, SpotStockStatus: "NoStock" → 可用于按量付费

2. 创建实例（先检查再执行）

[必须] 幂等性保证：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 → [必须] 验证名称是否完全匹配：

1. 遍历返回的 Instances 数组
2. 对于每个实例，将其 InstanceName 字段与目标名称逐字符比较（区分大小写，精确字符串匹配）
3. 找到完全匹配项（instance.InstanceName === targetName）→ 名称已存在：

• 从匹配的实例中提取 InstanceId
• 调用 get-instance --instance-id <id> 获取完整详情
• 比较关键参数（EcsSpec、ImageUrl、Accessibility 等）
• 匹配 → 返回现有的 InstanceId，不得重新创建
• 不匹配 → 请用户选择其他名称

1. 未找到完全匹配项（不存在满足 InstanceName === targetName 的实例）→ 名称可用，继续执行步骤 2.2 以创建实例

[警告] 关键要求：必须精确匹配名称

--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——预置

运行 aliyun pai-dsw create-instance，并提供必需参数：--workspace-id、--instance-name、--ecs-spec、--region，以及 --image-url 或 --image-id 二选一。

[必须] 区域确认：--region 参数为必填项，且必须与用户确认。未经用户明确批准，不得使用 CLI 默认区域。规格可用性和价格因区域而异。

[必须] EcsSpec 必须与镜像类型匹配：

- GPU 镜像 URL（包含 -gpu- 或 cu）→ 必须选择 GPU 规格（例如 ecs.gn6v-c4g1.xlarge）

- CPU 镜像 URL（包含 -cpu-）→ 必须选择 CPU 规格（例如 ecs.c6.large）

- 规格类型必须与镜像类型匹配，否则实例将无法启动

- 用例（大模型训练/数据分析）仅作为建议，镜像类型是最终判定依据

数据集挂载（可选）：如果用户指定了要挂载的数据集，请以 CLI 列表格式使用 --datasets 参数：

```bash

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

```

[必须] 数据集参数需要用户明确确认——不得假定或自动生成数据集配置。

官方镜像：[references/common-images.md](references/common-images.md)。

高级用法（VPC、数据集）：[references/related-commands.md](references/related-commands.md)。

响应：{"InstanceId": "dsw-xxxxx", ...}

[重要] 创建后立即返回：create-instance 返回 InstanceId 后，不得阻塞等待 Running 状态。而应：

1. 立即向用户返回 InstanceId 和当前状态（Creating）

2. 向用户提供用于稍后检查状态的命令：

```bash

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

```

3. 告知用户实例启动通常需要 2–5 分钟

为何重要：阻塞式轮询会导致 agent 无法响应用户的其他请求。创建 DSW 实例是一项长时间运行的操作；agent 应及时将控制权交还用户。

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 超时：对于长时间运行的操作，请增加读取超时时间：

```bash

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](references/related-commands.md#instance-status-values) 中的“实例状态值”。

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 等。

[必须] 更新前：

1. 调用 get-instance 检查当前状态和配置

2. 检查是否需要更新：

- 对于 --ecs-spec：将当前 EcsSpec 与目标规格进行比较。如果已相同，跳过更新并通知用户

- 对于 --image-id/--image-url：将当前 ImageId/ImageUrl 与目标值进行比较

- 对于 --instance-name：将当前 InstanceName 与目标值进行比较

3. 如果已达到目标配置，则返回当前实例信息——不得调用 update-instance

4. 如果需要更新，请使用 --start-instance true 在更新后自动启动实例

[重要] 始终使用其 InstanceId 更新指定的实例。不得用另一个已具有目标规格的实例替代——用户请求的是升级该特定实例，而不是寻找替代实例。

7. 启动实例

运行 aliyun pai-dsw start-instance --instance-id <id>，然后进行轮询（步骤 4），直至 Running。

前提条件：实例必须处于 Stopped 或 Failed 状态。启动前调用 get-instance 进行确认。

---

成功验证

完整验证步骤：[references/verification-method.md](references/verification-method.md)。

快速检查：get-instance 应返回 Status == "Running"，且 InstanceUrl 非空。

---

清理

此 skill 不提供实例删除功能（该操作不可逆——请使用控制台）。

要停止继续产生费用，请通过步骤 5（stop-instance）停止实例。

---

最佳实践

1. 创建前始终执行先检查后操作——使用 list-instances --instance-name <name> 避免实例重复错误。
2. 优先使用 PRIVATE 可见范围——可防止其他工作空间用户意外操作。
3. 更新前检查实例状态——先调用 get-instance；部分参数要求实例处于已停止状态，其他参数可在实例运行期间更新。
4. 对 list-instances 使用 --resource-id ALL——默认仅返回后付费实例。
5. 遵守轮询超时限制——有关超时时间和轮询间隔的指导，请参见步骤 4。
6. 预配前验证规格可用性——运行 list-ecs-specs，确认该规格在目标地域可用。
7. 使用标签标记实例——简化批量查询和生命周期管理。

---

参考资料

| 文档 | 路径 | |---|---| | CLI 安装 | [references/cli-installation-guide.md](references/cli-installation-guide.md) | | RAM 策略 | [references/ram-policies.md](references/ram-policies.md) | | CLI 命令 | [references/related-commands.md](references/related-commands.md) | | 验证 | [references/verification-method.md](references/verification-method.md) | | 验收标准 | [references/acceptance-criteria.md](references/acceptance-criteria.md) | | 常用镜像 | [references/common-images.md](references/common-images.md) | | PAI DSW API 概览 | help.aliyun.com |