alibabacloud-pai-dsw-manage

PAI DSW 实例管理

管理阿里云 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 插件 [MUST] 运行 aliyun configure set --auto-plugin-install true，以启用自动安装插件。 [MUST] 运行 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

[MUST] 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 检查凭证状态

aliyun configure list

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

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

1. 从阿里云控制台获取凭证
2. 在此会话之外配置凭证（在终端中运行 aliyun configure，或在 Shell 配置文件中设置环境变量）
3. 返回并重试，直到 aliyun configure list 显示有效配置文件

---

RAM 权限

完整权限列表和最小权限策略请参阅 references/ram-policies.md。

**[MUST] 权限失败处理：**执行期间的任何时候，若命令或 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：每小时价格，单位为 CNY

[MUST] 可用性检查逻辑：

• 对于按量付费/包年包月：检查 IsAvailable == true
• 对于抢占式实例：检查 IsAvailable == true 且 SpotStockStatus == "WithStock"
• 不要仅凭 SpotStockStatus 判断可用性——许多规格的 IsAvailable 为 true，但 SpotStockStatus 为 "NoStock"
• 示例：ecs.hfc6.10xlarge 的 IsAvailable: true, SpotStockStatus: "NoStock" → 可用于按量付费

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 字段与目标名称逐字符比较（区分大小写，字符串必须完全匹配）
  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 — 配置

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

[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 分钟

原因：阻塞轮询会妨碍 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 超时：对于长时间运行的操作，请增加读取超时时间：

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>，然后轮询（步骤 4），直到状态为 Running。

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

---

成功验证

完整验证步骤：references/verification-method.md。

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

---

清理

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

如需停止产生费用，请按照步骤 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