HuggingFace英译中模型迁移到ONNX实战：CPU推理提速与容器瘦身

如果你跟我一样，经历过这样一个瞬间——把自己电脑上跑得好好的 HuggingFace 英译中模型，一放到服务端就卡到怀疑人生：PyTorch 的 CPU 推理慢还能忍，整个依赖链追着容器体积一起膨胀就真的有点受不了了。这时候，把模型迁到 ONNX 就成了一个很自然的选项。这篇文章里我会完整记录一次把 HuggingFace Hub 上的英译中模型迁移到 ONNX 的实操过程：从模型选型、导出命令、ONNX Runtime 手写推理循环，到性能对比和量化，以及中途撞上的各种坑。适合那些正准备把翻译模型真正变成线上服务的同学，也适合只想知道 ONNX 导出到底难在哪、值不值得折腾的人。

1. 先想清楚再动手：为什么要迁移 ONNX，收益在哪里

1.1 一个 CPU 推理场景的切身体会

先说一个我实际遇到的场景。项目里需要跑一个英译中翻译模型，输入一般是几段英文技术文档，输出中文摘要。最初直接用的是 HuggingFace 的 Transformers 库，在开发机上推理一次大概 300 毫秒，感觉还行。等模型要搬到服务器上做成一个常驻服务时，问题就来了：为了一个翻译服务，得装完整套 PyTorch 环境，镜像体积轻松上 GB，冷启动时间被拖得很长。更麻烦的是，生产环境里不一定允许你随便装 Python 包，有时候运维只给了一个干净的容器，里面甚至连 conda 都不想放。

ONNX 的价值恰好在这里。模型导出成 ONNX 格式之后，推理阶段只需要一个 onnxruntime，它是独立的运行时，体积小、不依赖 PyTorch 全家桶。就算你坚持用 Python 调用 onnxruntime，也比直接依赖 torch 轻太多了。而且 onnxruntime 本身做了大量图优化和算子融合，在 CPU 上跑 transformer 类模型往往比 PyTorch eager 模式快不少。我实测过的几个模型，收益在 1.5 到 3 倍之间，具体取决于模型结构和机器。这个收益不是玄学，是 ONNX 静态图 + 算子融合带来的。

1.2 哪些场景值得迁，哪些场景可以先缓一缓

迁移 ONNX 不是银弹，我见过有人把 GPU 集群上好好的推理服务硬迁到 ONNX，最后收益甚微，还惹了一堆兼容性问题。什么时候值得迁？我根据自己的经验整理了一张对比表。

如果你的核心诉求是把翻译服务跑在 CPU 上、部署环境比较受限、或者想要在推理阶段做量化压缩，那 ONNX 是非常值得投入的方向。反之，如果你手里全是 A100 集群，跑的是批量离线翻译，PyTorch 本身性能已经够好，迁移 ONNX 的优先级就不高，因为动态序列长度和 KV cache 的优化会消耗你不少精力。

另外，ONNX 只是推理格式，它天然放弃了训练和微调能力。所以我的原则是：模型在实验阶段用 PyTorch 随便折腾，一旦要固化成服务，再考虑迁到 ONNX。这能让你在享受推理性能红利的同时，不牺牲研究阶段的灵活性。

2. 选对模型和备好环境：一开始就别给自己挖坑

2.1 从 Hub 上挑一个合适的英译中模型

标题里说的是 "HuggingFace 自己的英译中模型"，实际上指的就是从 HuggingFace Hub 上下载的专门做英文到中文翻译的模型。这类模型很多，选型的时候我会重点关注三件事：是不是 encoder-decoder 结构、tokenizer 是什么类型、模型在长句上的表现如何。

最典型的英译中模型是 MarianMT 系列里的 OPUS-MT 英译中模型。这个模型体积不大，encoder 和 decoder 各 4 层，词表大概几万，CPU 上跑起来压力小，译文质量在通用领域完全够用。它的 tokenizer 是 SentencePiece，特殊 token 很节俭，连 BOS token 常被复用到 EOS token，稍后推理循环里要注意。选择这类模型的好处是：结构干净、没有像某些大模型那样在导出时引入花里胡哨的 condition encoder，迁移到 ONNX 的阻力小很多。

