从数据集到线上:用 Fastino Agent 托管微调 GLiNER2.5-Decide 的完整链路

原创2026-10-09 18:15:271,873 阅读
文章标签:人工智能大模型NLP

从数据集到线上:用 Fastino Agent 托管微调 GLiNER2.5-Decide 的完整链路

GLiNER2.5-Decide 是 GLiNER2.5 家族中的 340M 参数英文决策分类模型,在 fastino/fast-decisions 基准的 17 个领域、每个领域 300 条留出样本上,以 60.2% 的精确匹配平均准确率超过了同家族 1B 版(59.6%)、JevK5(57.6%),也压过了 SemIf(Qwen3.5-4B)的 56.4%。模型卡片(README.md)给出的定位很明确:它不是通用大模型,不推理、不解释、不生成开放答案,而是一个专为运营决策而生的专家分类器——意图识别、工单路由、情感分析、紧急度打分、多标签属性抽取,一次前向传播全部完成。

但基座模型只是起点。真实业务里的标签体系是私有的:你的工单队列、你的产品属性、你的 SLA 分级,都不会出现在预训练数据里。本文基于仓库源码与 Fastino Agent 托管 API,梳理从训练数据构造、数据集上传、试点训练、检查点评估到部署冒烟测试的完整链路,并把每一环最容易踩的坑单独拎出来。

一、先读懂模型的"接口设计":微调是在喂一个 span 匹配器

微调之前,必须先理解 GLiNER2.5-Decide 的架构约定,否则训练数据会造错。

模型配置(config.json)显示它的主干是 DeBERTa-v3-large 编码器:architectures 为 Gliner2ForSchemaExtraction,24 层、hidden size 1024、16 注意力头,搭配 span_head(span_mode 为 markerV0,最大 span 宽度 8),输出侧用 token_pooling: first 聚合。分词器配置(tokenizer_config.json)里藏着更关键的信息:词表额外注入了 [SEP_STRUCT]、[SEP_TEXT]、[P]、[C]、[E]、[R]、[L]、[EXAMPLE]、[OUTPUT]、[DESCRIPTION] 等结构标记。

这套结构标记是"schema-driven 接口"的直接证据:调用时把标签集合作为输入注入,模型把分类任务建模为 span 匹配问题,而不是靠一个固定的输出层做 softmax。这也是为什么 README.md 反复强调"Pass any label set at call time"——调用方传入 {"intent": [...]} 这样的字典,模型一次前向就把意图、紧急度、路由等多个决策头全部打分:

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",
        },
    }},
)
# 可能输出:{"intent": "card_pin_change"}

理解这一点后,训练数据的形态就清楚了:一行 JSONL 不是"文本 + 一个类标"的朴素二元组,而是"文本 + 多个决策结构"的完整快照。

二、训练数据准备:标签对齐与防泄漏拆分

2.1 一行训练数据的正确形态:标签对齐

README.md 的 Fine-tuning 章节给出了卡片侧调用与训练行字段的严格对照:

卡片侧(调用时) 训练行内(training row)
{"intent": [...]} {"task": "intent", "labels": [...], "true_label": ["refund_request"]}
"multi_label": True "multi_label": true,且 true_label 里列全所有正确标签;cls_threshold 仅推理期生效
"prompt": "Did …?" 原样保留 "prompt"
"labels": {name: description} "labels": [names] 外加 "label_descriptions": {name: description}
序数 ["0", …, "10"] 就是普通单标签行,如 "true_label": ["7"]
一次调用多个决策 classifications 数组里放多个对象

对应到真实训练行:

{"input": "My subscription renewed after the service was already down. Can I get that charge refunded?", "output": {"classifications": [{"task": "intent", "labels": ["order_status", "refund_request", "cancel_subscription", "other"], "true_label": ["refund_request"]}]}}
{"input": "Battery dies before lunch, but the keyboard and the screen are great.", "output": {"classifications": [{"task": "aspects", "labels": ["battery", "keyboard", "screen", "camera", "price"], "true_label": ["battery", "keyboard", "screen"], "multi_label": true}]}}
{"input": "The treaty was signed in Paris in 1992 and entered into force the following year.", "output": {"classifications": [{"task": "answer", "labels": ["yes", "no"], "prompt": "Did the treaty enter into force in 1992?", "true_label": ["no"]}]}}

标签对齐的第一要义是训练行里的 labels 候选集必须与线上调用时传入的候选集一致。因为标签是模型的输入而不是固定输出维度,如果训练时漏了某个标签、线上却传了,模型对它的打分就没有训练基础;反过来,训练时塞了线上永远不会出现的标签,只会稀释 span 匹配的判别力。

另一个高频错误是单标签/多标签语义漂移:单标签任务里 true_label 只能有一个值,多标签任务必须把正确集合全部列全。SKILL.md 中 Fastino Agent 的评估协议也专门强调这一点——分类任务"label the complete correct set, keep single-label and multilabel modes consistent"。

2.2 防泄漏拆分:左到右切分的陷阱

