返回技能市场
开发运维 安全

PAI-Rec 诊断工具

@aliyun/alibabacloud-pai-rec-diagnosis

排查 PAI-Rec 引擎接口调用错误，结合引擎日志和接口返回数据，分析引擎配置存在的问题，帮助客户快速定位根因。

云Skills门户 热度 51v0.0.3

PAI-Rec 引擎诊断与配置验证

此 skill 为阿里云 PAI-Rec（可编程推荐系统）引擎提供全面的诊断和验证能力，包括接口故障排查和配置分析。

场景说明

PAI-Rec 是阿里云的可编程推荐系统，提供智能推荐能力。此 skill 可帮助用户：

  1. 诊断 PAI-Rec 引擎接口问题：当引擎 API 返回错误或非预期结果时，通过 EAS 服务日志和引擎配置跟踪请求，以确定根因。
  1. 验证引擎配置：部署前分析引擎配置文件中潜在的问题、不一致或错误配置。

架构：PAI-EAS 服务 + PAI-Rec 引擎 + 引擎配置管理

核心组件

  • PAI-EAS 服务：托管推荐引擎的弹性算法服务
  • PAI-Rec 引擎：处理请求的推荐引擎
  • 引擎配置：定义引擎行为的配置文件
  • 服务日志：包含请求跟踪信息的 EAS 服务日志

---

安装

预检查：要求阿里云 CLI >= 3.3.3

运行 aliyun version 验证版本是否 >= 3.3.3。如果未安装或版本过低，
运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 进行安装/更新，
或参阅 references/cli-installation-guide.md 获取安装说明。

预检查：必须更新阿里云 CLI 插件

[必须] 运行 aliyun configure set --auto-plugin-install true 以启用自动安装插件。
[必须] 运行 aliyun plugin update，确保所有现有插件始终为最新版本。

---

身份认证

预检查：必须提供阿里云凭证
安全规则：
- 严禁读取、回显或打印 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 策略

[必须] 权限失败处理： 如果执行过程中任何命令或 API 调用在任意时间因权限错误而失败，请遵循以下流程：
1. 阅读 references/ram-policies.md，获取此 SKILL 所需的完整权限列表
2. 使用 ram-permission-diagnose skill 指导用户申请所需权限
3. 暂停并等待，直至用户确认已授予所需权限

有关此 skill 所需 RAM 策略的详细信息，请参阅 [references/ram-policies.md](references/ram-policies.md)。

---

参数确认

重要：参数确认——执行任何命令或 API 调用前，
所有用户可自定义参数（例如，RegionId、服务名称、实例 ID，
环境名称、配置名称等）都必须与用户确认。
未经用户明确批准，不得假定或使用默认值。

必需参数

| 参数名称 | 必填/可选 | 说明 | 默认值 | |----------------|-------------------|-------------|---------------| | service-name | 必需 | PAI-EAS 服务名称 | N/A | | cluster-id | 必需 | EAS 集群/地域 ID | N/A | | instance-id | 必需 | PAI-Rec 实例 ID | N/A | | request-id | 必需（用于诊断） | 引擎 API 响应中的请求 ID | N/A | | config-name | 可选 | 引擎配置名称 | N/A | | environment | 可选 | 引擎环境（Prod/Pre） | N/A | | engine-config-id | 可选 | 特定引擎配置版本 ID | N/A | | region | 可选 | 阿里云地域 | N/A |

---

可观测性（每条 aliyun 命令都必须遵循）

加载此 skill 后，为整个会话生成一次随机会话 ID（由 32 个小写十六进制字符组成的字符串）。在下文中将其用作 {session-id}。

规则：每条调用云 API 的 aliyun CLI 命令都必须包含 --user-agent 标志。 本地实用命令（例如 configure、plugin、version）不支持此标志，应排除在外。

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-rec-diagnosis/{session-id}

示例（假设 session-id 为 a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6）：

