本文假设你完全没接触过大模型训练。读完并照做,你能用自己的业务数据训出一个专属的 Laya 模型并验证效果。全部步骤来自 Laya 官方文档(
docs/finetune.md)与官方源码 (laya/train.py),每一步都有可复制的命令和验证方法。 本文只讲微调与使用微调产物;如何在 Java/Spring Boot 中集成 laya-java (对象池、REST 接口等)见姊妹篇《别再拿大模型做工单分类了》,此处不重复。 官方项目:github.com/NandhaKishorM/laya(Apache-2.0)。
Laya 是一个"做判断题"的小模型。 它不聊天、不写文章,你给它一段文本和几个问题, 它一次性回答三类判断:
它出厂就带通用判断能力(叫"零样本"),但在你的具体业务上往往不够准。 微调(fine-tune)就是拿你自己标注过的几百到几千条数据,继续训练这个模型, 让它学会你业务里的判断标准。 类比:出厂模型是刚毕业的大学生,微调是入职培训。
三个提前说清的边界,避免走弯路:
laya-train,一条命令完成:读数据 → 训练 →
校准置信度 → 保存模型。不需要你写训练代码。官方给的效果参照(typed-decisions 基准,2000 道判断题):出厂模型准确率 0.362 (接近瞎猜的 0.318),微调后 0.766。微调是这个模型价值的大头。
| 你的设备 | 能否微调 | 说明 |
|---|---|---|
| NVIDIA GPU(16GB 显存,如 T4/4080) | ✅ 推荐 | 官方 notebook 用免费 Kaggle 2×T4 |
| Apple Silicon Mac(16GB 内存起) | ✅ 可以 | 官方提供 MPS 脚本,慢一些 |
| 只有 CPU | ⚠️ 勉强 | 加 --freeze-encoder 只训决策头,官方明说"增益比全量微调小得多" |
bash# 用途:建独立 Python 环境(需 Python 3.10+,python3 --version 先确认)
python3 -m venv .venv
# 用途:安装 laya(含训练所需的全部依赖 torch/transformers/safetensors)
# 国内加速可加 -i https://mirrors.aliyun.com/pypi/simple/
.venv/bin/python -m pip install -U laya
# 验证:laya-train 命令存在,且能看到全部参数说明
.venv/bin/laya-train --help
bash# 用途:确认训练设备被识别(Mac 应输出 MPS: True;NVIDIA 机器看 CUDA: True)
.venv/bin/python -c "import torch; print('MPS:', torch.backends.mps.is_available()); print('CUDA:', torch.cuda.is_available())"
Windows PowerShell:
py -3 -m venv .venv建环境,之后所有.venv/bin/python换成.\.venv\Scripts\python.exe,.venv/bin/laya-train换成.\.venv\Scripts\laya-train.exe。Windows 没有 MPS,设备自动选 CUDA 或 CPU; 需要 CUDA 时先按 pytorch.org 的安装选择器装对应驱动的 torch。
模型不用手动下载:laya-train 的 --base 参数会自动从 Hugging Face 拉取。
国内网络先设镜像:
bash# 用途:国内直连 HF 失败时走镜像(每个新终端都要执行)
export HF_ENDPOINT=https://hf-mirror.com
Windows PowerShell:
$env:HF_ENDPOINT = "https://hf-mirror.com",同样每个新终端都要执行。 hf-mirror.com 是社区镜像(非 HF 官方),成文时已验证 laya 两个底座仓库 (convaiinnovations/laya与convaiinnovations/laya-multilingual)都能拉到。 镜像也不通时的兜底:手动下载 checkpoint 目录,--base直接收本地目录路径。
一列文本、一列正确标签,就是普通表格。例如工单分部门(tickets.csv):
csvbody,department "三月账单扣了两次,请退回多收的款项",billing "应用一打开设置就闪退",technical "请问还在招后端工程师吗",hr "发票抬头开错了能重开吗",billing "API 一直返回 500,生产环境受影响",technical
规则(来自官方文档):
要多少条? 官方没有给硬性下限,但有两个实测参照帮你定预期:
新手建议:先攒 500~2000 条标注数据跑通流程,再按第六节的方法判断要不要加数据。
一行一个案例,一个案例可以同时问多道题,三种题型随意组合:
json{
"state": "三月账单扣了两次,请今天退回多收的款项,否则我们就退订。",
"questions": {
"department": {
"type": "choice",
"instructions": "这张工单应分配给哪个部门?",
"criteria": {
"billing": "付款、账单、退款",
"technical": "产品故障",
"hr": "招聘人事"
}
},
"urgent": { "type": "noul", "instructions": "用户是否要求今天处理?" },
"severity": {
"type": "score",
"instructions": "评估紧急程度。",
"criteria": ["低:可等待", "中:近期处理", "高:有明确期限"]
}
},
"expected": { "department": "billing", "urgent": true, "severity": 2 }
}
expected 是每题的正确答案:choice 填标签、noul 填 true/false、
score 填等级序号(0 起;填 1.5 这种小数会把权重平分到等级 1 和 2);expected 换成 gold 可以喂"概率分布"当目标(蒸馏教师模型时用),
格式 {"department": {"probabilities": {"billing": 0.9, "technical": 0.1}}};
两种写法可以混在同一文件里。新手用 expected 就够了。重要:questions 里的问法(instructions 和 criteria)要和你线上推理时用的一字不差。
训练教的是"这个问题怎么答",上线换了问法等于换了道题。
长训练开始前,先让官方工具检查数据能不能用:
bash# 用途:只做数据编译检查,不下载权重、不训练;打印可用条数、跳过原因、训练预算
.venv/bin/laya-train --data tickets.csv --text-column body --label-column department \
--base multilingual --dry-run
--base multilingual:中文数据必须选多语言底座(英文底座对中文会高置信度答错)。 纯英文数据可用--base english。
看输出里的两个东西:
① 跳过原因表(有跳过就要查明原因,不能无视):
| 原因 | 含义 |
|---|---|
empty_text / empty_label | 该行没文本 / 该题没答案 |
invalid_question / invalid_target | 问题定义或答案格式读不懂 |
options_collapsed | 选项太多,两个选项被挤成了相同 token(缩短选项描述或调大 --head-max-len) |
options_beyond_max_len | 选项总长超出窗口(调大 --max-len) |
② 优化器更新预算(决定训练量的真实数字,下一节展开):
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)
bash# 用途:完整微调 = 训练 + 自动留出校准集拟合置信度 + 保存模型
# 中文数据用 multilingual 底座;--out 是产出目录
.venv/bin/laya-train --data tickets.csv --text-column body --label-column department \
--base multilingual --out ./tickets-checkpoint
不需要指定设备:自动按 CUDA → MPS → CPU 选择。这条命令内部做了四件事:
耗时参照(官方口径):2×T4 上 6000 条决策约 4-6 分钟;3 万条 4 轮约 4-5 小时。 Mac MPS 会更慢,先用小数据试跑估时间。
| 参数 | 默认 | 什么时候动它 |
|---|---|---|
--base | english | 中文数据必须改 multilingual |
--epochs | 4 | 数据少于一两千条时加大(见 5.3) |
--micro-batch / --grad-accum | 8 / 8 | 显存/内存不够就把 micro-batch 降到 1~2,grad-accum 相应加大保持乘积≈64 |
--freeze-encoder | 关 | 只有 CPU 或内存很小时开;只训决策头,快但增益小 |
--loss | rlcd | 可试 soft-ce(官方实测两者相当,soft-ce 在部分基准还略好) |
--shuffle-options | 关 | 选项超过 10 个时建议开:每轮随机打乱选项顺序训练,治"位置偏置"(官方 20 选项实测:准确率 +0.55pt,顺序敏感答案减少约四分之一) |
--label-smoothing | 0.0 | 标注有噪声时可设 0.1,把一成权重分给其他选项 |
--encoder-lr / --head-lr | 2.5e-5 / 1e-4 | 学习率,新手别动 |
--eval-data | 无 | 强烈建议给:一份独立的测试文件,训练前后各测一次(第六节) |
--seed | 0 | 结果可疑时换种子重跑(见 6.2) |
Mac 16GB 内存的保守跑法(官方 MPS 脚本同款思路):
bash.venv/bin/laya-train --data tickets.csv --text-column body --label-column department \ --base multilingual --out ./tickets-checkpoint \ --micro-batch 1 --grad-accum 32 --epochs 8
模型每学一步叫一次"优化器更新"。官方公式:
更新次数 = epochs × ceil(ceil(训练条数 / micro_batch) / grad_accum)
直觉:6000 条数据默认参数 = 352 次更新,学得好;1100 条同样参数只有 72 次更新,
官方实测会塌缩。数据少了,就要用更多轮次把更新次数补回来:#963 实测加到最多
32 轮才学会(选中的轮次多在 17~31,配恒定学习率、按留出校准集选轮次)。但加轮次
是必要非充分——同一 issue 里阳性对照 8 轮就到 1.00,真实任务 32 轮也只从 0.24
提到 0.36;还学不会就按 6.2 诊断。--dry-run 打印的预算就是给你算这个的。
输出目录里有 checkpoint_latest/,每轮结束都会重写。训练崩溃/断电最多损失一轮,
但目前官方 CLI 没有断点续训参数——重跑就是从头训。长训练建议放 nohup/tmux 里,
下载类步骤(拉底座模型)失败重跑命令即可,HF 下载自带缓存不重复下载。
训练日志和产出配置(rl_agent_config.json 的 training.laya_train_calibration)里会写:
| 警告 | 含义 | 处置 |
|---|---|---|
not fitted: N calibration items, fewer than 10 | 校准数据不足 10 条,温度没拟合,置信度不可信 | 加数据;在此之前不要用置信度做自动分流 |
predictions collapsed to the class prior | 模型塌缩到瞎猜(输出几乎恒定) | 加 epochs / 加数据 / 换 seed 重跑 |
fitted on only N calibration items(N<50) | 温度拟合了但证据少 | 结果仅供参考,继续攒数据 |
这是官方文档里很实用的一招,区分"任务太难"还是"训练没配好":
label=billing; 三月账单…;另外官方实测(issue #963):同样配置 15 次重跑,9 次走出平台期 6 次没有—— 一次失败别下结论,换 seed 多跑两次。
bash# 用途:训练前后各答一遍 test.csv,报告里对比提升
.venv/bin/laya-train --data tickets.csv --text-column body --label-column department \
--base multilingual --out ./tickets-checkpoint --eval-data test.csv
注意:test.csv 必须和训练数据不重叠。官方工具按"文本 + 问题定义完全相同"检测
重叠并标记 overlapping_eval(此时指标不再算独立留出);改写/近义重复它查不出来,
要自己排除。不给 --eval-data 时报告的"训练后"数字来自校准集,参考价值有限。
模型说"我 90% 确定"不等于真有 90% 正确率——出厂模型普遍过度自信。 温度校准就是用一个数学变换把置信度修正到和真实正确率对齐,它不改变模型选哪个答案, 只改变"它报多确定"。
laya-train 自动做了这件事,但有两个官方点名的坑你要知道:
temperature_by_options(分桶温度)如果残留在
新配置里,会在推理时静默覆盖新校准值。官方脚本会自动删掉它;如果你手工拷贝配置,
记得检查这个字段。pythonimport json, laya
agent = laya.load("./tickets-checkpoint")
# 关键:用训练时保存的同一份问题定义(CSV 训练时自动生成在产出目录)
questions = json.load(open("./tickets-checkpoint/questions.json"))
print(agent.predict("上周的发票金额开错了", questions)["answers"])
微调产物就是标准 checkpoint,加载方式和官方模型完全一样,没有"微调专用 API"。
questions.json 是训练时问题的唯一权威副本——推理时的问法必须和它一字不差,
换了问法等于换了道题。
Spring Boot 集成方法见姊妹篇,这里只讲"换模型"这一步。Java SDK 吃 ONNX 格式, 把微调 checkpoint 导出一次:
bash# 用途:补导出依赖(导出后的 batch 1/2/3 校验需要 onnxruntime,裸 laya 不带)
.venv/bin/python -m pip install "laya[onnx]"
# 用途:获取官方导出脚本(在仓库 scripts/ 里,pip 包不带)
git clone --depth 1 https://github.com/NandhaKishorM/laya.git
# 用途:把微调 checkpoint 导出为 Java SDK 可读的 ONNX 图
cd laya
PYTHONPATH=. ../.venv/bin/python scripts/export_onnx.py \
--model ../tickets-checkpoint --output ../tickets-onnx/laya.onnx
# 验证:两个文件都在(权重在 .data 里,必须同目录)
ls ../tickets-onnx/laya.onnx ../tickets-onnx/laya.onnx.data
然后把服务配置里的两个路径指向新产物,重启即生效:
yamllaya:
checkpoint-dir: /path/to/tickets-checkpoint # 微调产出目录(含新校准温度)
graph-dir: /path/to/tickets-onnx # 刚导出的 ONNX 目录
温度、token 预算都从 rl_agent_config.json 自动读取,Java 代码零改动;
问题定义换成 questions.json 那份。回滚 = 把两个路径改回原模型目录,
上线前验证一次回滚路径。
| 现象 | 原因与处置 |
|---|---|
laya-train: command not found | 没用 venv 里的路径;用 .venv/bin/laya-train |
| 下载底座超时 | export HF_ENDPOINT=https://hf-mirror.com 后重跑(有缓存,不重复下载) |
must contain at least 2 distinct labels | CSV 标签列只有一个值,选择题至少要两个选项 |
dry-run 大量 options_collapsed | 选项描述太长挤爆了预算:缩短描述,或 --head-max-len 512 |
| 训练完准确率≈瞎猜 | 按 6.2 阳性对照诊断;小数据先加 epochs |
| 内存爆 / OOM | --micro-batch 1 --grad-accum 32;再不行 --freeze-encoder |
| 中文效果差且置信度虚高 | 底座用成了 english,换 --base multilingual 重训 |
| 上线后效果和测试不符 | 线上问法和训练问法不一致;对照 questions.json 逐字检查 |
官方微调文档:github.com/NandhaKishorM/laya/blob/main/docs/finetune.md · 另一个完整案例(16GB 单卡训浏览器 Agent 决策头):docs/finetune_browser_agent.md
本文作者:Weee
本文链接:
版权声明:本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!