在线策略蒸馏训练配置

百炼在线策略蒸馏训练配置：提交方式、教师模型配置、超参数、调参避坑、任务管理与常见问题

OPD 训练提交时需配置教师模型与超参。本文给出三种提交方式、教师模型配置、超参取值、调参决策、任务管理与常见问题排查。

提交训练任务

三种提交方式，灵活度递增。配置优先级：__init__()（SDK 初始化函数）默认值 < YAML < run() 运行时参数（后者覆盖前者）。传入 teacher_model 触发蒸馏。

推荐：一步完成（run）

通过 AgenticRL().run(...) 一步完成函数注册、数据上传与任务提交，多传 teacher_model 触发蒸馏。

from dashscope.finetune.agentic_rl import AgenticRL          # OPD 训练客户端
from dashscope.finetune.reinforcement import (               # 组件与数据类型
    RewardFunctionComponent, FunctionComponentModel,
    FunctionComponentRuntime, TrainingDataset,
    ValidationDataset, DataSourceType,
)

client = AgenticRL()                                        # 初始化训练客户端
result = await client.run(                                  # 异步提交：注册函数→上传数据→提交任务
    job_name="my-opd-job",
    model="qwen3.5-9b",                        # 学生模型（训练对象，被蒸馏的学生）
    teacher_model="qwen3.5-397b-a17b",         # 教师模型，OPD 唯一新增参数；传入即触发蒸馏
    training_datasets=[TrainingDataset(        # 训练集：FILE_ID 方式由 SDK 自动上传并换 file_id
        data_source_type=DataSourceType.FILE_ID,
        file_name="./data/train.jsonl")],
    validation_datasets=[ValidationDataset(    # 验证集：用于训练中评估，指标驱动调参
        data_source_type=DataSourceType.FILE_ID,
        file_name="./data/validation.jsonl")],
    functions=[
        # 不传 Rollout 组件 → Model OPD（原生 Rollout）；传 Rollout 组件 → Agentic OPD（自定义 Rollout，支持多轮/自定义交互）
        RewardFunctionComponent(               # 仅传 Reward 组件：在原生 Rollout + 教师蒸馏基础上叠加任务奖励
            name="reward-1", weight=1.0, timeout=120,   # weight=奖励权重，timeout=单次打分超时秒数
            fcmodel=FunctionComponentModel(
                zipdir=".",  # 工作区根目录（含 functions/），SDK 打包此目录上传至 FC
                classpath="functions.reward.reward.MyRewardProcessor"),  # 入口类全路径（示例类名，实际由您自定义）
            runtime=FunctionComponentRuntime(
                cpu=2, memory_size=4096, disk_size=512,            # 函数实例 CPU/内存/磁盘
                concurrency=20, capacity=10, min_capacity=10, max_capacity=30)),  # 并发与弹性容量
    ],
    # 纯蒸馏场景：改传 functions=None（而非空列表 []），不注册任何函数，reward 派生指标不上报
    hyper_parameters={                         # 训练超参，完整字段见下方 §训练超参数
        "algorithm": "gspo", "learning_rate": 1e-6, "lr_scheduler_type": "cosine",
        "n_epochs": 1, "n_rollouts": 8, "batch_size": 128,
    },
    resources={"charge_type": "mtu_postpaid", "mtu_spec_code": "MTU4", "mtu_capacity": 24},  # 计费资源：后付费/规格/容量
)

functions 参数决定运行模式（纯蒸馏 / Model OPD / Agentic OPD），与 teacher_model 无关——teacher_model 只负责触发蒸馏。模式选型详见概述适用场景。此处仅列 SDK 层的取值映射，区分依据是是否传入 Rollout 组件（决定用原生 Rollout 还是自定义 Rollout）：