aliyun eas describe-service --cluster-id cn-hangzhou --service-name my_service --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-rec-diagnosis/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

对于任何 aliyun API 命令调用，均不得跳过或省略 --user-agent，也不得更改其格式。

---

核心工作流

[必须] 分配会话级工作目录——所有临时产物
（原始配置转储、日志转储、脱敏输出）必须写入一个唯一的
会话级目录，以避免并行 skill
调用之间发生并发覆盖。在工作流开始时，在任何
会生成产物的 CLI 调用之前运行以下命令，并在整个会话中复用 $WORKDIR。
将完整模板作为位置参数传入（同时适用于 BSD/macOS 和
GNU/Linux 的 mktemp）；不得使用 -t prefix，因为该用法会回退到 $TMPDIR
（例如 macOS 上的 /var/folders），甚至可能在沙箱化 shell 中失败。
```bash
export WORKDIR=$(mktemp -d /tmp/pairec-diag-XXXXXX)
```
以下所示的所有文件路径（$WORKDIR/engine_configs_list.json 等）均位于
此目录内，且严禁替换为硬编码的 /tmp/... 路径。
[必须] 仅使用下文定义的工作流。 不得自行添加
步骤（例如实例资源检查、网络探测），也不得以手动
分析替代已定义的工作流步骤。

工作流 1：PAI-Rec 引擎接口诊断

当 PAI-Rec 引擎 API 返回错误或非预期结果时，此工作流可帮助诊断问题。

输入示例：

Service Name: embedding_recall
API Response:
{
    "code": 299,
    "msg": "items size not enough",
    "request_id": "941b4e14-d1c5-489f-a184-b2b17f8b4fdb",
    "size": 0,
    "experiment_id": "",
    "items": []
}

步骤 1：获取 EAS 服务信息

获取服务详情，以查找 EAS 服务 ID 和配置：

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

需要提取的内容：

  • Resource：EAS 服务资源 ID（例如 eas-r-1v4qb1yan3qmnjwxqe）
  • ServiceConfig.envs：包含以下内容的环境变量：
  • REGION：地域
  • INSTANCE_ID：PAI-Rec 实例 ID
  • CONFIG_NAME：引擎配置名称
  • PAIREC_ENVIRONMENT：环境（product/prepub）

步骤 2：从 API 响应中提取请求 ID

解析 API 响应的 JSON，以获取 request_id 字段。该字段将用于搜索服务日志。

步骤 3：查询 EAS 服务日志

使用请求 ID 作为搜索服务日志的唯一过滤条件。搜索 PAI-Rec 业务日志时，不得传入 --start-time / --end-time：

aliyun eas describe-service-log \
  --cluster-id <cluster-id> \
  --service-name <service-name> \
  --keyword <request-id> \
  --page-size 500

[关键] --keyword <request-id> 为强制要求——禁止本地后处理：

  • 必须传入 --keyword <request-id>（服务端过滤器，对完整的 request_id 进行区分大小写的精确匹配）。API 仅返回与该关键词匹配的日志行。
  • 不得省略 --keyword 后再进行本地过滤（例如通过管道传给 head、grep、python3、jq 或任何脚本）。
  • 不得在不带 --keyword 的情况下多次调用 describe-service-log，试图通过扫描完整日志流来查找相关日志行。
  • 如果带 --keyword 的调用返回空结果，应报告未找到匹配的日志——不得转而获取未过滤的日志。
  • 将 --page-size 设为 500 可在单页中获取完整调用链；单个请求的匹配条目通常少于 30 条。
❌ 错误（获取所有日志并在本地过滤——禁止）：
```bash
aliyun eas describe-service-log --cluster-id cn-beijing --service-name embedding_recall | head -300
aliyun eas describe-service-log --cluster-id cn-beijing --service-name embedding_recall | grep "request_id"
```
✅ 正确（服务端关键词过滤——强制要求）：
```bash
aliyun eas describe-service-log --cluster-id cn-beijing --service-name embedding_recall --keyword 0c6cbd91-5618-4705-8e08-9126bf4600f7 --page-size 500
```

