自动给代码写说明：摘要生成技术实战

可视化演示

交互展示大语言模型对齐评估的核心流程：多维对齐基准测试、红队安全对抗检测与人类反馈强化优化，可视化从评估到改进的闭环。

摘要生成概述

你接到一个整理老饭馆后厨仓库的任务：几十只没有标签的纸箱堆在墙角，有的渗着油渍，有的爬着霉斑，唯一认得这些箱子的大师傅已经退休。你只能一只只打开、辨认、再手写标签贴上去。如果此时有位助手能扫一眼箱子内部，直接脱口而出“秘制豆瓣酱，需冷藏保存”，你会不会激动得想给他涨工资？这位助手，就是代码摘要生成——它天生擅长让“沉默的代码”开口介绍自己。

在软件世界里，代码就是那些沉默的纸箱，函数是箱子，docstring 是标签。代码摘要生成（Code Summarization）指让程序自动阅读一段源代码，输出一句流畅的自然语言描述，说清楚“这段代码做了什么、怎么用、有哪些坑”。它的价值在于：接手历史项目时不再依赖“大师傅”口述，AI 自动把缺失的文档补回来；后续任何人翻代码都像看标签一样一目了然，文档维护成本被大幅压缩。

从数学视角看，这是一个条件语言模型问题。设 C 是输入的代码，S 是所有可能的描述句子，任务就是在所有句子中找出最合理的那句——也就是条件概率最高的 S。式中的竖线表示“在给定 C 的条件下”。

给纸箱贴标签看似简单，实际门道很深：太粗的标签等于没贴，太细的标签浪费笔墨，更别说有些箱子自带“伪装色”。正因如此，这项技术经历了一条清晰演进路线。接下来，我们就从最古老的土办法讲起，看看一代代“仓库管理员”是怎么把这件事越做越好的。

基于规则方法

最早的贴标签办法很朴素：看纸箱的长相。四四方方的大纸箱八成装干货，长条形的盒子多半是调味料瓶——这个规律百试百灵，于是有人把它写成一本《纸箱辨认手册》。对应到代码上，就是一系列启发式规则：看到动词 get 就写“获取”，看到函数名带 byId 就补上“根据 ID”，再按“动词 + 对象 + 参数”的模板拼成句子。

这类方法称为基于规则的方法，本质是两步走。第一步做结构分析，把代码拆成可识别的部件：主要做了什么动作（动词）、作用在什么对象上（名词）、在什么条件下（参数）；第二步做模板匹配，把部件填入预设的句子模板。规则库的构建依赖领域专家经验，用正则表达式和抽象语法树就能实现，成本极低，结果确定，这也是它至今仍被用作兜底方案的原因。

形式化地看，规则方法是一个复合函数：

其中 $\rho$ 把代码抽成结构化特征，$\mu$ 把特征映射到模板。

规则方法像一本装订考究的《纸箱辨认手册》，翻得快、零成本，但只认手册里画过的箱子。一旦遇到“细长箱子装干货”这种反常识的存在，它就果断翻车。于是下一代管理员开始思考：能不能不背手册，直接翻翻仓库角落那本旧台账，看看老前辈是怎么写标签的？

基于检索方法

仓库角落搁着一本泛黄的台账，记录着过去每只箱子的内容和标签。面对新箱子，你不必开箱，只需翻台账找一只“看起来最像”的箱子，把它的标签抄过来稍加改动——这就是基于检索的方法。它不追求从零造句，而是在已有“历史答案”中找参照。

检索方法的核心是相似代码检索。首先把代码表示成向量——常见做法是按 token 频次构建词袋向量，每个维度对应一个词条的权重；然后计算当前代码与库中代码的接近程度，选出最相近的几条，把它们的摘要直接复用，必要时将多段摘要做邻接拼接后稍作修剪。它继承了“以史为鉴”的优点：在垂直领域，检索结果可解释、可信度高，而且完全不需要训练模型。

相似度的计算最常用余弦公式：

