知识图谱构建这条链路上，真正让我加过班的从来不是模型选型，而是把模型吐出来的那一坨文本稳定地变成结构化三元组。做过抽取项目的人都懂：模型指标刷到 90 分，工程上线后能拿到的有效结构化结果可能只剩 70 分，剩下 20 分全是格式塌方、字段缺失、括号不配对、多余解释文字混进结果。CodeKGC 这篇工作的思路之所以值得单独写一篇笔记，就是因为它把这件事的因果顺序调了个头——不再让模型输出自由文本再靠正则去猜，而是让代码语言模型直接生成 Python 类实例代码，用代码的语法约束反过来框住输出，再用抽象语法树做后处理。生成式知识图谱构建里最难缠的"格式不可控"问题，被"写代码"这个动作天然吃掉了一大半。

这篇笔记面向三类人：手里有抽取任务、正在纠结输出格式怎么定的工程师；读过论文但想知道怎么真正跑起来、prompt 和解析器该怎么写的同学；以及被 schema 频繁变更折磨过、想找一个更可维护方案的技术负责人。我会把论文的设计动机、prompt 骨架、数据自举流程、AST 解析实现、消融结论的读法，以及我自己踩过的坑全部摊开讲，代码都能直接抄。

1. 为什么要把知识图谱构建当成"写代码"：核心设计思路拆解

我最初看到这个题目时第一反应是"噱头"，因为代码生成和关系抽取看起来八竿子打不着。把论文从头到尾读了两遍、又自己动手复现了一遍之后，我才承认这个视角转换是真有东西的。它解决的不是"模型更聪明"的问题，而是"输出空间被约束"的问题，这两件事在工程上的价值差着量级。

1.1 生成式抽取的三种输出形态与各自的天花板

把任意一个抽取任务交给生成式模型，输出格式无非三种路线。第一种是自由文本，让模型用自然语言描述抽到了什么，好处是零格式要求、模型最放松，坏处是后处理基本等于再写一个解析器，而且每次模型版本迭代解析规则都要跟着改，维护成本极高。第二种是结构化的 JSON 或标签序列，好处是语义明确，坏处是 JSON 对语法极度敏感，少一个逗号、多一个尾随逗号、字符串里混进未转义的双引号，整个解析就崩，而这些恰恰是大模型最容易犯的错。第三种就是 CodeKGC 选的路线：让模型生成一段可执行的类实例化代码。

代码这条路线的巧妙之处在于，它同时吃到了两个红利。一是 Python 的调用语法天然是"函数名 + 关键字参数"的结构，和"关系类型 + 头实体 + 尾实体"的图谱结构一一对应，不需要任何人为映射。二是代码语言模型在预训练阶段见过海量的函数调用和类定义，它对"Relation(subject='A', object='B', relation='C')"这种形态的生成先验，比对"输出 JSON"这种指令的先验还要强，因为后者是人为规定的，前者是语料里真实存在的模式。

我自己实测下来的体感是：同一个基座模型，在同样的小样本设置下，要求输出 JSON 的解析成功率大概在 85% 上下，要求输出类实例代码的成功率能到 95% 以上，而且失败的样本里绝大多数只是尾部多了一段解释文字，用截断就能救回来，不像 JSON 那样一旦结构错位就彻底报废。

1.2 代码与图谱的同构关系：schema 到类，三元组到实例

这个映射关系值得单独拆开讲，因为后面所有的 prompt 设计都建立在这上面。知识图谱的 schema 层，比如"人物—出生于—地点"这样的关系定义，对应到代码里就是一个类的定义，类名就是关系类型，类的构造参数就是关系涉及的槽位。图谱的实例层，比如"某人物 出生于 某地点"这条具体事实，对应到代码里就是一次实例化调用，实参就是实体值。

再往深一层，事件抽取也能套进这个框架。一个事件类型就是一个类，事件的论元角色就是构造参数，事件触发词和各个论元填充值就是实参。论文里把事件论元抽取统一成"事件与论元之间的关系"来处理，本质上是把事件抽取降维成关系抽取，这样一套 prompt 模板能吃下两种任务，工程上省了非常多重复建设。

