多标签一次抓全:GLiNER2.5-Decide 的 multi_label 与 cls_threshold 实战调参记录
多标签一次抓全:GLiNER2.5-Decide 的 multi_label 与 cls_threshold 实战调参记录
GLiNER2.5-Decide 是一个 340M 参数的专用决策分类模型:调用时动态传入任意标签集,单次前向即可完成意图、路由、情感、优先级等多项决策打分,无需提示词模板,也不生成任何 token。社区里围绕它讨论最集中的两个参数,莫过于 multi_label 与 cls_threshold——前者决定一个决策头能不能同时返回多个标签,后者决定哪些标签能跨过"及格线"。这两个参数用错了,多标签任务会要么漏标签、要么误报泛滥;用对了,一次调用就能把一条评论里的"电池、键盘、屏幕"三个产品属性全部抓出来。本文不空谈概念,直接对照本仓库 README.md 与 SKILL.md 中的真实接口、训练数据格式与评估规范,梳理一套可落地的调参路径。
先看清接口:两个参数藏在一个 schema 里
classify_text 的第二个参数是一个 schema 字典:每个 key 是一个"决策头"(intent、urgency、route……),value 可以是简单的标签列表,也可以是带参数的配置对象。多标签头就是后者,最典型的写法来自 README.md 的 Product aspects 示例:
model.classify_text(
"Battery dies before lunch, but the keyboard and the screen are the best I have used on a laptop.",
{"aspects": {
"labels": ["battery", "keyboard", "screen", "camera", "price", "support"],
"multi_label": True,
"cls_threshold": 0.4,
}},
)
这段评论既抱怨电池又夸键盘和屏幕,期望输出是 {"aspects": ["battery", "keyboard", "screen"]}。README 对两种模式的定义非常直白:单标签任务返回一个字符串,多标签任务返回所有超过阈值的标签("Multi-label tasks return every label above the threshold")。也就是说,cls_threshold 并不是一个只在多标签模式下才生效的锦上添花参数——它是多标签头"该留下谁"的裁决标准。
值得特别注意的是,在 README.md 的微调数据格式对照表中,有一行关键说明:"multi_label": True 对应训练行里的 "multi_label": true,且每个正确的标签都要写进 true_label;而 cls_threshold 是推理期专用参数(inference-only),不参与训练。这意味着训练阶段模型学到的是"哪些标签应该共存",而阈值只在部署阶段决定"信到什么程度才放行",两者职责分离,调参时不要混为一谈。
什么时候该开 multi_label
判断一个决策头要不要开 multi_label,标准不是"标签多不多",而是标签之间是否重叠、一条输入是否可能同时命中多个类别。仓库里恰好给了两个正反例。
正面例子是 Product aspects 与 Several decisions at once 中的 topics 头:一条评论可以同时夸键盘、贬电池,一条酒店留言可以同时涉及 hvac(空调)和 billing(账单),这些属性天然共存,硬要二选一就会丢失信息。README 中酒店场景的输出 {"topics": ["hvac", "billing"]} 就是多标签头的标准形态。
反面例子是意图路由、路由队列这类互斥任务:一条工单只能进一个队列,一个意图只能触发一个工作流,此时强行开 multi_label 反而有害——模型会在 refund_request 和 cancel_subscription 之间同时给出两个高置信标签,下游路由就得自己再写一套去重仲裁逻辑。SKILL.md 的措辞可以看作官方判据:"Multilabel classification: return every applicable category, including no labels when appropriate. Do not force a single prediction for overlapping topics or intents."——当话题或意图存在重叠时才不要强制单预测。
开错方向还有一个隐藏成本在训练侧:单标签头和多标签头的训练行格式不同。多标签行要求 true_label 里写全所有正确标签(如 ["battery", "keyboard", "screen"]),如果训练时漏标,模型就学不会共存关系,推理时再调阈值也补不回来。反过来,单标签头如果训练行里混进了多标签真值,模型会被训练数据"教坏"。所以开 multi_label 之前,先确认你的标注规范与数据格式是否对齐。
cls_threshold 如何控制精度与召回
多标签头的打分逻辑是逐标签独立打分,凡是分数超过 cls_threshold 的标签全部返回。这本质上是在精度与召回之间滑动:阈值调高,只有信心十足的标签才被放行,误报减少、精度上升,但容易漏掉语气委婉的冷门标签;阈值调低,更多标签被捞上来、召回上升,但"无关标签也冒出来"的噪声随之增加。README 的两个多标签示例都取了 0.4 作为默认参考值,但 0.4 不是真理——它取决于你的业务对误报和漏报的容忍度,也取决于标签本身的先验分布。
这里有两条来自 SKILL.md 的重要约束,实践中常被忽视。其一,"Do not assume confidence scores form a normalized probability distribution or convert scores between sigmoid and softmax without a supported contract"——多标签头打出来的分数不是归一化概率,你看到的 0.37 和 0.41 之间没有"概率差"的含义,也不应该拿它去和其他任务头的分数做横向比较。其二,"Tune thresholds on development data"——阈值必须基于开发集实测调,而不是凭直觉拍一个全局值。具体做法是:在开发集上对每个标签画出"阈值→精度/召回"曲线,再根据业务权重选择折中点的阈值;对不同的决策头甚至可以分别配置不同的 cls_threshold,不必全局统一。
评估侧同样要分层。SKILL.md 明确要求多标签任务报告 micro/macro-F1 与 exact-set accuracy(整组标签精确匹配的比例),同时给出 per-category 结果和在无匹配样本上的假阳性统计。只看整体 F1 会掩盖两类典型病:标签 A 被狂报、标签 B 永远打不中;或者无标签样本全被误判成某个高频标签。这两类病正好引出下一节。
冷门标签打不中的调参补救
"冷门标签打不中"是多标签实战中最常见的问题:稀有标签在训练数据里出现次数少,模型对它的决策边界模糊,推理时分数普遍偏低,一过 0.4 的阈值就被全部滤掉。这时候先别急着把阈值一路往下调——全局降阈值会把高频标签的误报一起放大,得不偿失。正确的处理顺序是数据层、标签层、阈值层三管齐下。
数据层看 SKILL.md 的训数据准备规范:要"include realistic negatives, rare labels, confusing near-matches, negation, misspellings and diverse writing styles"。冷门标签打不中,往往不是因为阈值太高,而是训练集里只有它出现时的正例、没有它不出现的负例,模型没学会"哪些话说得像这个标签但其实是另一个"。补齐混淆对(near-match)和否定表达,效果通常比调阈值更根本。
标签层看 README.md 的 Labels with a description 示例——当标签名本身不够表达语义边界时,可以给标签挂自然语言描述,描述会作为决策输入的一部分参与打分:
model.classify_text(
"Please reset the card PIN. The new one never arrived and the old one is locked after three tries.",
{"intent": {
"labels": {
"card_pin_change": "The customer wants a new PIN or the current PIN replaced",
"card_lost": "The physical card is missing",
"balance_inquiry": "The customer wants the current balance",
},
}},
)
"card_pin_change" 和 "card_lost" 这种高频混淆对,靠描述把语义边界点破,冷门标签的命中率会明显改善。对应地,微调训练行里要使用 "label_descriptions": {name: description} 字段保持训练与推理一致——README.md 的 Fine-tuning 表格明确要求"the same task, labels, prompt and multi_label you pass to classify_text"。
阈值层则要做"分标签微调":先用开发集的 per-category 结果找出哪些标签召回率低于目标线,对这些标签单独放宽阈值(或对整头降阈值但配合更强的 no-match 负例训练),而不是对所有标签一刀切。README 还提醒了一个容易踩的坑:序数评分(如 ["0", …, "10"])在训练时按普通单标签处理,"6" 和 "7" 之间的距离损失并不知道,这类头除了 accuracy 还要用 mean absolute error 评估——这个逻辑同样适用于多标签头的分数解释:分数低不代表"接近阈值",它只代表模型对该标签信心不足。
一份可复用的调参检查清单
把上面几节收拢,可以得到一条可照抄的多标签调参流水线,每步都能在本仓库找到对应依据:
- 判型:先问"标签互斥还是重叠"。意图/路由/队列这类互斥任务保持单标签;属性、主题、方面这类可能共存的才开
multi_label(README.md 正反例)。 - 校准数据:多标签训练行
true_label必须写全所有正确标签,multi_label字段与推理侧一致;cls_threshold不进训练行,别把它写进训练数据(README.md 对照表)。 - 跑基线:用 0.4 的
cls_threshold在开发集上先跑一遍,记录整体 micro/macro-F1、exact-set accuracy 与 per-category 结果(SKILL.md 评估规范)。 - 读诊断:找出三类典型病——整体 F1 低(可能标签本身难分)、单标签召回低(冷门标签)、no-match 样本假阳高(阈值过低或负例不足)。
- 对症下药:冷门标签优先补混淆负例与否定样本,其次给标签挂描述(
label_descriptions),最后才在开发集上逐标签扫阈值;不要假设分数是归一化概率,不要在 sigmoid/softmax 之间擅自转换(SKILL.md)。 - 分头调参:多决策头场景(如 README 的酒店案例:intent 单标签 + topics 多标签)允许每个头使用不同的
multi_label与cls_threshold配置,一次调用全部生效。 - 上测试集前冻结:确认训练、开发、测试集在泄漏防护下分离(SKILL.md 要求防近重复泄漏),用同一套输入、标签、阈值对选中检查点做最终评估,再进生产。
这套流程里最关键的心法是:multi_label 决定模型"能不能"同时给出多个答案,cls_threshold 决定"信到什么程度才给",而两者都不是在推理时孤军奋战的——它们的上限由训练数据与标签定义决定。先把数据与标签描述对齐,再用开发集数据驱动地调阈值,冷门标签打不中的问题大多能在这三步内收敛,而不是靠盲目压低全局阈值去"赌"召回。