[关键] 时间范围会在无提示的情况下丢弃业务日志：

  • 仅使用 --keyword（不指定时间范围）时，CLI 会返回与 request_id 匹配的完整 PAI-Rec 应用追踪日志（controller.go / feed.go / recall.go / rank_service.go 等）。
  • 即使时间窗口涵盖实际时间戳，添加 --start-time / --end-time 也会在无提示的情况下丢弃业务日志，并且仅返回基础设施噪声（/bin/sh 心跳、502 Bad Gateway 重试、postgres.go dbstat）。
  • 仅在不使用 --keyword 的大范围扫描中使用时间范围，并采用 yyyy-MM-dd HH:mm:ss UTC 格式（不含 T / Z）；像 2025-04-28T00:00:00Z 这样的 ISO-8601 格式会因 InvalidParameter 而被拒绝。

步骤 4：列出引擎配置

映射环境并列出匹配的配置：

环境映射：

  • product → Prod
  • prepub → Pre
aliyun pairecservice list-engine-configs \
  --instance-id <instance-id> \
  --environment <Prod|Pre> \
  --status Released \
  --name <config-name> > "$WORKDIR/engine_configs_list.json" 2>&1

[必须] 始终传入 --name <config-name> 以进行服务端筛选： <config-name> 已在步骤 1（ServiceConfig.envs.CONFIG_NAME）中获知；将其作为 --name 传入。若省略该参数，将返回此实例的全部配置清单（通常包含数百条无关记录），导致不得不在客户端筛选、浪费令牌，并可能触发 CLI 默认分页，致使目标记录被静默丢弃。--name 是服务端精确匹配筛选条件；不得改用 grep / jq select 进行后处理。此规则同样适用于此 skill 中对 list-engine-configs 的每次调用（包括工作流 2 的步骤 1）。

要提取的内容：

  • 查找 Status: Released 的配置
  • 获取 EngineConfigId 和 Version

步骤 5：获取引擎配置详情

aliyun pairecservice get-engine-config \
  --instance-id <instance-id> \
  --engine-config-id <engine-config-id> > "$WORKDIR/raw_engine_config.json" 2>&1

[必须] 显示前进行脱敏——配置可能包含明文密码或 访问密钥。打印到终端之前，必须始终先将其通过脱敏程序进行管道处理； 终端上只能显示经过脱敏的输出（凭据替换为 *REDACTED*）。 位于 $WORKDIR/raw_engine_config.json 的原始文件可以 直接传给 scripts/validate.py（该脚本不会打印凭据值）。

python3 scripts/sanitize_config.py "$WORKDIR/raw_engine_config.json"

要提取的内容：

  • ConfigValue：实际的引擎配置（JSON/YAML）

步骤 5.5（可选）：静态配置健全性检查

对获取到的 ConfigValue 运行 scripts/validate.py，以排除结构/ 引用错误。参见 [references/config-validation.md](references/config-validation.md)。

printf '%s' "$CONFIG_VALUE" | python3 scripts/validate.py --stdin

运行时机：当日志指向某个配置元素，或首次诊断该配置时。 跳过时机：当日志显示根因与配置无关（缺少 scene_id、上游 5xx 错误）时。 [不得] 禁止替换或重复实现 validate.py（限制与工作流 2 § 步骤 3 相同）。 [必须] 范围规则：只有当发现项与当前 request_id 的日志证据相关联时，才能将其纳入最终诊断。

步骤 5a（条件执行）：获取实验配置

条件： API 响应中的 experiment_id 非空（例如 "ER14_L21_L26#EG21_L38#EG38#E44_GL36_GL37"）。

解析： 从字符串中提取 EG{id}（实验组）和 E{id}（实验）的数字 ID。忽略 ER、L、GL 前缀，这些前缀不包含配置。

