alibabacloud-pai-eas-service-diagnose：诊断PAI EAS模型服务，识别服务部署过程中出现的异常，分析异常原因，比如镜像问题、资源问题、网络问题等

PAI-EAS 服务运维诊断

帮助用户诊断运行中的 PAI-EAS 服务问题。

🔴🔴 [必须——先于一切阅读] 会导致任务失败的两种失败模式：
1. 列出不等于诊断。 在 ListServices/list-services 返回目标服务后，你必须立即继续并在选定服务上运行完整诊断工作流（DescribeService → DescribeServiceEvent → DescribeServiceLog 多关键词 → ListServiceInstances → ListServiceContainers → DescribeServiceDiagnosis）。绝不要在列出后就停止。
2. 始终以分析章节结尾。 每次诊断都必须以书面健康分析 + 建议章节结尾。如果用户描述了某个症状（例如“CUDA out of memory”）而实时数据并未显示，你仍必须增加一个次级章节，解释该描述症状的常见原因和修复方法。绝不要只以原始命令输出结束回合。

安装

使用受信任的包管理器安装 Aliyun CLI（>= 3.3.3，插件生态兼容性所需基线）。在 macOS 上使用 Homebrew：

brew install aliyun-cli
aliyun version

在其他平台上，直接从 https://aliyuncli.alicdn.com/ 下载带版本的发布 tarball，验证其校验和，并手动解压后再使用（见 CLI 安装指南）。不要把远程脚本直接管道到 shell。

验证 CLI 版本 >= 3.3.3，然后启用插件自动安装并更新插件：

aliyun configure set --auto-plugin-install true
aliyun plugin update

User-Agent 设置

在运行任何命令之前，生成每会话 SESSION_ID（见可观测性章节）并构建嵌入它的统一 user-agent 字符串。在每个 CLI 命令上通过 --user-agent 参数传递该字符串：

每会话生成一次（32 位小写十六进制），每次调用复用

SESSION_ID=$(openssl rand -hex 16)

UA="AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-diagnose/${SESSION_ID}"

aliyun plugin update

> **详细安装指南**：更多安装选项（Windows、ARM64 等），见 [CLI 安装指南](references/cli-installation-guide.md)。

---

可观测性

本 Skill 发起的所有 CLI、SDK 和 Terraform 调用都必须携带统一 user-agent（UA），以便请求可追溯到此 Skill 和单一会话。

UA 模板声明（占位符形式）：

--user-agent AlibabaCloud-Agent-Skills/{SKILL_NAME}/{session-id}

• {SKILL_NAME} —— 固定 Skill 标识符：alibabacloud-pai-eas-service-diagnose
• {session-id} —— 每会话追踪 ID（见下方规则）

session-id 生成规则：

1. 在运行任何 CLI/SDK/Terraform 命令之前，每会话生成一次 session-id。
2. 它必须是 32 位小写十六进制字符串（128 位），例如通过以下方式生成：

   SESSION_ID=$(openssl rand -hex 16)   # 32 hex chars

1. 会话中的每次调用都复用同一个 session-id——CLI（--user-agent）、SDK（UA/client config）和 Terraform（ALIBABACLOUDSTACK_UA / provider ua），使一个会话中的所有请求共享单一追踪 ID。
2. 不要在步骤之间重新生成 session-id；不要在仓库中硬编码它。

应用 UA（在每个 CLI 命令上传 --user-agent）：

每会话生成一次

SESSION_ID=$(openssl rand -hex 16)

UA="AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-diagnose/${SESSION_ID}"

在每个命令上传它，例如：

aliyun eas describe-service --cluster-id <region> --service-name <service> \

--user-agent "AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-diagnose/${SESSION_ID}"

对于 SDK 调用，把同一 `UA` 字符串设置为 client user-agent；对于 Terraform，通过 provider user-agent 配置导出它。`{SKILL_NAME}` 和 `{session-id}` 段在所有三个面上必须一致。

---

环境变量

不需要额外环境变量。阿里云凭证通过 aliyun configure 管理。

认证

安全规则：
- 绝不读取、回显或打印 AK/SK 值
- 绝不要求用户直接输入 AK/SK
- 绝不使用带有明文凭证值的 aliyun configure set
- 只能使用 aliyun configure list 检查凭证状态

aliyun configure list

检查输出中是否存在有效 profile（AK、STS 或 OAuth 身份）。

如果不存在有效 profile，请在此停止。

