编辑
2026-11-19
实用工具
0

目录

零基础微调 Laya:一份 CSV 加一条命令,训出你自己的决策模型
一、5 分钟背景:Laya 是什么,微调是什么
二、准备环境
2.1 硬件要求(先对号入座)
2.2 安装(macOS / Linux)
三、准备数据:最简单只要一份 CSV
3.1 CSV 格式(推荐新手从这里开始)
3.2 JSONL 格式(需要多问题/多题型时用)
四、训练前体检:--dry-run(不加载模型,几秒钟)
五、开始训练:一条命令
5.1 标准跑法
5.2 关键参数速查(都有官方默认值,不懂就先别动)
5.3 数据少为什么要加 epochs:看"更新次数"不是"轮数"
5.4 中断了怎么办
六、训练完先看体检报告,再谈效果
6.1 三种官方警告,见到必须处理
6.2 准确率上不去?官方的"阳性对照"诊断法
6.3 用独立测试集验证
七、为什么"校准"是训练的一部分(小白必读)
八、使用微调后的模型
8.1 Python 直接用(三行)
8.2 已有 laya-java 服务:导出 ONNX + 改两个路径
九、常见问题

零基础微调 Laya:一份 CSV 加一条命令,训出你自己的决策模型

本文假设你完全没接触过大模型训练。读完并照做,你能用自己的业务数据训出一个专属的 Laya 模型并验证效果。全部步骤来自 Laya 官方文档(docs/finetune.md)与官方源码 (laya/train.py),每一步都有可复制的命令和验证方法。 本文只讲微调与使用微调产物;如何在 Java/Spring Boot 中集成 laya-java (对象池、REST 接口等)见姊妹篇《别再拿大模型做工单分类了》,此处不重复。 官方项目:github.com/NandhaKishorM/laya(Apache-2.0)。

一、5 分钟背景:Laya 是什么,微调是什么

Laya 是一个"做判断题"的小模型。 它不聊天、不写文章,你给它一段文本和几个问题, 它一次性回答三类判断:

  • choice:多选一。"这条工单归哪个部门?" → billing(附每个选项的概率)
  • score:打等级分。"有多紧急?" → 在 [不急, 尽快, 十万火急] 里给期望分
  • noul:判真假。"客户是否威胁退订?" → 0.87(命题成立的概率)

它出厂就带通用判断能力(叫"零样本"),但在你的具体业务上往往不够准。 微调(fine-tune)就是拿你自己标注过的几百到几千条数据,继续训练这个模型, 让它学会你业务里的判断标准。 类比:出厂模型是刚毕业的大学生,微调是入职培训。

三个提前说清的边界,避免走弯路:

  1. 微调 ≠ 从零训练。你不需要训一个全新模型(官方也不提供从零预训练的工具), 只是在官方发布的模型基础上继续训练,一张普通 GPU 甚至你的 MacBook 就够。
  2. 官方有开箱即用的微调命令 laya-train,一条命令完成:读数据 → 训练 → 校准置信度 → 保存模型。不需要你写训练代码。
  3. 训练在 Python 侧做。微调产物是一个标准 checkpoint 目录,Python 直接加载即用; 已有 laya-java 服务的,导出 ONNX 后改两个配置路径就能换上新模型(第八节)。

官方给的效果参照(typed-decisions 基准,2000 道判断题):出厂模型准确率 0.362 (接近瞎猜的 0.318),微调后 0.766。微调是这个模型价值的大头。

二、准备环境

2.1 硬件要求(先对号入座)

你的设备能否微调说明
NVIDIA GPU(16GB 显存,如 T4/4080)✅ 推荐官方 notebook 用免费 Kaggle 2×T4
Apple Silicon Mac(16GB 内存起)✅ 可以官方提供 MPS 脚本,慢一些
只有 CPU⚠️ 勉强加 --freeze-encoder 只训决策头,官方明说"增益比全量微调小得多"

2.2 安装(macOS / Linux)

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 直接收本地目录路径。

三、准备数据:最简单只要一份 CSV

3.1 CSV 格式(推荐新手从这里开始)

一列文本、一列正确标签,就是普通表格。例如工单分部门(tickets.csv):

csv
body,department "三月账单扣了两次,请退回多收的款项",billing "应用一打开设置就闪退",technical "请问还在招后端工程师吗",hr "发票抬头开错了能重开吗",billing "API 一直返回 500,生产环境受影响",technical

规则(来自官方文档):

  • 标签列有哪些不同值,就自动构成一个 choice 问题的选项,按首次出现的顺序排列;
  • 至少要有 2 个不同标签,否则报错;
  • 空文本或空标签的行会被跳过并计数;
  • Excel 导出的带 BOM 的 UTF-8 文件可以直接读。

要多少条? 官方没有给硬性下限,但有两个实测参照帮你定预期:

  • 官方基准用 6000 条训练决策,效果 0.766;
  • 官方 issue #963 实测:1100 条数据用默认参数训练会"塌缩"(模型输出退化到 接近瞎猜,且表面上训练正常完成)。小数据需要更多轮次(见 5.3)。