# For each EG{id}:
aliyun pairecservice get-experiment-group \
  --instance-id <instance-id> \
  --experiment-group-id <id> > "$WORKDIR/experiment_group_<id>.json" 2>&1
# For each E{id}:
aliyun pairecservice get-experiment \
  --instance-id <instance-id> \
  --experiment-id <id> > "$WORKDIR/experiment_<id>.json" 2>&1

要提取的内容： Config 字段——其中包含会覆盖基础引擎配置的覆盖参数（例如 default.RecallNames、rankconf、filterNames、default.SortNames）。

覆盖优先级（低 → 高）： 基础引擎配置 < ExperimentGroup.Config < Experiment.Config。在步骤 6 中按此优先级应用，以了解实际运行时行为。

验证实验配置是否与基础配置匹配（检查引用是否存在）：

python3 scripts/validate.py "$WORKDIR/raw_engine_config.json" \
  --experiment-config "$WORKDIR/experiment_group_<id>.json" \
  --experiment-config "$WORKDIR/experiment_<id>.json"

步骤 6：综合分析

结合分析以下组成部分：

  1. API 响应：错误码、消息和返回的数据
  2. 服务日志：request_id 对应的追踪日志，其中显示了处理流程
  3. 引擎配置：可能影响该行为的设置
  4. 实验覆盖（当 experiment_id 非空时）：有效配置 = 在基础配置之上应用实验参数后的配置

要检查的常见问题：

  • 配置不匹配（例如召回设置、过滤规则）
  • 实验覆盖（例如实验更改了基础配置中的 RecallNames / rankconf）
  • 资源限制（例如条目不足、超时设置）
  • 数据源问题（例如表访问、特征可用性）
  • 环境不一致（例如在预发布环境中使用生产配置）

[必须] 仅依据证据的报告规则：

交付给用户的最终诊断必须严格以 EAS 服务日志和引擎配置直接显示的内容为依据。应用以下约束：

  • 仅报告观察到的内容。 引用确切的日志行（file:line、级别、消息）以及能够证明每项结论的确切配置片段。
  • 说明直接因果链，即从日志证据到 API 响应的因果关系，并到此为止。
  • 不得添加以下任何内容，除非用户明确提出要求：
  • 日志/配置中未体现的推测性根因（例如“客户端可能发送了错误的 X”）
  • 修复建议或补救步骤
  • 条件性的“如果 X，则 Y”情形
  • 偏离主题的最佳实践建议（安全、回退设计、命名等）
  • 对日志/配置未涵盖的上游系统、客户端代码或数据源进行猜测
  • 如果证据不足以得出结论，应明确说明还需要哪些额外数据（具体日志行、其他配置版本或其他环境），而不是猜测。
  • 建议仅按需提供。 只有用户在后续对话中明确请求时，才提供修复方案或建议。

---

工作流 2：PAI-Rec 引擎配置验证

此工作流验证引擎配置中是否存在潜在问题。

输入： 配置名称和环境（Prod/Pre）

步骤 1：列出配置版本

如果用户未提供 engine-config-id，请列出可用版本：

aliyun pairecservice list-engine-configs \
  --instance-id <instance-id> \
  --environment <Prod|Pre> \
  --name <config-name>

向用户显示：

  • Version：版本号
  • Status：配置状态（已发布/草稿/已归档）
  • GmtCreateTime：创建时间戳
  • EngineConfigId：版本 ID

请用户选择一个版本或提供 engine-config-id。

步骤 2：获取配置详情

aliyun pairecservice get-engine-config \
  --instance-id <instance-id> \
  --engine-config-id <engine-config-id> > "$WORKDIR/raw_engine_config.json" 2>&1

[必须] 显示前脱敏——打印到终端前必须进行脱敏：

python3 scripts/sanitize_config.py "$WORKDIR/raw_engine_config.json"

步骤 3：运行模式和规则验证