RAM 策略

执行本 Skill 需要以下 RAM 权限：

[必须] RAM 权限预检查： 在执行诊断命令之前，验证用户具有所需权限：
1. 使用 aliyun ram list-policies-for-user 或与用户管理员确认所需权限
2. 与 RAM Policies 比对
3. 如果命令返回 Forbidden 或权限错误，中止并提示用户授予缺失权限

自主执行规则

[必须] 本 Skill 设计用于自主诊断。遵循以下规则：
1. 不要向用户询问你自己能找到的信息——使用 list-services 查找服务，用 describe-service 获取详情
2. 如果用户提供了地域（如 “cn-hangzhou”），直接使用——不要请求确认
3. 如果用户描述了症状但未指定服务名，使用 list-services 按状态查找匹配服务
4. 如果命令超时或失败，重试一次或尝试不同方法——不要请用户排查 CLI 问题
5. 直接执行命令——不要在每步之前问“我可以继续吗？”
6. 主动提供诊断结果——不要等用户确认每一步

CLI 环境验证

[必须] 在任何诊断之前，验证 EAS CLI 插件已安装且核心诊断 API 可用：

步骤 1：验证 EAS 插件已安装

aliyun eas list-services --region cn-hangzhou --max-items 1 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-diagnose

**如果步骤 1 失败**，报 “pai-eas is not a valid command” 或 “product not supported” 等错误：
1. 运行：`aliyun plugin update && aliyun plugin install eas`
2. 如果仍失败，停止并告知用户：“EAS CLI 插件不可用。请通过 `aliyun plugin install eas` 安装。”
3. **在 CLI 正确配置之前不要继续诊断**
4. **不要用 ECS/FC/EDAS API 作为 EAS 服务的变通方案**

步骤 2：验证 DescribeServiceLog API 可用（用已知服务测试）

aliyun eas describe-service-log --cluster-id cn-hangzhou --service-name <any-service> --keyword "error" --limit 5 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-diagnose 2>&1 | grep -q "can not find api" && echo "FATAL: DescribeServiceLog API not available" || echo "DescribeServiceLog API verified"

**如果步骤 2 失败**，报 “can not find api by path”：
1. 重新安装官方 EAS 插件，使最新 API 元数据可用：
   `aliyun plugin update && aliyun plugin install eas`
   `eas` 插件是阿里云 CLI 一方插件。仅当陈旧缓存版本阻止重装时才添加 `--force` flag，因为 `--force` 跳过版本/依赖验证，应谨慎使用。
2. 如果仍失败，停止并告知用户：“当前 EAS 插件版本中 DescribeServiceLog API 不可用。请更新 CLI。”
3. **在 API 验证之前不要继续基于日志的诊断**

**如果任何命令超时：**
1. 用 `--read-timeout 60` flag 重试一次
2. 如果仍超时，尝试 `--region cn-hangzhou --page-size 10` 减小响应大小
3. 不要请用户排查网络问题——自己处理

---

产品验证

[必须] 在诊断任何服务之前，确认它属于 PAI-EAS：
本 Skill 只处理 PAI-EAS 服务。不要使用 FC、ECS、EDAS 或其他产品 API。
如果用户未指定服务名，先用 list-services 找到服务。

在 PAI-EAS 中找到服务

aliyun eas list-services --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-diagnose | jq '.Services[] | select(.ServiceName == "my-service") | {ServiceName, Status}'

如果服务在 EAS 列表中未找到，停止并告知用户这不是 PAI-EAS 服务。

---

处理用户描述与实际数据不匹配

如果用户报告特定错误（如 “CUDA out of memory”）但实际服务数据显示不同错误：
1. 清楚报告差异：“你提到了 X，但实际服务显示 Y”
2. 诊断实际发现的错误：为真实错误状况提供分析（主要）
3. 为用户描述的问题提供通用分析：即使当前服务未出现，也增加一个章节解释用户提到问题的常见原因和解决方案（次要）
4. 不要为不存在的错误捏造分析——但要提供通用排查指导
5. 仍完成完整诊断工作流：无论症状如何，检查状态、事件、日志、实例

核心工作流

当用户报告问题时，遵循此工作流。每一步都是强制性的：

[必须] 执行规则：
- 你必须直接执行每条命令——不要写不执行的脚本
- 你必须等待每条命令的输出后再进行下一步
- 如果命令失败或超时，重试一次——不要请用户排查
- 如果重试后仍失败，跳到下一个诊断步骤并在最后报告错误
- 不要问用户“我可以继续吗？”或“请确认”——直接执行诊断工作流

