企业官网建设流程全解析

1. 为什么要把英译中模型从原生框架搬到 ONNX

做过翻译模型部署的人大概都有过这种体验：在训练脚本里跑得好好的模型，一旦要上线服务，推理速度就成了瓶颈。尤其是英译中这种序列到序列的任务，自回归解码意味着每生成一个 token 都要跑一次前向计算，原生框架的推理效率往往撑不住线上并发。我最初也是直接用原生框架搭服务，单条请求延迟还能接受，QPS 一上来就崩了。

ONNX 在这类场景下的价值就很明显了。它把模型的计算图固化成一种中间表示，推理时不再需要原生框架那套动态图机制，配合 ONNX Runtime 还能吃到算子融合、内存复用、多线程调度这些底层优化。实测下来，同一个英译中模型迁到 ONNX 之后，单条推理延迟能压到原来的六成左右，批量推理的吞吐提升更明显。这不是玄学，是计算图静态化之后运行时少做了很多重复工作。

不过迁移这件事没有想象中那么"一键完成"。英译中模型通常是 Encoder-Decoder 结构，导出的时候要处理动态输入长度、KV Cache、解码循环这些细节，稍不注意就会导出失败或者导出后结果不对。我前后踩了大概两轮坑才把整条链路跑通，这篇就把完整过程拆开讲清楚，包括每一步为什么这么做、参数怎么定、遇到报错怎么排查。

适合读这篇的人：手上有 HuggingFace 上的英译中模型、想把它部署成低延迟服务的开发者；或者你只是想搞清楚 ONNX 导出 Seq2Seq 模型到底有哪些坑。不需要你精通 ONNX，但至少要能跑通基础的 Python 和 transformers 代码。

2. 动手之前先把模型结构和导出边界摸清楚

2.1 英译中模型的典型结构决定了导出难点

HuggingFace 上的英译中模型，绝大多数是标准的 Encoder-Decoder 架构，比如基于 Transformer 的翻译模型。Encoder 负责把英文源句编码成隐状态序列，Decoder 再一步步自回归地生成中文 token。这个结构本身不复杂，但导出 ONNX 的时候有两个地方特别容易出问题。

第一个是动态序列长度。训练时输入句子长度是变化的，导出 ONNX 如果写死了序列长度，那上线后遇到更长的句子就直接报错。所以导出时必须把 batch size 和 sequence length 都声明成动态维度。第二个是自回归解码。原生框架里 Decoder 是循环调用的，每次把上一步的输出拼回输入。ONNX 是静态图，没有原生的循环语义，要么把整个解码循环展开成固定步数，要么用带 past_key_values 的增量解码方式。前者对长文本不友好，后者才是正路。

2.2 先确认模型能不能干净地导出

不是所有 HuggingFace 模型都能顺利导出 ONNX。有些模型用了自定义算子，或者 forward 函数里有 Python 控制流，这些在导出时都会卡住。我的建议是动手前先做一次"探针式导出"：拿一个极小的输入，用torch.onnx.export跑一遍，看能不能过。如果这一步就报错，后面所有优化都是空谈。

具体操作上，先加载模型和 tokenizer，构造一个input_ids和attention_mask，然后调导出接口。这一步不用管输出对不对，只看能不能生成 onnx 文件。能生成，说明模型结构基本兼容；报错了，就得去看是哪个算子不支持，或者哪段逻辑需要改写。

提示：探针导出时把opset_version设成 14 或更高。低版本 opset 对 Transformer 里的一些算子支持不全，容易误报"不支持"，白白浪费时间。

2.3 环境版本是隐形杀手

我第一轮踩的最大的坑其实不在模型，而在版本。transformers、torch、onnx、onnxruntime这四个库的版本组合非常敏感。比如某个版本的 transformers 在导出时默认走了一条新的 attention 实现路径，导出的图里带了一些 onnxruntime 不认的算子；又比如 torch 2.x 之后导出接口的参数语义有调整，老教程里的写法直接失效。

我最后稳定跑通的组合是：torch 2.1 以上、transformers 4.35 以上、onnx 1.15、onnxruntime 1.17。这个组合不是唯一解，但实测兼容性比较稳。如果你用的是别的版本，遇到奇怪的报错，第一反应应该是去查版本兼容矩阵，而不是死磕代码。

3. 导出 ONNX 的完整操作链路

3.1 加载模型与构造 dummy 输入

先把模型和 tokenizer 拉起来。这里有个细节：导出时模型要切到eval()模式，并且用torch.no_grad()包住，否则导出图里会混进 dropout 和梯度相关的节点，既增大模型体积又可能引入不确定性。

import torch from transformers import AutoTokenizer, AutoModelForSeq2SeqLM model_name = "your-en-zh-model" tokenizer = AutoTokenizer.from_pretrained(model_name) model = AutoModelForSeq2SeqLM.from_pretrained(model_name) model.eval() dummy_text = "This is a test sentence for export." inputs = tokenizer(dummy_text, return_tensors="pt") input_ids = inputs["input_ids"] attention_mask = inputs["attention_mask"]