[必须] 将提取的 ConfigValue JSON 输入 scripts/validate.py。该脚本会执行以下校验： JSON 模式（references/schema.json）和引用一致性规则，并按以下状态码退出： 0 表示通过，1 表示失败。

# From a saved JSON file (recommended)
python3 scripts/validate.py "$WORKDIR/raw_engine_config.json"
# Or pipe ConfigValue directly via stdin
printf '%s' "$CONFIG_VALUE" | python3 scripts/validate.py --stdin

需要 jsonschema（pip install jsonschema）；如果缺少该依赖，脚本将回退到以下方式： — 仅进行规则验证，不执行模式检查。

[不得] 不得替换或重复实现 validate.py：

  • 不得跳过该脚本；不得使用 Python / jq / grep / 任何其他工具手写等效检查——该脚本是权威验证器。
  • 脚本运行后，不得重新实现、重新检查或“二次确认”任何规则；必须原样采信其输出，包括结果为 0 error(s), 0 warning(s) 的无问题运行。
  • 如果脚本无法运行（缺少 Python、依赖项问题等），必须修复环境并重新运行——不得改为手动检查。
  • 仍允许检查脚本范围之外的事项（参见步骤 4）。

脚本检查内容（摘要）：

  1. 结构——JSON 格式正确性、必填字段、类型（RecallConfs，

    2. FilterConfs、SortConfs、AlgoConfs、SceneConfs、RankConf、 FeatureConfs、UserFeatureConfs、DebugConfs、FeatureLogConfs、 CallBackConfs、PipelineConfs 等）

  2. 枚举值——RecallType / FilterType / SortType /

    3. DebugConfs.OutputType / GeneralRankConfs.ActionConfs[].ActionType

  3. 引用一致性——SceneConfs.RecallNames → RecallConfs；

    4. FilterNames → FilterConfs；SortNames → SortConfs； RankConf.RankAlgoList → AlgoConfs；任意 DaoConf.AdapterType + *Name → 对应的 *Confs（Hologres / Redis / MySQL / TableStore / FeatureStore / …）

  4. 业务规则
  • User2ItemExposureFilter 启用 WriteLog=true 并使用 FeatureStore 适配器时：必须设置

    • TimeInterval > 0

  • accumulator 模式下的 PriorityAdjustCountFilter：Count 必须严格

    • 递增（如需为各召回设置独立上限，请使用 Type="fix"）

  • PipelineConfs.*.Name 必须全局唯一
  • DebugConfs.Rate 必须是 [0, 100] 范围内的整数
  1. 重复名称检测——范围包括 RecallConfs、FilterConfs、SortConfs、

    2. AlgoConfs

详细用法、退出码、示例输出和完整规则列表详见： [references/config-validation.md](references/config-validation.md)。

步骤 4：基于证据的报告

[必须] 报告第一行的强制要求： 必须逐字引用 validate.py 的 stdout，内容必须为以下两者之一： Validation passed: configuration is well-formed； Validation finished: N error(s), M warning(s)。报告如未包含上述确切行即为无效。 （必须从步骤 3 重新开始。）

仅允许进行手动检查，且仅限于 validate.py 范围之外的问题：环境 / 地域 / 模型签名不匹配、跨版本差异、 RankScore 变量与模型输出字段之间的命名冲突，以及 对脚本要求人工判断的任何 [WARNING] 进行根因解读。 除非能将脚本未报告的发现关联到上述 某个范围外问题，否则不得添加该发现。

报告结构：

  • ✅ 检查通过——引用 validate.py 的 0 error(s), 0 warning(s) 行
  • ⚠️ 警告——复制脚本输出的每条 [WARNING] <path>: <message>，

    • 以及手动检查发现的任何范围外不一致项

  • ❌ 错误——复制脚本输出的每条 [ERROR] <path>: <message>
  • 缺失证据说明——仅当列出 ≥1 条 ⚠️ 警告时才包含：说明需要哪些额外数据才能将该警告升级为已确认的错误。如果警告数为 0，则必须省略本节；不得用通用的范围外免责声明（跨版本差异、远程连接性、地域/端点一致性）填充本节——这些内容属于主动提供的最佳实践建议，仅依据证据的规则禁止这样做。