如果你要处理的是垂直领域文本，比如医学、法律，我建议去 Hub 上搜一下有没有对应的微调模型。有的话优先用微调版，没有的话就用通用模型先顶住，然后在自己的语料上做后处理术语替换。不要一上来就盯着一百多亿参数的大模型，CPU 翻译场景用小模型性价比高得多，推理速度快一个数量级，线上维护也轻松。

2.2 环境准备清单

环境部分其实很简短，但版本坑我至少踩过两次。我的建议是尽量保持相关库的新版本，避免 transformers 版本太老导致导出 op 集不全。下面这行可以一把梭：

pip install torch transformers onnx onnxruntime optimum

导出翻译模型通常需要optimum，它封装了从 HF 模型到 ONNX 的转换逻辑，省掉很多手写导出的痛苦。如果你要用 GPU 加速推理，把onnxruntime替换成onnxruntime-gpu即可。另外建议装一个psutil用来观察内存占用，毕竟迁移 ONNX 的动机之一就是把内存打下来。

我装完环境后会先跑一段小验证，确认 onnxruntime 能被正常导入、optimum的 CLI 命令能命中：

python -c "import onnxruntime, optimum; print(onnxruntime.__version__, optimum.__version__)"

这一步看似多余，却能提前暴露最让人头疼的版本冲突。遇到过 transformer 版本和 optimum 不兼容导致导出报错的同学，应该都能理解这个检查的必要性。

3. 导出全流程拆解：三条路线怎么选

3.1 最快的路线：optimum 一条命令导出

导出阶段，我最推荐的就是直接用optimum-cli，一条命令就能把 HF 模型变成 ONNX 文件。如果目标是导出 Hub 上的模型，命令是这样的：

optimum-cli export onnx --model your-org/opus-mt-en-zh ./onnx-en2zh

your-org/opus-mt-en-zh换成你实际使用的模型仓库名；如果你已经下载到本地，也可以直接写本地目录路径。命令执行完之后，./onnx-en2zh目录下会出现转换好的模型文件。

如果你更习惯用 Python API 来控制导出流程，也可以这么写：

from optimum.onnxruntime import ORTModelForSeq2SeqLM from transformers import AutoTokenizer model_id = "your-org/opus-mt-en-zh" save_dir = "./onnx-en2zh" ort_model = ORTModelForSeq2SeqLM.from_pretrained(model_id, export=True) ort_model.save_pretrained(save_dir) tokenizer = AutoTokenizer.from_pretrained(model_id) tokenizer.save_pretrained(save_dir)

这个方式的好处是顺手把 tokenizer 也保存到了同一个目录，后面加载就很统一。export=True的意思是从 HF 模型现场导出 ONNX，如果目录里已经有 ONNX 文件，第二次加载就不需要再导出，速度会快很多。

3.2 导出产物长什么样

导出完成后，打开./onnx-en2zh目录，通常能看到这几类文件：

在 encoder-decoder 架构里，最终翻译过程是先跑 encoder，把源句子编码成 hidden states；再由 decoder 逐 token 生成中文。如果每次都把 decoder 跑一遍，而不缓存历史计算的 key-value，性能会非常差。所以 optimum 会额外导出一个decoder_with_past_model.onnx，它接受历史 KV cache 作为输入，也把新算出来的 KV cache 作为输出，供下一次迭代使用。这也是 ONNX 迁移 seq2seq 模型时最核心的一个设计。

3.3 为什么不建议手写 torch.onnx.export

很多同学会想，既然 torch 本身就能导出 ONNX，那是不是可以不用 optimum，自己写torch.onnx.export更可控？我的观点是：如果你想彻底搞懂原理，完全可以手写一次，但我劝你不要在线上项目里这么做，至少别作为首选方案。

手写导出 encoder-decoder 到 ONNX 的难点有两个。第一，decoder 的输入输出里有 KV cache，它是一堆动态形状的张量，序列长度每迭代一次都会变，导出的dynamic_axes配置稍不留神就报错或者错得离谱。第二，你要维护一个带 past 状态的 decoder 包装类，把 HF 模型内部那些past_key_values的元组展开成 ONNX 需要的扁平输入。这听起来不难，实际操作时张量名的映射关系经常把人绕晕。

