当前位置：首页 > news >正文

RepairFormer：基于Transformer的JSON/YAML等结构化输入自动修复实战

news 2026/8/28 5:00:51

RepairFormer 是面向结构化输入的自动化修复方向的一种命名：当 JSON、YAML、XML 或配置文本因为少逗号、引号未闭合、字段拼错、内容被截断而无法解析时，不再靠手写正则逐一补救，而是用 Transformer 学习“坏输入 -> 好输入”的映射。这正是 Automated Repair of Structured Inputs 要解决的核心问题。下面按工程落地主线展开：先说明任务边界，再讲数据构造和评估，给一个基于 T5 的最小实现，然后讨论训练、验证、生产部署和常见坑。文章里的代码是示例实现，不代表特定论文源码；在你的项目里需要按实际数据格式和依赖版本调整。

1. 核心概念：RepairFormer 在解决什么问题

1.1 结构化输入为什么这么容易损坏

所谓结构化输入，并不是指“有格式的文档”这么简单，而是指那些必须满足解析器要求的文本。程序只有先把它解析成结构体、对象或语法树，才能进入下游业务逻辑。常见类型包括 JSON、YAML、XML、CSV、命令行参数、配置文件模板、日志模板，甚至源代码片段。

这些输入在真实生产环境里很容易损坏：上游系统输出被截断，手工编辑时少打一个逗号，脚本拼接字符串时漏掉引号，跨系统拷贝时全角字符混入半角字符，不同版本工具对格式的要求不一致。解析器一旦失败，业务就会中断，而传统日志往往只给出一个“第几行第几列”的语法错误，无法自动告诉你应该补什么。

输入类型	典型解析工具	常见损坏形态
JSON	`json.loads`	缺逗号、尾逗号、单引号、双引号未闭合
YAML	`yaml.safe_load`	缩进错误、冒号后没有空格、特殊字符未转义
XML	`xml.etree.ElementTree`	标签不闭合、属性缺少引号
CSV	`pandas.read_csv`	列数不一致、转义问题
命令行参数	`shlex.split`	引号嵌套、反斜杠失控

RepairFormer 想解决的问题，就是把这些损坏字符串自动转换成“能解析，且尽量保持原意”的合法字符串。

1.2 修复的本质是序列到序列生成

传统方案通常走两条路：一是写解析器的容错恢复规则，二是写正则或脚本做字符级替换。前者的问题是容错规则通常只能处理语法层面的局部错误，碰到字段名拼错、字段缺失这类需要上下文推理的问题就无能为力。后者的问题是规则会越写越多，不同错误组合在一起时，正则几乎无法覆盖。

RepairFormer 的思路把修复重新建模成一个条件生成问题：给定一段坏输入x，生成一段好输出y。用概率表达就是最大化P(y|x)。这里的x和y都是 token 序列，所以模型的输出可以适应任意长度的编辑操作：插入逗号、删除多余字符、重排字段、补全引号、修正拼写。

把修复建模成生成任务还有一个好处：不需要显式枚举错误类型。模型只要在足够多的“坏输入-好输出”样本上训练，就能自己学到哪些上下文信号可以用来判断什么地方出了问题。

1.3 RepairFormer 的核心设计

从模型结构上看，RepairFormer 这类方案通常采用编码器-解码器架构。编码器负责读取原始损坏文本，通过自注意力建立整段文本的上下文表示；解码器则逐个 token 生成修复后的输出。

这种结构很适合结构化文本修复，因为结构化文本存在大量长距离依赖：JSON 里后一个对象的所有字段都依赖前面某个大括号是否闭合，XML 里每个结束标签都要匹配开始标签，YAML 的缩进决定了嵌套层级。自注意力机制可以让模型在生成某个 token 时，直接看到很远位置的相关 token，而不是像 RNN 那样只能依赖压缩后的隐状态。

另一个关键点是修复输出必须“可校验”。模型生成的结果不能只“看起来像”，还要能通过对应解析器。因此在工程实现中，模型生成之后通常还要套一层解析校验和规则兜底，这一点在后文会重点展开。

2. 数据与评估：不要在错误的指标上优化模型

2.1 训练样本从哪里来

要训练修复模型，第一件事是构造“坏输入 -> 好输出”的成对数据。数据来源可以分成两类：真实数据和合成数据。

真实数据来自线上日志和人工修正。比如系统记录了解析失败的原始文本，人工修好之后把修复结果保存下来，这就是质量很高的训练样本。但真实脏数据通常数量少、分布不均匀，很多错误类型可能只出现一两次。

合成数据则用来扩充覆盖度。方法很简单：先准备一批合法结构化文本，再按预设规则破坏它们。下面是一个 JSON 数据破坏示例，用于说明思路。

