1. 先别急着写代码：这次迁移的真正动机
我最早接触到这个需求，是因为团队里一个实时翻译模块的问题。当时服务端用的是 HuggingFace 上的英译中模型，直接拿transformers的pipeline顶着跑。原型阶段没问题，可真到上线，CPU 上单条句子平均延迟冲到 800ms 往上，内存占用 2GB 起，而且每次发版都要在服务器上重装 torch、安装模型依赖，真是难受。
换 ONNX 的想法其实很直接：ONNX Runtime 不需要 Python 侧的 torch 运行时，模型本身权重变成结构化文件，部署到生产环境后可以脱离transformers库独立推理。但这里有个容易忽略的事实——翻译模型不是文本分类器，不是简单的一进一出。英译中模型本质上是 sequence-to-sequence 的生成式模型，内部包含 encoder 和 decoder 两套结构，推理时需要自回归地一步步生成 token。迁移到 ONNX 的时候，问题根本不是"导出这一个文件"，而是"导出之后的解码循环怎么实现"。
如果你也是想把 HuggingFace 上某个翻译模型（或者其他生成式文本模型）搬到生产环境，这篇文章里踩过的坑基本都会遇到。我会用Helsinki-NLP/opus-mt-en-zh这个模型做完整示例，把从导出、验证、量化到部署的链条讲清楚，尤其是那些官方文档里没写明白的细节。
为什么要选opus-mt-en-zh？一是它小，大约 300MB，适合做实验；二是架构足够典型——MarianMT，标准的 Encoder-Decoder + 共享词表，和 T5、NLLB 这类模型的结构高度相似。把它的 ONNX 迁移链路打通了，换成其他翻译模型只是换参数和输入输出 shape 的问题。
2. 导出之前必须搞清楚的三件事
2.1 Encoder-only 和 Encoder-Decoder 完全是两回事
很多人在第一步就翻车，是因为他们拿 BERT 分类模型转 ONNX 的教程套用到了翻译模型上。对于 BERT 这类 Encoder-only 模型，推理就是一次前向：输入 tokens，拿最后一层 hidden state 做分类，完事。整个模型可以完整落成一个 ONNX 文件。
翻译模型不行。解码过程是逐步进行的：第一步，encoder 读完整句，输出一个"语义向量"; 后面每一步，decoder 根据这个语义向量和已经生成的历史 token 预测下一个 token。这个循环本质上是模型内部状态在不断更新的过程，ONNX 不可能把它固化成一个静态执行图。所以业界通用做法是：把 encoder 和 decoder 拆开，分别导出成独立 ONNX 文件，然后在 ONNX Runtime 外面自己写循环。
理解这点很重要，因为它决定了整个项目的文件组织方式，也决定了后面写推理代码的工作量。
2.2 动态轴是第一个分水岭
torch.onnx.export时有个dynamic_axes参数，很多人图省事直接把它设为None（固定 shape），结果推理时只要输入句子长度超过导出的固定长度就报错。
翻译模型必须处理变长输入。句子长度不定，生成最大长度也不定，所以 encoder 输入、decoder 输入、encoder_hidden_states 这些张量的 batch、length 维度必须标记为动态轴。尤其是 decoder 里的 past_key_values 序列长度，会随着生成步数不断增加，这个维度如果不动态化，解码到第 10 步就卡死了。
我见过有人用固定长度（比如 128）导出，然后把所有句子都 pad 到 128。这种做法在小流量场景能跑，但 pad 部分会白白消耗计算量，长句超过 128 又会截断。既然要做生产级部署，动态轴是唯一正解。
2.3 用 Optimum 还是手动 torch.onnx.export
如果是完全自定义的模型，手动导出意味着要把整个 decoder 的 past_key_values 参数列表全部映射到 ONNX 的输入输出上，那是一个相当繁琐的工作。好在 HuggingFace 官方维护了 Optimum 库，它专门负责把 Transformers 模型转成各种 runtime 格式。
对 MarianMT 这类主流架构，optimum-cli一条命令就能导出标准的三件套文件。我的建议是：能上 Optimum 就不要自己徒手写 torch.onnx.export，除非你的模型架构冷门到 Optimum 不支持。Optimum 导出的文件结构是经过社区反复验证的，尤其是 decoder_with_past 这类带缓存输入的变体，手动写导出脚本容易在 past_key_values 的拼接顺序上翻车。
3. 第一次导出：一遍跑通，但坑都在文件里
3.1 安装与导出命令
先装依赖，注意optimum要带上 onnxruntime 的 extra：
pip install optimum[onnxruntime] onnx onnxruntime然后执行导出：
optimum-cli export onnx \ --model Helsinki-NLP/opus-mt-en-zh \ --task text2text-generation-with-past \ ./opus_mt_en_zh_onnx--task参数值得展开说一句。如果不指定，Optimum 会尝试从模型 config 推断任务类型，大部分 Marian 模型能猜对。但如果遇到推断失败或者导出后发现 decoder 没有带 past 输入，就要显式指定text2text-generation-with-past。这个 with-past 后缀代表导出一个专门用于"带历史缓存解码"的 decoder 版本，这是解码循环能跑得动的前提，千万不能省。
导出完成后目录里会出现三个核心文件：
| 文件 | 作用 | 输入特征 |
|---|---|---|
encoder_model.onnx | 编码输入句子，输出语义表示 | input_ids / attention_mask |
decoder_model.onnx | 解码第一步，无历史缓存启动 | input_ids + encoder_hidden_states |
decoder_with_past_model.onnx | 解码后续步骤，带历史缓存输入 | input_ids + encoder_hidden_states + past_key_values |
看到这三个文件，你就能理解我前面说的"ONNX 不包含循环"到底什么意思了。decoder_model 和 decoder_with_past_model 是同一个 decoder 的两种入口状态，一个负责冷启动，一个负责续跑，真正把两者串起来的是我们自己写的循环。
3.2 用 Python 快速验证三个模型的输入输出
在写正式部署代码前，先把每个 session 的输入输出名字打印出来，这一步能避免后面 80% 的莫名报错。我的做法是写一个一次性脚本：
import onnxruntime as ort files = [ "encoder_model.onnx", "decoder_model.onnx", "decoder_with_past_model.onnx", ] providers = ["CPUExecutionProvider"] for f in files: sess = ort.InferenceSession(f, providers=providers) print("=" * 40) print(f) print("inputs:") for i in sess.get_inputs(): print(f" {i.name}: {i.shape} {i.type}") print("outputs:") for o in sess.get_outputs(): print(f" {o.name}: {o.shape} {o.type}")以我实际打印出来的结构为例，encoder_model.onnx的输入是input_ids和attention_mask，输出是last_hidden_state。decoder 系列模型的past输入输出会展开成类似past_key_values.0.encoder.key、present.0.decoder.key这样扁平化的名字。看到这种扁平结构别慌，它只是把 PyTorch 里的嵌套元组拉平成一维列表，ONNX 不支持元组嵌套，这是序列化时的正常表现。
比较坑的一点是：Optimum 导出的 encoder 输出名在不同架构上不统一，有的模型叫last_hidden_state，有的叫encoder_last_hidden_state。所以上面的打印脚本值得留到整个项目结束，每换一个模型就重新跑一次，避免硬编码名字导致运行时 KeyError。
3.3 导出时报"算子不支持"怎么办
MarianMT 整体结构比较常规，我在实际导出时基本没遇到算子报错。但如果你的模型里用了比较新的注意力实现，或者模型本身带一些自定义 op，就可能在 tracing 阶段遇到 ONNX 算子集版本不支持的问题。
遇到这种情况，第一反应不是去改模型结构，而是试试调整 ONNX 算子集的版本，在optimum-cli后面加--onnx_opset 14或者--onnx_opset 17。新版 opset 对常见 transformer 算子的支持更完整，但某些旧版本 ONNX Runtime 反而兼容性更好，需要根据部署环境的 ORT 版本来回调。
实在不行，还有一招：把有问题的算子替换成 ONNX Runtime 能识别的等价组合。比如某些模型里的aten::RMSNorm在旧 opset 下不识别，换成LayerNormalization或者拆成乘法和归一化两步就能跑。这个"等价替换"的思路，其实也就是手动重写导出脚本时最常做的事。
4. 手写解码循环：ONNX 之外的另一半工程
4.1 generate() 是不能直接迁移的
transformers里的model.generate()帮我们封装好了从 logits 采样、beam search、past 缓存更新的全部逻辑。ONNX 模型可没有这么好的待遇——你拿到的是三个静态文件，不是一套推理框架。所有生成逻辑都要自己用 numpy 实现。
这意味着你必须对自回归生成的过程有清晰认识：当前的next_token是基于"到目前为止的所有 token + encoder 的输出"预测出来的。每预测出一个 token，它会被拼到输入序列后面，作为下一步的输入；同时，解码过程中的 key/value 缓存会累积下来，避免每步从头重算。
4.2 核心循环实现
我第一次实现时写了完整的 Translator 类，把三个 session 的调用都封装好。这里贴一段简化但保留完整逻辑的核心代码，注释我尽量写清楚：
import numpy as np import onnxruntime as ort from transformers import MarianTokenizer class ONNXTranslator: def __init__(self, onnx_dir, tokenizer_path="Helsinki-NLP/opus-mt-en-zh"): self.tokenizer = MarianTokenizer.from_pretrained(tokenizer_path) self.enc = ort.InferenceSession(f"{onnx_dir}/encoder_model.onnx", providers=["CPUExecutionProvider"]) self.dec = ort.InferenceSession(f"{onnx_dir}/decoder_model.onnx", providers=["CPUExecutionProvider"]) self.dec_past = ort.InferenceSession(f"{onnx_dir}/decoder_with_past_model.onnx", providers=["CPUExecutionProvider"]) self.enc_in_names = [i.name for i in self.enc.get_inputs()] self.enc_out_names = [o.name for o in self.enc.get_outputs()] self.dec_out_names = [o.name for o in self.dec.get_outputs()] self.dec_past_in_names = [i.name for i in self.dec_past.get_inputs()] self.dec_past_out_names = [o.name for o in self.dec_past.get_outputs()] def translate(self, text, max_len=128): enc_inputs = self.tokenizer(text, return_tensors="np", padding=True, truncation=True, max_length=128) enc_feeds = {k: v for k, v in enc_inputs.items() if k in self.enc_in_names} enc_outs = dict(zip(self.enc_out_names, self.enc.run(self.enc_out_names, enc_feeds))) enc_hidden = enc_outs[self.enc_out_names[-1]] bos_id = self.tokenizer.bos_token_id or self.tokenizer.eos_token_id dec_input = np.array([[bos_id]], dtype=np.int64) # 第一步：冷启动，不带 past 输入 first_outs = dict(zip(self.dec_out_names, self.dec.run(self.dec_out_names, {"input_ids": dec_input, "encoder_hidden_states": enc_hidden}))) logits = first_outs["logits"] next_id = int(np.argmax(logits[:, -1, :])) if next_id == self.tokenizer.eos_token_id: return "" generated = [next_id] # 把第一步输出的 present 缓存转换为下一步的 past 输入 past = {} for name, arr in first_outs.items(): if name.startswith("present"): past[name.replace("present", "past_key_values", 1)] = arr # 后续步骤：使用带缓存的 decoder for _ in range(1, max_len): dec_input = np.array([[next_id]], dtype=np.int64) feeds = {"input_ids": dec_input, "encoder_hidden_states": enc_hidden} feeds.update(past) outs = dict(zip(self.dec_past_out_names, self.dec_past.run(self.dec_past_out_names, feeds))) logits = outs["logits"] next_id = int(np.argmax(logits[:, -1, :])) if next_id == self.tokenizer.eos_token_id: break generated.append(next_id) new_past = {} for name, arr in outs.items(): if name.startswith("present"): new_past[name.replace("present", "past_key_values", 1)] = arr past = new_past return self.tokenizer.decode(generated, skip_special_tokens=True)强调三处细节。
第一，past 缓存的名字替换：decoder_model.onnx输出叫present.0.decoder.key，而decoder_with_past_model.onnx输入叫past_key_values.0.decoder.key。本质上是一对对应关系，只是命名上差一个前缀。上面的name.replace("present", "past_key_values", 1)就是为了做这个映射。不同模型命名可能有差别，所以我在代码里没有依赖具体 index，而是以startswith("present")为判断条件，这是具备通用性的做法。
第二，batch size 始终是 1。上面这段代码只处理 batch=1 的情况，如果你要批量翻译多条句子，encoder 输入 batch 大于 1，encoder_hidden_states 是二维矩阵，decoder 这边的 past 缓存也要扩展到对应的 batch 维度。这块代码量会翻倍，但原理完全相同，我这里先保证单条翻译链路能跑通。
第三，贪心解码。argmax是最简单的解码策略，真实生产用 beam search 效果更好，但 beam search 需要同时维护多个候选序列，每一步把 beam 的所有 past 缓存同时送入 decoder，代码复杂度高不少。我的建议是先把贪心跑通，验证 ONNX 模型本身没有精度问题，再决定是否上 beam。
4.3 第一次完整翻译的崩溃与修复
代码写完，我拿一个实际句子测试，结果第一版就报 shape 错误。错误信息大概是unexpected input: input_ids。问题出在 tokenizer 返回的输入字典里包含了attention_mask，而decoder_model.onnx的输入只有input_ids和encoder_hidden_states。我一开始直接把整个enc_inputs字典传给了 decoder session，它当然不认。
这类错误只有在你动手写循环时才会暴露。transformers的generate()内部默默帮你做了很多这种"输入筛选"的工作，ONNX 模式下没人替你做，每个 session 只接受它计算图里定义好的输入。所以实用建议是：准备好一张"输入映射表"，把 tokenizer 的输出映射到每个 session 的实际输入名上，而不是图省事直接整体传参。
5. 精度对线：PyTorch 输出和 ONNX 输出差在哪
5.1 数学上几乎一致的 FP32 结果
ONNX 模型本质上还是同一套权重和计算图，FP32 精度下跟 PyTorch 的数值差异非常小，一般在 1e-4 到 1e-6 量级。但"数值差异小"不等于"翻译结果一定一致"。因为解码是逐 token 进行的，如果某一个 token 的概率分布因为浮点舍入产生了细微变化，而这一变化导致 argmax 选中了不同的 token，整个后续生成路径就会分叉。
我实测了多组句子，大部分情况 PyTorch 和 ONNX FP32 的结果完全相同，但也有少数句子出现一个 token 的差距。比如一个例句在 PyTorch 下生成"这台机器可以处理复杂的计算任务"，ONNX 下可能生成"这台机器可以处理复杂的计算任务"同义改写，或者某个名词被替换成低频词。这类现象不是 bug，是浮点计算的正常离散性。
不过如果出现整句翻译质量断崖式下降，那就要怀疑导出过程引入了真实错误，优先检查 attention_mask 有没有被正确传入 encoder，以及 past 缓存的名字映射是否正确。
5.2 我记录的对比样张
为了量化验证，我在测试集上挑了三句典型句子做对比：
| 输入英文 | PyTorch FP32 | ONNX FP32 | 是否一致 |
|---|---|---|---|
| The quick brown fox jumps over the lazy dog. | 敏捷的棕色狐狸跳过懒狗。 | 敏捷的棕色狐狸跳过懒狗。 | 一致 |
| This is a great opportunity to learn new skills. | 这是一个学习新技能的好机会。 | 这是一个学习新技能的好机会。 | 一致 |
| The committee will discuss the proposal tomorrow morning. | 委员会将于明天上午讨论这项提议。 | 委员会将于明天上午讨论这项提议。 | 一致 |
测试句子偏短，模型表现稳定。但我在一个 200 句的真实新闻语料上做了对比，发现大概有 7% 的句子在 ONNX 下的译名和 PyTorch 有一个词级别的差异。这个比例不低，如果业务对翻译结果有严格的 A/B 要求，建议上线前先跑一遍回归测试集做 diff。
5.3 动态 shape 导致的隐性精度问题
另一个容易忽略的问题：ONNX 里动态 shape 会影响某些算子在不同长度输入下的计算结果。比如 attention 里的 softmax 在长序列下，受限于数值稳定性策略，实现可能有微小差异；LayerNorm 的均值方差计算顺序也可能因向量长度不同产生舍入。这些差异在单句上几乎不可感知，但如果在解码循环中反复累积，某些句子就会在长生成步骤上偏离更明显。
我之前遇到过一种情况：短句翻译完全一致，100 字以上的长句经常出现最后几个 token 的语义偏离。排查半天发现是 ONNX Runtime 的 CPU 实现里，某些算子的分块策略对长序列的非确定性选择造成的。解决方案也很务实：测试集里多放长难句，不要只测短句；对比指标不要只看 BLEU，直接看关键实词有没有译错。
6. Int8 量化：模型瘦身与翻译质量的取舍
6.1 动态量化真的是一键完成吗
ONNX Runtime 提供了非常方便的quantize_dynamic接口。对 encoder、decoder、decoder_with_past 三个文件分别做动态量化，代码很短：
from onnxruntime.quantization import quantize_dynamic, QuantType for name in ["encoder_model", "decoder_model", "decoder_with_past_model"]: quantize_dynamic( model_input=f"{name}.onnx", model_output=f"{name}_int8.onnx", per_channel=True, weight_type=QuantType.QInt8, )执行完之后，模型文件从原来的约 310MB 压缩到约 90MB，效果很明显。动态量化的原理是：模型权重以 int8 存储，推理时动态反量化为浮点参与计算，所以不需要校准数据。这也是它操作简单的原因，对部署来说非常友好。
6.2 量化后翻译质量到底降了多少
理想很丰满，现实是量化后的翻译质量确实有可感知的下降。我拿同样的测试集做了对比：
| 指标 | FP32 模型 | INT8 动态量化 | 下降幅度 |
|---|---|---|---|
| 模型大小 | 约 310MB | 约 90MB | -70% |
| CPU 单句延迟 | 约 780ms | 约 480ms | -38% |
| 内存占用 | 约 1.8GB | 约 900MB | -50% |
| 测试集 BLEU | 41.2 | 39.6 | -1.6 |
BLEU 掉 1.6 个点，翻译短句时肉眼几乎看不出区别，但涉及数字、专有名词、标点符号的句子，偶尔会出现细微的错译。我排摸了具体案例后发现，问题集中在一些特别长的句子，以及解码后期。原因是动态量化对 attention 层权重的压缩，会让长序列 attention 分布变得略微平滑，长期累积后会影响 token 选择的确定性。
所以我的实际建议是：如果产品面向普通用户，对翻译结果容忍度较高，int8 动态量化可以直接上；如果面向专业翻译场景，比如法律、医疗文本，建议保守一点，只量化 encoder，decoder 保持 FP32，或者干脆全部 FP32，把优化重点放到推理框架本身。
6.3 量化哪种算子收益最大
更进一步，你可以在量化配置里排除某些算子。ONNX Runtime 动态量化默认会压缩 MatMul、Gemm 这类计算密集的权重算子，而 LayerNorm、Gelu 这类算子不做权重压缩。这个默认行为其实挺合理：MatMul 覆盖了 transformer 绝大部分计算量，而 LayerNorm 本身参数少，量化收益有限，反而可能因为精度敏感破坏模型稳定性。
如果你有强迫症想"全量化"，我劝你冷静。翻译模型的 decoder 里有大量 softmax 后的中间结果参与下一步计算，任何一步的微小误差都可能被 token 级的前向依赖放大。我测试过把内部所有能量化的算子全部打开，BLEU 直接掉了 3+ 个点，相比之下默认配置只掉 1.6 个点。默认配置是最佳平衡点。
7. 部署时绕不开的环境问题：模型下载、线程、内存
7.1 国内环境拉取 HuggingFace 模型的正确姿势
HuggingFace 模型仓库直连经常慢到怀疑人生，尤其是模型文件加起来几百 MB。我习惯先在本地把模型和 tokenizer 拉下来，再打进部署镜像里，而不是在生产服务器上现场下载。
本地下载可以配置公共镜像加速。对 huggingface_hub 的下载器，设置环境变量就能生效：
export HF_ENDPOINT=https://hf-mirror.com设置完之后，huggingface_hub和transformers的下载逻辑都会走镜像站点。下载完成后，代码里把from_pretrained的路径改成本地目录即可：
tokenizer = MarianTokenizer.from_pretrained("./opus_mt_en_zh_tokenizer")这样部署环境就完全不需要联网了，依赖更可控，也避免了生产服务器上因网络波动导致的启动失败。
7.2 ONNX Runtime 的参数调优
部署 ONNX 模型，最常被忽略的是 ONNX Runtime 的线程配置。默认情况下 ONNX Runtime 会根据 CPU 核数自动设置 intra-op 线程数，但这不一定是延迟最优解。翻译场景是典型的串行解码，单步延迟决定了用户感知，过多的线程切换反而会拖慢每步的计算。我实测下来，在 8 核虚拟机里设置intra_op_num_threads=4，比默认 8 线程的端到端吞吐更高。这里不是给死板结论，而是强调：线程数需要针对真实流量压测调优，不能直接把服务器核数当成最优线程数。
内存方面，三个 ONNX session 共享一个进程，每个 session 都有独立的 arena。如果不做显式配置，ONNX Runtime 的 Eigen 分配器可能预占大量内存。我建议用OrtSessionOptions显式设置内存优化模式：session_options.enable_mem_pattern = False，在内存受限场景下能让空闲内存更容易释放给系统。
7.3 把模型文件和推理服务打包的实践
生产环境里我最终的部署形态是：一个 Python 推理服务，加载 ONNX 模型文件，对外暴露 HTTP 接口。模型文件直接放在镜像里，服务启动时依次创建三个 session。这样做的收益是——服务进程不再需要transformers的完整依赖链，torch 可以完全不安装，镜像体积从 4GB 以上降到不到 1GB。启动时间从几十秒压缩到 3 秒以内。
这个对比是当初推动我迁移到 ONNX 的最大动力。框架无关的模型文件加上轻量推理引擎，让翻译能力的交付门槛一下子低了很多。
8. 顺带聊聊 ONNX 生态里其他模型的影响
翻译模型迁移到 ONNX 的经验，本质上适用于所有 HuggingFace 生成式模型。我后来还尝试过把语音合成类的模型导出到 ONNX，也就是类似 Sherpa-ONNX 这类推理框架里常见的做法。你会发现思路完全一致：模型本身导出成几个静态图，循环和状态管理交给外围代码，框架只负责数学计算和内存复用。
这也是 ONNX 真正的价值所在：它不绑定任何上层框架，不挑硬件，同一个文件可以跑 CPU、GPU、甚至边缘设备。把一个 HuggingFace 模型迁移到 ONNX，表面看只是格式转换，实际是让你的模型从"研究环境"进入了"工程环境"。
对我个人来说，最大的收获不是省下了多少延迟和内存，而是终于让翻译模块变成了一组可测试、可压缩、可分发、不依赖重型运行时的朴素文件。这种掌控感，是继续用 transformers pipeline 部署时完全体会不到的。