• Model OPD：不传 Rollout 组件 → 用原生 Rollout，含纯蒸馏（functions=None）与加 Reward（仅传 Reward 组件叠加任务奖励）两档
• Agentic OPD（无 Reward）：仅传 Rollout 组件 → 自定义 Rollout（支持多轮对话、自定义交互、结构化 tool call）+ 教师蒸馏
• Agentic OPD（含 Reward）：同时传 Rollout + Reward → 自定义 Rollout + 教师蒸馏 + Reward
• 传 None（而非空列表 []）→ 纯蒸馏，reward 派生指标不上报，蒸馏损失类指标与 teacher 健康类指标仍正常上报

YAML 配置

适合多次实验或管理多组参数，通过 teacher_model 字段指定教师模型。

## config.yaml（简化示意）
name: "my-opd-job"
model:
  name: "qwen3.5-9b"                           # 学生模型（训练对象）
teacher_model: "qwen3.5-397b-a17b"             # 教师模型（OPD 新增），传入即触发蒸馏

datasets:
  - type: "training"                           # 训练集
    data_source_type: "file_id"                # file_id 方式：SDK 自动上传并换 file_id
    file_name: "./data/train.jsonl"
  - type: "validation"                         # 验证集，训练中评估用
    data_source_type: "file_id"
    file_name: "./data/validation.jsonl"

functions:                                     # 不传 Rollout 组件即 Model OPD；纯蒸馏写 functions: null
  - type: "reward"                             # 仅传 Reward：原生 Rollout + 教师蒸馏 + 任务奖励
    name: "reward-1"
    weight: 1.0                                # 奖励权重，多 reward 时加权求和
    timeout: 120                               # 单次打分超时秒数
    fcmodel:
      classpath: "functions.reward.reward.MyRewardProcessor"  # 入口类全路径（示例类名，实际由您自定义）
    runtime:
      cpu: 2                                   # 函数实例 CPU 核数
      memory_size: 4096                        # 内存 MB
      concurrency: 20                          # 单实例并发打分数
      capacity: 10                             # 当前实例数
      min_capacity: 10                         # 最小实例数（保底）
      max_capacity: 30                         # 最大实例数（弹性上限）

training:
  type: "pg_opd"                               # OPD 训练类型；传 teacher_model 后自动置此值，无需手填
  hyper_parameters:
    algorithm: "gspo"                          # 训练算法
    learning_rate: 1e-6                         # 学习率，OPD 起点低于 SFT
    lr_scheduler_type: "cosine"                 # 学习率调度器
    n_epochs: 1                                # 训练轮次
    # ... 完整字段见下方 §训练超参数
  resources:
    charge_type: "mtu_postpaid"                # 后付费计费
    mtu_spec_code: "MTU4"                       # 算力规格
    mtu_capacity: 24                           # 容量

加载并执行：

client = AgenticRL()                                            # 初始化训练客户端
client.init(config_path="config.yaml", name="my-opd-from-yaml") # 加载 YAML 配置，name 覆盖 YAML 中的 job_name
result = await client.run()                                     # 异步提交任务；run() 参数覆盖 init() 与 YAML 默认值

CLI 命令

通过 dashscope rl run 提交，--teacher-model 覆盖 YAML 中的 teacher_model。

dashscope rl run -c config.yaml --teacher-model qwen3.5-397b-a17b
# -c 指定 YAML 配置文件路径
# --teacher-model 指定教师模型，覆盖 YAML 中的 teacher_model 字段；传入即启用 OPD

--teacher-model help 文案（原文）：Enable OPD with this teacher model (overrides YAML); Rollout and Reward are optional. 含义：启用 OPD 并指定教师模型（覆盖 YAML）；Rollout 与 Reward 可选。

常用 CLI 命令：

import asyncio
from dashscope.finetune.agentic_rl import AgenticRL          # OPD 训练客户端
from dashscope.finetune.reinforcement import (                # 组件与数据类型
    RewardFunctionComponent, FunctionComponentModel,
    FunctionComponentRuntime, TrainingDataset,
    ValidationDataset, DataSourceType,
)

