“知识图谱构建”这个词听着很重，落到代码上其实就一句话：给一段文本，让它吐出若干结构化事实。过去几年这条线上的做法基本分两派——一派是序列标注，把实体和关系的边界标出来再拼；另一派是当成翻译任务，输入句子、输出“(头实体, 关系, 尾实体)”这样的扁平字符串。两派都能跑通，但都有各自的别扭。第一次看到用代码语言模型做生成式KGC的思路时，我其实是不信的：生成一个Python字典和生成一句自然语言，差别真的大到值得单独设计一套架构？把这篇CodeKGC的论文啃完、又自己按它的思路跑了两轮之后，我的结论变了——差别比我预想的大，而且大在非常具体的地方，不是那种“换个backbone涨零点几个点”的差别。

这篇笔记面向两类人：一是正在做关系抽取、事件抽取，想把生成式方案接进现有流水线的工程师;二是读过论文但对其中的格式设计、适配层、评测口径仍有疑问的同学。我会按“为什么这么设计—具体怎么拼—实测会出什么问题”的顺序拆，凡是论文没写透、我靠常见实践补出来的部分，都会标明是补充推断，不冒充原文。

1. 把三元组写成Python类，这个思路到底在解决什么

1.1 序列标注与纯文本生成在KGC上的两处硬伤

先说序列标注的老问题。它把KGC拆成“识别span + 分类关系”两步，天然要求输出是离散的、可对齐的。好处是速度快、可解释，坏处是遇到重叠实体、嵌套关系、一个句子对应多条事实时就非常难受——你得设计一套复杂的标注体系（比如指针网络、多标签BIO），每加一种新结构就要改一次标签空间，改完还得重新标数据。这套东西维护成本极高，做到后面往往是“标注体系比模型还复杂”。

纯文本生成（也就是把输出序列化成自然语言或扁平三元组串）解决了结构灵活性的问题，但又引入了新麻烦：模型对“格式”的把握是软的。你让它输出(北京, 首都, 中国)，它可能给你(北京, 中国, 首都)，也可能漏掉括号，或者在多事实场景下把两条事实糊在一起。根本原因是自然语言预训练语料里本来就没有强制的结构约束，模型学到的是“像人说话”，不是“像程序输出”。

1.2 代码预训练语料里自带的“结构感”

CodeKGC的核心洞察就落在这里：代码语料天然是强结构、强语法约束的。Python里一个类定义长这样：

class Triple: subject: str predicate: str object: str

它有明确的嵌套层次、有配对的括号、有字段名与值的绑定关系。在代码语料上预训练过的模型（比如CodeT5这类），在生成这类结构时对“左括号必须有右括号”“字段名后面必须跟冒号”这类约束的敏感度，明显高于纯自然语言模型。这不是玄学，是预训练分布决定的——你在GitHub级别的语料上见过几千万次合法的Python语法结构，模型对“不合语法”的序列会给出更低的概率。

于是论文的思路就很自然了：既然KGC的输出本质是结构化的，那就别用自然语言格式输出，改用代码格式输出，并且用代码语言模型来生成。同时，输入的文本理解部分仍然交给自然语言PLM（它更懂语义），两边用一个适配层接起来。这套“理解归理解、生成归生成”的分工，是整篇论文的骨架。

1.3 这套设计覆盖的四类KGC任务

论文没有只做关系抽取，而是把生成式KGC的几个主流子任务都纳入了同一框架，这在我看来是它比同类工作更实用的地方。具体包括：常规关系抽取（句子级，一条或多条事实）、事件抽取（事件类型 + 论元角色 + 论元span）、以及带schema约束的抽取。它们共用同一套“输入文本 + schema提示 → 输出代码结构”的范式，区别只在schema的定义不同。

这个统一性带来的直接好处是工程上只需要维护一套推理管线。你想想实际项目里，关系抽取和事件抽取往往是两套模型、两套后处理、两套评测脚本，一旦要加新的事件类型，就得动一遍全链路。而在这套范式下，加新类型基本等于改一段schema提示文本——这个诱惑对做落地的人是非常大的。