这种同构带来的直接好处有三个。第一，schema 变成了 prompt 里可以显式书写的代码片段，而不是含糊的自然语言描述，模型对"这个类只有这三个参数"的约束感知更强。第二，代码的语法是刚性的，模型即使想幻觉出一个不存在的字段，也会因为不符合类定义而在解析阶段被白名单过滤掉，这在 JSON 方案里做不到，因为 JSON 多一个 key 是合法的。第三，类型注解可以承载值的约束，比如主体和客体标注为字符串、关系标注为枚举，模型在生成时会倾向于遵守这些约束，即使它不完全理解类型系统。

提示：这里的"同构"是设计层面的同构，不要理解成模型真的在做符号推理。模型仍然是在做序列生成，代码只是给它提供了一个更强的输出先验和一个更宽容的解析接口。

1.3 论文的完整流水线：prompt、自举、微调、解析四段式

把整篇论文的流水线摊平，其实是四个阶段串起来的。第一阶段是 prompt 构造，把任务描述、schema 定义、若干示例拼成一个代码风格的上下文，喂给一个能力较强的闭源模型。第二阶段是数据自举，让这个强模型对训练语料逐条生成候选代码输出，用人工标注的金标准去过滤，只保留完全正确的样本，形成一份"代码风格"的训练集。第三阶段是用这份数据微调一个小参数量的代码基座模型，把强模型的能力蒸馏下来。第四阶段是推理时用微调后的模型生成代码，再用 AST 解析器转成结构化结果。

这个设计里最值得琢磨的是第二阶段的动机。直接让强模型在线推理成本太高，而且不可控；直接把原始标注数据拿来微调小模型，小模型学不会代码风格的输出格式。用强模型做一次格式转换加质量过滤，相当于既做了数据蒸馏又做了格式对齐，一举两得。过滤环节用金标准做硬匹配，虽然会损失一部分召回（模型生成了正确的三元组但格式略有偏差就被丢掉），但换来的是训练数据的纯度，对于只有 7B 量级的小模型来说，数据纯度比数据规模重要得多。

我在复现时把过滤线放松过一次，允许"关系名大小写不一致"的样本进入训练集，结果微调后模型的输出稳定性明显下降，经常在关系名上自由发挥。后来改回严格过滤，并且把关系名统一成 schema 里的原始写法再训练，输出规范性问题基本消失。这个教训很朴素：小模型对训练数据的格式非常敏感，你给它什么格式，它就学什么格式，容不得半点含糊。

2. 核心细节解析：prompt 骨架、schema 注入与解析容错

这一部分是我认为整篇论文最值得抄的部分，因为流水线的其他环节都可以替换，唯独 prompt 骨架和解析器的设计是通用的，换成任何抽取任务都能直接搬。

2.1 代码风格 prompt 的四段式骨架

