alibabacloud-pai-rec-diagnosis

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

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

场景说明

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

1. 诊断 PAI-Rec 引擎接口问题：当引擎 API 返回错误或意外结果时，跟踪请求在 EAS 服务日志和引擎配置中的记录，以确定根本原因。

2. 验证引擎配置：在部署前分析引擎配置文件，排查潜在问题、不一致或配置错误。

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

主要组件

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

---

安装

预检查：需要 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，确保所有现有插件始终为最新版本。

---

身份验证

预检查：需要阿里云凭证

安全规则：

• 绝不读取、回显或打印 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 策略

**[MUST] 权限失败处理：**在执行期间的任何时候，若命令或 API 调用因权限错误而失败，请按以下流程处理：

1. 阅读 references/ram-policies.md，获取此 SKILL 所需权限的完整列表
2. 使用 ram-permission-diagnose 技能，引导用户申请所需权限
3. 暂停操作，等待用户确认已授予所需权限

有关此技能所需 RAM 策略的详细信息，请参阅 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 响应中的 Request ID	N/A
config-name	可选	引擎配置名称	N/A
environment	可选	引擎环境（Prod/Pre）	N/A
engine-config-id	可选	特定引擎配置版本 ID	N/A
region	可选	Alibaba Cloud 区域	N/A

---

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

加载此技能后，生成一个随机会话 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。

---

核心工作流

[MUST] 为每个会话分配一个工作目录 — 所有临时文件 （原始配置转储、日志转储、脱敏后的输出）都必须写入每个会话专属的 唯一目录，以避免并行调用技能时相互覆盖。在工作流开始时、任何 会生成文件的 CLI 调用之前运行以下命令，并在整个会话中复用 $WORKDIR。 将完整模板作为位置参数传递（兼容 BSD/macOS 和 GNU/Linux 的 mktemp）；不要使用 -t prefix，它会回退到 $TMPDIR （例如 macOS 上的 /var/folders），在沙盒 Shell 中甚至可能失败。

export WORKDIR=$(mktemp -d /tmp/pairec-diag-XXXXXX)

下文展示的所有文件路径（$WORKDIR/engine_configs_list.json 等）都位于此 目录中，绝不能替换为硬编码的 /tmp/... 路径。

[MUST] 仅使用下文定义的工作流。 不要自行添加步骤 （例如检查实例资源、探测网络），也不要用手动分析替代已定义的工作流步骤。

工作流 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 响应中提取 Request 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

[CRITICAL] --keyword <request-id> 为必填项——禁止本地后处理：

• 必须传入 --keyword <request-id>（服务端筛选，对完整的 request_id 进行区分大小写的精确匹配）。API 仅返回与关键字匹配的日志行。
• 禁止省略 --keyword 后再在本地筛选（例如通过管道传给 head、grep、python3、jq 或任何脚本）。
• 禁止在不带 --keyword 的情况下多次调用 describe-service-log，试图通过扫描完整日志流找到相关行。
• 如果带 --keyword 的调用返回空结果，应报告未找到匹配的日志——切勿改为获取未经筛选的日志。
• --page-size 设为 500 可在单页中捕获完整跟踪；单个请求通常匹配不到 30 条记录。

❌ 错误（获取所有日志后在本地筛选——禁止）：

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"

✅ 正确（使用服务端关键字筛选——必需）：

aliyun eas describe-service-log --cluster-id cn-beijing --service-name embedding_recall --keyword 0c6cbd91-5618-4705-8e08-9126bf4600f7 --page-size 500

[CRITICAL] 时间范围会悄然过滤掉业务日志：

• 仅使用 --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

[MUST] 始终传入 --name <config-name> 进行服务端筛选： <config-name> 已在步骤 1 中获知（ServiceConfig.envs.CONFIG_NAME）；将其传入 --name。省略该参数会返回整个实例的配置清单（通常有数百条无关项），迫使客户端进行筛选、浪费 Token，并可能触发 CLI 默认分页，导致目标行被悄然丢弃。--name 是服务端的精确匹配筛选条件；切勿用 grep / jq select 进行后处理。本技能中的每次 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

[MUST] 显示前必须清理——配置中可能包含明文密码或访问密钥。打印到终端前，始终先通过清理器处理；终端中只能显示已清理的输出（凭据替换为 ***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。

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