2. CodeKGC的骨架：理解与生成为什么必须拆开

2.1 双编码器加适配层的拼装逻辑

论文的模型结构可以概括为：一个自然语言PLM负责编码输入句子，一个代码LLM负责解码输出结构，中间插入适配模块做表示对齐。为什么不能干脆用一个代码模型端到端搞定？因为代码模型的自然语言理解能力通常弱于同规模的纯文本模型——它的预训练语料里代码占比高，语义理解的“厚度”不够。反过来，纯文本模型生成代码结构的语法稳定性又不如代码模型。两边各取所长，是这个架构最朴素的动机。

适配层的存在解决的是表示空间错位问题。PLM输出的隐状态维度和分布，跟代码解码器期望的输入不在一个空间里，直接接上去会掉点。常见的做法是用若干层可训练的投影/适配模块做转换，训练时冻结两侧主干、只训适配层和少量参数。这样做的好处不仅是省显存，更重要的是避免小数据集上把预训练能力训崩——KGC的标注数据规模通常不大，全参数微调很容易过拟合。

注意：适配层的具体结构在论文里有描述，但不同复现实现差异很大。如果你只是想把思路用起来，不必严格复刻，一个两层MLP加LayerNorm就能跑出接近的效果，我试过，差距在可接受范围内。

2.2 输入侧的schema提示怎么写才不浪费token

输入模板的设计比想象中重要。论文的做法是把“本次要抽取哪些类型”作为schema提示拼在文本前面。一个典型的输入大概是这样：

Schema: [per:title, per:employee_of, org:country_of_headquarters] Text: 张三于2019年加入某公司担任技术总监。

这里有个很实际的取舍：schema要不要全量拼进去。全量拼的好处是模型知道完整的输出空间，坏处是token消耗大、长尾类型会稀释注意力。我的做法是分层——高频类型固定拼，低频类型按召回候选动态拼。这个改动对线上延迟有帮助，对精度影响很小。

另一个细节是schema里类型的书写顺序。代码模型对“字段出现的先后”是有记忆的，如果你训练时字段按A、B、C排，推理时按C、B、A排，输出稳定性会下降。这个现象在论文里没展开，但我在复现时踩到了，后面第5节会细说。

2.3 输出侧用类定义而不是裸JSON的理由

这是整篇论文里我个人最认可的一个设计选择。输出格式有几种写法：

论文选择的是中间那种：在输出里带上类定义，让模型在生成过程中反复“看到”字段名和类型。这相当于把schema从输入侧复制了一份到输出侧，形成双重约束。代价是序列变长，收益是字段遗漏率显著下降。论文里做过格式的消融对比，代码格式相对自然语言格式的提升是稳定的，具体数值建议直接看原文表格，我这里不给二手数字。

3. 三种输出格式的实测体感与错误模式

3.1 裸JSON在多样本场景下最先崩

我第一版用的是最省事的裸JSON，理由是解析方便。跑下来发现一个问题：单条事实的句子表现很好，一旦一句话里有多条事实，模型经常把两条事实的字段交叉赋值，或者少写一个大括号。深究原因，JSON的花括号嵌套层次在长序列里对模型来说不够“显眼”，而代码里的类实例化语句因为每行一个对象、行与行之间有换行分隔，天然形成了边界。

所以我后来的做法是：不用数组包多个对象，而是每个对象独立一行、独立实例化。这样每行的结构完全一致，模型只需要学好“一行长什么样”，多行就是重复。这个改动让我在多事实样本上的解析失败率明显下降。

3.2 字段顺序和换行不是小事

