Skip to main content

强化学习提交前自检

提交 RL 训练任务前的分层自检流程:从免费的本地校验到低成本的链路冒烟,在产生训练费用之前拦截数据、代码、配置与函数错误。

RL 训练按训练单元小时计费(以 IV 型 24 实例后付费为例,约 984 元/小时),任务启动后才暴露的错误成本最高。本页提供按成本递进的提交前自检流程:每步成本远低于后续步骤,拦截上一步验证不出的错误。 各步骤说明:

步骤

成本量级

拦截的错误

前提

检查数据格式

0 元(本地)

JSONL 格式错、字段缺失、数据量不足

Python 3.10+ 本地环境

本地验证函数

0 元(本地)

依赖缺失、classpath 错、数据模型构造错、评分逻辑错

本地环境 + 项目目录

远程测试函数

数元(FC 实例冷启动与少量调用)

云端容器环境错(依赖装不上、打包问题、运行时异常)

API Key + DashScope SDK

提交冒烟测试

约 16 元起

提交配置错、超参被拒、资源配置非法

API Key + MTU 后付费开通

精简首次训练

数百元起(视停止时机,完整跑通千余元)

只有真实训练才暴露的问题(采样慢、首个 step 报错)

同正式训练

已完整走过自检流程、后续仅部分变更时,无需全量重走:
  • 更换数据(新数据集或数据扩量)→ 从「检查数据格式」重起
  • 修改函数代码 → 从「本地验证函数」重起
  • 仅调整超参或资源配置 → 从「提交冒烟测试」重起(约 16 元验证新配置被服务端接受)

检查数据格式(免费)

在项目根目录执行以下脚本,逐行校验训练/验证数据(files 路径替换为实际数据集):
import json, sys
from pathlib import Path

errors = []
files = ["data/calc_train_min.jsonl", "data/calc_validation_min.jsonl"]
batch_size = 64  # 与提交时的 hyper_parameters.batch_size 一致

for name in files:
    lines = Path(name).read_text(encoding="utf-8").strip().splitlines()
    for i, ln in enumerate(lines, 1):
        try:
            obj = json.loads(ln)
            if "messages" not in obj:
                errors.append(f"{name}:{i} 缺 messages 字段")
            if "rollout_extra" not in obj:
                errors.append(f"{name}:{i} 缺 rollout_extra 字段")
        except json.JSONDecodeError as e:
            errors.append(f"{name}:{i} JSON 解析失败: {e}")
    if len(lines) <= batch_size:
        print(f"[WARN] {name} 仅 {len(lines)} 行,数据量须大于 batch_size")

print(f"共检查 {len(files)} 个文件,错误 {len(errors)} 项")
for e in errors[:10]:
    print("[FAIL]", e)
sys.exit(1 if errors else 0)
通过标准:错误 0 项,无 WARN(或 WARN 数据量符合预期);并确认两点——验证集与训练集相互独立(不同源、不重叠);rollout_extra 中的 key 与 Reward 评分逻辑读取的 key 一致。 数据行数与 batch_size 的关系按场景区分:
  • 提交冒烟测试:少量数据即可(如 10 行),同时将 batch_size 调小——服务端要求 batch_size 取值范围为 8~2048,冒烟时设为 8 即可提交。
  • 正式训练:训练数据量须大于 batch_size;batch_size 越大训练越稳定,按训练配置 — 必填参数表取值。
数据格式字段含义与数据量建议见强化学习训练概述 — 数据格式。

本地验证函数(免费)

组件可导入与可构造

classpath 即 包路径.模块.类名 字符串(如 functions.reward.my_reward.MyRewardProcessor),在本地自检、函数注册、训练提交三处填写的必须是同一个值。将以下示例中的类替换为自定义函数类后,在项目根目录执行:
import sys
sys.path.insert(0, ".")  # 在项目根目录执行

try:
    # 1) 数据模型可构造(AgentOutput 四字段)
    from dashscope.finetune.reinforcement.component.data.base_data_model import AgentOutput
    AgentOutput(messages=[{"role": "user", "content": "hi"}],
                reward_score=0.95, rollout_extra={"answer": "42"},
                rollout_metrics={"latency": 1.2})

    # 2) 自定义函数类可导入(与注册/提交时的 classpath 为同一字符串)
    from functions.rollout.my_rollout import MyRolloutProcessor
    from functions.reward.my_reward import MyRewardProcessor

    print("导入自检 OK")
