文档导航

在你自己的决策上微调 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

发布那一格是循环的最后一公里,它刻意做得无聊:

  1. 在 Kaggle 里放一个可写的 HF_TOKEN(Add-ons → Secrets)。缺了它那一格会抛出错误,并给出 确切的指示。
  2. 设置目标仓库 —— 交付的那一格默认用项目自己命名空间里的一个名字,所以运行前先改掉它。
  3. 运行它。它写出一张模型卡,卡上的数字来自这次运行的对比表,然后上传 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 就是那种如果在一个照搬的配置 里存活下来、就会静默让校准失效的东西。