import json import random def corrupt_json_text(text: str) -> str: """按随机方式破坏一段合法 JSON 文本。""" op = random.randint(0, 2) if op == 0: idx = text.find(",") if idx != -1: return text[:idx] + text[idx + 1:] elif op == 1: return text.replace('"', "'", 2) else: cut = random.randint(max(1, len(text) // 2), len(text) - 1) return text[:cut] return text clean = "{\"name\": \"demo\", \"status\": \"running\", \"retry\": 3}" bad = corrupt_json_text(clean)

这个函数只是演示基本思路，真实项目里需要设计更细的错误注入逻辑：随机删除冒号、随机交换字段名、随机多打一个右括号、把字段名status改成statsu等。

合成数据能快速起步，但它有一个明显风险：如果测试数据和训练数据来自同一套破坏规则，得到的评估结果会虚高。所以训练、验证、测试集应该尽量按来源切分，最好让测试集包含一部分真实线上坏样本。

2.2 评估指标不止一种

修复任务不能只用一个准确率衡量。至少要区分“能解析”和“修复正确”两层含义。

指标	计算方式	说明
合法率	模型输出能被解析器解析的比例	只能说明格式正确，不代表语义正确
修复率	模型输出与参考结果在语义上一致的比例	更接近真实修复目标
字段保留率	输出中保留参考结果关键字段的比例	适合字段多、顺序不敏感的结构
人工接受率	人工抽检时接受输出的比例	最接近生产验收标准

对于 JSON，可以先用json.loads判断合法率，再用解析后的对象相等判断修复率。由于 JSON 对象本身不区分字段顺序，直接比较解析后的字典可以避免“字段顺序不同但语义一致”被误判成失败。

下面是一个评估函数示例：

import json def evaluate_repair(pred_texts, target_texts): valid = 0 repaired = 0 total = len(pred_texts) for pred, target in zip(pred_texts, target_texts): try: pred_obj = json.loads(pred.strip()) valid += 1 target_obj = json.loads(target.strip()) if pred_obj == target_obj: repaired += 1 except Exception: continue return { "valid_rate": valid / total, "repair_rate": repaired / total, }

需要注意的是：修复率不等于业务成功率。如果修复后的 JSON 可以解析，但字段status从running变成了stopped，对下游来说就是一次严重事故。因此在生产环境评估时，还需要针对关键字段单独做一致性校验。

2.3 数据划分要防泄漏

修复模型很容易在数据划分上踩坑。如果同一份合法文档被破坏成多个坏样本，并且这些坏样本同时出现在训练集和测试集，模型就会通过“记忆原文”的方式拿到高分，而不是真正学会修复。

推荐做法是：

先按来源文件或业务场景切分数据，而不是按行随机切分。
验证集和测试集应包含训练集未覆盖的损坏模式。
每个批次里不要出现来自同一条原始记录的大量变体。
真实坏样本要单独保留，作为最终验收集。

数据泄漏最常见的结果是训练损失很低、测试修复率也很高，但一上真实流量就明显下降。检查方式很简单：抽几条测试集输入，确认它们和训练集中的原文不重复，且损坏模式不在训练集里大量出现。

3. 环境准备与依赖

3.1 环境要求

后端模型可以选择 T5、BART 等通用序列到序列模型，也可以自己实现编码器-解码器。为了快速跑通，建议从 T5 的 small 版本开始。

组件	推荐配置	说明
Python	3.10 或 3.11	Transformers 对 Python 版本有要求
PyTorch	2.0 以上	训练和推理的基础框架
Transformers	4.30 以上	提供预训练模型和 Trainer
显存	至少 8GB	训练 T5-small 可接受，更大模型需要更高显存
内存	16GB 以上	数据读取和训练过程较稳定

如果你的机器只有 CPU，也可以跑小规模实验，但训练速度和生成速度都会明显偏慢。

3.2 安装依赖

建议先创建独立虚拟环境，避免污染系统 Python。

python -m venv venv source venv/bin/activate python -m pip install --upgrade pip pip install torch transformers datasets accelerate sentencepiece

如果使用 GPU，请根据本机 CUDA 版本到 PyTorch 官方页面选择对应安装命令。sentencepiece是 T5 tokenizer 依赖，不能省略。accelerate是 Transformers Trainer 的辅助依赖。

3.3 项目结构

一个最小项目可以这样组织：

repairformer/ ├── data/ │ └── pairs.jsonl ├── src/ │ ├── dataset.py │ ├── train.py │ └── predict.py ├── models/ │ └── repairformer/ ├── logs/ └── configs/ └── train.yaml

这里把数据、源码、模型输出和日志分开，方便训练和调试。

4. 最小可运行的 RepairFormer 实现

4.1 先构造一个最小数据集

准备一个 JSONL 文件data/pairs.jsonl，每行是一条训练样本，包含input和output两个字段。

{"input": "{\"name\": \"demo\" \"status\": \"running\"}", "output": "{\"name\": \"demo\", \"status\": \"running\"}"} {"input": "{\"name\":\"demo\",\"status\":\"running\"}", "output": "{"name":"demo","status":"running"}"} {"input": "{\"retry\": 3, \"timeout\": 5", "output": "{\"retry\": 3, \"timeout\": 5}"}

input是坏文本，output是修复后的完整合法文本。这里没有使用 diff 或补丁格式，原因是完整输出更容易训练，也更容易在推理时直接校验。

4.2 编写 Dataset 和预处理

下面实现一个 PyTorch Dataset。这里以 T5 为例，其他 seq2seq 模型类似。

import json import torch from torch.utils.data import Dataset class RepairDataset(Dataset): def __init__(self, data_path, tokenizer, max_length=512): self.tokenizer = tokenizer self.max_length = max_length self.samples = [] with open(data_path, "r", encoding="utf-8") as f: for line in f: line = line.strip() if not line: continue obj = json.loads(line) self.samples.append((obj["input"], obj["output"])) def __len__(self): return len(self.samples) def __getitem__(self, idx): bad_text, good_text = self.samples[idx] src = self.tokenizer( bad_text, return_tensors="pt", truncation=True, max_length=self.max_length, ) tgt = self.tokenizer( good_text, return_tensors="pt", truncation=True, max_length=self.max_length, ) labels = tgt["input_ids"].squeeze() labels[labels == self.tokenizer.pad_token_id] = -100 return { "input_ids": src["input_ids"].squeeze(), "attention_mask": src["attention_mask"].squeeze(), "labels": labels, }

这里把pad_token_id替换成-100，是为了在计算交叉熵损失时忽略填充位置。T5 的 decoder 也需要接收labels，Trainer 会自动把labels右移并生成 decoder attention mask。

4.3 微调 T5 模型

训练脚本可以直接使用 Hugging Face 的Seq2SeqTrainer。下面是一个最小训练流程。

from transformers import ( AutoTokenizer, AutoModelForSeq2SeqLM, DataCollatorForSeq2Seq, Seq2SeqTrainingArguments, Seq2SeqTrainer, ) model_name = "t5-small" tokenizer = AutoTokenizer.from_pretrained(model_name) model = AutoModelForSeq2SeqLM.from_pretrained(model_name) train_dataset = RepairDataset("data/pairs.jsonl", tokenizer) eval_dataset = RepairDataset("data/eval.jsonl", tokenizer) data_collator = DataCollatorForSeq2Seq(tokenizer, model=model) training_args = Seq2SeqTrainingArguments( output_dir="./models/repairformer", eval_strategy="epoch", save_strategy="epoch", load_best_model_at_end=True, metric_for_best_model="repair_rate", greater_is_better=True, predict_with_generate=True, num_train_epochs=5, per_device_train_batch_size=8, per_device_eval_batch_size=8, gradient_accumulation_steps=2, fp16=True, logging_dir="./logs", ) trainer = Seq2SeqTrainer( model=model, args=training_args, train_dataset=train_dataset, eval_dataset=eval_dataset, data_collator=data_collator, compute_metrics=compute_metrics, ) trainer.train()

在较新版本的 Transformers 中，evaluation_strategy参数已改名为eval_strategy。如果使用旧版本，需要改回evaluation_strategy。fp16只在 GPU 支持时开启，CPU 环境要去掉或改为bf16=False。

4.4 推理与验证

训练完成后，写一个简单的推理函数。

import torch from transformers import AutoTokenizer, AutoModelForSeq2SeqLM def load_repair_model(model_dir, device="cuda"): tokenizer = AutoTokenizer.from_pretrained(model_dir) model = AutoModelForSeq2SeqLM.from_pretrained(model_dir) model.to(device) model.eval() return model, tokenizer def repair_text(text, model, tokenizer, device="cuda", max_length=512): inputs = tokenizer(text, return_tensors="pt", max_length=max_length, truncation=True) inputs = {k: v.to(device) for k, v in inputs.items()} with torch.no_grad(): outputs = model.generate( **inputs, max_length=max_length, num_beams=4, ) return tokenizer.decode(outputs[0], skip_special_tokens=True)

推理时使用 beam search 而不是贪心解码，通常能降低缺 token 的概率。但 beam search 不是万能，输出仍然需要用解析器校验。

5. 关键设计详解：为什么这样建模更容易成功

5.1 为什么选编码器-解码器而不是纯语言模型

纯 decoder 模型也能做“修复”，比如把坏文本和好文本拼接后继续生成。但序列到序列模型在结构上更自然：编码器可以双向看到整段坏输入，解码器在生成时通过交叉注意力访问编码器表示。这种设计让模型更容易对齐输入和输出。

从工程角度看，T5 和 BART 都有成熟的预训练权重，微调成本低。T5 在训练时通常需要给输入加一个任务前缀，比如"repair: "或"fix json: "。如果训练时加了前缀，推理时也必须加同样的前缀，否则效果会下降。

5.2 标签是完整好序列，不是补丁

有人会觉得，既然坏输入和好输入差异不大，标签可以只写“差异补丁”。但补丁格式并不唯一：先删哪个字符、后插哪个字符，不同人写的补丁可能完全不同。这会让模型学习目标不稳定。

完整好序列虽然生成 token 数量更多，但它定义清晰，不受补丁路径影响。对修复模型来说，最重要的是输出能通过解析器，并且和原始意图一致。完整序列天然满足这个约束。

5.3 输出校验必须独立于模型

无论模型生成的结果多自然，都不能在未校验的情况下直接交给下游。修复模型必须搭配一个独立校验器。

def safe_repair(text, model, tokenizer): repaired = repair_text(text, model, tokenizer) try: json.loads(repaired) return repaired except Exception: # 如果模型失败，可以走规则修复，或返回原始输入让上层处理 return text

这个示例简单，但已经体现了核心原则：模型输出必须经过解析器确认，不能只看模型自信度。生产环境还需要补充结构字段校验、类型校验和行为影响评估。

5.4 规则修复和模型修复的融合

模型并不是万能的，规则修复也并非完全无用。合理的做法是把两者分层：

场景	建议
全角逗号、全角冒号、不可见字符	用规则预处理，成本最低
尾逗号、多闭合括号	可以先用规则修复
字段名拼错、字段缺失、长文本截断	需要模型上下文推理
模型输出仍不合法	回退到规则修复或原样返回

规则层适合“错误类型固定、修复动作明确、不会误伤正常文本”的场景。模型层适合“需要依赖上下文判断”的场景。两者结合后，既降低了模型压力，也提高了整体修复率。

6. 运行验证与结果分析

6.1 训练日志怎么看

训练过程中，除了看 loss，还要看生成指标。直接看 loss 下降会让你误以为模型学会了修复，因为 loss 下降只能说明模型记住了训练分布，不代表输出能通过解析器。

可以启动 TensorBoard 观察指标变化：

tensorboard --logdir ./logs

关注两个曲线的相对变化：

valid_rate快速上升，说明模型学到了“生成合法结构”的基本语法。
repair_rate缓慢上升，说明模型开始恢复语义信息。
如果valid_rate高但repair_rate低，说明模型擅长“补全格式”，但容易改错业务字段。

6.2 测试集上如何评估修复率

训练结束后，把测试集输入预测脚本，生成结果后统一评估。

python src/predict.py \ --model models/repairformer/checkpoint-1000 \ --input data/test.jsonl \ --output data/pred.jsonl

然后对pred.jsonl执行evaluate_repair，统计合法率和修复率。注意测试集切分要与训练集来源不同，否则指标会虚高。

6.3 失败样本拆解

当一个测试样本失败时，需要分清楚失败发生在哪一层。可以用下面表格记录。

输入	模型输出	参考输出	问题定位
`{"a":1 "b":2}`	`{"a":1, "b":2}`	`{"a":1, "b":2}`	成功
`{"a":1, "b":2`	`{"a":1, "b":2}`	`{"a":1, "b":2}`	缺失部分较长，依赖闭合生成
`{"statsu":"running"}`	`{"stats":"running"}`	`{"status":"running"}`	语义误纠

如果失败主要集中在长文本，考虑增大max_length，或者把修复范围切分成字段块。如果失败集中在字段拼写，需要补充更多真实拼写错误样本，而不是继续增大模型。

7. 从实验到生产：RepairFormer 落地要补什么

7.1 学习环境与生产环境的差异

实验环境里跑通一个 notebook，和生产环境稳定提供服务之间差得很远。下表列出主要差异。

维度	实验环境	生产环境
模型来源	checkpoint 文件	模型服务或优化后的推理引擎
输入数据	清洗后的 jsonl	任意用户输入，可能出现超长、恶意、非常规字符
输出校验	简单`json.loads`	字段类型、范围、敏感信息检测
失败兜底	手动重试	规则修复、告警、人工复核
日志与监控	少量打印	指标、链路追踪、阈值告警
数据隐私	往往不考虑	脱敏、权限控制、审计