optimum 最大的价值就是把这两件事封装好了。它导出的 ONNX 模型输入输出命名是约定好的，后面用 ORT 写推理循环也能对上。我自己第一次手写导出时，光调试past_key_values的形状和对齐就花了整整一个下午，最后决定以后这种翻译模型一律交给 optimum，省下来的时间都够写完整个推理服务了。

4. 用 ONNX Runtime 搭一个可跑的英译中推理循环

4.1 encoder 前向：一句话的事

导出完成后，就可以脱离 Transformers 库，只用 onnxruntime 做推理了。加载模型的方式很直接：

import onnxruntime as ort encoder_sess = ort.InferenceSession("./onnx-en2zh/encoder_model.onnx", providers=["CPUExecutionProvider"]) decoder_sess = ort.InferenceSession("./onnx-en2zh/decoder_with_past_model.onnx", providers=["CPUExecutionProvider"])

如果你熟悉 onnxruntime，这一步其实就一句话的事。真正要注意的是下面 encoder 输入的张量名，必须以实际模型为准，我建议用get_inputs()动态获取而不是硬编码：

enc_input_names = [inp.name for inp in encoder_sess.get_inputs()] print(enc_input_names)

典型的 encoder 输入是input_ids和attention_mask，形状都是[batch, sequence_length]。这里我把英文句子喂给 tokenizer，然后直接转成 numpy 数组：

from transformers import AutoTokenizer import numpy as np tokenizer = AutoTokenizer.from_pretrained("./onnx-en2zh") text = "Hello, this is a test sentence." encoded = tokenizer(text, return_tensors="np") input_ids = encoded["input_ids"].astype(np.int64) attention_mask = encoded["attention_mask"].astype(np.int64) enc_outputs = encoder_sess.run(None, { "input_ids": input_ids, "attention_mask": attention_mask, }) encoder_hidden = enc_outputs[0]

这里encoder_hidden就是 encoder 输出的上下文向量，形状一般是[batch, src_seq_len, hidden_size]。后面 decoder 的跨注意力要一直用到它，得妥善保存。

4.2 decoder 循环：past_key_values 的进出规则

decoder 部分比 encoder 麻烦不少，核心是理解 KV cache 的递归逻辑。第一次迭代时，decoder 只输入一个起始 token；之后每一次迭代，输入当前最新生成的 token 和上一步返回的 KV cache，输出新的 logits 和新的 KV cache。如果中间断错了，生成的译文要么发散，要么效率极低。

我先获取 decoder 的输入输出名，把 past 相关的张量名筛出来：

dec_input_names = [inp.name for inp in decoder_sess.get_inputs()] dec_output_names = [out.name for out in decoder_sess.get_outputs()] past_inputs = [name for name in dec_input_names if name.startswith("past")] present_outputs = [name for name in dec_output_names if name.startswith("present")]

不同版本导出的张量命名可能略有差异，但前缀基本就是past_key_values、present_key_values之类的形式。有了这些信息，就可以构造 feed dict 了。

4.3 完整推理函数与边界处理

下面这个函数是我实际用过的贪心解码版本，兼容了不少边界情况：

def translate_sentence(text, max_new_tokens=256): encoded = tokenizer(text, return_tensors="np") enc_input_ids = encoded["input_ids"].astype(np.int64) enc_attention_mask = encoded["attention_mask"].astype(np.int64) encoder_outputs = encoder_sess.run(None, { "input_ids": enc_input_ids, "attention_mask": enc_attention_mask, }) encoder_hidden = encoder_outputs[0] bos_id = tokenizer.bos_token_id if tokenizer.bos_token_id is not None else tokenizer.eos_token_id eos_id = tokenizer.eos_token_id generated = [] decoder_input_ids = np.array([[bos_id]], dtype=np.int64) past_values = {} for _ in range(max_new_tokens): feed = { "input_ids": decoder_input_ids, "encoder_hidden_states": encoder_hidden, "encoder_attention_mask": enc_attention_mask, } if past_values: feed.update(past_values) outputs = decoder_sess.run(None, feed) out_dict = dict(zip(dec_output_names, outputs)) logits = out_dict["logits"] next_token_id = int(np.argmax(logits[:, -1, :], axis=-1)[0]) if next_token_id == eos_id: break generated.append(next_token_id) decoder_input_ids = np.array([[next_token_id]], dtype=np.int64) for present_name in present_outputs: past_name = present_name.replace("present", "past") past_values[past_name] = out_dict[present_name] return tokenizer.decode(generated, skip_special_tokens=True)

