在你自己的决策上微调 Laya
在 typed-decisions 基准上,基础 checkpoint 零样本的得分接近随机 —— 0.36 和 0.35,对 0.318 的 随机基线而言 —— 而微调后的 checkpoint 在同一批 2,000 个决策上达到 0.766,高于 TypeSafe Jev 已发布的 0.727,也高于 0.735 的教师自一致上限。微调承载了大部分价值,公开的 微调 notebook 在 Kaggle 免费的 2xT4 GPU 上跑完整个循环:构建数据集、用 RLCD 训练、拟合校准温度、评估,并把 结果推到 Hub。这一页讲解那个 notebook,并指出当数据换成你自己的之后,哪些部分仍然关键。
同样的循环也在包里。laya-train 用一条命令在一台设备上、从一份带标签决策的 CSV 或 JSONL 跑完
它,而 laya.train.finetune 从 Python 做同样的事;两者都在下面先讲,在 notebook 之前。
另一个完整示例 —— 在单张 16 GB GPU、不花钱调 API 的情况下训练一个浏览器智能体决策头 —— 在 把 Laya 微调成浏览器智能体决策头。
用 laya-train 微调
laya-train(也可以写作 laya train)构建训练条目、微调、在训练前就留出的切片上拟合校准
温度,并保存一个 laya.load 能打开的 checkpoint。它在一台设备上运行:CUDA、MPS 或 CPU。
从 CSV
每个决策一行,文本在一列、正确的标签在另一列:
laya-train --data tickets.csv --text-column body --label-column department \
--base english --out ./tickets-checkpoint
标签那一列变成一个覆盖它各不同取值的 choice 问题,顺序按它们首次出现的先后,id 由
--question-id 给出(默认 label),指令由 --instructions 给出。这个问题会作为
questions.json 保存在 checkpoint 旁边;在推理时向微调后的模型问同一个问题:
import json, laya
agent = laya.load("./tickets-checkpoint")
questions = json.load(open("./tickets-checkpoint/questions.json"))
print(agent.predict("We were billed twice for March.", questions)["answers"])
从 Excel 保存、带字节序标记(byte-order mark)的文件会照常读取。文本或标签为空的行会被跳过并 计数。
从 JSONL
每一行是一个 case,一个 case 可以问任意类型的多个问题。有两种标签形状会被读取,一个文件里可以 混用:
{"state": "We were billed twice for March.",
"questions": {"department": {"type": "choice", "instructions": "Which team should handle this?",
"criteria": {"billing": "invoices, refunds", "technical": "bugs, outages"}},
"urgent": {"type": "noul", "instructions": "Does this need an answer today?"}},
"expected": {"department": "billing", "urgent": true}}
expected为每个问题保存一个答案,正是laya-evals读取的格式,所以同一个文件既能训练 checkpoint 又能评估它:choice 是一个标签,noul 是true/false,score 是一个档位(像1.5这样的分数档位会把它的权重分摊到档位 1 和 2 之间)。--label-smoothing 0.1把每个 答案权重的十分之一挪到其他选项上。gold保存教师对每个问题的概率,也就是 notebook 的 schema:{"department": {"probabilities": {"billing": 0.9, "technical": 0.1}}}。noul 的概率用"false"/"true"作键,score 的概率用档位索引的字符串作键。
在长跑之前检查数据
laya-train --data tickets.csv --text-column body --label-column department --dry-run
--dry-run 用 --base 的 tokenizer 和配置构建训练条目,不加载它的权重、也不训练,并打印读入
了多少行、它们产出了多少条目、跳过了多少问题以及原因,还有配置好的默认值将花掉的
optimizer 更新预算(见按 optimizer 更新次数估算一次运行):
| 原因 | 问题被跳过的原因是 |
|---|---|
empty_text、empty_label |
那一行没有文本,或那个问题没有答案 |
invalid_question、invalid_target |
那个问题或它的答案读不出来 |
options_collapsed |
head 预算让两个选项剩下同样的 token(#538) |
options_beyond_max_len |
那个问题的选项放不进 max_len |
按 optimizer 更新次数估算一次运行
--epochs、--micro-batch 和 --grad-accum 决定一次运行获得多少训练量,但真正要紧的数字是它
执行的 optimizer 更新次数。一个 epoch 被拆成 ceil(items / micro_batch) 个微批;每
grad_accum 个微批跑一次更新,外加每个 epoch 末尾那个不满的窗口一次,后者即使装得更少也会走
一步:
updates = epochs * ceil(ceil(train_items / micro_batch) / grad_accum)
--dry-run 和一次运行的开始都会打印这个预算,来自校准之后的训练计数,并带上有效批大小:
optimizer budget: 1100 train item(s), effective batch up to 64 (micro_batch 8 x grad_accum 8), 72 optimizer updates over 4 epoch(s)
默认值(4 个 epoch、有效批 64)是 notebook 的。在 typed-decisions 的 6,000 个决策上,默认的 400 条目校准切片留下 5,600 个训练条目,所以一次默认运行花 352 次更新 —— 只有在不切出任何 切片时才是 376。这个数字是拿不同规模的运行相互比较的参照,不是一条截断线:同样设置下 1,100 个 训练条目给出 72 次更新(当 1,100 是切分之前的计数、10% 的切片留出 110 个时是 64),而 #963 测到一个 head 在那里坍缩,而 8 个 epoch 在任务本身上仍然失败。因此一个小数据集需要更多 epoch 才能达到相近的更新次数。
一次运行写了什么
--out 得到 laya.load 读取的目录结构(model.safetensors、encoder/、tokenizer/、
rl_agent_config.json),外加 questions.json 和一个在每个 epoch 之后被重写的
checkpoint_latest/,所以一次崩溃至多损失一个 epoch。
配置记录这次运行用到的 max_len 和 head_max_len,训练设置在 training.laya_train 下,校准
报告在 training.laya_train_calibration 下:按问题类型,温度依据多少个校准条目、它们的准确率
和平均置信度,以及有什么可怀疑的。同样的 issues 会在运行期间以警告打印出来:
laya.train: choice calibration: not fitted: 2 calibration items, fewer than 10, so the temperature stays 1.0
像这样的警告意味着这个 checkpoint 的置信度没有校准过;在有一次数据更多的运行把它们拟合好之前,
别拿它去对 min_confidence 做门控。
诊断一次停在随机水平的运行
如果一次微调从未升到类别先验之上,单凭准确率说不清是任务难还是预算错了。一个标签编码的正对照
能把两者分开:给每个训练和测试文本前面加一个把答案拼出来的标记(例如 label=<department>; ),
在这份副本上微调。模型可以从标记上读出答案,所以同样的预算有了一个可以轻松学会的信号去拟合。
- 正对照学不会 → 怀疑预算、优化或运行设置,而不是任务。
- 正对照达到 1.00 而真实任务停在先验上 → 证据指向任务或表示的难度,而不是更新次数太少。 #963 在 8 个 epoch 下把两者都测了: 正对照达到 1.00,而真实任务仍然坍缩。
一个通过的正对照只表明这次运行能拟合一个刻意做简单的信号;它不证明真实任务可学,也不证明这个 checkpoint 能泛化。
在 ln K 平台附近起飞也依赖种子,所以单次运行不能作为任何一方的证据。
#963 在相同的数据和配置下,看到 15 次运行里
有 9 次离开平台、6 次在 32 个 epoch 内从未离开。在断定一个任务不可学、或一个预算没问题之前,
用不同的种子重复这次运行,并在对 min_confidence 做门控之前先读一读运行打印的坍缩警告。
选项
| flag | 默认值 | 它改变什么 |
|---|---|---|
--base |
convaiinnovations/laya |
从哪个 checkpoint 起步:一个目录、一个内置名(english、multilingual、typed-decisions)或一个 Hub repo id |
--loss |
rlcd |
rlcd 是 notebook 的目标函数;soft-ce 只在软交叉熵上训练(#741) |
--shuffle-options |
关 | 每个 epoch 用随机的选项顺序重新编码 choice 问题,并把答案挪到对应位置 |
--label-smoothing |
0.0 |
从单个答案上挪走的权重 |
--freeze-encoder |
关 | 只训练决策头;能装进一张小 GPU 或 CPU,但收益远小于完整微调 |
--epochs、--micro-batch、--grad-accum |
4, 8, 8 | notebook 的 4 个 epoch 和 64 的有效批 |
--encoder-lr、--head-lr |
2.5e-5, 1e-4 | 学习率 |
--max-len、--head-max-len |
基础 checkpoint 的 | token 预算;notebook 用 1024 和 256 |
--device、--seed |
auto, 0 |
CUDA 上混合精度默认开启。在一张 fp16 比 fp32 还慢的 GPU 上(比如 GTX 16xx 那些卡),从 Python
在 TrainConfig 里设 amp=False。
这些选项值多少
每次运行在一张 T4 上对 convaiinnovations/laya 做完整微调,用 notebook 的设置,来自
#887。
在 typed-decisions 上(6,000 个训练决策,全部 2,000 个测试决策,一个种子):
| 运行 | 准确率 | ECE | 选项反转后会改变的 choice 答案 |
|---|---|---|---|
| 基础 checkpoint | 0.362 | 0.174 | 0.357 |
--loss rlcd(默认) |
0.7715 | 0.150 | 0.065 |
--loss soft-ce |
0.790 | 0.157 | 0.078 |
--loss soft-ce --shuffle-options |
0.7875 | 0.159 | 0.062 |
在 MASSIVE 的英文 intent 上,每个问题 20 个选项(11,514 个训练行,全部 2,974 个测试 case,
每个还用 3 种打乱的顺序各答一遍;--loss soft-ce,每行两个种子):
| 运行 | 准确率 | 选项重排后会改变的答案 |
|---|---|---|
| 基础 checkpoint | 0.730 | 0.187 |
不带 --shuffle-options |
0.936 | 0.026 |
带 --shuffle-options |
0.941 | 0.019 |
在 4 个选项时,单是微调就已经让答案在重排下稳定,打乱带不来任何可测量的变化。在 20 个选项时, 它把准确率提高 0.55 个点,并把会改变的答案砍掉约四分之一,两者在两个种子上都显著,代价是训练 时间多约 14%。当问题有很多选项时用它。
从 Python 微调
laya-train 调用的就是 laya.train.finetune:
import laya
from laya.train import TrainConfig, finetune
report = finetune("train.jsonl", "english", "./my-checkpoint",
TrainConfig(loss="soft-ce", shuffle_options=("choice",)))
print(report["train_items"], report["skipped"], report["calibration"])
agent = laya.load("./my-checkpoint")
TrainConfig() 拥有上表里的默认值,外加命令没有暴露的设置:amp 和
gradient_checkpointing(CUDA 上默认开启)、校准切片(calib_max=400 个条目或
calib_frac=0.1,取较小的那个)以及 option_layout。返回的报告有 train_items、
calibration_items、skipped、epoch_loss、拟合出的 temperature 和
temperature_by_options,以及 calibration 报告。对于你自己的数据管线,train_model 和
calibration_records 是 finetune 由之构成的两半;API 参考把它们都列了
出来。
notebook 按顺序做了什么
| # | 步骤 | 发生的事 |
|---|---|---|
| 1 | 环境 | 断言两张 T4 GPU 都可见且已分配 |
| 2 | 安装 | laya、transformers、datasets 以及训练依赖 |
| 3 | 预处理 | 1,200 个训练用例(6,000 个类型化决策)变成带软目标的 tokenized 条目,写成磁盘文件供两个 DDP rank 使用 |
| 4 | 训练 | 在 torchrun --nproc_per_node=2 下跑 train_ddp.py,四个 epoch |
| 5 | 校准 | 每种类型一个温度,在训练前就留出的切片上拟合(在训练脚本内部,最后一个 epoch 之后) |
| 6 | 评估 | 微调后的 checkpoint 回答官方 test 划分 —— 400 个用例、2,000 个决策 —— 并给出每用例延迟 |
| 7 | 指标 | 准确率、软准确率、Brier、ECE、score MAE、档位内一位、KL/TV 和延迟分位数;一张与 Jev 和教师上限正面比较的表 |
| 8 | 发布 | (可选)用这次运行自己的数字生成一张模型卡,把文件夹上传到 Hub |
| 9 | 报告 | benchmark_report.json,含指标表和各工作流的准确率 |
Kaggle 设置:Accelerator 选 GPU T4 x2,Internet 设 On。输出落在
/kaggle/working/laya_finetuned_typed_decisions。
训练配方
RLCD 在基准的金标分布上训练,而不是在硬标签上:每个条目都带上教师给每个选项分配的概率, 损失的两半都读这个目标 ——
- 一个策略梯度项,作用在采样得到的带噪 logit 投影上(GRPO 风格:每个条目四个样本,探索 噪声从 0.4 退火到 0.1),由适当的评分规则给奖励(球面 0.75,排序概率 1.0);
- 一个全权重的软交叉熵项,对着同一个分布。
notebook 为 16 GB 显卡设置的旋钮:
| epochs | 4 |
| 有效批大小 | 64 个序列(每微批 8 个,2 张 GPU,4 步累积) |
| 学习率 | encoder 2.5e-5,head 1e-4 —— AdamW,余弦调度 |
| 内存 | fp16 autocast,encoder 和 head 上开梯度 checkpointing,梯度范数裁剪 1.0 |
| 序列预算 | max_len 1024,head_max_len 256,max_tokens_per_batch 4096 |
2xT4 上的运行时间,演示是分钟级,真实数据是小时级:演示的 6,000 个决策大约 4–6 分钟,而对约 30k 个问题跑四个 epoch 大约 4–5 小时。
要把它指向你的数据,替换那两个 load_dataset 调用,并保持行 schema:每个用例带 state、
questions 和 gold(教师对每个问题给出的概率),预处理器把它们变成条目。问题类型是
choice、score 和 noul;任何你能用它们对某个状态表达出来的东西都可以。
校准是这次运行的一部分
这是照搬循环时最容易被丢掉的一步,而一旦有人用置信度做门控,它就是关键。
notebook 在把训练数据分片到各个 rank 之前,先切出一份校准切片(最多 400 个条目,或 10%, 固定种子,每个 rank 上完全一样)。在运行已经训练过的条目上拟合温度,测的是拟合本身而不是校准 —— 模型在那些条目上几乎必然正确,优化器没有什么需要软化,于是返回一个退化的 scale。
最后一个 epoch 之后,rank 0 用 LBFGS 在 log 温度上拟合每种问题类型一个温度(choice、
score、noul),钳制在 [0.1, 10](切片不足十个条目时为 1.0,拟合抛异常时为 1.2)。
这些值作为 temperature 写进 rl_agent_config.json,notebook 在同一次写入里移除任何继承来的
temperature_by_options:那些旧的分桶值在推理时优先,会静默盖掉新的拟合。
温度缩放不改变 argmax —— 也不改变准确率;变的是置信度。checkpoint 按交付状态是过度自信的, 所以依赖任何阈值之前先拟合,并在留出数据上评估结果,再声称有改进。配置持久化的回归测试不需要 下载或训练就能跑:
python tests/test_calibration_persistence.py
信任它之前先评估
评估是对官方测试划分的一次完整遍历:400 个用例、2,000 个决策,横跨 Agent Trace
Observability、Customer Service、Invoice Processing 和 Security Incidents。它计算准确率、软
准确率、Brier、ECE(通过 laya.common.ece_score)、score MAE、档位内一位和延迟分位数,然后
构建一张正面比较表,其中的参考行是固定的:
| model | kind | accuracy | ECE |
|---|---|---|---|
| TypeSafe Jev 1.13.0 | general | 0.727 | 0.144 |
| ModernBERT-base (149M) | specialist | 0.646 | 0.179 |
| Teacher Self-Agreement | ceiling | 0.735 | — |
| Laya (published checkpoint) | fine-tuned | 0.766 | — |
你自己运行里的 Laya 行也以同样方式计算 —— notebook 用这次运行自己的数字重建那张表。两个值得
照搬的习惯:把你关心的切片(一种语言、一个工作流)留在留出数据里,并把校准和准确率一起报告,
因为训练信号是一个分布,而不只是一个标签。等你有了数字,仓库的
Discussions 是分享它们的地方;基准和已知
限制在仓库根目录的 BENCHMARKS.md 里。
推到 Hub
发布那一格是循环的最后一公里,它刻意做得无聊:
- 在 Kaggle 里放一个可写的
HF_TOKEN(Add-ons → Secrets)。缺了它那一格会抛出错误,并给出 确切的指示。 - 设置目标仓库 —— 交付的那一格默认用项目自己命名空间里的一个名字,所以运行前先改掉它。
- 运行它。它写出一张模型卡,卡上的数字来自这次运行的对比表,然后上传
model.safetensors、encoder/、tokenizer/、rl_agent_config.json、那张卡和基准报告。
结果加载起来和任何其他 checkpoint 一样 —— 没有微调专用的 API:
import laya
agent = laya.load("your-org/your-checkpoint") # the repo you just pushed
result = agent.predict(state, questions)
一个滚动更新的 checkpoint_latest/ 在每个 epoch 后会被覆盖,所以 Kaggle 超时或 OOM 的代价是
一个 epoch,而不是整次运行。
要当心什么
- 循环的好坏取决于目标。 RLCD 在你的问题上模仿教师的分布;训练前(或训练的同时)收集教师 置信度,并把它们的质量当作上限。
- 校准切片小是故意的。 最多 400 个条目或 10% —— 够拟合三个按类型的标量,不够用来验证。 自己留出一份评估数据。
- 你的标签必须能放进三种原语。 如果你的决策不是 choice、不是量表、也不是是非概率,先把 它塑造成其中一种。两个尖锐的边缘已经有记录:选项多会削弱置信度的选择 (#394),强制选择的否定可能跟着问题走 而不是跟着状态走(#377)。
- 要交付配置,不只是权重。 被移除的
temperature_by_options就是那种如果在一个照搬的配置 里存活下来、就会静默让校准失效的东西。