检索法本质是“抄作业”，仓库越大、台账越全，命中率越高；可要是台账里根本没出现过同类箱子，或者老前辈当初就把标签写错了，它只能将错就错。要想真正“无中生有”地造句，还得靠能自动统计语言规律的办法。

统计语言模型

如果既不想背手册，也没有旧台账可翻，还有一个更“笨”但更灵活的思路：把仓库里所有旧标签摊开，统计字词规律。比如一百张酱料标签里有八十五张出现“冷藏保存”，那么当一句话出现了“酱料”，模型就有把握补上“冷藏保存”。这就是统计语言模型的思想。

最经典的实现是 n-gram 模型。它假设当前词只与前 n-1 个词有关，用大规模语料中的词频概率估计条件概率。生成摘要时，模型几乎不看代码特征，单纯按概率从词表里挑选下一个词，逐个拼出整句——这就是序列生成。虽然“懂”得很浅，但它第一次让机器学会了“概率化造句”，而不是死记硬背。

以 bigram（n=2）为例，条件概率的估计公式为：

统计学徒的世界里只有词和频率，没有语法更没有语义，它造得出“冷藏、酱料、保存”这样断断续续的高频词串，却组织不出通顺的长句。要让标签写得像真人一样自然，只能请一位见过无数仓库的老师傅登场了。

预训练模型

终于，老板重金请来一位见过几百万间厨房仓库的老管家。他不翻手册、不看账本，只消扫一眼箱子里的东西就能脱口而出：“此为樟茶鸭腌料，含花椒与茶叶，需密封避光保存。”这位老管家，就是基于 Transformer 的预训练模型。

预训练模型（如 GPT、T5 系列）在海量“代码 + 自然语言”对上做自监督学习，学会了代码与语言之间的深层映射。针对代码场景的 CodeT5 采用编码器-解码器架构：编码器把代码的理解编码成语义向量，这是“代码理解”；解码器逐词写出描述，这是“代码生成”。相比 n-gram，它能捕捉长距离依赖，还能感知变量名、函数调用图的上下文，真正做到了理解代码意图。

生成阶段，模型按自回归方式逐词决策，整句概率是每个词条件概率的连乘：

老管家虽见多识广，也难免偶尔脱口而出看似漂亮、实则对不上号的话——把“料酒”说成“酱油”。标签写得流畅不等于内容准确，所以验收环节必不可少：机器粗筛加人工校验，双管齐下才能真正放心。

质量评估

验收标签时，最省事的办法是拿一份“标准答案”来比对字句重合度。假设标准标签是“开盖后冷藏保存”，助理写的却是“放冰箱，盖好”，虽然意思沾边，字面却对不上——这种按“字句重合”打分的方法，就是自动评估指标 BLEU（Bilingual Evaluation Understudy）。

BLEU 最初用于机器翻译，后来成为文本生成领域的通用指标。它统计候选摘要与参考摘要的 n-gram 精确率：1-gram 看单个词是否命中，2-gram 看相邻词对是否命中，3-gram、4-gram 依次递进，越高的阶越能反映句子的流畅度和局部语序。把各阶分数做几何平均，再用简短惩罚因子 BP 压制“只写几个关键词糊弄”的偷懒行为。

BLEU 的完整计算公式为：

然而，字句重合终究不等于语义一致：助理完全可能写出与标准答案毫无重合、但意思更准确的标签。所以 BLEU 只适合当“粗筛漏斗”，真正拍板前还要人工开箱验货，确认标签与实物相符——这正是文档治理中最重要的一环：人机协同校验。

实战应用

故事来到最终章。你要把整间仓库几百只箱子全部贴上合格标签，还要立下规矩：以后新入库的箱子必须“先贴标签再上架”。对应到实际工程，就是批量补注释与文档治理——一次性的历史债清理和长期性的流程约束。

实践中，完整的落地路径分四步。第一步扫描代码库，找出所有缺少 docstring 的公共函数；第二步调用预训练模型批量生成候选摘要；第三步用 BLEU 做机器粗筛，对核心模块再走人工抽检；最后把通过校验的摘要合并回代码库，并接入 CI 流水线——以后任何新增代码若缺少注释，流水线会自动拦截并提醒补写。这就是工具链集成的完整闭环，让文档债不再“复利增长”。