有几个细节值得展开讲。第一，bos_id的取值：MarianMT 这类模型经常没有专门的 BOS token，常用 EOS token 替代，所以这里做了个兜底。第二，每次迭代传入的decoder_input_ids只包含当前最新生成的 token，而不是整个已生成序列。这是 KV cache 推理的关键，也是新手最容易写错的地方。第三，out_dict["logits"]的形状是[1, 当前序列长度, vocab_size]，取最后一维的最后一行的 argmax 就是新 token。

如果你在实际运行时报Past相关输入缺失，那就说明导出模型把 past 输入当成了必填项。这种情况的兜底方案是：在第一次运行时给每个 past 输入传一个形状合法的空张量，比如np.zeros([1, num_heads, 0, head_dim], dtype=np.float32)，然后从第二次迭代开始替换成真实缓存。

5. 迁移完必须做的两件事：性能对比和译文质量校验

5.1 延迟和吞吐量：用数据说话，别拍脑袋

迁移完成后，我第一件事就是把 PyTorch eager 版本和 ONNX Runtime 版本拉出来跑同一个句子，而不是急着上线。测试环境是一台普通 CPU 服务器，句子长度在 20 到 40 个 token 之间，解码长度 30 个 token 左右。预热几轮后取平均结果如下：

这组数据不代表所有模型，但趋势很明确：ONNX Runtime 在 CPU 上的推理优化是实打实的。如果你的服务是面向大量短句翻译，这个提升非常可观。测量时需要注意一点，不要拿第一次推理的耗时当基准，因为 ORT 的 session 第一次调用时有初始化开销，要等预热完成之后再计时才公平。

5.2 译文质量：抽样对比与 BLEU 参考

性能上去了，质量不能掉链子。我通常会在测试集上做两件事。第一步是人工抽样对比，把原模型和 ONNX 模型的输出并排放在一起，重点看专有名词、数字、长句断句是否一致。第二步是算 BLEU，用sacrebleu在标准翻译测试集上对比。正常情况下，FP32 的 ONNX 模型和 PyTorch 模型输出几乎完全一致，BLEU 差异都在 0.1 分以内，可以忽略不计。如果出现明显差异，优先检查导出的 dynamic axes 是否设置正确，或者推理循环里的 KV cache 是否出现了错位。

如果做了 INT8 量化，质量下降会变得肉眼可见。我的经验是，英译中模型做动态量化后 BLEU 可能下降 1 到 3 分，短句还好，长句容易出现“翻译发飘”的情况。量化之前要记得准备一个校准集，几百句代表性的语料就够了，然后对比量化前后的译文，决定是否要换静态量化或者混合精度方案。

5.3 顺带聊聊量化

ONNX Runtime 的quantize_dynamic用起来特别简单，两行代码就能生成 INT8 模型：

from onnxruntime.quantization import quantize_dynamic, QuantType quantize_dynamic( "./onnx-en2zh/decoder_with_past_model.onnx", "./onnx-en2zh/decoder_with_past_int8.onnx", weight_type=QuantType.QUInt8, )

但对 transformer 模型，无脑全量化会踩坑。像LayerNormalization、Gelu这类算子对精度影响很大，量化后模型在长句上的表现会明显变差。我实际的做法是限制只量化MatMul，并且在量化前先人工对比几个长句的翻译结果。量化能带来额外 20% 到 30% 的性能提升，但如果你的编译服务不缺这点性能，我更建议先保持 FP32，把正确性放到第一位。

6. 这一路踩过的坑和对应解法

6.1 动态轴没配好，batch=1 都跑不动