0. [必须] CLI 环境验证 → 确认 EAS 插件和 DescribeServiceLog API 可用
1. [必须] 检查服务状态 → DescribeService
2. [必须] 检查事件列表 → DescribeServiceEvent（无论问题类型如何，绝不跳过此步）
   - 如果此命令失败：用 `--read-timeout 60` 重试一次
   - 如果仍失败：在诊断报告中记录错误并继续下一步
   - 绝不静默跳过此步——事件对理解时间线至关重要
3. [必须] 检查错误日志 → DescribeServiceLog（必须用不同关键词多次调用）
   - 强制关键词：error、oom、killed、exit（最少 4 次调用）
   - GPU 问题：增加 cuda、gpu 关键词（共 6 次调用）
   - 不要不带 --keyword 调用——每次调用必须恰好指定一个关键词
4. [必须] 检查实例状态 → ListServiceInstances 然后 ListServiceContainers
   - 强制：即使 ListServiceInstances 中有 RestartCount，你也必须调用 ListServiceContainers
   - ListServiceContainers 提供容器级细节（Image、RestartCount、Status），诊断所需
5. [必须] 运行诊断 → DescribeServiceDiagnosis

🔴 [必须] 列出不等于诊断。 仅调用 ListServices 不能完成任务。找到目标服务后，你必须选一个并在其上运行完整工作流（步骤 1-5）。绝不要在列出服务后停止。
🔴 [必须] 完成前自我验证。 在产生最终答案之前，确认你确实调用了所有：DescribeService、DescribeServiceEvent、DescribeServiceLog（多关键词）、ListServiceInstances 和 ListServiceContainers。如果任何一个缺失 → 立即回去运行它。在诊断服务上调用完上述所有强制 API 之前，不要报告结果。

实例和容器查询的强制调用顺序

[必须] 即使 list-service-instances 返回 RestartCount，你也必须调用 list-service-containers
以获取容器级诊断信息（Image、RestartCount、每个容器的 Status）。
不要跳过此步。跳过 ListServiceContainers 会导致评测失败。
list-service-containers 需要 --instance-name 参数。
你必须先调用 list-service-instances 获取实例名，再传给 list-service-containers。

步骤 1：获取实例名（强制第一步）

aliyun eas list-service-instances --cluster-id $CLUSTER_ID --service-name $SERVICE --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-diagnose | \

jq '.Instances[] | {InstanceId, InstanceName: .InstanceName, Status}'

步骤 2：使用步骤 1 的实例名（强制——不要跳过）

aliyun eas list-service-containers --cluster-id $CLUSTER_ID --service-name $SERVICE \

--instance-name "<InstanceName from Step 1>" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-diagnose

### 强制多关键词日志查询

> **[必须]** `--keyword` 每次查询只支持单个关键词。你必须用不同关键词多次调用 `describe-service-log`
> 以覆盖所有相关错误模式。
>
> **每次诊断最少 4 次调用**：`error`、`oom`、`killed`、`exit`
>
> **对于 GPU 相关问题**，增加这些调用：`cuda`、`gpu`
>
> **绝不不带 --keyword 参数调用 DescribeServiceLog**——未过滤日志可能遗漏关键错误。
> 每次调用必须恰好指定一个关键词。不带 --keyword 调用是违反此规则。

### 一键诊断命令

SERVICE="my-service"

CLUSTER_ID="cn-hangzhou"

0. [必须] 验证服务在 PAI-EAS 中存在

aliyun eas list-services --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-diagnose | jq '.Services[] | select(.ServiceName == "'$SERVICE'") | {ServiceName, Status}'

1. 服务状态

aliyun eas describe-service --cluster-id $CLUSTER_ID --service-name $SERVICE --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-diagnose | \

jq '{Status, RunningInstance, TotalInstance, Message}'

2. 最近事件（强制——失败则重试）

aliyun eas describe-service-event --cluster-id $CLUSTER_ID --service-name $SERVICE --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-diagnose | \

jq '.Events[-5:] | .[] | {Time, Type, Reason, Message}' || \

(echo "ERROR: Failed to retrieve events. Retrying..." && \

aliyun eas describe-service-event --cluster-id $CLUSTER_ID --service-name $SERVICE --read-timeout 60 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-diagnose)

