【Bug已解决】TypeError： export() got an unexpected keyword argument 'preprocessor' 解决方案

一、现象长什么样

你在把模型导出成 ONNX / TorchScript 时，按某些示例把preprocessor（预处理配置）也作为参数传给export()，结果报：

TypeError: export() got an unexpected keyword argument 'preprocessor' File ".../onnx/export.py", line 88, in export torch.onnx.export(model, dummy, path, **kwargs) # kwargs 里混进了 preprocessor # 另一种常见变体 TypeError: export() got an unexpected keyword argument 'preprocessor' File ".../transformers/commands/export/export.py", line 210, in execute model.config.preprocessor = preprocessor # 误把 preprocessor 当 export 参数

最典型的触发代码：

from transformers.onnx import export, FeaturesManager # 用户以为能这样把预处理一并导出 onnx_path = export( preprocessor=tokenizer, # <- 这个 kwarg 不被 export() 接受 model=model, config=onnx_config, output=Path("./model.onnx"), )

最让人困惑的是：文档/示例里明明提到了preprocessor，但export()函数签名里没有这个参数，于是传进去就TypeError。

二、背景

模型导出（ONNX/TorchScript）和预处理（tokenizer/feature extractor/image processor）是两件独立的事：

• export()/torch.onnx.export()的参数是模型 + 一张 dummy 输入 + 导出路径 + 算子/动态轴等图相关选项。
• preprocessor（tokenizer 等）是把原始文本/图像变成模型输入张量的 Python 对象，它本身不参与计算图，理论上不该成为export()的参数。

问题出在：早期某些高层封装（或社区示例）把preprocessor也暴露成export的可选参数，想"一键把预处理也固化进图"。但底层torch.onnx.export根本不认这个 kwarg，于是一旦你按高层封装的签名传preprocessor=，而实际调用链把它原样透传给了torch.onnx.export，就抛TypeError: unexpected keyword argument 'preprocessor'。

三、根因

根因有三类：

1. 参数透传未过滤。export(model, ..., **kwargs)把用户传的所有 kwarg 不加区分地透传给torch.onnx.export。当kwargs里混入preprocessor（属于"图外"对象），torch.onnx.export的签名没有这个参数 →TypeError。

2. 高层封装与底层签名不一致。 你调用的那个export()（比如transformers.onnx.export）声明了preprocessor参数，但内部它自己用了preprocessor，却不小心又把整个**kwargs（含preprocessor）继续往下传，导致重复/越界。

3. 用户误把 preprocessor 当图的一部分。 预处理（tokenizer）是 Python 逻辑，不是张量运算，本不应进计算图。把它当export参数，概念上就错了；正确做法是：导出纯模型图，预处理在推理时单独跑。

四、最小可运行复现

下面用纯 Python 模拟"export 把 kwargs 原样透传给 torch.onnx.export，混入 preprocessor 触发 TypeError"：

from typing import Dict, Any class _TorchOnnxExport: """模拟 torch.onnx.export 的签名：只接受模型/dummy/path/动态轴等。""" def __call__(self, model, dummy, path, **kwargs): # 它不认 preprocessor if "preprocessor" in kwargs: raise TypeError("export() got an unexpected keyword argument 'preprocessor'") return f"exported->{path}" def export_top(model, dummy, path, **kwargs): """有 bug 的封装：把 kwargs 原样透传。""" return _TorchOnnxExport()(model, dummy, path, **kwargs) # 复现：用户传了 preprocessor try: export_top(model="M", dummy="D", path="m.onnx", preprocessor="TOK") print("复现失败") except TypeError as e: print("复现成功:", e) # 修正：封装层先把图外参数过滤掉 def export_fixed(model, dummy, path, preprocessor=None, **kwargs): # preprocessor 在封装内消费，不往下透传 _ = preprocessor return _TorchOnnxExport()(model, dummy, path, **kwargs) print("修正后:", export_fixed(model="M", dummy="D", path="m.onnx", preprocessor="TOK"))

运行后，原样透传的export_top因preprocessor混入而TypeError，修正版在封装层消费掉preprocessor、不再下传，顺利导出。

五、解决方案（第一层：最小直接修复）

最快的止血：不要把preprocessor传给export()，把它和模型导出分开处理：

from transformers.onnx import export as onnx_export, FeaturesManager from pathlib import Path # 1) 只导出模型计算图（不含 preprocessor） onnx_path = onnx_export( model=model, config=onnx_config, # 描述输入/输出/动态轴的 ONNXConfig output=Path("./model.onnx"), ) # 2) preprocessor（tokenizer）单独保存，推理时配合使用 tokenizer.save_pretrained("./model_onnx") # 与 onnx 放同目录 # 如果确实需要一个"接受 preprocessor"的封装，用过滤函数隔离： def safe_export(model, dummy_inputs, output_path, preprocessor=None, **graph_kwargs): """第一层修复：把图外参数（preprocessor）在入口处剥离，只把图相关 kwarg 下传。""" if preprocessor is not None: # preprocessor 在这里被消费（例如保存到同目录），不进 torch.onnx.export getattr(preprocessor, "save_pretrained", lambda p: None)(str(output_path.parent)) import torch torch.onnx.export(model, dummy_inputs, str(output_path), **graph_kwargs) return output_path