我最早是自己写torch.onnx.export导出翻译模型的，当时给dynamic_axes配错了，只把 batch 维设成动态，序列长度维写死成了固定值。结果模型在短句上跑得飞起，一遇到超过固定长度的英文句子就报维度不匹配错误。翻译模型的源句子长度本质上是可变的，input_ids和attention_mask的 sequence 维度一定要设成动态。用 optimum 导出时默认会处理这件事，但如果你自己手写导出，务必将 encoder 的input_ids、attention_mask和encoder_hidden_states的 sequence 维度都标为动态。

另外，动态 shape 越灵活，图中的算子融合就越保守。如果你的线上场景句子长度相对可控，可以在导出时限制一个最大长度，比如 128 或 256，让序列长度变成有限集合，这样 ONNX Runtime 的优化更激进，推理延迟还能再降一截。这个取舍要根据实际语料分布来定，不能盲目套用。

6.2 SentencePiece 对空格敏感，翻译结果莫名多词

MarianMT 这类模型用 SentencePiece 分词，它对输入文本的空格和标点都比较敏感。我用一个测试句子时发现，ONNX 版本的输出里莫名出现了一个孤零零的连字符，排查了半天才发现是上游文本预处理把句子里的换行符替换成了空格，导致 tokenizer 切分出来的子词边界发生了变化。这个坑和 ONNX 本身无关，但迁移之后更容易暴露，因为焦油更多集中在推理流程里。

解决办法很简单：喂给 tokenizer 的文本尽量保持原始格式，不要做多余的规整化。如果你发现译文里有很多零散的空格碎片，可以考虑检查tokenizer.decode时的clean_up_tokenization_spaces参数，不同版本默认值不太一样，手动设一下能改善输出可读性。中文输出一般不太受影响，但英文片段多的时候这个问题很烦人。

6.3 量化后的“发飘”问题

INT8 量化之后，我发现模型在翻译中等长度的句子时偶尔会输出完全离谱的结果，比如重复某个词好几遍，或者把一个否定句翻成了肯定句。这是典型的量化敏感度问题。后来我看了下 ONNX Runtime 导出的算子列表，发现问题出在对LayerNormalization和部分激活函数的量化上。这两个算子在 transformer 里承担着分布缩放的作用，一旦被量化，误差会沿着层传播放大。

解决方式是使用quantize_dynamic时通过op_types_to_quantize参数限制量化范围，比如只量化MatMul：

quantize_dynamic( "./onnx-en2zh/decoder_model.onnx", "./onnx-en2zh/decoder_int8.onnx", op_types_to_quantize=["MatMul"], weight_type=QuantType.QUInt8, )

这样改写之后，长句的翻译质量明显回稳，虽然压缩率低了一点，但比“速度快但结果没法用”强太多了。如果你有时间折腾，可以再用qdq静态量化加校准集的方式做一次，效果通常比动态量化更稳定。

6.4 别把 EOS 逻辑写错，否则就是死循环

我早期手写推理循环时，把结束 token 判断放在了argmax之前，导致模型都输出 EOS 了还在继续跑，最后生成了几百个无意义 token。这种死循环在 PyTorch 里不太容易触发，因为 transformers 的generate会自己处理很多边界条件；换成手写 ORT 循环后，所有逻辑都暴露在眼前，一点小疏漏都会被放大。

我的经验是：生成循环里一定要写两重保险。第一，每次迭代都检查next_token_id == eos_id，满足就 break；第二，用max_new_tokens限制最大解码步数，防止模型抽风一直不输出 EOS。真实线上环境里建议再加一个超时检查，比如解码超过 N 秒直接返回已生成的部分译文，至少不会让请求卡死。

还有一个隐藏很深的点，就是 decoder 的输入序列。如果你在迭代时错误地把整个已生成序列都喂进去，而不是只喂最新 token，KV cache 就会和新输入冲突，logits 变得很奇怪，翻译结果会逐渐失控。这个问题只会在手写循环时出现，但一旦出现就很让人头大，所以我特别提醒一句：迭代时要看清喂给 decoder 的input_ids到底是什么形状。

英译中模型迁移到 ONNX 这条路，走过一次之后就会发现，真正难的不是某一条命令，而是对 encoder-decoder 推理机制的理解。当你把手写推理循环跑通，看着 CPU 上流畅产出的中文译文，再对比一下迁移前的延迟数据时，之前踩过的坑都值了。