Plugin 异常处理

概述#

强化学习精调依赖开发者自定义的 Plugin 函数（Rollout 与 Grader），这类函数在独立的 FaaS 环境中运行，是精调任务失败的高发环节。本文帮助您在任务失败时，按报错类型快速定位原因、区分是平台问题还是自定义代码/数据问题，并借助控制台的 Plugin 管理、资源监控与轨迹日志能力完成排查。

Plugin 函数的开发规范、可观测性配置与测试方法见强化学习最佳实践，本文只聚焦异常发生后的定位与恢复。

精调任务失败状态排查#

任务失败时，控制台会在精调任务详情页展示失败状态与后端返回的报错信息。请先根据报错类型判断问题归属，再采取对应处理方式。

报错类型	可能原因	处理方式
`internal error` / `unknown error`	平台侧异常，与您的代码和数据无关。	平台会在约 15 分钟后自动重试，您也可以手动重试恢复。多次重试仍失败时，请提交工单处理。
`Call plugin error`	调用 Plugin 函数（Rollout / Grader）时报错，大概率是自定义函数自身的问题。	观察对应 Plugin 输出的日志以定位问题，详见通过 Plugin 管理定位问题。常见子类见下方 Plugin 错误码与处理。
`Invalid data`	数据错误，通常是数据文件路径不存在或文件缺失。	检查数据文件路径以及数据文件是否存在。
`Invalid value`	数据格式错误，字段格式或数值不合法。	检查数据格式是否符合要求。
`Loss nan`	训练过程中 Loss 值溢出为 `nan`。	检查数据质量与训练参数配置，必要时从小规模数据集与更保守的参数重新验证。

按问题归属可归纳为三类：

平台问题：internal error / unknown error，无需您处理，等待自动重试，或提交工单即可。
Plugin 问题：Call plugin error（含超时、EOF、500、FaaS OOM 等），由自定义函数触发，需结合 Plugin 日志排查。
数据问题：Invalid data / Invalid value / Loss nan，需检查数据文件与格式。

Plugin 错误码与处理#

Call plugin error 是 Plugin 调用失败的统称，后端会在错误信息中携带更具体的原因。常见子类及处理建议如下：

错误信息	含义	处理建议
`Timeout`	Plugin 函数执行超时。	检查函数内是否存在长阻塞调用；协程并发场景需使用异步接口，同步长耗时逻辑需去掉 `async` 以启用线程并发。详见强化学习最佳实践的并发规范。
`EOF`	与 Plugin 函数的连接被意外中断。	多为函数进程异常退出，结合日志查看是否有未捕获异常或内存溢出。
`500`	FaaS 环境返回服务端错误。	多为运行环境问题，查看 Plugin 日志确认具体报错，必要时重试，或提交工单。
`FaaS OOM`	函数内存超限被终止。	降低单次处理的数据量或并发度，或在函数配置中调高内存规格。
`Create faas fault`	创建 FaaS 函数失败，常见于配额不足。	确认账号 FaaS 配额是否充足，清理不再使用的函数或申请扩容。
Reward 返回异常数值	Grader 返回了 `nan` 等非法评分。	检查 Grader 函数的评分逻辑，对异常分支做兜底处理，避免返回非法数值。

通过 Plugin 管理定位问题#

当任务包含自定义 Plugin 时，精调任务详情页会显示 Plugin 标签页，集中展示每个 Plugin 的状态、代码、监控与日志，是排查 Call plugin error 的主要入口。

查看 Plugin 状态#

Plugin 状态包括 等待中、运行中、完成和失败。当状态为失败时，代码页面会展示对应的失败原因说明，可据此定位是超时、内存溢出还是函数内部报错。

查看 Plugin 代码#

Plugin 标签页以只读方式展示本次任务实际运行的 Plugin 函数代码，便于您核对提交的版本是否正确。您也可以通过 下载代码 操作，将代码保存到本地进一步排查。

查看 Plugin 资源监控#

通过 Plugin 选择器 切换不同 Plugin，可查看其实时资源监控指标，用于判断失败是否由资源瓶颈引起。首屏展示的核心指标包括：

函数执行 QPS（counts/s）
函数执行延迟（ms）
函数错误 QPS（counts/s）
函数 CPU 使用率（%）
函数内存使用率（%）
函数实例数量（counts）
函数出公网流量（mib/s）
函数实例并发请求量（counts）

监控支持查看过去 1 小时、3 小时、6 小时、12 小时、3 天、7 天及自定义时间范围的数据，默认每 1 分钟自动刷新，也支持手动刷新。

注意：Plugin 运行结束（完成或失败）后，监控数据会在留存期限到期后被回收，届时将无法查看。请在任务结束后及时排查。

查看自定义 Plugin 日志#

日志是定位 Call plugin error 最直接的手段。在 Plugin 标签页点击 查看日志，可跳转到精调详情页的日志 > 自定义 Plugin 日志，查看您在 Rollout 和 Grader 函数中通过 logger 记录的关键信息。

通过轨迹分析定位问题#

除按 Plugin 维度排查外，您还可以从单条训练轨迹的视角定位问题。在轨迹分析中：

点击某条轨迹后，可查看该轨迹执行时的日志信息，包含时间与日志详情。
失败（failed）和丢弃（discard）状态的轨迹默认展开日志，成功的轨迹可手动展开。
日志区域提供 Plugin 筛选器，支持下拉切换不同 Plugin 查看对应日志。
支持全屏查看轨迹详情与日志，全屏模式下仍可上下切换轨迹。

预防建议#

Plugin 异常大多可以在提交任务前发现。为避免消耗较高的强化学习任务因代码或数据问题失败，建议：

提交前完成测试：依次完成本地测试与在线 FaaS 测试，验证 Rollout、Grader 函数的功能、交互逻辑与并发性能。
提前配置可观测性：在测试 Plugin 函数或提交任务前，先完成轨迹分析、自定义日志与效果指标的配置，便于问题发生时快速定位。
规范并发与错误处理：协程并发函数避免同步长阻塞调用；对工具调用失败、异常评分等分支做明确的错误处理与兜底。

以上测试与配置的详细步骤见强化学习最佳实践。