except Exception as e:
    print(f"[FAIL] {type(e).__name__}: {e}")
    sys.exit(1)
通过标准:导入自检 OK。常见 FAIL 是 ModuleNotFoundError(依赖未列入 requirements.txt 或本地未安装)——云端容器同样会报此错误,请在本地先行修复。
评分函数中 TaskStatus 的用法有一个高频错误:评分得 0 分应返回 SUCCESS,临时性错误(超时、网络抖动)才返回 FAILED。详见开发指南 — 评分场景的 TaskStatus 判定。

设计最小测试用例

在本地实测评分之前,先为自定义函数设计 3 个可人工推算出预期得分的测试输入——预期得分以自定义评分逻辑为准:

用例

构造方法

预期得分

满分样例

messages 中放一条必然命中评分条件的回答(包含正确答案、满足格式),ground_truth 填对应真值

评分逻辑的满分(如 1.0)

零分样例

messages 中放一条必然不命中的回答(答案错误、格式不符)

0.0

边界样例

最易判错的形态:空 messages、超长回答、答案部分匹配、大小写不同

按已定义的边界行为(边界行为未定义时,先在评分逻辑中补充定义——边界未定义是训练期错误的常见来源)

三份测试输入分别保存(如 my_reward_test_full.json、my_reward_test_zero.json、my_reward_test_edge.json)。Reward 类输入模板:
{
  "func_type": "reward",
  "ground_truth": "42",
  "agent_output": {
    "messages": [
      {"role": "user", "content": "计算 6 × 7"},
      {"role": "assistant", "content": "### ANSWER: 42 ###"}
    ]
  }
}
Rollout 类测试输入结构(messages、model_resource、sampling_params 等字段)见开发指南 — 测试输入格式。 评分逻辑设计层面,提交前建议完成两项自检:Reward 撰写前自检 10 问;准备 50-200 条人工标注的 gold set 用于评分一致性自检。同时注意 reward_metrics 的字段名保持稳定——改名会中断控制台指标曲线的连续性。

本地服务实测

不部署到云端,在本地以服务方式启动自定义函数并逐个发送上述测试输入:
# 终端 1:启动本地函数服务(bash,PROCESSOR_CLASS 换为自定义类)
FUNC_TYPE=reward PROCESSOR_CLASS=functions.reward.my_reward.MyRewardProcessor \
PYTHONPATH=. python -m dashscope.finetune.reinforcement.component.server.server

# 终端 2:逐个发送三份测试输入
curl -X POST http://localhost:8000/api/v1 \
  -H "Content-Type: application/json" \
  -d @my_reward_test_full.json
Windows PowerShell 等价命令:
# 终端 1
$env:FUNC_TYPE="reward"
$env:PROCESSOR_CLASS="functions.reward.my_reward.MyRewardProcessor"
$env:PYTHONPATH="."
python -m dashscope.finetune.reinforcement.component.server.server

# 终端 2(PowerShell 下 curl 为 Invoke-WebRequest 别名,@file 语法不可用)
Invoke-RestMethod -Method Post -Uri http://localhost:8000/api/v1 `
  -ContentType "application/json" -InFile my_reward_test_full.json
预期返回示例(各字段位置以实际返回为准):
{"reward": {"reward_score": 1.0, "reward_metrics": {"accuracy": 1.0}},
 "status": "success", "error": null, "error_code": null}
通过标准:三份输入的返回 status 均为 success,且 reward 中的 reward_score 与预期得分逐个一致。任一不一致即为评分逻辑缺陷,请在本地修复至一致后再进行远程测试。
Rollout 函数实测需将测试输入中的 model_resource 换为可用的推理端点与 API Key:须使用支持推理调用的 API Key(在百炼控制台 API-KEY 页面创建,sk- 前缀)。训练提交所用的凭证若不支持推理调用,此处会返回 401(Incorrect API key)。训练期无需自行配置推理端点——端点与 Key 由训练框架运行时自动注入(见RolloutInput 关键字段)。

远程测试函数