论文的 prompt 大致可以拆成四块：任务指令、schema 定义、示例、生成触发前缀。任务指令用一两句话说明"从给定句子中抽取所有关系，以代码形式输出"，不需要长篇大论，因为代码风格的输出本身就是最强的指令。schema 定义这一段是核心，用注释或者类定义的形式把当前任务支持的所有关系类型列出来。示例部分给两到三个完整的"输入句子 + 输出代码"对，让模型对齐格式。最后一段是触发前缀，通常就是一行Relation(或者一句"请输出："，作用是告诉模型从哪里开始续写。

触发前缀这个细节很多复现版本会漏掉。它在工程上有两个作用：一是明确告诉模型"接下来该写代码了"，避免它先输出一段分析；二是让后处理阶段有一个稳定的锚点，解析器可以直接从第一个Relation(开始截取，前面即使有零星的说明文字也不影响。

下面是我实际用的一份模板，做了简化但保留了核心结构：

PROMPT_TEMPLATE = '''You are an information extraction engine. Extract all relations from the given sentence and output them as Python code. # Supported relation schema (you MUST only use these): {schema_block} # Example 1 Sentence: {demo_sentence_1} Output: {demo_output_1} # Example 2 Sentence: {demo_sentence_2} Output: {demo_output_2} # Task Sentence: {input_sentence} Output: '''

其中schema_block是动态拼进去的，形式如下：

class Relation: """Represents one fact triple.""" def __init__(self, subject: str, object: str, relation: str): self.subject = subject # head entity, copied from the sentence self.object = object # tail entity, copied from the sentence self.relation = relation # must be one of the allowed labels # allowed labels: # 出生于, 就职于, 配偶, 导演, 主演, 位于

这种写法的关键点是：类定义给出结构，注释给出约束，允许标签列表给出闭集。三样东西缺一不可。只给类定义，模型会自己编关系名；只给标签列表，模型不知道输出格式；只给注释，模型可能把注释当成正文复制进去。

2.2 schema 注入的 token 账与上下文预算分配

真实业务里关系类型动辄几十上百个，全塞进 prompt 迟早撑爆上下文。我在做一份包含 60 个关系的 schema 时算过一笔账：每条关系的类定义加注释平均 35 到 45 个 token，60 条就是 2100 到 2700 token。加上两个示例各约 120 token，任务指令 80 token，输入句子平均 60 token，总计接近 3000 token。对于一个上下文窗口 4096 的模型来说，留给输出的空间只剩 1000 token 出头，勉强够生成十几条三元组，稍微长一点的句子就会被截断。

我的处理办法是给上下文做预算切分：schema 最多占 40%，示例占 25%，输入占 10%，剩下 25% 留给输出。当 schema 超出预算时，不是硬截断，而是先用一个轻量的检索步骤缩小候选关系集。具体做法是把输入句子和每条关系的描述文本各做一次向量化，取相似度最高的 top-k 条关系拼进 prompt。k 的取值和句子长度相关，短句取 8 到 12 条，长句取 15 到 20 条，实测召回损失在 2 个点以内，但解析成功率和生成完整度提升很明显。

另一个省钱的办法是把 schema 写成紧凑格式，用一行一个标签的形式代替完整类定义，只保留一个类定义作为格式示例。这样每条关系的 token 消耗能压到 8 到 10 个，60 条关系总共 600 token 左右，代价是模型对字段约束的感知会弱一些，需要在示例里把字段顺序固定死来补偿。我在两个方案之间来回切换过，结论是关系数少于 30 个时用完整类定义，超过 30 个时用紧凑列表加固定示例，性价比最高。

2.3 用 AST 做后处理：从字符串到结构化结果的关键一跳

这是整篇论文里我最欣赏的工程设计。论文报告里专门对比了"严格字符串匹配"和"基于语法树解析"两种评估方式，结论是同样的模型输出，用 AST 解析能多捞回相当一部分本来正确的样本。原因很简单：模型生成的代码里可能有多余空格、换行位置奇怪、参数顺序颠倒、甚至混进了别的内容，但只要能通过 Python 的语法解析，抽象语法树就能把结构完整地还原出来，而这些差异在严格字符串匹配下全被判成错误。

AST 解析还有一个隐藏价值：它天然支持字段级校验。遍历语法树时，你可以检查每次调用的函数名是不是 schema 里允许的，关键字参数的名称是不是类定义里声明的，参数值是不是字符串常量。任何一项不符合，就地丢弃或者修正，而不是等到下游入库时才发现脏数据。这比在 JSON 上做同样的事要方便，因为 JSON 的解析结果是一个嵌套字典，你还得再写一层结构校验逻辑。

我实测过三种解析策略在同一批 500 条输出上的表现，结果差异相当大：

注意这个表里的"成功解析率"指的是能把模型输出还原成结构化三元组的比例，不是准确率。但它说明的问题很关键：链路损耗可以从 39 个点压到 4 个点，这个收益比换一个更大的模型来得直接。

2.4 解码参数与停止条件的工程细节

解码这块论文里写得比较简略，但实操中影响很大。关系抽取是确定性任务，我一般把温度设成 0，用贪心解码，保证同样输入得到同样输出，方便做回归测试。如果追求召回可以开小规模的 beam search，beam 宽度 3 到 5，但要注意 beam 会让生成偏向"更常见的模式"，在长尾关系上反而可能掉点。采样方案我不推荐，尤其是在需要精确匹配实体字符串的场景，采样出来的实体拼写变体多到没法归一化。

最大生成长度要按任务估算。一条三元组代码大概 40 到 60 token，一个句子平均抽 2 到 4 条，加上可能的多余文字，max_new_tokens设成 256 比较稳妥，句子特别长或者关系特别密集的场景设到 512。设太小会出现"生成到一半被硬截断"，表现为最后一个括号缺失，AST 解析直接失败；设太大则单个 batch 的显存占用上去了，吞吐下降。

停止条件也要显式设置。如果模板里用了"输出结束后空一行"的约定，可以把\n\n加到 stop 序列里，让模型生成完最后一条就停，避免它自作主张再写一段"以上是抽取结果"之类的总结。这类总结文字是解析失败的高频来源，我甚至见过模型在代码后面补一句中文解释，导致整段输出无法解析。

3. 动手复现：从零走通一次代码式关系抽取

这一节是纯实操，我按自己复现时的工作顺序来写，你可以按同样的顺序走一遍，大概一个下午能跑通端到端。

3.1 环境准备与最小依赖集

依赖比想象中少，核心就是推理框架和解析用的标准库。ast是 Python 内置的，不需要额外安装，这一点比 JSON 方案还省事，因为不用装任何 schema 校验库。

pip install torch transformers accelerate sentencepiece pip install scikit-learn # 只在做 schema 检索时用

模型侧我用的是一个 7B 量级的代码基座模型，加载时用半精度，单卡 24G 显存足够推理，微调需要开 LoRA 或者梯度检查点。如果你手上只有消费级显卡，用 4bit 量化加载也能跑通推理链路，只是生成质量会掉一点，做流程验证完全够用。

需要注意的是，代码基座模型的分词器对缩进和换行比较敏感，拼 prompt 的时候不要用奇怪的空白字符，统一用空格缩进、统一换行符，能减少很多莫名其妙的解析失败。

3.2 prompt 模板与示例构造

示例的选择比数量重要。我的经验是给两个示例：第一个示例覆盖单关系、短句、实体边界清晰的情况；第二个示例覆盖多关系、实体有重叠、关系名较长的复杂情况。两个示例的输出格式必须完全一致，包括引号风格（统一用单引号）、参数顺序（统一 subject、object、relation）、以及多条结果之间的换行方式。

DEMO_1_SENTENCE = "某位作家在1998年完成了他的第一部小说。" DEMO_1_OUTPUT = """Relation(subject='某位作家', object='1998年', relation='创作时间') Relation(subject='某位作家', object='第一部小说', relation='创作作品')""" DEMO_2_SENTENCE = "这家公司由两位工程师创立，总部后来迁到了另一座城市。" DEMO_2_OUTPUT = """Relation(subject='这家公司', object='两位工程师', relation='创始人') Relation(subject='这家公司', object='另一座城市', relation='总部所在地')"""

示例里的实体一定要从句子中原样复制，不能用改写或简称。这一点非常关键，因为模型有很强的模式模仿倾向，如果示例里的实体是被改写过的，模型在真实推理时也会跟着改写实体，最后算指标时全是"看起来对但字符串不匹配"的样本，白白丢分。

还有一个小技巧：在示例输出后面不要加任何多余的空行或注释，让"最后一行代码"成为上下文里最接近生成起点的内容，模型续写时就会自然地接着写下一行代码。

3.3 输出解析器实现：AST 主路径加正则兜底

解析器我写了三版，最终稳定下来的是"先截取、再 AST、失败则正则修复后重试"的结构。第一版只用正则，遇到嵌套引号就崩；第二版只用 AST，遇到模型输出的半截代码也崩；第三版加了截取和兜底，成功率才上来。

import ast import re ALLOWED_FIELDS = {"subject", "object", "relation"} def _extract_code_block(text: str) -> str: """从模型原始输出里截出候选代码段。""" # 优先取 markdown 代码块 m = re.search(r"```(?:python)?\s*(.*?)```", text, re.S) if m: return m.group(1).strip() # 否则从第一个 Relation( 开始，截到最后一个右括号 start = text.find("Relation(") if start == -1: return "" end = text.rfind(")") if end == -1 or end <= start: return text[start:] return text[start:end + 1] def _parse_by_ast(code: str): triples = [] try: tree = ast.parse(code) except SyntaxError: return None for node in ast.walk(tree): if not isinstance(node, ast.Call): continue func = node.func if not (isinstance(func, ast.Name) and func.id == "Relation"): continue kv = {} for kw in node.keywords: if kw.arg not in ALLOWED_FIELDS: continue if isinstance(kw.value, ast.Constant) and isinstance(kw.value.value, str): kv[kw.arg] = kw.value.value if ALLOWED_FIELDS.issubset(kv.keys()): triples.append((kv["subject"], kv["object"], kv["relation"])) return triples def _parse_by_regex(code: str): """兜底：处理引号未闭合、括号缺失等残破输出。""" pattern = re.compile( r"subject\s*=\s*['\"](.*?)['\"]\s*,\s*" r"object\s*=\s*['\"](.*?)['\"]\s*,\s*" r"relation\s*=\s*['\"](.*?)['\"]", re.S, ) return [(m.group(1), m.group(2), m.group(3)) for m in pattern.finditer(code)] def parse_relations(raw_text: str): code = _extract_code_block(raw_text) if not code: return [] triples = _parse_by_ast(code) if triples: return triples return _parse_by_regex(code)

这段代码里有几个细节值得说。ast.walk会遍历整棵树，即使模型在代码前后夹杂了其他语句，只要Relation(...)调用存在就能被捞到。字段白名单那一步是防幻觉的关键，模型如果编出一个confidence='high'这样的参数，会被直接忽略。最后兜底的正则用了非贪婪匹配加re.S标志，能处理跨行的情况，但确实处理不了值里含同款引号的极端情况，那种我一般直接判失败，因为强行修复的收益不如重新生成一次。

注意：ast.parse只接受合法 Python 语法，如果模型生成的是带类型注解的调用或者用了双引号包裹嵌套单引号，可能直接抛SyntaxError。我的做法是在解析前做一次轻量预处理，把中文全角引号替换成英文引号，把连续两个以上空格压成一个，能救回一部分样本。

3.4 自举训练数据的构造流程与过滤策略

这个环节是我复现时花时间最多的，因为过滤策略直接决定微调后模型的上限。整个流程是：取一批有标注的训练语料，把标注转成代码格式作为参考；用强模型对每一条输入生成若干候选；用参考结果做严格匹配过滤；把通过的样本组成训练集。

候选数量我设的是 20，这个数字来自一个粗略的成本估算。假设训练集有 5 万条样本，每条生成 20 个候选，平均每条输出 150 token，总生成量是 1.5 亿 token。如果每 1 万条样本里能筛出 3000 条完全正确的样本，最终能拿到 1.5 万条高质量训练数据，这个规模微调 7B 模型是够的，再多也学不出新东西，反而增加过拟合风险。

过滤规则我列了五条，全部通过才算合格：一是能被 AST 完整解析；二是字段齐全且没有多余字段；三是关系名在 schema 白名单里；四是三元组集合与金标准完全一致（允许顺序不同）；五是实体字符串与原文完全一致，不做任何模糊匹配。

第三条和第五条是最容易放水的地方。我一开始觉得关系名大小写不一致是小事，后来发现放进去之后微调出来的模型会把关系名写得五花八门，前端统计时同一个关系的数量被拆成好几份。实体字符串也是同理，一旦允许模糊匹配，模型就会学到"可以稍微改写实体"的错误信号，而实体改写对下游对齐是致命的。

训练数据还需要做去重和负样本补充。去重是在归一化之后（小写、去标点、去多余空格）做集合去重，防止同一句话出现几十次导致过拟合。负样本指的是"句子中确实没有关系"的样本，这类样本要保留一部分，占比控制在 10% 到 15%，让模型学会在该空的时候输出空，而不是硬凑三元组。

3.5 微调与评估：指标计算和对照实验设计

微调用 LoRA 就够了，rank 设 16，学习率 1e-4 到 2e-4，batch size 视显存而定，训练 3 个 epoch 左右。我在小数据集上试过全参数微调，掉点比 LoRA 更快，因为数据量撑不住。

评估这块要特别注意指标口径。关系抽取一般用 micro-F1，匹配规则是三元组完全一致才算对，实体的比较要先做归一化。归一化包括转小写、去首尾空白、去英文冠词、统一中英文标点。这一步不做，指标会虚低好几个点，而且是那种"看一眼 badcase 发现全是对的"的虚低，非常打击人。

def normalize(text: str) -> str: text = text.strip().lower() text = re.sub(r"\s+", " ", text) text = re.sub(r"^(the|a|an)\s+", "", text) return text def compute_f1(preds, golds): tp = fp = fn = 0 for pred, gold in zip(preds, golds): p = {(normalize(s), normalize(o), r) for s, o, r in pred} g = {(normalize(s), normalize(o), r) for s, o, r in gold} tp += len(p & g) fp += len(p - g) fn += len(g - p) precision = tp / (tp + fp) if tp + fp else 0.0 recall = tp / (tp + fn) if tp + fn else 0.0 f1 = 2 * precision * recall / (precision + recall) if precision + recall else 0.0 return precision, recall, f1

对照实验建议至少做三组：代码风格对比自然语言风格（同一模型、同一后处理口径）、代码基座对比通用基座（同参数量）、AST 解析对比严格匹配（同一批输出）。这三组跑下来，你才能真正把论文里那些增益拆开看清楚，知道哪部分来自模型能力、哪部分来自格式约束、哪部分来自解析容错。

4. 论文里的对照实验怎么读：消融结论与适用边界

论文的实验部分列了不少数字，但直接照搬结论容易误读。我按自己的理解把它的增益来源拆成了三块，这个拆法建议你在读任何一篇生成式抽取的论文时都用一遍。

4.1 代码风格对自然语言的增益到底来自哪里

论文里有一组很明显的结果：同样的基座、同样的训练数据，代码风格输出的效果优于自然语言风格。很多人把这条读成"代码语言模型更强"，这个解读不准确。增益其实分成三份：一是 schema 被显式写成类定义之后，模型对字段的约束感知更强，幻觉字段变少；二是 AST 解析比文本解析宽容得多，同样的输出质量能还原出更多正确结果；三是代码基座在预训练阶段见过大量结构化代码，对"类 + 参数"的模式有先验。

第二份增益最容易被忽略，但它可能是最大的一块。如果你用同样的严格字符串匹配去评估代码风格输出，优势会立刻缩水一大截。所以我在复现时坚持用同一个解析器去跑两种风格的输出，只比较"最终结构化结果"的指标，这样得出的差距才可信。结果是：在解析口径对齐之后，代码风格仍然领先，但领先幅度比论文表格里看到的要小一些，剩下的那部分才是模型本身带来的真实增益。

4.2 基座选择：代码预训练的红利与代价

论文里小参数量的代码基座微调之后，效果能追上参数量大得多的通用模型，这一点在当时的语境下是比较有冲击力的。背后的理由不难理解：代码基座在海量代码语料上做过预训练，它对缩进、括号配对、函数调用语法的建模能力天然更强，而这些恰恰是输出稳定性的来源。相比之下，通用模型需要靠 prompt 和微调去"学"这套格式，学得慢而且不稳。

但代价值得说清楚。代码基座在纯自然语言理解任务上通常会比同规模的通用基座弱一点，如果你的流水线里抽取只是其中一环，前面还有阅读理解、指代消解之类的子任务，全链路都换成代码基座未必划算。我的做法是混合部署：抽取环节用代码基座，前置的自然语言处理环节保留通用基座，两边通过结构化接口对接，各取所长。

另外要注意一个坑：微调代码基座时，如果训练数据里的 prompt 和推理时的 prompt 格式不一致（比如示例数量不同、schema 块的位置不同），效果会掉得很厉害。我自己遇到过训练时用了两个示例、推理时图省事放了一个示例，结果 F1 掉了 6 个点，排查了半天才发现是格式对齐问题。

4.3 这些结论在真实业务里的适用边界

论文的实验场景都是 schema 相对固定的公开基准，关系类型是闭集，句子也相对规范。搬到真实业务里，有几个边界必须提前想清楚。

第一个边界是 schema 的动态性。业务上的关系类型是会变的，今天加两个、明天删一个，如果你的 prompt 是硬编码 schema 的，每次变更都要重新验证一遍模型输出，成本不低。缓解办法是把 schema 抽成配置，用热加载的方式注入 prompt，同时准备好新关系的示例，至少保证模型看到新关系时知道格式。

第二个边界是跨句和指代。论文处理的基本是单句内的关系，遇到跨句指代、代词消解，代码风格本身帮不上忙，还是得靠前置的文本处理或者多轮上下文拼接。我做过一个跨句实验，把前后三句拼成一段输入，召回确实涨了，但模型开始把相邻句子的实体错误关联，精度掉得更多，最后还得靠规则后过滤。

第三个边界是语言。论文的实验是英文场景，中文场景下你几乎一定要重做自举数据，因为代码基座的中文实体会话能力弱于英文，容易在实体复制上出错。我的做法是中文任务全部走自举，而且把过滤线收得更紧，实体必须逐字匹配原文才算通过。

5. 常见问题与排查技巧实录

这一节是我踩过的坑的汇总，按现象、原因、处理方式组织，你可以当成排查手册用。

5.1 解析失败与字段缺失的高频原因

最常见的失败是"少一个右括号"，典型表现是解析器报SyntaxError: unexpected EOF。原因多半是max_new_tokens设小了，生成到一半被截断。解决办法有两个：直接调大生成长度，或者在解析前做一次括号补齐，把所有未闭合的左括号按栈的顺序补上右括号。后者有点危险，可能补出一个语义错误的三元组，我更倾向于调大长度。

第二种是"字段缺失"，模型只生成了subject和object，忘了relation。这种情况在关系数量多、示例覆盖不足时特别常见。我的处理是在解析阶段直接把缺字段的样本丢弃，同时在 prompt 里把必填字段在类定义中加粗强调，并在示例后加一行注释写明三个参数都是必填。加了这行之后，缺字段的比例从 4% 降到了 0.6%。

第三种是"多余字段"，模型自作主张加了confidence或者evidence之类的参数。这个不致命，解析时按白名单过滤掉就行，不需要重新生成。

5.2 幻觉实体、关系名漂移与重复生成

幻觉实体是生成式抽取的老问题，模型会造出原文里根本不存在的实体。代码风格对这个问题有一点抑制作用（因为示例里实体的位置很固定），但抑制不住根本。我的做法是在解析后加一道原文校验：实体字符串必须在输入句子里出现过（允许大小写和空白差异），不满足的直接丢弃。这道校验能干掉大部分幻觉，代价是牺牲了少量"实体被合理改写"的情况，但在精确率优先的场景下是划算的。

关系名漂移指的是模型输出了 schema 之外的关系，或者把"出生于"写成"出生地是"。这个只能用白名单硬过滤，同时可以考虑加一层同义映射表，把几个高频的漂移写法映射回标准名。我没有做模糊匹配，因为一旦允许模糊匹配，边界会越来越松，最后等于没有 schema。

重复生成指的是同一句话里同一条三元组被生成多次。原因是解码时的重复惩罚不足，或者输入句子本身有重复结构。处理很简单，解析之后按归一化结果做集合去重，成本几乎为零。

5.3 常见问题速查表

5.4 几条不太会在论文里写的实操心得

第一条，先把解析器打磨好，再考虑换模型。我见过太多人一上来就换更大的模型，结果指标只涨了一点点，因为它换掉的是模型的输出质量，而链路损耗一点没动。你把解析成功率从 75% 提到 95%，收益可能比从 7B 换到 13B 还大。

第二条，保留原始输出，永远不要只存解析后的结果。badcase 分析的时候，你需要看到模型到底写了什么，是格式问题还是语义问题。我在数据库里单独留了一个字段存 raw text，后来排查问题全靠它。

第三条，schema 变更要做回归集。每次加关系或者改关系名，拿固定的两百条样本跑一遍，看老关系的召回有没有掉。实测下来，加新关系时老关系的召回平均会掉 1 到 2 个点，因为 prompt 变长了，模型的注意力被稀释。这个损失是正常的，但你得知道它存在，而不是等线上报警才发现。

第四条，别指望模型自己学会"输出空"。没有关系的句子，模型倾向于硬凑一条出来。负样本的比例和 prompt 里的明确指令（"如果没有关系，只输出[]"）都得有，缺一个都不行。

提示：如果你的下游系统对精度要求极高，可以在解析之后再加一层置信度过滤，比如要求模型在生成时同时输出一个 0 到 1 的分数，低于阈值的结果直接丢给人工复核。这个改动不大，但对线上质量的影响很直接。

我个人在实际项目里用这套代码式抽取跑了大半年，最大的感受是它把"格式工程"和"语义工程"这两件事解耦了。格式的事情交给类定义、AST 解析和白名单校验，这三样都很稳定，不会因为换个模型就失效；语义的事情才交给模型，模型好一点差一点，影响的是召回而不是整条链路能不能跑通。这种分层带来的可维护性，比指标上多那两个点值钱得多。后来我又把同一套模板套到了事件抽取上，只改了类定义和槽位名，解析器和校验逻辑一行没动，那半天的工作量让我对"代码作为中间表示"这个思路彻底服气了。