强化学习的可观测配置与指标参考

@observe_processor — 追踪处理器入口

加在 process() 方法上，创建顶层 ENTRY Span。SDK 根据父类自动识别类型：继承 AbstractRolloutProcessor → ROLLOUT 类型，继承 AbstractRewardProcessor → REWARD 类型。自动记录每次调用的输入、输出、耗时、成功/失败状态。

Rollout 侧（functions/rollout/rollout.py）：

from dashscope.finetune.reinforcement.component.observability import (
    observe_processor
)

class CalcXRolloutProcessor(AbstractRolloutProcessor):
    @observe_processor  # Span 类型 = ROLLOUT
    async def process(self, input: RolloutInput) -> RolloutOutput:
        await self._async_setup()
        return await self._async_process(input)

Reward 侧（functions/reward/reward.py）：

class DemoRewardProcessor(AbstractRewardProcessor):
    @observe_processor  # Span 类型 = REWARD
    async def process(self, input: RewardInput) -> RewardOutput:
        score = await evaluate(content, input.ground_truth)
        return RewardOutput(
            reward=Reward(
                reward_score=score,
                reward_metrics={"test1": 0.5, "test2": 0.3}
            ),
            status=TaskStatus.SUCCESS,
        )

trace_client() — 追踪 LLM 客户端

在初始化方法中调用，包装 LLM 客户端实例。之后该客户端的所有 LLM 请求都会自动产生 LLM Span，记录模型名、请求内容、Token 用量、延迟等。

支持的客户端类型（鸭子类型自动检测）：

• OpenAI 客户端（AsyncOpenAI / OpenAI）

• OpenAI completions 资源（.chat.completions）

• LangChain ChatOpenAI 等类（通过 .client / .async_client）

• DashScope Generation 类（传入类本身，非实例）

示例（functions/rollout/rollout.py）：

from langchain_openai import ChatOpenAI
from dashscope.finetune.reinforcement.component.observability import (
    trace_client
)

class CalcXRolloutProcessor(AbstractRolloutProcessor):
    def _build_llm(self, input: RolloutInput) -> ChatOpenAI:
        llm = ChatOpenAI(
            model=input.model_resource.model_name,
            openai_api_key=api_key,
            openai_api_base=input.model_resource.base_url,
            ...
        )
        trace_client(llm)  # 包装后自动追踪所有 LLM 调用
        return llm

trace_tool() — 追踪工具调用

在获取工具实例后调用，包装工具对象。之后每次工具调用都会产生 TOOL Span，记录工具名、参数、返回值、延迟。

支持的输入格式：

• 单个 LangChain BaseTool

• 列表 / 元组 / 字典（自动遍历）

• LangGraph ToolNode（自动展开 .tools_by_name）

• MCP 工具（自动检测，provider 设为 "mcp"）

示例（functions/rollout/rollout.py）：

from dashscope.finetune.reinforcement.component.observability import (
    trace_tool
)

class CalcXRolloutProcessor(AbstractRolloutProcessor):
    async def _init_resources_async(self):
        client = MultiServerMCPClient({
            "calculator": {"url": "http://localhost:10086/sse"}
        })
        tools = await client.get_tools()
        trace_tool(tools)  # 必须在 get_tools() 之后调用

@observe_llm — 自定义 LLM 函数

当 trace_client() 无法自动检测您的 LLM 客户端时，用此装饰器手动标记 LLM 调用函数。

签名要求：函数必须包含 * 后的关键字参数 model 和 messages。

from dashscope.finetune.reinforcement.component.observability import (
    observe_llm
)

@observe_llm  # 标记为 LLM Span
async def call_custom_llm(*, model: str, messages: list, **kwargs):
    # 自定义 LLM 调用逻辑
    ...

@observe_tool — 自定义工具函数

当 trace_tool() 无法自动检测您的工具时（如普通 Python 函数充当工具），用此装饰器手动标记。可通过 name 参数自定义 Span 名称。

from dashscope.finetune.reinforcement.component.observability import (
    observe_tool
)

@observe_tool(name="response_scorer")  # 标记为 TOOL Span
def score_response(*, messages: list) -> float:
    # 自定义评分逻辑
    ...

数据链路与成本来源

• 数据流：函数代码（三个核心装饰器）→ OpenTelemetry SDK → ARMS → 控制台轨迹/指标页签

• 成本来源：ARMS Span 存储（按量计费）+ 函数侧少量 CPU/网络开销 + 训练延迟少量增加

开发期 vs 大规模训练的开关策略

关闭命令：runtime.env = {"ENABLE_TRAJECTORY": "false"}。

自定义指标的成本治理

• reward_metrics / rollout_metrics 数量与基数（cardinality）影响 ARMS 存储

• 避免高基数字段（user_id / request_id）当指标 key

• 关键指标 ≤10 个，不留临时调试指标

• @sub_reward_func 子维度合并后落到对应 Reward 函数的 reward_metrics 下，路径可控