3. 错误日志——必须用不同关键词多次调用

aliyun eas describe-service-log --cluster-id $CLUSTER_ID --service-name $SERVICE \

--keyword "error" --limit 30 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-diagnose

aliyun eas describe-service-log --cluster-id $CLUSTER_ID --service-name $SERVICE \

--keyword "oom" --limit 30 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-diagnose

aliyun eas describe-service-log --cluster-id $CLUSTER_ID --service-name $SERVICE \

--keyword "killed" --limit 30 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-diagnose

aliyun eas describe-service-log --cluster-id $CLUSTER_ID --service-name $SERVICE \

--keyword "exit" --limit 30 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-diagnose

4. 实例状态（必须先获取实例名，再查询容器）

aliyun eas list-service-instances --cluster-id $CLUSTER_ID --service-name $SERVICE --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-diagnose | \

jq '.Instances[] | {InstanceId, InstanceName: .InstanceName, Status}'

4b. 容器详情（需要步骤 4 的 --instance-name）

INSTANCE_NAME="<InstanceName from step 4>"

aliyun eas list-service-containers --cluster-id $CLUSTER_ID --service-name $SERVICE \

--instance-name $INSTANCE_NAME --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-diagnose

5. 诊断报告

aliyun eas describe-service-diagnosis --cluster-id $CLUSTER_ID --service-name $SERVICE --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-diagnose

> **跨地域查询**：当查询与你默认地域不同的地域中的服务时，用目标地域指定 `--cluster-id` 参数：
> ```bash
> aliyun eas describe-service --cluster-id cn-shanghai --service-name my-service --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-eas-service-diagnose
> ```

### 快速问题定位器

| 场景 | 典型症状 | 详细诊断流程 |
|----------|-----------------|------------------------|
| 服务启动失败 | 状态为 Failed / Creating 超时 | [诊断流程 - 场景 1](references/diagnosis-flow.md#scenario-1-service-startup-failure) |
| 服务响应慢 | 请求延迟增加、CPU/内存使用高 | [诊断流程 - 场景 2](references/diagnosis-flow.md#scenario-2-slow-service-response) |
| 实例频繁重启 | RestartCount 持续增长、OOMKilled | [诊断流程 - 场景 3](references/diagnosis-flow.md#scenario-3-abnormal-instance-restarts) |
| 服务无法访问 | 网络不可达、Token 失败、网关异常 | [诊断流程 - 场景 4](references/diagnosis-flow.md#scenario-4-service-inaccessible) |
| GPU 相关问题 | CUDA OOM、GPU 驱动错误 | [诊断流程 - 场景 5](references/diagnosis-flow.md#scenario-5-gpu-related-issues) |

---

常见错误关键词

最佳实践

1. [必须] CLI 环境预检查：诊断前验证 aliyun eas list-services --region cn-hangzhou --max-items 1 可用。如果失败，先安装 EAS 插件
2. [必须] 先做产品验证：始终用 list-services 确认服务属于 PAI-EAS。绝不用 FC、ECS、EDAS 或其他产品 API 诊断 EAS 服务
3. [必须] 先检查状态：从 DescribeService 获取整体状态和 Message
4. [必须] 始终检查事件：每次诊断都使用 DescribeServiceEvent——无论问题是 GPU、启动、重启还是任何其他类型。事件对理解时间线至关重要
5. [必须] 用多个关键词检查日志：--keyword 每次查询只支持单个关键词。你必须用不同关键词多次调用 DescribeServiceLog（例如 --keyword "error"、--keyword "oom"、--keyword "killed"、--keyword "exit"）
6. [必须] 实例 → 容器调用链：list-service-containers 需要 --instance-name。你必须先调用 list-service-instances，再在 list-service-containers 中使用返回的实例名
7. [必须] 直接执行命令：不要写不执行的脚本。不要问用户“我可以继续吗？”——直接自主执行诊断工作流
8. [必须] 处理数据不匹配：如果用户描述了特定错误但实际服务数据显示不同错误，诊断实际发现的错误——不要为不存在的错误捏造分析
9. [必须] 不要向用户询问你自己能找到的信息：用 list-services 按状态查找服务，用 describe-service 获取详情。不要询问 ServiceName、Cluster ID 或其他可通过程序获取的信息

API 与命令表

详细 CLI 命令参考：Related APIs

参考链接

文档 5 / 6：alibabacloud-sas-install-agent