提交 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 并回到本地验证复现 |
远程测试 |
| Windows 打包兼容问题(CLI 与 SDK 共用打包链路,两侧均会复现;实例启动即退出时日志为空) | 在 WSL 或 Linux 环境执行远程测试与提交;该问题已反馈 DashScope SDK 维护方 |
后续步骤
- 自检全过,提交正式训练 → 强化学习训练配置 — 提交与配置
- 测试用例设计与函数开发细节 → 强化学习开发指南
- 训练启动后的指标观察与异常归因 → 强化学习的可观测配置与指标参考
- 回顾端到端流程 → 强化学习训练概述