1. 从 pth 到 Onnx一次把转换和部署链路跑通PyTorch 训练出来的权重默认存成.pth这东西在 PyTorch 生态里用着很顺但一旦要跨框架、跨语言、跨端部署就会卡住。Onnx 就是来解决这个问题的它把模型的计算图用一套中立格式描述出来Python 里能用 onnxruntime 跑C、C#、Java、移动端也都有对应运行时等于给模型换了一张“通用身份证”。这篇面向的是已经训好 PyTorch 模型、准备做跨框架推理的开发者重点不是讲 Onnx 原理而是把torch.onnx.export导出、TaoToken 统一 Key 接入、onnxruntime 加载、以及 PyTorch 与 Onnx 输出一致性比对这一整条链路一次跑通。我试过在几个视觉分类和检测项目里做这套转换最容易翻车的不是导出本身而是导出后数值对不上、动态维度写死、以及部署侧拿 Key 和调 API 时配置散落各处。所以下面会把可复制的导出配置、settings.json骨架、验证脚本和常见报错都摊开写你照着改输入尺寸和权重路径就能用。2. TaoToken 前置统一 Key 与 API 通道准备在进入导出之前先把部署侧要用的模型服务通道准备好。TaoToken 在这里的角色是提供一个统一的 Key 和 API 入口让你在验证 Onnx 推理结果、或者后续接模型对话做结果复核时不用每个模型单独维护一套鉴权和地址。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数。你需要先拿到 API Key入口在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。拿到之后不要硬编码进脚本而是写进一个settings.json让导出脚本、验证脚本、后续的编码 Agent 都读同一份配置。这样做的实际好处是换 Key、换模型、换环境时只改一个文件不会出现“导出脚本能跑、验证脚本 401”这种低级问题。如果你后面还要做长期编码或 Agent 类任务可以了解下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。模型对话调试入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。settings.json骨架可以这样写字段名按你自己的项目习惯调整关键是 Key 和 base_url 集中管理{ taotoken: { api_key: sk-你的Key填这里, base_url: https://taotoken.net/api, default_model: 你的默认模型名, timeout: 60 }, onnx: { opset_version: 17, input_name: Inp, output_name: Outs, dynamic_axes: { Inp: { 0: batch, 2: height, 3: width }, Outs: { 0: batch } } } }注意api_key不要提交到公开仓库建议用环境变量覆盖或者把settings.json加进.gitignore只提交一份settings.example.json。3. 可复制配置torch.onnx.export 导出与加载3.1 环境安装先把依赖装齐onnx 负责格式和检查onnxruntime 负责推理pip install onnx onnxruntime pip install torch torchvision如果你要用 GPU 跑 onnxruntime把onnxruntime换成onnxruntime-gpu但导出阶段用 CPU 就够了导出和推理设备可以分开。3.2 自适应加载 pth 权重很多时候你拿到的.pth和当前模型定义不是完全对齐的直接load_state_dict会报 missing keys 或 size mismatch。下面这个加载器只加载 key 存在且 shape 一致的权重其余跳过适合迁移学习和微调场景import torch import numpy as np def model_loader(model, model_path, device): print(开始从本地加载权重文件) model_dict model.state_dict() pretrained_dict torch.load(model_path, map_locationdevice) load_key, no_load_key, temp_dict [], [], {} for k, v in pretrained_dict.items(): if k in model_dict.keys() and np.shape(model_dict[k]) np.shape(v): temp_dict[k] v load_key.append(k) else: no_load_key.append(k) model_dict.update(temp_dict) model.load_state_dict(model_dict) print(f成功加载 {len(load_key)} 层跳过 {len(no_load_key)} 层) return model3.3 导出为 Onnx导出时最容易忽略的是eval()和torch.no_grad()训练态下的 Dropout、BatchNorm 会让导出图带上随机行为导致后面比对输出对不上。输入尺寸要包含 batch 维动态维度用dynamic_axes声明否则部署时换个 batch 就报错import torch import json def convert_to_onnx(pth_path, onnx_path, model, settings_pathsettings.json): with open(settings_path, r, encodingutf-8) as f: cfg json.load(f)[onnx] device torch.device(cpu) model model_loader(model, pth_path, device) model.eval() model.to(device) dummy_input torch.rand(1, 3, 224, 224).to(device) with torch.no_grad(): torch.onnx.export( model, dummy_input, onnx_path, input_names[cfg[input_name]], output_names[cfg[output_name]], dynamic_axescfg[dynamic_axes], opset_versioncfg[opset_version], do_constant_foldingTrue, export_paramsTrue ) print(f导出完成{onnx_path})opset_version建议 17 起步太低会缺算子太高部分运行时还没跟上。do_constant_foldingTrue会把能提前算的常量折叠掉图更干净。3.4 加载与检查 Onnx 模型导出后先别急着推理用 onnx 自带的 checker 过一遍能挡掉不少结构问题import onnx model onnx.load(onnx_model.onnx) onnx.checker.check_model(model) output model.graph.output print(output)可视化直接打开 https://netron.app/ 把.onnx拖进去能直观看到每层节点、输入输出维度和算子类型。排查“某层没导出”“维度写死”这类问题时Netron 比打印 graph 快得多。3.5 层编辑插入和删除输出节点有时候你需要在中间层加一个输出方便做特征提取或调试。用helper.make_tensor_value_info构造节点信息再 insert 到 graph 的 output 里import onnx from onnx import helper model onnx.load(converted_vig.onnx) prob_info helper.make_tensor_value_info( layer1, onnx.TensorProto.FLOAT, [1, 3, 320, 280] ) model.graph.output.insert(0, prob_info) onnx.save(model, onnx_model_new.onnx) # 删除节点 # model.graph.output.remove(item)注意插入的节点名必须是图里真实存在的 tensor 名写错了 checker 不一定报但推理时会找不到输出。4. 验证请求PyTorch 与 Onnx 输出一致性比对导出完最重要的一步是数值比对。同一份输入分别喂给 PyTorch 和 onnxruntime看最大绝对误差是否在可接受范围。浮点运算顺序不同误差不可能为 0一般1e-4到1e-5量级算正常import numpy as np import torch import onnxruntime as ort def compare_outputs(model, onnx_path, input_shape(1, 3, 224, 224)): model.eval() dummy torch.rand(*input_shape) with torch.no_grad(): torch_out model(dummy).cpu().numpy() sess ort.InferenceSession(onnx_path, providers[CPUExecutionProvider]) input_name sess.get_inputs()[0].name onnx_out sess.run(None, {input_name: dummy.numpy()})[0] diff np.abs(torch_out - onnx_out) print(f最大绝对误差: {diff.max():.6e}) print(f平均绝对误差: {diff.mean():.6e}) print(fPyTorch 输出形状: {torch_out.shape}) print(fOnnx 输出形状: {onnx_out.shape}) return diff.max() compare_outputs(model, onnx_model.onnx)如果最大误差在1e-4以内基本可以认为转换成功。如果误差到1e-1甚至更大优先检查三件事模型是否eval()、输入是否做了相同的归一化、动态维度是否和实际输入匹配。验证通过后如果你想把推理结果接到模型服务做二次处理或结果复核可以用 TaoToken 的模型对话入口 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 手动试一条请求确认 Key 和通道是通的。接入细节看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。5. 本篇常见错排查5.1 导出报 Unsupported operator多半是 opset 版本太低或者模型里用了自定义算子。先把opset_version提到 17再不行就在导出时加operator_export_typetorch.onnx.OperatorExportTypes.ONNX_ATEN_FALLBACK试试但要注意 fallback 出来的算子部分运行时可能不支持。5.2 输出误差过大按顺序查model.eval()有没有调、torch.no_grad()有没有加、输入归一化是否一致、BatchNorm 的 running stats 是否加载正确。我踩过的坑是导出时忘了 evalDropout 在推理时还在随机丢误差直接飙到 0.3。5.3 动态 batch 推理报维度错误检查dynamic_axes是否把 batch 维标成了batch同时确认 onnxruntime 传入的输入 shape 和声明一致。如果导出时 batch 写死成 1后面传 batch4 就会报 shape mismatch。5.4 onnxruntime 找不到 providerproviders[CPUExecutionProvider]是最稳的。要用 GPU 得装onnxruntime-gpu并且 CUDA、cuDNN 版本要和运行时匹配否则会静默回退到 CPU你以为在用 GPU 其实没有。5.5 settings.json 读取报 KeyError字段名拼写不一致或者 JSON 里有尾逗号。用json.load之前先确认文件能被标准 JSON 解析器解析别用带注释的伪 JSON。5.6 401 或鉴权失败先确认base_url是https://taotoken.net/api不要带 UTM 参数再确认 Key 没有多余空格最后去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 看 Key 是否还有效。控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 能看到调用记录排查起来更直接。6. 把 Key 和导出配置收进同一条链路整条链路跑通之后建议把导出、检查、比对写成一个脚本读同一份settings.json这样每次换模型只改权重路径和输入尺寸。长期做编码或 Agent 任务的话Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 可以把模型调用和工程流程放在一起管理。ClaudeCode 相关接入参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_code_anthropicutm_campaignrewrite 。最后留一个实用习惯每次导出后把opset_version、输入尺寸、最大误差记进一个export_log.md下次换环境或换权重时出问题能直接对照上次的成功参数比重新猜快得多。