第一层让用户立刻消除TypeError，且概念上把"模型图"和"预处理"正确分离。

六、解决方案（第二层：结构性改进）

用OnnxExportWrapper集中声明"哪些参数属于图、哪些属于图外"，自动过滤后再透传：

from dataclasses import dataclass, field from typing import Dict, Any, Callable @dataclass class OnnxExportWrapper: """区分图内参数与图外参数（preprocessor 等），避免 TypeError。""" # torch.onnx.export 真正接受的图相关参数白名单 GRAPH_KWARGS = {"input_names", "output_names", "dynamic_axes", "opset_version", "do_constant_folding", "use_external_data_format"} def split(self, kwargs: Dict[str, Any]): graph_kwargs = {} extra = {} for k, v in kwargs.items(): if k in self.GRAPH_KWARGS: graph_kwargs[k] = v else: extra[k] = v # preprocessor / tokenizer 等图外对象 return graph_kwargs, extra def export(self, backend_export: Callable, model, dummy, path, **kwargs): graph_kwargs, extra = self.split(kwargs) # extra 里若有 preprocessor，在封装内消费（如保存），不上传 if "preprocessor" in extra: pre = extra.pop("preprocessor") getattr(pre, "save_pretrained", lambda p: None)(str(path.parent)) return backend_export(model, dummy, str(path), **graph_kwargs) # 使用 import torch wrapper = OnnxExportWrapper() wrapper.export( torch.onnx.export, model, dummy_inputs, Path("./m.onnx"), preprocessor=tokenizer, # 不再触发 TypeError input_names=["input_ids"], output_names=["logits"], dynamic_axes={"input_ids": {0: "batch"}}, )

OnnxExportWrapper的语义是：preprocessor这类图外对象永远停留在封装层，只有白名单内的图相关参数才被透传给底层export，从结构上杜绝unexpected keyword argument。

七、解决方案（第三层：断言 / CI 守护）

用 pytest 固化"export 不接受 preprocessor 这类图外 kwarg，封装必须过滤"：

import pytest def test_preprocessor_not_passed_to_backend(): from onnx_wrap import OnnxExportWrapper seen = {} def fake_backend(model, dummy, path, **kwargs): seen.update(kwargs) return "ok" wrapper = OnnxExportWrapper() wrapper.export(fake_backend, "M", "D", "m.onnx", preprocessor="TOK", input_names=["x"], output_names=["y"]) assert "preprocessor" not in seen, "preprocessor 不应透传给底层 export" assert seen.get("input_names") == ["x"], "图相关参数应保留" def test_graph_kwargs_whitelist(): from onnx_wrap import OnnxExportWrapper w = OnnxExportWrapper() g, extra = w.split({"preprocessor": "T", "dynamic_axes": {"x": {0: "b"}}, "tokenizer": "Z"}) assert "preprocessor" in extra and "tokenizer" in extra assert "dynamic_axes" in g def test_raises_on_unknown_graph_kwarg_still_filtered(): from onnx_wrap import OnnxExportWrapper w = OnnxExportWrapper() # 即使误传未知图外参数，也应归到 extra 而不是崩溃 g, extra = w.split({"preprocessor": "T", "bogus": 1}) assert "bogus" in extra

CI 跑pytest tests/test_onnx_export.py，以后只要有人又把手预处理当export参数原样透传，测试立刻红灯。

八、排查清单

当export()报got an unexpected keyword argument 'preprocessor'，按顺序查：

1. 检查是不是把preprocessor=/tokenizer=传给了export/torch.onnx.export—— 这些图外对象不该进 export 参数。
2. 看封装层是否把**kwargs原样透传给底层torch.onnx.export且没过滤 —— 加白名单过滤。
3. 概念上区分：导出的是模型计算图，预处理在推理时单独跑（tokenizer 单独save_pretrained）。
4. 若确实需要"一键导出含预处理"，应在封装内消费preprocessor（保存同目录），而非下传。
5. 长期方案：用OnnxExportWrapper的图内/图外参数白名单，结构性避免误传。

九、小结

"export()got an unexpected keyword argument 'preprocessor'" 的根因是：preprocessor（tokenizer 等）是图外对象，却被当作export()的参数原样透传给了底层torch.onnx.export，而后者只认图相关参数；本质是"模型计算图"与"预处理逻辑"概念混淆。

• 第一层：不要把preprocessor传给export，模型图与预处理分开处理，立刻消除 TypeError。
• 第二层：用OnnxExportWrapper用白名单区分图内/图外参数，图外对象在封装层消费、不下传。
• 第三层：pytest 断言"preprocessor 不进底层 export、图相关参数保留、未知图外参数归 extra"，防止回归。

记住：导出的计算图只含张量运算；tokenizer/processor 是 Python 预处理，不该进export()的参数表——透传前先按白名单过滤，就不会有 unexpected keyword argument。