新手建议:先攒 500~2000 条标注数据跑通流程,再按第六节的方法判断要不要加数据。

3.2 JSONL 格式(需要多问题/多题型时用)

一行一个案例,一个案例可以同时问多道题,三种题型随意组合:

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)要和你线上推理时用的一字不差。 训练教的是"这个问题怎么答",上线换了问法等于换了道题。

四、训练前体检:--dry-run(不加载模型,几秒钟)

长训练开始前,先让官方工具检查数据能不能用:

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)

五、开始训练:一条命令

5.1 标准跑法

bash
# 用途:完整微调 = 训练 + 自动留出校准集拟合置信度 + 保存模型 # 中文数据用 multilingual 底座;--out 是产出目录 .venv/bin/laya-train --data tickets.csv --text-column body --label-column department \ --base multilingual --out ./tickets-checkpoint

不需要指定设备:自动按 CUDA → MPS → CPU 选择。这条命令内部做了四件事:

  1. 把数据编译成训练样本;
  2. 训练前先切出一小块校准集(最多 400 条或 10%,取小者)——这块数据不参与训练, 专门用来校准置信度(第七节解释为什么);
  3. 用 RLCD 目标训练(默认 4 轮);
  4. 拟合温度、把校准值写进模型配置、保存完整 checkpoint。

耗时参照(官方口径):2×T4 上 6000 条决策约 4-6 分钟;3 万条 4 轮约 4-5 小时。 Mac MPS 会更慢,先用小数据试跑估时间。

5.2 关键参数速查(都有官方默认值,不懂就先别动)

参数默认什么时候动它
--baseenglish中文数据必须改 multilingual
--epochs4数据少于一两千条时加大(见 5.3)
--micro-batch / --grad-accum8 / 8显存/内存不够就把 micro-batch 降到 1~2,grad-accum 相应加大保持乘积≈64
--freeze-encoder关只有 CPU 或内存很小时开;只训决策头,快但增益小
--lossrlcd可试 soft-ce(官方实测两者相当,soft-ce 在部分基准还略好)
--shuffle-options关选项超过 10 个时建议开:每轮随机打乱选项顺序训练,治"位置偏置"(官方 20 选项实测:准确率 +0.55pt,顺序敏感答案减少约四分之一)
--label-smoothing0.0标注有噪声时可设 0.1,把一成权重分给其他选项
--encoder-lr / --head-lr2.5e-5 / 1e-4学习率,新手别动
--eval-data无强烈建议给:一份独立的测试文件,训练前后各测一次(第六节)
--seed0结果可疑时换种子重跑(见 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

5.3 数据少为什么要加 epochs:看"更新次数"不是"轮数"

模型每学一步叫一次"优化器更新"。官方公式:

更新次数 = 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 打印的预算就是给你算这个的。

5.4 中断了怎么办

输出目录里有 checkpoint_latest/,每轮结束都会重写。训练崩溃/断电最多损失一轮, 但目前官方 CLI 没有断点续训参数——重跑就是从头训。长训练建议放 nohup/tmux 里, 下载类步骤(拉底座模型)失败重跑命令即可,HF 下载自带缓存不重复下载。

六、训练完先看体检报告,再谈效果

6.1 三种官方警告,见到必须处理

训练日志和产出配置(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)温度拟合了但证据少结果仅供参考,继续攒数据

6.2 准确率上不去?官方的"阳性对照"诊断法

这是官方文档里很实用的一招,区分"任务太难"还是"训练没配好":

  1. 复制一份数据,给每条文本前面加个泄露答案的标签,如 label=billing; 三月账单…;
  2. 用同样参数训练这份"作弊数据";
  3. 作弊数据也学不会 → 问题在训练预算/配置(加更新次数、查数据格式); 作弊数据学到 1.00 而真实数据仍瞎猜 → 任务本身难或数据表达有问题。

另外官方实测(issue #963):同样配置 15 次重跑,9 次走出平台期 6 次没有—— 一次失败别下结论,换 seed 多跑两次。

6.3 用独立测试集验证

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 自动做了这件事,但有两个官方点名的坑你要知道:

  1. 校准必须用没训练过的数据。所以工具在训练前就切出校准集。如果你自己写训练循环, 千万别拿训练数据拟合温度——模型对训练过的题近乎全对,拟合会退化。
  2. 配置文件要跟着模型走。旧模型的 temperature_by_options(分桶温度)如果残留在 新配置里,会在推理时静默覆盖新校准值。官方脚本会自动删掉它;如果你手工拷贝配置, 记得检查这个字段。

八、使用微调后的模型

8.1 Python 直接用(三行)

python
import 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 是训练时问题的唯一权威副本——推理时的问法必须和它一字不差, 换了问法等于换了道题。

8.2 已有 laya-java 服务:导出 ONNX + 改两个路径

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

然后把服务配置里的两个路径指向新产物,重启即生效:

yaml
laya: 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 labelsCSV 标签列只有一个值,选择题至少要两个选项
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 许可协议。转载请注明出处!