本地通过后,将函数注册到云端并在真实 FC 容器中执行一次——本地与容器环境的差异(依赖安装、打包路径、运行时行为)只有这一步能拦住。
Windows 系统限制:当前 SDK 版本在 Windows 上打包函数存在兼容缺陷,注册可成功但 test_functions 会以 Precondition Failed 失败(函数实例在启动前即退出)。建议在 WSL 或 Linux 环境执行本步骤与后续的提交操作;该问题已反馈 SDK 维护方。
import asyncio, json
from dashscope.finetune.reinforcement import (
    AgenticRLFunctionComponent, FunctionType, FunctionComponentModel)
from dashscope.finetune.agentic_rl import AgenticRL

async def main():
    client = AgenticRL()
    # 注册自定义函数(classpath 与本地导入自检为同一字符串)
    ids = await client.register_functions(
        functions=[AgenticRLFunctionComponent(
            type=FunctionType.REWARD,
            fcmodel=FunctionComponentModel(
                classpath="functions.reward.my_reward.MyRewardProcessor"))],
        lazy_load=False)   # 立即拉起实例用于测试
    # register_functions 返回 6 元组,依次为:
    # (rollout_entity_ids, reward_entity_ids, group_reward_entity_ids,
    #  rollout_instance_ids, reward_instance_ids, group_reward_instance_ids)
    # 未注册的类型为空列表
    reward_entity_ids, reward_instance_ids = ids[1], ids[4]

    # 逐个发送本地验证的三份测试用例(input_data 接受 dict)
    for case in ["my_reward_test_full.json", "my_reward_test_zero.json",
                 "my_reward_test_edge.json"]:
        with open(case, "r", encoding="utf-8") as f:
            input_data = json.load(f)
        result = await AgenticRL.test_functions(
            instance_id=reward_instance_ids[0],
            functype=FunctionType.REWARD,
            input_data=input_data,
        )
        print(case, result)

asyncio.run(main())
通过标准:三份用例的返回与本地验证结果逐项一致。云端结果与本地不一致时,优先检查 requirements.txt(容器按其安装依赖);实例日志可通过 query_all_function_instance_logs 拉取(用法见强化学习开发指南 — 远程测试)——若函数实例在启动阶段即失败,日志可能尚未产生(返回空列表),此时以 test_functions 返回结果中的错误信息为准。
  • Rollout 函数的远程测试会将测试输入中的 model_resource 作为真实推理端点调用,填入有效的基座模型与 API Key 即可。CLI 等价命令:dashscope rl test_functions "rw-ins-xxx" --type reward --input my_reward_test_full.json。
  • 每次 register_functions 与每次 run() 提交都会注册新的函数实体并累积在账号中(本地项目根目录还会生成 start.sh 与临时打包文件,可忽略或删除)。函数稳定后可用 submit_job 以 entity_id 复用注册结果,避免重复注册(见训练配置 — 分步提交)。

提交冒烟测试

用与正式提交完全相同的参数(函数、数据、超参、资源)真实提交一次,确认服务端接受全部配置后立即取消。计费口径:以 24 实例后付费为例约 984 元/小时(后付费最小计费粒度 1 分钟,即约 16 元/分钟);从提交到取消控制在 1 分钟内约 16 元起,取消动作每延迟 1 分钟增加约 16 元。
import asyncio
from dashscope.finetune.agentic_rl import AgenticRL

async def main():
    client = AgenticRL()
    # run 为 async;参数为正式提交的完整参数(函数/数据/超参/资源)
    result = await client.run(
        model="your-model",
        functions=[...], training_datasets=[...], validation_datasets=[...],
        hyper_parameters={...}, resources={...})

    # 先确认提交结果再取 job_id(提交被拒时 output 为空,直接取值会报错)
    if result.status_code != 200:
        print(f"提交被拒: {result.message}")   # 服务端拒绝原因(如 batch_size 超范围)
        return

    # ---- 拿到 job_id 后立即执行以下两行(get/cancel 为同步方法,无需 await)----
    job_id = result.output.job_id
    g = AgenticRL.get(job_id=job_id)      # 回显任务详情,核对超参与资源配置
    c = AgenticRL.cancel(job_id=job_id)   # 立即取消,控制费用