接着说一个容易被忽略的点：字段顺序。代码模型对字段顺序的敏感性，来自于训练时类定义的固定写法。如果你在微调数据里字段顺序是随机的，模型推理时就会摇摆;如果你统一成固定顺序，模型几乎不会写错。所以数据构造阶段一定要做一次强制规范化——把所有的subject、predicate、object按固定顺序重排，别指望模型自己学。

换行同理。有些实现为了省token把类实例写成一行，结果模型在长输出时特别容易漏逗号。保留换行看似浪费token，实际上是给模型一个“自然的分隔符”，性价比很高。

3.3 生成式输出绕不开的四类错误

跑生成式KGC，你迟早会遇到这四类错误，提前知道能省很多时间：

• 语法错误：括号不配对、引号缺失、逗号漏写。这类错误在代码格式下反而比JSON少，但仍然存在。
• 字段缺失：主体、关系、客体三选二。常见于长文本末尾，本质是解码长度或注意力衰减。
• 实体幻觉：生成的原句中根本不存在的实体。这是生成式方法的通病，靠后处理校验能挡掉大部分——做一次“生成实体是否出现在原文”的子串匹配，就能过滤一大半。
• 类型越界：生成了schema里没有的关系类型。这类错误通常说明schema提示没拼全，或者训练数据里出现了schema外的标签。

提示：实体幻觉的校验一定要做，而且要用规范化后的字符串做匹配（去空格、统一全半角），否则会误杀。这一步我放在解码后的第一道后处理，成本几乎为零，收益很大。

4. 指标怎么读：BLEU高不代表图谱对

4.1 四个生成指标各自在测什么

论文沿用了生成式信息抽取的常规评测口径：BLEU、METEOR、ROUGE、BERTScore。这四个指标的侧重点完全不同，混着看容易误判：

实际选型时我的建议是：BLEU和ROUGE看结构稳定性，BERTScore看语义召回，但最终决策一定要落到“精确匹配的F1”上。生成式方法的论文常用BLEU做主线，是因为它和人类判断有一定相关性，但落到业务里，你需要的是“这条三元组对不对”，那是0/1判断，不是n-gram重叠。

4.2 数据集差异带来的口径漂移

论文覆盖的几个数据集差异其实挺大。WebNLG这类数据的特点是单句事实密度高、关系类型相对规整;NYT那类来自新闻语料，句子长、实体多、噪声大;事件抽取的数据集则是论元角色多、一个事件对应一组论元，输出长度显著更长。这意味着同一套超参在不同数据集上表现差异会很明显。

我复现时的经验是：短输出任务（单三元组关系抽取）解码长度给128足够;事件抽取这类多论元任务，给到512甚至更长才保险。统一按最长任务配置，会让短任务的推理时间凭空翻倍，得不偿失。按任务分别配置解码上限，是个很划算的优化。

4.3 训练配置与复现要点

论文的训练配置属于这类工作的常规区间：适配层用较小的学习率，batch size控制在显存允许的范围内，训练若干轮后按验证集选点。我把它落成实际配置时做了几处调整：

config = { "max_input_length": 256, "max_output_length": 512, "learning_rate": 1e-4, "warmup_ratio": 0.1, "batch_size": 8, "grad_accum": 4, "epochs": 20, "freeze_backbone": True, }

冻结主干这件事要强调一下。如果你的数据只有几千条，全参数微调几乎必然过拟合，验证集指标会在前几轮冲高然后一路下滑。冻结主干、只训适配层，收敛慢一点但更稳，最终结果通常也更好。这个结论在论文的实验设置里有体现，我在自己的数据上也验证过。

5. 复现路上踩到的坑和排查顺序

5.1 序列化不一致：最隐蔽也最致命

这是我踩得最深的一个坑。训练数据是由脚本从标注文件转成代码格式的，推理时我又写了一个脚本转schema提示。两个脚本对空值、对多值字段、对特殊字符的处理不一致，导致训练和推理看到的格式有细微差异。表现是：训练loss降得很好，验证集指标也不错，但上线后错得离谱。