dummy 输入的作用是给导出器一个"形状模板"。因为我们要用动态维度，所以这个模板的具体长度不重要，重要的是它能让导出器把计算图走通一遍。

3.2 用动态轴声明可变维度

导出时最关键的一步是dynamic_axes参数。它告诉 ONNX：哪些维度是运行时才确定的。对英译中模型来说，input_ids的第 0 维（batch）和第 1 维（序列长度）都应该是动态的，attention_mask同理，输出的 logits 也要对应声明。

torch.onnx.export( model, (input_ids, attention_mask), "model.onnx", input_names=["input_ids", "attention_mask"], output_names=["logits"], dynamic_axes={ "input_ids": {0: "batch", 1: "src_len"}, "attention_mask": {0: "batch", 1: "src_len"}, "logits": {0: "batch", 1: "tgt_len"}, }, opset_version=14, do_constant_folding=True, )

do_constant_folding=True是个容易被忽略但很有用的选项。它会在导出阶段把能提前算出来的常量节点合并掉，减小图体积，对推理速度也有正面影响。

3.3 导出后先验证数值一致性

导出成功不等于导出正确。我见过导出过程零报错、但推理结果完全乱码的情况。所以导出后第一件事是拿同一组输入，分别用原生模型和 ONNX 模型跑一遍，对比输出。

import onnxruntime as ort import numpy as np sess = ort.InferenceSession("model.onnx") ort_inputs = { "input_ids": input_ids.numpy(), "attention_mask": attention_mask.numpy(), } ort_outputs = sess.run(None, ort_inputs) with torch.no_grad(): pt_outputs = model(input_ids, attention_mask).logits.numpy() diff = np.abs(ort_outputs[0] - pt_outputs).max() print("max diff:", diff)

正常情况下这个 diff 应该在 1e-4 量级以内。如果 diff 很大，说明导出过程中有算子行为不一致，得回去查是哪一层出的问题。这一步是后面所有工作的地基，千万别跳过。

3.4 处理解码循环：从完整模型到增量解码

上面导出的是"单步前向"的模型，也就是给定输入，输出一次 logits。但翻译是自回归的，要循环调用才能生成完整句子。最朴素的做法是在 Python 里写循环，每次把上一步生成的 token 拼到 decoder 输入里，重新跑一遍完整前向。这样能跑通，但效率很低，因为每一步都在重复计算 Encoder 的输出和 Decoder 已生成部分的 KV。

真正高效的做法是导出带past_key_values的增量解码模型。思路是把 Encoder 和 Decoder 拆开导出：Encoder 只跑一次，输出编码结果；Decoder 每次只接收新生成的 token 和上一步的 KV Cache，输出新的 logits 和更新后的 Cache。这样每步计算量大幅下降，长文本生成时优势特别明显。

这个拆分导出稍微复杂一些，需要构造带 past_key_values 的 dummy 输入，并且把 Cache 的维度也声明成动态。我建议先用单步模型把整条链路跑通，确认结果正确之后，再升级到增量解码版本。

4. 迁移过程中最容易翻车的几个点

4.1 动态轴声明不全导致长句报错

这是最高频的坑。很多人只声明了 batch 维是动态的，忘了序列长度也是动态的。结果测试时用短句没问题，一上长句就报 shape mismatch。判断方法很简单：导出后用两个长度差很大的输入各跑一次，如果短的能过、长的报错，基本就是动态轴没声明全。

还有一种隐蔽情况是 KV Cache 相关的维度没声明动态。增量解码模型里，Cache 的序列长度维度会随着生成过程不断增长，如果导出时写死了，跑到一定长度就会崩。这个坑在短文本测试时完全看不出来，必须用长文本压测才能暴露。

4.2 tokenizer 的特殊行为被忽略

英译中模型的 tokenizer 往往有一些特殊设置，比如特定的prefix、eos_token、decoder_start_token_id。导出 ONNX 只导了模型，tokenizer 还是在 Python 侧跑的，这部分逻辑必须和训练时保持一致。我遇到过导出后翻译结果总是缺最后一个字的情况，排查半天发现是解码循环里判断结束的条件写错了，把 eos 的处理逻辑搞混了。

注意：解码循环的终止条件要同时考虑 eos token 和最大长度限制。只判 eos 可能在模型异常时死循环，只判长度又可能生成多余内容。

4.3 精度问题：fp32 还是 fp16

ONNX 支持 fp16 推理，理论上更快、更省显存。但英译中模型对数值精度比较敏感，直接转 fp16 有时会出现翻译质量下降，表现为个别词翻译错误或者语句不通顺。我的经验是：如果追求稳定，先用 fp32 跑通全流程；确认没问题后，再尝试 fp16，并且一定要做质量对比测试，不能只看速度。