运行时机： 日志指向某个配置元素，或首次诊断该配置时。 跳过时机： 日志表明根因与配置无关（缺少 scene_id、上游 5xx）。 [MUST NOT] 不得替换或重复实现 validate.py（与工作流 2 § 步骤 3 的限制相同）。 [MUST] 范围规则： 只有与当前 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）
• 资源限制（例如，条目不足、超时设置）
• 数据源问题（例如，表访问、特征可用性）
• 环境不一致（例如，在预发环境中使用生产配置）

[MUST] 仅基于证据进行报告的规则：

提供给用户的最终诊断 MUST 严格依据 EAS 服务日志和引擎配置中的直接信息。遵守以下限制：

• 仅报告观察到的内容。 引用证明每项结论的确切日志行（文件:行号、级别、消息）和确切配置片段。
• 陈述从日志证据到 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：配置状态（Released/Draft/Archived）
• 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

[MUST] 显示前进行脱敏 — 输出到终端前务必先进行脱敏：

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

步骤 3：运行 Schema + 规则验证

[MUST] 将提取的 ConfigValue JSON 输入 scripts/validate.py。该脚本会执行 JSON Schema（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）；如果未安装，脚本将回退到仅进行规则验证，不执行 Schema 检查。

[MUST NOT] 不要替换或重复实现 validate.py：

• 不要跳过该脚本；不要使用 Python、jq、grep 或任何其他工具手动编写等效检查——该脚本是权威验证器。
• 脚本运行后，不要重新实现、复查或“二次确认”任何规则；请完全信任其输出，包括显示 0 error(s), 0 warning(s) 的无错误运行结果。
• 如果脚本无法运行（缺少 Python、依赖问题等），请修复环境并重新运行——不要改为手动检查。
• 仍可检查脚本范围之外的内容（见步骤 4）。

脚本检查内容（摘要）：

1. 结构 — JSON 格式是否正确、必填字段、类型（RecallConfs、 FilterConfs、SortConfs、AlgoConfs、SceneConfs、RankConf、 FeatureConfs、UserFeatureConfs、DebugConfs、FeatureLogConfs、 CallBackConfs、PipelineConfs 等）
2. 枚举值 — RecallType / FilterType / SortType / DebugConfs.OutputType / GeneralRankConfs.ActionConfs[].ActionType
3. 引用一致性 — SceneConfs.RecallNames → RecallConfs； FilterNames → FilterConfs；SortNames → SortConfs； RankConf.RankAlgoList → AlgoConfs；任何 DaoConf.AdapterType + *Name → 对应的 *Confs（Hologres / Redis / MySQL / TableStore / FeatureStore / …）
4. 业务规则
   • User2ItemExposureFilter 在 WriteLog=true 且使用 FeatureStore 适配器时：必须设置 TimeInterval > 0
   • PriorityAdjustCountFilter 在 accumulator 模式下：Count 必须严格递增（每个召回项单独限额时使用 Type="fix"）
   • PipelineConfs.*.Name 必须全局唯一
   • DebugConfs.Rate 必须是 [0, 100] 范围内的整数
5. 重复名称检测 — 在 RecallConfs、FilterConfs、SortConfs、 AlgoConfs 中检测重复名称

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

步骤 4：基于证据的报告

[必须] 报告的首行： 原样引用 validate.py 的标准输出，内容必须是 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。

快速验证：

1. 对于诊断工作流：

   • 成功获取服务信息
   • 找到包含 request_id 的日志
   • 正确加载配置
   • 找到根因

2. 对于验证工作流：

   • 成功获取配置
   • 执行所有验证检查
   • 清楚报告问题
   • 提供建议（如适用）

---

清理

此技能仅执行只读 Alibaba Cloud API 调用（不会创建远程资源）。临时产物会存放在 /tmp 下每个会话独有的本地 $WORKDIR 中（参见核心工作流前言）。此技能不会自动删除 $WORKDIR；操作系统级临时文件策略会回收这些文件（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 策略	PAI-Rec 和 EAS API 所需的 RAM 权限
相关命令	完整的 CLI 命令参考
验证方法	详细的验证流程
CLI 安装指南	Alibaba Cloud CLI 安装说明
配置示例	引擎配置示例和常见模式
配置验证	scripts/validate.py 的用法、退出代码和规则目录
故障排除指南	常见问题及解决方案
配置脱敏	在交由大模型分析前隐去凭据