指标分层解读法

• 必看（日常体检 8-10 个）：北极星 + 三个核心指标 + 截断率 + 单步耗时（健康判据已在关键指标速查表）

• 选看（按场景）：Agent 看 trace/num_llm_calls / trajectory/num_turns；长文看 length 系列

• 排错下钻：timing 子项 / fully_async 队列 / critic 分布 max/min

控制台 5 个页签的使用场景见上方「控制台查看效果」节的页签速查表。

P1 不收敛 & P2 震荡

• P1 主信号：critic/rewards/mean 长平台 + actor/ppo_kl ≈ 0 + actor/grad_norm 极小

• P1 根因：lr 太小 / Reward 恒返回相同值 / 数据不足

• P2 主信号：rewards/mean 大幅震荡 + grad_norm 飙升 + pg_clipfrac >5%

• P2 根因：lr 过大 / batch 过小 / advantage 方差未归一化

P3 KL 爆炸 & P4 熵骤降（模式崩溃）

• P3 主信号：actor/ppo_kl 持续 >0.1 + pg_clipfrac 同步升 + 轨迹乱码/重复

• P3 处置建议：kl_loss_coef ↑（0.001 → 0.01）+ lr ↓ + ppo_mini_batch_size ↓

• P4 主信号：actor/entropy 几十步内贴 0 + rewards/mean 虚假上升 + Sample 维度同模板复述

• P4 根因：Reward 单模式过度奖励 / KL 太小 / 温度过低

P5 Reward Hacking & P6 验证集崩塌

• P5 主信号：训练 reward 涨 + validation 停 / 跌 + response_length_non_aborted/mean 线性暴涨 + 某 reward_metrics 子维独占增益

• P5 归因路径：指标异常 → 轨迹 Sample 抽样 → 看 assistant 是否堆字数 / 抄题面 / 借助工具钻 Reward 漏洞（详见《强化学习开发指南》§Reward Hacking 识别与防御）

• P6 主信号：validation/data/reward/mean@1 出现下行拐点而训练 reward 仍升

• P6 处置建议：早停（在产出页签选取较早的 Checkpoint）+ KL 约束 ↑ + 扩验证集

P7 训练变慢 & P8 输出乱码 & P9 截断率高

• P7 主信号：timing/s/step 突增

• P7 下钻：rollout/agent_loop_latency / update_actor；根因 response_length 上涨 / FC 扩容滞后（看 fully_async 队列）/ 工具延迟

• P8 主信号：轨迹乱码 / 非自然语言，通常 P3 KL 已爆 → 与 P3 联动处置

• P9 主信号：trajectory/response_length/clip_ratio 或 prompt_length/clip_ratio 高

• P9 处置建议：max_length ↑ 或缩 prompt；同时检查 Reward 是否变相鼓励长输出

Step / Sample / Trajectory 三维度的协同用法

标准路径：指标页签看到拐点 → Step 锁定"哪段训练坏了"（趋势拐点）→ Sample 找"哪些样本拉偏均值" → Trajectory 看"这一条推理链 / 工具调用细节" → 回到代码改 Reward / 数据。

工具调用分析与 Tracing Span 树

• 工具调用分析：工具名 / 参数 / 返回 / 耗时——排查 Agent 工具失败必看

• Tracing 子页签给每条轨迹 Span 树（ENTRY:ROLLOUT → LLM → TOOL → REWARD）

• 典型用法：Reward 突然变低 → 看某工具是否开始报错 / MCP server 是否不可用

• 注意：Server 端 @observe_tool 对 Client 无效，必须 Client 端 trace_tool(tools)

自定义指标（rollout_metrics / reward_metrics）的归因价值

• 系统指标只告诉你"坏了"，自定义指标告诉你"哪一维度坏了"

• 命名规范建议：按业务子维度命名（accuracy / format_score / tool_success_rate / answer_length）

• 多 Reward 函数场景：通过 RewardFunctionComponent(name=...) 区分；通过 reward_metric_weight 调权重

• 反模式：把日志或调试信息塞进 metrics，导致 cardinality 爆炸

何时该跳出控制台

• 怀疑 Reward 实现 → 用 test_functions 本地复现

• 怀疑数据 → 抽 JSONL 看 rollout_extra

• 怀疑超参 → 回提交脚本对照《强化学习训练配置 — 提交与配置》

标准排查流程

1. Step 1 详情页签确认状态与失败时间点

2. Step 2 日志页签末尾 100-500 行（SDK AgenticRL.logs(job_id, lines=100) / CLI dashscope rl logs --lines 100）

3. Step 3 区分错误层：

   • 用户函数错（Rollout/Reward 抛异常）→ test_functions 本地复现 → 改代码 → 重新 register/run

   • 框架错（OOM / 资源不足 / 网络）→ 看 fully_async 队列 + 调 concurrency / capacity

   • 数据错（JSONL 解析失败）→ 校验单条格式与 rollout_extra

训练期常见报错模式