async def submit(args):
    client = AgenticRL()                                    # 初始化训练客户端
    # 纯蒸馏时传 None 而非空列表：None 使控制面（调度层）执行原生 Rollout，[] 不一定等价
    # --no-reward 是示例侧便利开关（非 SDK 参数），等价于 SDK 层 functions=None
    function_components = (
        None if args.no_reward                              # 纯蒸馏：不注册任何函数
        else [RewardFunctionComponent(                      # 加 Reward：原生 Rollout + 教师蒸馏 + 任务奖励
            name="reward-1", weight=1.0, timeout=120,       # weight=奖励权重，timeout=单次打分超时秒数
            fcmodel=FunctionComponentModel(
                zipdir=str(args.workspace_dir.resolve()),   # 工作区根目录，显式指定避免入口类定位失败
                classpath="functions.reward.reward.MyRewardProcessor"),  # 入口类全路径（示例类名，实际由您自定义）
            runtime=FunctionComponentRuntime(**build_runtime()))]        # 并发与弹性容量由 build_runtime() 构造
    )
    result = await client.run(                              # 异步提交：注册→上传→提交
        job_name=args.job_name,
        model=args.student_model,          # 学生模型（训练对象）
        teacher_model=args.teacher_model,  # 教师模型，传入即触发蒸馏
        training_datasets=[...],           # 训练集（示例省略构造）
        validation_datasets=[...],         # 验证集（示例省略构造）
        functions=function_components,     # None=纯蒸馏；[Reward...]=Model OPD；含 Rollout=Agentic OPD
        hyper_parameters={...},            # 训练超参（示例省略，见下方 §训练超参数）
    )
    return result.output.job_id            # 返回 job_id，供后续查询/取消/日志使用

配置教师模型

teacher_model 是触发蒸馏的提交参数。传入即触发蒸馏，不传则不触发。传入后 SDK 内部字段 training_type 自动置为 pg_opd（策略蒸馏训练类型标识，对应 YAML 中的 training.type），无需也不能手动指定训练类型。

行为结论：

• 传 teacher_model 即强制 training_type=pg_opd，无需也不能手动指定训练类型
• YAML 中写 training.type: pg_opd 但未传 teacher_model 时，控制面报错 error 3006（教师模型缺失）
• hyper_parameters 中未声明的键不会被识别，不会报错也不会生效

三条硬约束

教师模型配置须同时满足以下三条约束，任一不满足都会导致蒸馏失效或提交被拒。

训练超参数

hyper_parameters 字段名与取值范围一致，按 4 组分类：算法（algorithm；kl_loss_coef OPD 未启用）/ 优化（learning_rate, lr_scheduler_type, lr_warmup_steps, n_epochs）/ 数据吞吐（batch_size, n_rollouts, ppo_mini_batch_size, max_length, max_prompt_length）/ 评估保存（eval_steps, save_steps, save_strategy, save_total_limit）。

必填参数综合表

下方综合表合并字段定义、取值范围与按模型规模 × 数据阶段的起点推荐；直接采用起点列即可启动训练，再按 §调参决策表迭代。

模型规模分界：学生模型参数量 ≤14B 算小模型，≥30B 算大模型（如 Qwen3.5-9b 属小，397b-A17b 属大）。表中"小模型快速验证"列适用于链路冒烟与小规模训练，"大模型"列适用于正式大规模训练；介于两者之间取两列并集后按实际收敛情况微调。

三个必须一起调整的参数关系（决定调参时哪几个必须联动）：

• 样本数：batch_size × n_rollouts = 每步实际生成样本数
• mini-batch 上限：ppo_mini_batch_size ≤ batch_size × n_rollouts
• learning_rate 决定蒸馏收敛速度——OPD 无 kl_loss_coef 约束模型偏离初始策略（防止输出风格漂移），学习率是唯一控制收敛速度的参数

选填参数

以下参数用于控制分布式训练资源配置，一般使用默认值即可。表中默认值为未传时的取值，实际取值以提交时传入为准。

教师模型部署参数与不启用项

