# Plugin 异常处理

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

<span id="overview"></span>
# 概述

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

Plugin 函数的开发规范、可观测性配置与测试方法见 [强化学习最佳实践](/docs/reinforcement-learning-best-practices)，本文只聚焦异常发生后的定位与恢复。

<span id="task-failure-status"></span>
# 精调任务失败状态排查

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

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

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

* **平台问题**：`internal error` / `unknown error`，无需您处理，等待自动重试，或 [提交工单](https://console.volcengine.com/workorder/create?step=2&SubProductID=P00001166) 即可。
* **Plugin 问题**：`Call plugin error`（含超时、EOF、500、FaaS OOM 等），由自定义函数触发，需结合 Plugin 日志排查。
* **数据问题**：`Invalid data` / `Invalid value` / `Loss nan`，需检查数据文件与格式。

<span id="plugin-error-codes"></span>
# Plugin 错误码与处理

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

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

<span id="plugin-management"></span>
# 通过 Plugin 管理定位问题

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

<span id="view-plugin-status"></span>
## 查看 Plugin 状态

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

<span id="view-plugin-code"></span>
## 查看 Plugin 代码

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

<span id="view-plugin-monitoring"></span>
## 查看 Plugin 资源监控

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

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

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

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

<span id="view-plugin-logs"></span>
## 查看自定义 Plugin 日志

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

<span id="trace-analysis"></span>
# 通过轨迹分析定位问题

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

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

<span id="prevention"></span>
# 预防建议

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

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

以上测试与配置的详细步骤见 [强化学习最佳实践](/docs/reinforcement-learning-best-practices)。