转换 fp16 可以用 onnxruntime 提供的工具，也可以用onnxconverter-common里的convert_float_to_float16。转换后记得用一批真实句子跑翻译，人工抽查几十条，确认质量没有明显退化再上线。

4.4 批处理时的 padding 陷阱

线上服务通常要支持批处理，但英译中模型对 padding 很敏感。如果 batch 里句子长度差异大，padding 产生的无效 token 会干扰 attention 计算，导致结果偏差。正确做法是在 tokenizer 阶段就做好 padding，并且把attention_mask正确传给模型。ONNX 模型这边只要保证 mask 输入正确，attention 层会自动忽略 padding 位置。

我实测过一个反例：为了图省事，把 batch 里所有句子 pad 到统一长度但不传 mask，结果短句的翻译质量明显下降。加上 mask 之后问题消失。这个细节在单条推理时看不出来，批处理时才会暴露。

5. 推理服务的性能调优与实测数据

5.1 ONNX Runtime 的会话配置

模型导出只是第一步，推理性能还取决于 ONNX Runtime 的会话配置。几个关键参数：intra_op_num_threads控制单算子内部的并行线程数，inter_op_num_threads控制算子之间的并行度。对于翻译这种以矩阵运算为主的模型，intra_op_num_threads设成物理核心数通常比较合适。

options = ort.SessionOptions() options.intra_op_num_threads = 8 options.inter_op_num_threads = 2 options.graph_optimization_level = ort.GraphOptimizationLevel.ORT_ENABLE_ALL sess = ort.InferenceSession("model.onnx", options, providers=["CPUExecutionProvider"])

graph_optimization_level设成ORT_ENABLE_ALL会启用所有图优化，包括算子融合和常量折叠。这个选项对推理速度有实打实的提升，建议默认打开。

5.2 实测数据对比

我在一台 8 核 CPU 的机器上做了对比测试，模型是中等规模的英译中模型，测试集是 200 条长度在 10 到 40 个词之间的英文句子。

数据上看，ONNX fp32 相比原生框架延迟降了约四成，fp16 再降三成左右，模型体积也几乎减半。批量吞吐的提升更明显，因为 ONNX Runtime 在批处理时的调度效率比原生框架高不少。

5.3 增量解码带来的额外收益

上面这组数据用的是单步模型加 Python 循环解码。后来我升级到增量解码版本，长句的延迟改善非常明显。原因是单步模型每生成一个 token 都要重算整个 Decoder 的 KV，而增量解码只算新 token 那一步。句子越长，差距越大。对于 40 词左右的句子，增量解码版本比单步版本快了将近一倍。

代价是导出和调用逻辑更复杂，需要管理 KV Cache 的传递。如果你的场景以短句为主，单步模型够用；如果长句占比高，增量解码值得投入。

6. 上线前必须做的几项验证

6.1 数值一致性回归测试

导出后和优化后，都要跑一遍数值一致性测试。准备一批覆盖不同长度、不同领域的英文句子，分别用原生模型和 ONNX 模型翻译，对比输出。允许有极小的数值差异，但翻译结果应该完全一致。如果出现个别句子翻译不同，要定位到具体是哪个 token 开始分叉，再回去查对应的算子。

6.2 边界输入测试

专门构造一些边界输入：空字符串、超长句子、纯标点、中英混排。这些输入在真实场景里一定会遇到，提前测出来比线上炸了强。空字符串要确认不会崩，超长句子要确认不会 OOM，纯标点要确认不会死循环。

6.3 并发压测

用压测工具模拟多并发请求，观察延迟和错误率。ONNX Runtime 的会话是线程安全的，但 Python 侧的 tokenizer 和调度逻辑不一定。如果发现并发下延迟飙升，可能是 GIL 或者线程配置的问题。这时候可以考虑把推理服务拆成多进程，每个进程独立持有一个 ONNX 会话。

提示：压测时不要只测平均延迟，要看 P99。翻译服务的用户体验往往由最慢的那批请求决定，P99 超标比平均延迟高更值得警惕。

7. 一些个人体会和后续可扩展的方向

整套流程走下来，我最大的感受是：ONNX 迁移的难点不在导出本身，而在导出之后的验证和调优。导出可能半小时就搞定了，但把数值对齐、把性能调到位、把边界情况测全，花的时间是导出的好几倍。所以别指望"一键迁移"，把它当成一个正经的工程任务来做。

另外，如果你的模型规模比较大，CPU 推理始终有上限，可以考虑接 GPU 版的 ONNX Runtime，或者用 TensorRT 进一步加速。不过那是另一条链路了，坑也不少，建议先把 CPU 版本跑稳再说。

最后分享一个小技巧：导出时把模型的配置信息（比如最大序列长度、特殊 token id）一起存成一个 json，推理服务启动时读这个 json 来初始化。这样模型更新时不用改代码，换个文件就行，运维会感谢你的。