不得添加推测性的修复方案或离题的最佳实践内容；仅当用户明确要求时 才提供建议。

---

成功验证方法

有关详细验证步骤，请参见 [references/verification-method.md](references/verification-method.md)。

快速验证：

  1. 对于诊断工作流：
  • 已成功获取服务信息
  • 找到包含 request_id 的日志
  • 已正确加载配置
  • 已确定根因
  1. 对于验证工作流：
  • 已成功获取配置
  • 已执行所有验证检查
  • 已清晰报告问题
  • 已提供建议（如适用）

---

清理

此 skill 执行只读的阿里云 API 调用（不会 创建远程资源）。临时产物存放在每个会话专用的本地 $WORKDIR 中，其路径位于 /tmp 下 （参见核心工作流前言）。此 skill 不会自动删除 $WORKDIR — OS 级临时文件策略会回收该目录（macOS 会定期清理 /tmp；大多数 Linux 发行版会在重启时或通过 systemd-tmpfiles 清理该目录）。若要更早释放磁盘空间， 请在工作流之外手动运行 rm -rf /tmp/pairec-diag-*。

---

最佳实践

  1. 日志查询——仅使用关键词，不指定时间范围，不进行本地过滤：对于请求级诊断，将 --keyword <request_id> 传递给 aliyun eas describe-service-log，并保持 --start-time / --end-time 未设置。严禁省略 --keyword 后再进行本地后处理（例如 | head、| grep、| python3）— 这会使服务端过滤失效、浪费词元，并且可能漏掉第一页之后的日志。由于 CLI 存在特殊行为，将关键词与时间范围结合使用会过滤掉业务日志（参见工作流 1 的步骤 3）。仅可将时间范围用于不针对特定请求的宽泛扫描，并且只能使用 yyyy-MM-dd HH:mm:ss UTC 格式（不含 T / Z）。
  2. 信任 validate.py：对于工作流 2，应将 scripts/validate.py 视为其规则目录的唯一事实来源。不得跳过该脚本而手动编写检查，也不得在其无错误运行后再手动重新验证这些规则。手动检查仅用于其范围之外的问题（环境/地域/模型签名问题、跨版本差异、RankScore 与模型输出字段命名不一致）。
  3. 环境意识：始终验证配置是否与目标环境（Prod 与 Pre）相匹配；如果问题持续存在，请与已知正常的版本进行比较。
  4. 日志保留：EAS 服务日志的保留时间有限；问题发生后应及时诊断。
  5. 仅基于证据得出结论：每项陈述都必须以具体日志行或配置片段为依据。遵循系统化工作流，不要仅凭错误消息仓促下结论。除非用户明确要求，否则不得推测、不得提出修复方案，也不得主动提供最佳实践建议。如果证据不足，应说明缺少哪些信息，而不是进行推断。

---

参考链接

| 参考文档 | 说明 | |--------------------|-------------| | [RAM 策略](references/ram-policies.md) | PAI-Rec 和 EAS APIs 所需的 RAM 权限 | | [相关命令](references/related-commands.md) | 完整的 CLI 命令参考 | | [验证方法](references/verification-method.md) | 详细验证流程 | | [CLI 安装指南](references/cli-installation-guide.md) | 阿里云 CLI 安装说明 | | [配置示例](references/configuration-examples.md) | 引擎配置示例和常见模式 | | [配置验证](references/config-validation.md) | scripts/validate.py 的用法、退出码和规则目录 | | [故障排查指南](references/troubleshooting-guide.md) | 常见问题和解决方案 | | [配置脱敏](scripts/sanitize_config.py) | LLM 分析前的凭据脱敏 |

qianwen skills install @aliyun/alibabacloud-pai-rec-diagnosis