排查方法很土但有效——把训练集里的一条样本和推理时实际喂进去的输入，逐字符diff一遍。我那次 diff 出来一个全角逗号，改掉之后效果立刻回来了。所以现在我养成习惯：训练/推理共用同一个模板函数，只允许通过参数控制差异，绝不允许复制粘贴出两份。

5.2 解码截断：静默失败的重灾区

生成式方法有个非常讨厌的特性：超长输出会被静默截断，截断的部分没有任何报错，你只会在评测时发现“怎么召回这么低”。事件抽取任务尤其容易中招，因为论元一多，输出长度就爆了。

判断方法很简单：统计一下训练集和验证集里目标序列长度的分布，看95分位是多少，再对比你设的max_output_length。如果分位数贴着上限，那就一定要调大。另外可以在解码时记录每个样本的输出长度，出现“顶格”的样本单独拎出来看，往往就是问题所在。

5.3 类别不平衡与负样本构造

KGC的数据天然不平衡：高频关系占绝大多数，长尾关系样本极少。生成式方法对此的敏感度不如分类方法那么直接，但也存在——模型倾向于生成高频类型，长尾类型的召回明显偏低。

我的处理是分层采样加类型提示。分层采样保证每个batch里长尾类型有最低出现比例;类型提示是在schema里把本次可能出现的类型按候选顺序排，把可能性高的放前面。这两个操作加起来，长尾召回有肉眼可见的改善。

5.4 评测脚本对空格和顺序过分敏感

最后一个坑，也是很多人忽略的：官方评测脚本往往对格式极度敏感。多余的空格、字段顺序不同、实体列表顺序不同，都可能被判为错误。而生成式模型的输出顺序本来就不稳定。我见过有人指标低了好几个点，最后发现只是评测前没做规范化。

我的做法是评测前统一走一遍规范化流程：去多余空白、统一标点、对多元组按固定键排序、统一大小写策略。这一步做完再比对，指标才是可信的。

6. 这套方法在工程上该用在哪，不该用在哪

6.1 适用边界：什么时候它真的划算

CodeKGC这套范式的最大价值在于“结构复杂且会变”的场景。如果你的抽取任务里，输出结构是固定三元组、类型也就那么十几种、数据量还很大，那老实说，用传统的序列标注或者分类式方案更划算——推理快、可控性强、出错可定位。生成式方法在这种场景下的优势体现不出来，反而会带来解析失败、幻觉、延迟不可控这些新问题。

但当你的输出结构本身就在演进——今天要三元组，明天要加事件论元，后天要加属性限定——那生成式加代码格式的方案优势就非常明显。改一个schema模板就能支持新任务，不需要重标数据、不需要改模型结构。这种“结构可扩展性”是它真正的杀手锏。

6.2 接到业务系统上要改的三处

第一处是后处理。论文里的评测是离线的，输出合法就算对。线上不行，必须有语法校验、实体存在性校验、schema合法性校验三道关。三道关都过的才进图谱，过不了的进人工复核队列。

第二处是置信度。生成式模型给出的是序列概率，不是分类置信度。直接拿平均logprob当置信度用，校准效果一般。我的做法是结合三个信号：序列平均logprob、实体是否在原文出现、输出长度是否接近上限，做一个简单的规则打分，比单用logprob靠谱。

第三处是缓存。schema提示和输入文本的组合是高度重复的，尤其在批量处理新闻流的时候。把“文本+schema”的哈希做缓存，命中率不低，能显著降低推理成本。

最后分享一个我在实际使用中的体会：这类生成式结构化抽取的方法，最容易被低估的不是模型本身，而是数据构造环节。我前后花了大概六成时间在格式规范化、模板统一、后处理校验上，真正调模型的时间反而少。如果你准备上手，建议先把“一条样本从原始标注到最终代码串”的完整链路写成一个可复用的函数，再谈训练。链路对了，模型的效果才有意义;链路错了，你调的所有参数都是在拟合噪声。