PyPTO-Gym 模型转换矩阵解读：pypto-convert-model 的三格式 Round-Trip 校验与冻结测试证据

PyPTO-Gym 模型转换矩阵解读pypto-convert-model 的三格式 Round-Trip 校验与冻结测试证据【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym本文以 PyPTO-Gym 仓库中pypto-convert-modelskill 自带的转换证据文件 matrix.md 为主体逐列解读这张模型 × 目标格式校验矩阵它由谁生成、七种状态码如何定义、测试设备如何自动检测、11 个被测模型从哪里来、每个格子结果背后的真实含义是什么以及如何在本地复现并刷新这张矩阵。读完后你可以独立读懂该仓库任何一次批量转换的 PASS/FAIL 证据并按同样的流程接入自己的模型。1. matrix.md 是什么一次批量转换实验的冻结证据pypto-convert-model是一个在onnx ↔ pt (TorchScript) ↔ safetensors三种格式之间双向互转的工具链核心承诺是每转换一次就把产物重新加载用同一个 dummy input 各跑一次 forward再与源模型输出比对以max_abs差异作为首要判据。详见 SKILL.md。matrix.md 就是这条工具链批量实验run.py跑完后提交进仓库的聚合结果表属于冻结测试证据它记录的是某一次真实运行环境下、11 个注册模型 × 3 个目标格式的全部结论。文件开头一行记录了当时的测试设备Test device (auto-detected):npu即该次实验运行在 Ascend NPU 环境上设备自动检测机制见第 3 节。2. 矩阵本体完整表格与状态码图例以下是该文件的完整内容逐行继承原文档modelonnxptsafetensorsresnet18L-FAILL-FAILL-FAILmobilenet_v2L-FAILL-FAILL-FAILefficientnet_b0L-FAILL-FAILL-FAILmlp_mixerL-FAILL-FAILL-FAILgmlpL-FAILL-FAILL-FAILresmlpL-FAILL-FAILL-FAILswitch_base_8L-FAILL-FAILL-FAILqwen_moeL-FAILL-FAILL-FAILtoy_moeC-FAILOKmax_abs0.00e00OKmax_abs0.00e00toy_soft_moeC-FAILOKmax_abs0.00e00OKmax_abs0.00e00toy_switch_moeC-FAILOKmax_abs0.00e00OKmax_abs0.00e00图例原文逐字继承Legend: OKpass, DIFFconverted but output differs, SKIPnot applicable, C-FAILconvert failed, T-FAILtest failed, T-SKIPtest skipped, L-FAILload failed.这 7 种状态码不是随手定的它们与 run.py 中的STATUS_EMOJI映射一一对应——矩阵格子里显示的是短标签内部记录的是全名矩阵显示内部 status含义OKPASS转换成功且 round-trip 比对通过allcloseDIFFDIFF转换成功但输出差异超出容差SKIPSKIP不适用转换器抛出 NotImplementedErrorC-FAILCONVERT_FAIL转换阶段本身失败T-FAILTEST_FAIL转换成功但产物复测阶段失败T-SKIPTEST_SKIP复测被跳过L-FAILLOAD_FAIL源模型加载失败还没走到转换矩阵的写盘逻辑在 run.py 的 write_matrix()行顺序取自注册表REGISTRY的插入顺序列固定为TARGET_FORMATS [onnx, pt, safetensors]见 registry.py当某格带 diff 数据时会在标签后追加br/max_abs...格式化为两位有效数字的科学计数法。每跑完一个模型就会立即重写一次矩阵文件因此矩阵天然支持部分进度累积——main() 启动时还会先读回references/results/*.json里的历史结果合并进来。3. Test device: npu 是怎么来的设备自动检测矩阵首行的设备标签由pick_device()在运行启动时确定。device_util.py 的检测优先级为NPU CUDA/ROCm XPU MPS CPUNPU 通过torch.npu.is_available()或尝试导入torch_npu判定结果会缓存进模块级变量_CACHED整个进程内只检测一次。两个细节值得注意强制覆盖环境变量CONVERT_EXP_DEVICEnpu|cuda|xpu|mps|cpu可覆盖自动检测若指定的设备不可用会直接抛错并列出可用设备而不是静默回退。ORT 执行器独立选择ONNX 产物复测走 onnxruntimeonnxruntime_providers() 按Tensorrt → CUDA → ROCm/MIGraphX → CANN(Ascend NPU) → QNN → Dml → CoreML → OpenVINO → Xnnpack → CPU的优先级从本机已安装的 provider 中挑选。也就是说即使 PyTorch 侧跑在 NPU 上ONNX 侧实际用哪个执行器取决于 ORT 的构建形态。比对阶段对设备同样敏感compare.py 的 reference_output() 会把模型临时搬上加速器算参考输出再恢复回 CPU——因为后续 ONNX/TorchScript 导出假定模型在 CPU 上若加速器 OOM统一内存主机上常见则自动回退 CPU 继续跑保证转换流程不因显存中断。4. 矩阵里的 11 个模型注册表与加载器矩阵每一行对应 registry.py 中REGISTRY的一个条目共 11 个模型、3 个类别cnn / mlp / moe类别模型来源仓库 id加载器输入cnnresnet18HFmicrosoft/resnet-18image-classification图像 (1,3,224,224)cnnmobilenet_v2HFgoogle/mobilenet_v2_1.0_224image-classification图像 (1,3,224,224)cnnefficientnet_b0timmtimm/efficientnet_b0.ra_in1ktimm图像 (1,3,224,224)mlpmlp_mixertimmtimm/mixer_b16_224.goog_in21k_ft_in1ktimm图像 (1,3,224,224)mlpgmlptimmtimm/gmlp_s16_224.ra3_in1ktimm图像 (1,3,224,224)mlpresmlptimmtimm/resmlp_12_224.fb_in1ktimm图像 (1,3,224,224)moeswitch_base_8HFgoogle/switch-base-8seq2seq-lm文本 promptmoeqwen_moeHFQwen/Qwen1.5-MoE-A2.7Bcausal-lm文本 promptsize_warning_gb: 14moetoy_moe / toy_soft_moe / toy_switch_moetoy本地本地构建toy张量 (2,64)加载器由 loaders.py 的 load() 分发统一返回(model, sample_input, meta)三元组image-classification / seq2seq-lm / causal-lm走transformers自动类加载并用TensorOutputAdapter、_CausalLogits这类薄包装把 HF 的 dataclass 输出剥成裸 logits、把输入固定成位置参数签名保证三种格式走同一条导出路径timmtimm.create_model(name, pretrainedTrue)causal-lm默认以fp16 low_cpu_mem_usageTrue加载可用CONVERT_EXP_DTYPE覆盖为 float16/bfloat16/float32这是针对统一内存主机上 14B 模型 fp32 加载爆 RAM 的对策toy不下载任何东西直接实例化 toy_moe.py 里三个用随机权重的小型 MoE 分类器TopKMoEtop-k2 门控、SoftMoE所有专家全加权、SwitchMoEtop-1 门控。build_toy()固定torch.manual_seed(42)输入为torch.randn(2, 64)——权重与输入完全确定性这正是第 5 节零差异结果的关键。注册表还提供了by_category()辅助函数qwen_moe条目带size_warning_gb: 14提醒 7B 量级 LLM 下载前需要向用户确认磁盘与时间成本。5. 逐行解读本矩阵L-FAIL、C-FAIL 与零差异 OK8 个 HF/timm 模型整行 L-FAIL。从源码结构看这对应 process_model() 中的加载分支源模型加载load()对 HF/timm 模型意味着从远端下载权重并实例化抛异常后三个目标格式会被统一标记为LOAD_FAIL并直接返回因此这些行连转换都未开始。值得注意的是该分支不会写每模型明细 JSONJSON 落盘在 L169-L170 的格式循环之后这与仓库references/results/目录下只提交了 3 个 toy 模型 JSON 的事实完全吻合。从源码结构看加载阶段的常见诱因是网络下载失败或依赖缺失但该文件本身未记录具体错误信息此处不做断言。3 个 toy 模型的 onnx 列为 C-FAIL。明细 toy_moe.json 给出了确切原因onnx: { status: CONVERT_FAIL, error: OnnxExporterError(Module onnx is not installed!) }即冻结这份证据的运行时没有安装onnx包——这是环境缺包问题而不是 ONNX 导出逻辑本身的缺陷pt 与 safetensors 两条路径不依赖 onnx 模块所以正常通过。toy 模型的 pt / safetensors 列为OK且max_abs0.00e00。明细 JSON 同时给出了耗时与产物体积pt 转换 0.35 s、产物 0.3 MBsafetensors 转换 0.0 s、产物 0.27 MB两者diff均为max_abs0.0, mean_abs0.0, max_rel0.0, allclosetrue。零差异的成因是双重的build_toy()固定随机种子使源模型确定而 ptTorchScript与 safetensors 的 round-trip 本质是权重的精确往返同一份权重在同一设备上 forward 结果逐位一致。对比判据本身由 compare.py 的 diff() 定义两端输出展平后以 float64 计算逐元素绝对/相对误差非有限值且非同符号无穷计为 invalid 并强制allclosefalse返回max_abs / mean_abs / max_rel / p50 / p95 / p99 / top_mismatch(前 5 个最大误差索引) / allclose等字段判定阈值默认atol1e-4, rtol1e-3。SKILL.md 同时给出了实践预期在 opset 差异、动态轴、dtype 转换下1e-4 ~ 1e-3 量级的漂移属正常应把矩阵中的max_abs作为第一信任信号CUDA 上由于 cudnn 重复 forward 有约 5e-4 噪声port.py会把容差放宽到atol5e-3CPU 校验仍用atol1e-4。6. 复现与刷新矩阵环境、命令与产物布局6.1 环境检查python -c import torch, onnx, onnxruntime, safetensors, onnx2torch; print(ok)依赖来自 requirements.txt按 SKILL.md 的划分用途依赖必装torch2.5, transformers4.46, onnx, onnxruntime, safetensorsonnx - pt / safetensorsonnx2torchsafetensors I/Otimm 或 transformers用于实例化 HF 仓库的架构6.2 批量实验生成/刷新矩阵# registry 中全部 11 个模型 python scripts/run.py # 只跑子集 python scripts/run.py mobilenet_v2 toy_moe注意路径约定run.py/port.py需以 scripts/ 目录为工作目录执行脚本内用Path(__file__).resolve().parent.parent定位 skill 根目录。6.3 单模型转换port.py# pt - onnxTorchScript 自包含只需 --input-shape python scripts/port.py model.pt out.onnx --input-shape 1,3,224,224 # safetensors - onnx仅权重架构经 HF repo 提供 python scripts/port.py model.safetensors out.onnx \ --hf-repo google/mobilenet_v2_1.0_224 # onnx - pt经 onnx2torch 重建计算图 python scripts/port.py model.onnx out.pt --input-shape 1,3,224,224常用选项--input-format/--output-format覆盖扩展名推断--hf-repo为 safetensors 端提供架构--skip-verify关闭 round-trip 校验超大模型-v输出各阶段计时、两端 forward 的 min/max/mean/std/first5 统计、diff 分布p50/p95/p99与 top-5 mismatch 索引。退出码语义0PASS、1DIFF转出但差异超容差、2转换失败。6.4 产物布局冻结证据提交进仓库references/matrix.md聚合表references/results/model.json每模型明细含 convert_seconds、artifact 路径、size_mb、diff。运行时产物gitignore默认位于~/.cache/pypto-convert-model/可用$CONVERT_MODEL_WORKDIR覆盖内含models/HF/timm 下载缓存、outputs/model/fmt/转换产物、logs/master.loglogs/model__format.log运行日志。6.5 已知限制与新增模型解读矩阵前应了解 SKILL.md 记录的四条限制transformers5的 attention 路径回归会导致 transformer-MoESwitch-T、Qwen-MoE的 onnx/pt 导出失败safetensors 权重路径始终可用绕过办法是降级transformers5或只走 safetensorsCUDA fp32 非确定性噪声aarch64 无onnxruntime-gpu轮子导致 ORT 回退 CPU统一内存主机的 RAM 压力已由 fp16 默认加载缓解。新增模型的固定动作在 registry.py 增加条目CNN 用image-classification或timm加载器transformer LM 用causal-lm/seq2seq-lm自定义架构用toy类别并按 toy_moe.py 的写法定义模块然后重新运行run.py刷新矩阵。转换逻辑一律复用 converters.py 中注册到CONVERTERS字典的函数不要另起炉灶。7. 小结matrix.md 不是一张静态结果表而是registry → load → convert → round-trip test → write_matrix整条流水线的可审计终点8 行 L-FAIL 说明那次实验的远端加载未成功3 行 toy 证据则以max_abs0.00e00证明了 pt/safetensors 往返的位级一致性onnx 列的 C-FAIL 则精确定位到运行环境缺onnx包。当你拿到一份新的矩阵时按先看设备行、再按状态码分层排查L-FAIL 查加载与网络、C-FAIL 查转换依赖、T-FAIL 查产物加载、DIFF 查 max_abs 与 opset/dtype、最后对照results/model.json取明细的顺序阅读就能快速定位问题所在阶段。【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考