强化学习的可观测配置

Step 1：添加依赖

在项目根目录的 requirements.txt 中添加以下 OpenTelemetry 相关依赖：

opentelemetry-api==1.41.1
opentelemetry-sdk==1.41.1
opentelemetry-exporter-otlp-proto-http==1.41.1
opentelemetry-processor-baggage==0.62b1
loongsuite-util-genai==0.4.0

Step 2：添加观测代码

代码改动集中在 5 个装饰器/函数。它们会自动嵌套，形成完整的调用链：

[ENTRY: ROLLOUT] @observe_processor          ← Rollout 处理器入口
├── [LLM] trace_client / @observe_llm        ← LLM 调用
│   └── (OpenAI / LangChain / DashScope API)
├── [TOOL] trace_tool / @observe_tool        ← 工具调用
│   ├── tool: calculator (MCP)
│   └── tool: response_scorer (自定义)
└── [custom] rollout_metrics                 ← Rollout 自定义指标

[ENTRY: REWARD] @observe_processor           ← Reward 处理器入口
├── [LLM] trace_client / @observe_llm        ← LLM 调用（评分用）
├── [TOOL] trace_tool / @observe_tool        ← 工具调用
└── [custom] reward_metrics                  ← Reward 自定义指标

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)

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,
        )

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

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() 之后调用

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

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

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

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

Step 3：提交任务

提交任务时，Runtime 的 env 字段留空即可——链路追踪默认开启：

from dashscope.finetune.agentic_rl import AgenticRL
from dashscope.finetune.reinforcement import (
    RolloutFunctionComponent, RewardFunctionComponent,
    FunctionComponentModel, FunctionComponentRuntime
)

client = AgenticRL()

rollout_runtime = FunctionComponentRuntime(
    cpu=2, memory_size=4096, disk_size=512,
    concurrency=30, capacity=30,
    min_capacity=30, max_capacity=60,
    env={}  # 留空 = 默认开启 Tracing
)

reward_runtime = FunctionComponentRuntime(
    cpu=2, memory_size=4096, disk_size=512,
    concurrency=30, capacity=30,
    min_capacity=30, max_capacity=60,
    env={}
)

result = await client.run(
    model="qwen3.5-9b",
    functions=[
        RolloutFunctionComponent(
            name="rollout-1",
            fcmodel=FunctionComponentModel(
                classpath="functions.rollout.rollout.CalcXRolloutProcessor"),
            runtime=rollout_runtime,
        ),
        RewardFunctionComponent(
            name="reward-1",
            weight=1.0,
            fcmodel=FunctionComponentModel(
                classpath="functions.reward.reward.DemoRewardProcessor"),
            runtime=reward_runtime,
        ),
    ],
    ...
)

轨迹详情 — 对应 @observe_processor

在轨迹 Tab 的轨迹详情子页面，可以看到每次 Rollout 的完整交互过程：

• 轨迹列表：展示所有采样轨迹，支持按 Sample ID / 轨迹 ID / Epoch / Step 筛选

• 对话过程：完整的多轮交互（user → assistant → tool_call → tool_result → assistant），直观看到模型的推理链

• Reward 分数：每个 Step 显示对应的 Reward 分数和状态（SUCCESS/FAILED）

工具调用分析 — 对应 trace_tool / @observe_tool

在轨迹 Tab 的工具调用分析子页面，可以查看：

• 工具调用记录：工具名称、调用参数、返回结果和耗时

• Tracing 子 Tab：每条轨迹的 Span 树，可展开查看每次工具调用和 LLM 请求的完整详情

典型用途：排查 Agent 的工具调用失败——哪个工具报错？参数传递是否正确？耗时是否过长？

Reward 分析 — 对应 reward_metrics

在轨迹 Tab 的Reward 分析子页面，从三个维度评估训练效果：

• Step 维度：选择训练 Step，查看该 Step 下所有样本的 Reward 聚合（平均分、成功率、趋势图），判断整体训练趋势

• Sample 维度：选择 Sample ID，查看同一样本在不同轨迹中的 Reward 对比，发现问题样本

• Trajectory 维度：查看单条轨迹的每个评分维度原始分，用于归因分析

指标 Tab — 对应 rollout_metrics / reward_metrics

在指标 Tab 的 trace/ 分组，可以看到您在代码中定义的所有自定义指标的聚合曲线（avg / sum）。

除了 trace/ 分组（40 个指标，含用户自定义），以下系统分组也与 Agent 行为分析密切相关：

• actor/（8 个）：策略网络指标 — loss、entropy、KL 散度、grad_norm

• critic/（12 个）：价值网络指标 — rewards、advantages、score 的 max/mean/min

• trajectory/（16 个）：轨迹统计 — 回复长度、截断率、对话轮次

• perf/（5 个）：性能指标 — MFU、throughput、time_per_step、total_num_tokens

完整的 13 组 / 123 个训练指标说明请参见强化学习训练配置中的指标参考章节。

时间线 Tab

在时间线 Tab 查看训练各阶段（Rollout 生成、Reward 计算、模型更新、Checkpoint 保存）的起止时间和持续时长，帮助判断是否存在性能瓶颈。

Trace 数据在哪里查看？

在百炼控制台完成 ARMS 授权后：

• 轨迹 Tab → 轨迹详情 / Reward 分析 / 工具调用分析

• 指标 Tab → trace/ 分组

Trace 看不到怎么办？

按以下顺序排查：

1. 确认 Runtime env 中没有设置 ENABLE_TRAJECTORY=false（默认开启，无需显式设置）

2. 确认已在百炼控制台授权 ARMS 服务

3. 检查 requirements.txt 是否包含 OpenTelemetry 相关依赖

4. 检查 process() 方法是否添加了 @observe_processor 装饰器

开启 Tracing 对性能有影响吗？

Tracing 会增加少量存储和延迟开销。建议在开发调试阶段开启，正式大规模训练时如只需看训练指标（Actor/Critic/Perf 等）而无需轨迹详情，可以关闭：在 Runtime env 中设置 {"ENABLE_TRAJECTORY": "false"}。关闭后系统指标不受影响。

如何在指标中区分不同的 Reward 函数？

通过 RewardFunctionComponent(name="reward-1") 为每个 Reward 函数设置唯一名称。该名称会出现在指标路径中（trace/reward_metrics/reward-1/...），控制台会自动按名称分组展示。

如何关闭 Tracing 以节省成本？

在 Runtime 的 env 中设置 {"ENABLE_TRAJECTORY": "false"}。可以通过 FunctionComponentRuntime(env={"ENABLE_TRAJECTORY": "false"}) 或 YAML 中设置 env: {ENABLE_TRAJECTORY: false}。