【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( preprocessortokenizer, # - 这个 kwarg 不被 export() 接受 modelmodel, configonnx_config, outputPath(./model.onnx), )最让人困惑的是文档/示例里明明提到了preprocessor但export()函数签名里没有这个参数于是传进去就TypeError。二、背景模型导出ONNX/TorchScript和预处理tokenizer/feature extractor/image processor是两件独立的事export()/torch.onnx.export()的参数是模型 一张 dummy 输入 导出路径 算子/动态轴等图相关选项。preprocessortokenizer 等是把原始文本/图像变成模型输入张量的 Python 对象它本身不参与计算图理论上不该成为export()的参数。问题出在早期某些高层封装或社区示例把preprocessor也暴露成export的可选参数想一键把预处理也固化进图。但底层torch.onnx.export根本不认这个 kwarg于是一旦你按高层封装的签名传preprocessor而实际调用链把它原样透传给了torch.onnx.export就抛TypeError: unexpected keyword argument preprocessor。三、根因根因有三类参数透传未过滤。export(model, ..., **kwargs)把用户传的所有 kwarg 不加区分地透传给torch.onnx.export。当kwargs里混入preprocessor属于图外对象torch.onnx.export的签名没有这个参数 →TypeError。高层封装与底层签名不一致。 你调用的那个export()比如transformers.onnx.export声明了preprocessor参数但内部它自己用了preprocessor却不小心又把整个**kwargs含preprocessor继续往下传导致重复/越界。用户误把 preprocessor 当图的一部分。 预处理tokenizer是 Python 逻辑不是张量运算本不应进计算图。把它当export参数概念上就错了正确做法是导出纯模型图预处理在推理时单独跑。四、最小可运行复现下面用纯 Python 模拟export 把 kwargs 原样透传给 torch.onnx.export混入 preprocessor 触发 TypeErrorfrom 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 fexported-{path} def export_top(model, dummy, path, **kwargs): 有 bug 的封装把 kwargs 原样透传。 return _TorchOnnxExport()(model, dummy, path, **kwargs) # 复现用户传了 preprocessor try: export_top(modelM, dummyD, pathm.onnx, preprocessorTOK) print(复现失败) except TypeError as e: print(复现成功:, e) # 修正封装层先把图外参数过滤掉 def export_fixed(model, dummy, path, preprocessorNone, **kwargs): # preprocessor 在封装内消费不往下透传 _ preprocessor return _TorchOnnxExport()(model, dummy, path, **kwargs) print(修正后:, export_fixed(modelM, dummyD, pathm.onnx, preprocessorTOK))运行后原样透传的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( modelmodel, configonnx_config, # 描述输入/输出/动态轴的 ONNXConfig outputPath(./model.onnx), ) # 2) preprocessortokenizer单独保存推理时配合使用 tokenizer.save_pretrained(./model_onnx) # 与 onnx 放同目录 # 如果确实需要一个接受 preprocessor的封装用过滤函数隔离 def safe_export(model, dummy_inputs, output_path, preprocessorNone, **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), preprocessortokenizer, # 不再触发 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, preprocessorTOK, 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 extraCI 跑pytest tests/test_onnx_export.py以后只要有人又把手预处理当export参数原样透传测试立刻红灯。八、排查清单当export()报got an unexpected keyword argument preprocessor按顺序查检查是不是把preprocessor/tokenizer传给了export/torch.onnx.export—— 这些图外对象不该进 export 参数。看封装层是否把**kwargs原样透传给底层torch.onnx.export且没过滤 —— 加白名单过滤。概念上区分导出的是模型计算图预处理在推理时单独跑tokenizer 单独save_pretrained。若确实需要一键导出含预处理应在封装内消费preprocessor保存同目录而非下传。长期方案用OnnxExportWrapper的图内/图外参数白名单结构性避免误传。九、小结export()got an unexpected keyword argument preprocessor 的根因是preprocessortokenizer 等是图外对象却被当作export()的参数原样透传给了底层torch.onnx.export而后者只认图相关参数本质是模型计算图与预处理逻辑概念混淆。第一层不要把preprocessor传给export模型图与预处理分开处理立刻消除 TypeError。第二层用OnnxExportWrapper用白名单区分图内/图外参数图外对象在封装层消费、不下传。第三层pytest 断言preprocessor 不进底层 export、图相关参数保留、未知图外参数归 extra防止回归。记住导出的计算图只含张量运算tokenizer/processor 是 Python 预处理不该进export()的参数表——透传前先按白名单过滤就不会有 unexpected keyword argument。