Fastino 的数据集处理有一个非常容易被忽略的实现细节。Fastino API(OpenAPI 文档)对 train_ratio 的说明是:"Left-to-right split with no shuffle; validation is the tail"——训练/验证切分是"从左到右、不洗牌、验证集取尾部"的固定规则。

这带来一个直接后果:上传数据的行顺序本身就是评估逻辑的一部分。如果生产环境同一份工单模板的重复样本、同源改写样本聚在一起,而它们恰好落在验证集尾部,验证指标会被同源近重复样本严重虚高;反之,验证集落在"难样本聚集区",指标又会异常偏低。SKILL.md 的防泄漏要求是:

  • 训练、开发、最终测试三份数据严格分离,测试集不参与任何调参;
  • 对相关文档、模板、实体进行分组,防止近重复泄漏(group related documents, templates and entities to prevent near-duplicate leakage);
  • 保留数据来源可溯源性,只上传有权训练的授权数据。

实操建议:上传前先按文本相似度或模板 ID 做分组随机化,把同源样本打散到不同分段,再按确定的顺序写入文件。因为切分不洗牌,文件的"物理顺序"就是切分依据,这一点必须当成一等公民对待。

2.3 数据多样性:别把"数量"当"质量"

Fastino Agent 上传通道支持 jsonl、csv、tsv、parquet、json 五种格式,并提供 column_mapping 把源列映射到标准列名(如 {"sentence": "text", "category": "label"}),分类任务将 dataset_type 设为 classification 即可。

但格式正确只是及格线。SKILL.md 明确列出了高质量数据的构成要素:真实负例、稀有标签、易混淆的近匹配、否定表达、拼写错误、多样化的写作风格。对于决策分类模型,负例尤其关键——像 spam/ham、handoff 的 yes/no 这类二分类决策,如果训练集里全是正例,模型会把阈值整体推向"永远输出 yes"。

平台侧还会对数据质量做硬校验。数据集接口返回的 warnings 字段会直接告诉你三类"训不好"的问题:too_few_rows(行数太少)、single_class(只有一个类别)、too_many_labels(标签数超限——一个训练任务最多接受 250 个唯一标签)。遇到 single_class 警告时,增加行数没有意义,先补齐类别分布才是正解。

三、上传数据集与试点训练:避坑要点

3.1 上传三步走

Fastino 的数据集上传是"预签名 URL"三步流程,绕过 API Gateway 的体积限制:

  1. POST /v1/datasets/upload/url:声明数据集名称、类型(classification)、格式和列映射,拿到 dataset_id、presigned_url 和 version_number;
  2. 用 HTTP PUT 把文件直接传到预签名 S3 URL;
  3. POST /v1/datasets/upload/process:提交 dataset_id 触发后台解析,之后轮询 GET /v1/datasets 直到状态从 initialized → uploading → converting → validating 走到 ready。

状态停留在 failed 时,接口会返回 processing_error 说明失败原因,不要盲目重传同一份文件。

3.2 试点训练的参数纪律

训练提交是 POST /v1/training-jobs,核心字段如下(默认值来自 Fastino API 文档):

  • base_model:fastino/GLiNER2.5-Decide;
  • datasets:上一步就绪的数据集引用(支持多数据集联合训练);
  • training_type:lora 或 full——具体哪种可用取决于模型目录里 training_types 的声明,先查 GET /v1/base-models 再提交,直接硬编码 full 可能被 400 拒绝;
  • validation_data_percentage:默认 0.2,留出比例,范围 0.0–0.9;
  • nr_epochs:默认 100,配合 early_stopping_patience(默认 3)和 early_stopping_min_delta 使用,通常远在 100 之前就停;
  • learning_rate:默认 2e-5;GLiNER 额外支持 encoder_learning_rate 与 task_learning_rate 分开设置;
  • batch_size:默认 4,建议省略让平台套用目录默认值。

试点训练(pilot)的要点是小步快跑:先用少量数据、少 epoch 验证数据管线能跑通、指标能正常返回,再放大规模。SKILL.md 特别强调两条纪律:保存 job_id——提交后立刻记下,用 GET /v1/training-jobs/{job_id} 和 /logs 轮询状态,而不是在超时后盲目重复提交;提交时带上 Idempotency-Key 请求头,重试相同请求会返回原始任务而不是另起一个烧钱的任务。

3.3 三个被低估的坑

坑一:不 pin seed,指标可能漂得离谱。 Fastino API 的 seed 契约文档记录了一个真实测量结果:在 seed 控制功能上线前,三次完全相同的 GLiNER2 编码器训练,分类 macro-F1 落在 0.38–0.63 之间——同一份数据、同一份配置,三次训练结果差异巨大。pin 一个 seed 能消除数据洗牌和初始化带来的可复现噪声,但它不承诺 bit 级一致(GPU 归约顺序仍非确定)。训练时显式传 seed,评估时才能比较"配置差异"而不是"运气差异"。

坑二:验证集切分与 seed 解耦。 平台对编码器训练强制"验证集是尾部、不随 seed 变化"的固定左到右切分,所以两个只差 seed 的任务会在同一批留出数据上评分。这本身是好事,但也意味着:如果上传文件顺序没做好分组随机化(见 2.2),再 pin seed 也救不回泄漏的验证指标。