推进这类治理项目时，团队常用一个覆盖度指标来衡量效果：

从一只只开箱手写标签，到 AI 批量起草、机器粗筛、人工抽验，再到流水线自动维护——代码摘要生成的完整路径，本质上就是让“沉默的代码”开口介绍自己。愿你接手任何一座“旧仓库”时，都能用这套手艺把它打理得井井有条，让后来者翻开代码就像翻看一本贴满标签的相册。

AI 应用场景

Python 演示

import mathimport refrom collections import Counter  def split_words(name):    # 把 snake_case / camelCase 拆成单词列表    s = re.sub(r'([a-z0-9])([A-Z])', r'\1_\2', name)    return [w for w in re.split(r'[_\W]+', s.lower()) if w]  VERB_MAP = {    'get': '获取', 'fetch': '拉取', 'calc': '计算',    'compute': '计算', 'sum': '汇总', 'update': '更新',    'set': '设置', 'create': '创建', 'add': '新增',    'delete': '删除', 'remove': '移除', 'find': '查找'}  def generate_summary(func_name, params, has_return):    # 规则方法：拆函数名 -> 动词映射 -> 模板拼接    words = split_words(func_name)    verb = words[0] if words[0] in VERB_MAP else '处理'    obj = '_'.join(words[1:]) if len(words) > 1 else '数据'    summary = VERB_MAP.get(verb, verb) + obj    if params:        summary += '，参数：' + ', '.join(params)    if has_return:        summary += '，返回结果'    return summary  def ngrams(tokens, n):    # 生成 n-gram 列表，如 2-gram: [('a','b'), ('b','c')]    return [tuple(tokens[i:i + n]) for i in range(len(tokens) - n + 1)]  def bleu(candidate, reference, max_n=4):    # BLEU 评估：n-gram 精确率 + 简短惩罚    c_len, r_len = len(candidate), len(reference)    if c_len == 0 or r_len == 0:        return 0.0    precisions = []    for n in range(1, max_n + 1):        cand_ng = Counter(ngrams(candidate, n))        ref_ng = Counter(ngrams(reference, n))        matched = sum((cand_ng & ref_ng).values())        total = max(sum(cand_ng.values()), 1)        precisions.append(matched / total)    if min(precisions) == 0:        return 0.0    bp = 1.0 if c_len > r_len else math.exp(1 - r_len / c_len)    return bp * math.exp(sum(math.log(p) for p in precisions) / max_n)  def main():    funcs = [        ('calc_total_price', ['items', 'tax_rate'], True),        ('fetch_user_by_id', ['user_id'], True),        ('update_stock', ['product_id', 'delta'], False)    ]    for fname, params, has_ret in funcs:        summary = generate_summary(fname, params, has_ret)        print(f'{fname}({", ".join(params)}) -> {summary}')     # 用 BLEU 对比候选摘要与参考摘要    cand = ['calc', 'total', 'price', 'from', 'items', 'tax']    ref = ['calculate', 'total', 'price', 'from', 'a', 'list']    print('BLEU =', round(bleu(cand, ref), 4))  if __name__ == '__main__':    main()

1. split_words(name)把函数名拆成单词列表，是规则方法“结构分析”的第一步。
2. VERB_MAP = {...}动词映射表，相当于规则方法里的《纸箱辨认手册》。
3. summary = VERB_MAP.get(verb, verb) + obj模板填充的核心逻辑：动词 + 对象拼成一句话。
4. def ngrams(tokens, n)生成任意阶 n-gram，为 BLEU 计算提供基础单元。
5. matched = sum((cand_ng & ref_ng).values())统计候选与参考被命中的 n-gram 总数，对应 BLEU 公式中的分子。
6. bp = 1.0 if c_len > r_len else math.exp(1 - r_len / c_len)实现简短惩罚 BP，防止“只写关键词糊弄”。
7. for fname, params, has_ret in funcs:批量处理入口，对应实战中“扫描代码库逐个函数生成摘要”。

常见误区

面试题