asyncio.run(main())
通过标准:
  • run 正常返回(status_code 为 200)且 job_id 非空——函数注册、数据上传、参数校验全链路被服务端接受
  • get 回显的 hyper_parameters 中,未显式填写的字段会被服务端自动补默认值(如 enable_thinking、max_off_policy_strategy 等)——核对补全值与预期无冲突
  • 核对两项资源配置:mtu_capacity = nnodes_rollout × n_gpus_rollout + nnodes_training × n_gpus_training(约束说明);函数 Runtime 的 memory_size ≥ 4096、disk_size ≥ 512(Runtime 资源配置)
拿到 job_id 后立即执行 cancel——未取消的任务会排队进入 RUNNING 并按训练单元小时计费。若脚本在 cancel 前抛错(如对同步方法误用 await),任务可能已提交但脚本丢失 job_id,此时通过 AgenticRL.list() 找回最新任务再取消。

精简首次训练

正式全量训练前,用最小数据量 + 1 个 epoch 真实跑一次:确认首个 step 能产出轨迹与指标、Reward 有梯度(非恒 0 恒 1)。 时长预期(demo 精简数据 128 条、batch_size=64、24 实例后付费的实测口径):
  • 提交到进入 RUNNING 约 1 分钟(资源排队正常时)
  • 首个 step 产出轨迹与指标通常需 30 分钟以上(首个 step 需完成全部 Rollout 采样)
  • 完整跑通到 SUCCEEDED 约 1 小时 45 分钟
费用口径(按训练单元小时计,单价见训练单元价格):
  • 以「首个 step 指标出现且正常」为停止点,通常在数百元量级;完整跑通约千余元
  • 任务在进入训练前取消不计费(实测 usage 为 0);进入训练后按实际用量计,任务详情的 usage 字段回显累计用量(实测参考:完整跑通 1h43m 的任务 usage=4384)
  • 全量训练费用估算:实例数 × 预计时长 × 小时单价——预计时长可用「数据量 / batch_size × 每 step 耗时 × n_epochs」粗算,或先以精简首跑的实测时长等比放大
首个 step 指标是否正常的判定标准(critic/rewards/mean、actor/entropy 等健康判据)见可观测配置 — 关键指标速查。具体实践(精简数据集、n_epochs=1)见强化学习训练概述 — 起步技巧。

常见报错速查

本表覆盖数据检查至提交环节的高频报错。任务已进入训练后(首个 step 崩溃、采样超时、输出乱码等)的报错归因,请转可观测配置 — 问题排查决策树。 自检各层的高频报错与定位:

环节

错误信息

原因分析

处理方法

提交

ValidationError: extra inputs are not permitted(如 weight)

该参数不属于当前组件类型(weight 是 RewardFunctionComponent 的字段,不在 AgenticRLFunctionComponent 上)

核对组件类型与字段归属;分步提交不带 weight

提交

[3005] Job submission failed: TypeError(unexpected keyword argument)

调用了不存在的方法参数(如 run(lazy_load=...)、submit_job(training_file_ids=...))

数据集用 datasets=[Dataset(type=DatasetsType.VALIDATION, data_source_type=DataSourceType.FILE_ID, file_id=...)] 完整三参数传入;其余参数以本页与配置篇提交方式示例为准

提交

[400] InvalidParameter:batch_size need to be in range [8, 2048]

batch_size 超出服务端允许范围(冒烟时数据量少,batch_size 须调至 8)

调整 batch_size 至 8~2048;冒烟场景配合少量数据(见检查数据格式)

提交

[1002] I/O error: Failed to load from dict

YAML 方言错误(不支持的顶层键或字段类型)

使用配置篇的 job.yaml 模板结构

提交

TypeError: object FineTune can't be used in 'await' expression

对同步方法(submit_job / get / cancel / list / logs)误用 await

去掉 await;注意 run/register_functions/upload_datasets/test_functions 为 async,任务管理类方法为同步

远程测试

ModuleNotFoundError(实例日志中)

requirements.txt 缺依赖,或包结构无法在容器内解析

补齐 requirements.txt 并回到本地验证复现

远程测试

Precondition Failed(test_functions 返回),或实例日志含 bash\r: No such file or directory、start.sh 中出现反斜杠模块路径

Windows 打包兼容问题(CLI 与 SDK 共用打包链路,两侧均会复现;实例启动即退出时日志为空)

在 WSL 或 Linux 环境执行远程测试与提交;该问题已反馈 DashScope SDK 维护方

后续步骤