• algorithm：默认 gspo（GSPO，分组相对策略优化）。启用 reward 时决定策略优化的实现方式；纯蒸馏（不注册 reward）时不参与损失计算，一般无需改动
• 教师模型的部署资源：可显式配置 opd_teacher_* 参数，不传取默认值。示例默认值如下：

教师模型经 vLLM（百炼推理引擎）部署，KV cache（推理显存中缓存已计算 token 的机制）容量决定打分吞吐。按教师模型规模与序列长度调整：

• 序列长：调高 opd_teacher_max_model_len（伴随 opd_teacher_max_num_batched_tokens↑）
• 显存紧：调低 opd_teacher_gpu_memory_utilization

其余参数一般保持默认。

• kl_loss_coef：OPD 不消费该参数——蒸馏不通过 KL 散度（衡量两个概率分布差异的指标）约束策略偏离，收敛速度由 learning_rate 单独控制。必填表中标"—"即表示 OPD 不消费。保留默认或留空均可，无需清零或删除。

调参与避坑

调参决策表

指标异常时对照本表选择首选调整项与幅度；完整指标含义与排查决策树见在线策略蒸馏可观测配置。

调参操作建议

• 先看 valid_token_rate：该指标小于 1 时教师模型打分存在缺失，其余指标解释力下降，应先排查再调超参
• 一次只动一个变量：同时调 learning_rate 和 batch_size 会无法归因
• 训练 eval_steps × 3 步再判断趋势：蒸馏曲线噪声较小但短周期难以判断趋势，至少 3 个评估间隔再判断走向

反模式

以下配置在实践中已证实会导致训练失败或资源浪费，应避免。

任务管理

本节给出训练任务的查询、取消、删除与查看日志命令，以及实验管理与续训方法。

SDK / CLI 命令对照

任务管理命令（查询、取消、删除、日志）如下，提交时多传 teacher_model：

实验管理

• YAML 多实验模式：job_name 标识实验、finetuned_output 标识产出模型，每次实验改这两个即可隔离；YAML 集中管理配置便于 Git 版本化
• 配置优先级：__init__() < YAML < run() 运行时参数——做对照实验只改最外层
• 扫参 / CI 场景（进阶用法，一般用户可跳过）：函数已稳定只换超参时，可在 functions 组件级传入 entity_id（如 RewardFunctionComponent(..., entity_id="rw-xxx")）复用已注册组件，省去重复注册与上传。Entity ID（ro- 表示 Rollout、rw- 表示 Reward）从首次注册返回值中取，字段名 entity_id，可入 CI 配置长期复用：

result = await client.run(...)                    # 首次提交：注册函数组件并上传代码/数据
entity_id = result.output.entity_id              # 从首次注册返回值取 entity_id，ro- 表示 Rollout、rw- 表示 Reward
# 后续扫参/CI 只换超参时，在组件级传 entity_id="rw-xxx" 复用已注册组件，省去重复注册与上传

续训与 Checkpoint

Checkpoint 保留与选择：

• save_strategy=steps + save_steps=100 + save_total_limit=3：最多保留 3 个，超出自动清理最旧
• 选哪个 Checkpoint：启用 reward 时看 validation/data/reward/mean@1 选最佳点（纯蒸馏不启用 reward 时该指标不上报，依据 actor/distillation/loss 趋稳点选择），不一定是最后一个
• 保留 3~5 个权衡空间与回滚需求

基于已发布 Checkpoint 续训：

• 续训 = 把上次产出的模型作为 model 入参再次提交，超参可微调（lr 通常调小）
• 适用：数据增量 / Reward 调整 / 长链路逐步收敛
• 注意：基础模型版本须一致，跨基座模型不可直接续训
• 多阶段训练流水线中，每阶段产出可作为下一阶段的 model 入参逐级递进

后续步骤

• 回顾原理与场景选型 → 在线策略蒸馏训练概述
• Model OPD 开发（纯蒸馏/Reward） → Model OPD 开发
• Agentic OPD 开发（自定义 Rollout） → Agentic OPD 开发
• 训练指标速查、效果判断与问题排查 → 在线策略蒸馏可观测配置

常见问题