坑三:试点阶段就盯 FP 和类别回退。 SKILL.md 的建议是"progress stalls 时先查 false positives 和 category regressions,再决定扩数据还是加训练时长"——很多人指标上不去的第一反应是加数据,但 GLiNER2 这类 span 匹配模型,更多时候是标签定义歧义导致的类别混淆。先看混淆矩阵,再动数据。

四、检查点评估:准确率、macro-F1、多标签 micro-F1

训练期间和结束后,GET /v1/training-jobs/{job_id}/checkpoints 返回全部检查点,字段包括 epoch、step、training_loss、validation_loss、accuracy,以及两个用于选型的标志位:is_best(当前最优)和 is_final(最终产物)。is_deployable 标记该检查点是否通过可部署校验。

SKILL.md 给出了与任务类型严格对应的指标矩阵,这是评估环节最值得对照的清单:

  • 单标签分类:准确率(accuracy)、macro-F1、混淆模式;
  • 多标签分类:micro-F1、macro-F1、精确集合准确率(exact-set accuracy,即预测标签集合与真实集合完全一致才算对);
  • 所有任务:逐类别结果 + 无匹配样本上的假阳性统计。

多标签任务里,exact-set accuracy 比 micro/macro-F1 更贴近线上体验——决策系统关心的是"整组标签是否给对",而不是平均召回。而 cls_threshold 是仅推理期生效的参数(README 对照表明确标注),意味着调阈值不影响训练,只影响打分后的截断。在 dev 集上扫一遍阈值曲线再定值,比凭感觉拍 0.4/0.5 靠谱。

还有一个容易混淆的特例:序数评分头不能用 accuracy 一票定胜负。README 明确警告,"0" 到 "10" 作为字符串标签训练时,每个标签独立打分,损失函数并不知道 "6" 比 "0" 更接近 "7"。因此序数任务要同时报告 mean absolute error(MAE)和准确率——一个 8 分误判成 7 分的系统,比 8 分误判成 2 分的系统在准确率上完全一样,但业务代价天差地别。

评估还有一个常被忽视的维度是校准:SKILL.md 提醒"less confident predictions are not necessarily better decisions",置信度不是概率,也不要在没有契约的情况下把 sigmoid/softmax 分数互转。当你需要拿置信度做分级处理时,先验证分数与真实正确率的关系,而不是默认分数高就一定对。

五、部署与冒烟测试:上线前的最后一步

5.1 部署动作与权责

选中检查点后,部署动作只有一步:POST /v1/training-jobs/{job_id}/checkpoints/{checkpoint_id}/deploy。响应返回 deployment_path(不可变的部署前缀)和 mme_path(兼容别名),之后通过 POST /v1/chat/completions 以 OpenAI 兼容格式调用微调后模型。

但部署不等于上线。SKILL.md 的约束很明确:不要替换现有生产模型,除非用户明确要求;部署前的冒烟测试必须通过真实 serving API 完成,而不是本地复现。

5.2 冒烟测试清单

冒烟测试的核心是"评估与线上同构"。逐条对照:

  1. 标签定义一致性:评估时用的 task、labels、prompt、multi_label 结构,在 serving 请求里必须原样保留(Fastino API 的 schema 字段承载这些结构)。换了个标签写法,冒烟结果就不可比。
  2. 同输入对照:用与评估完全相同的输入文本、标签、阈值和打分方式,分别请求基座模型和微调检查点,对比输出——验证微调确实改变了行为,且改变方向符合预期。
  3. 新样本泛化:用训练集里没出现过的实体名、模板和措辞变体再测一轮,观察是否只是"背下了训练样本"。
  4. 阈值复验:serving 请求里 threshold 默认 0.5,但如果你在 dev 集上调过阈值,serving 时要把调好的值显式传入,否则线上行为与评估结果脱节。
  5. 负面样本:专门喂无匹配样本,确认不会大量误报。

5.3 长文档与容错

GLiNER2.5-Decide 的编码器 max_position_embeddings 是 512(config.json),长文档必须分块处理。正确姿势是重叠分块 + 原始偏移映射 + 结果去重(SKILL.md 原文),而不是静默截断丢弃尾部文本——对邮件分诊这类任务,关键信息往往就在签名区和末尾 PS。批量请求按 API 支持的方式并行,不要自己并发轰炸。

最后是工程侧的容错:加超时和有限退避处理瞬时错误与限流;对认证、校验和终态训练错误要清晰暴露,不要无限重试;非幂等提交(如部署)先确认任务状态再决定是否重试。

结语

回看整条链路,GLiNER2.5-Decide 的托管微调有一个和其他模型家族截然不同的心智模型:因为标签是运行时输入,训练数据的价值不在"教会模型新类别",而在"教会模型你的决策结构"。标签对齐决定线上行为是否忠实于训练意图,防泄漏切分决定评估数字是否可信,检查点指标的选择决定你选出的模型是否真的匹配业务目标。把这几环做实,340M 的模型就能在私有分类体系里跑出 4B 级模型的效果——而且是在 CPU 上、没有一次 token 生成的开销。

登录后查看全文
GLiNER2.5-Decide