https://pypi.org/project/onnx/
https://onnx.ai/
https://github.com/onnx/onnx
https://onnxruntime.ai/
https://pypi.org/project/protobuf/
https://protobuf.com.cn/
https://github.com/protocolbuffers/protobuf#protobuf-compiler-installation
【技术分享】ComfyUI中protobuf版本兼容性问题的优雅解决方案：猴子补丁实战
告别环境崩溃：ONNX 与 Protobuf 版本兼容性指南
前言
在深度学习环境配置中，ONNX 与 Protobuf 的版本冲突几乎是每个算法工程师的"必经之路"。你是否遇到过 TypeError: Descriptors cannot not be created directly？或者是模型加载时突然 Segmentation fault？
这一切的根源在于 Protobuf 在 3.20 版本后经历了一次破坏性的架构升级。本文将基于 ONNX 官方源码和 Release 记录，梳理出一份最权威的兼容性对照表。
一、 为什么 ONNX 对 Protobuf 版本如此敏感？
ONNX（Open Neural Network Exchange）本质上是一种使用 Protobuf (Protocol Buffers) 定义的序列化格式。
-
编译期依赖 ：ONNX 的
.proto文件需要通过protoc编译器生成 C++/Python 代码。 -
运行期依赖 ：Python 环境中的
protobuf库负责解析模型文件。
当 Protobuf 从 3.x 升级到 4.x（也称为 v21.0）时，其内部 C++ 实现和 Python API 发生了重大变化，导致旧版本的 ONNX 无法直接调用新版的 Protobuf 描述符。
二、 ONNX 与 Protobuf 版本兼容性矩阵
根据对 ONNX 官方 requirements.txt 和 GitHub Issue 的追踪，整理出如下对应关系：
| ONNX 版本 | 推荐 Protobuf 版本 | 兼容性状态 | 核心依据/引用 |
|---|---|---|---|
| 1.17.0 - 1.18+ | >= 4.25.1 | 原生支持 | ONNX Main Requirements |
| 1.13.0 - 1.16.x | 3.20.2 - 3.20.3 | 黄金组合 | Issue #4239 |
| 1.12.0 | 3.12.2 - 3.20.1 | 分水岭 | v1.12.0 Tag Deps |
| 1.8.0 - 1.11.0 | 3.12.x - 3.16.0 | 旧版稳定 | ONNX v1.10 Release |
三、 关键转折点与官方依据
1. Protobuf 4.x 的"破坏性"引入 (ONNX 1.13.0)
在 ONNX 1.13.0 之前，安装 Protobuf 4.x 会导致严重的 API 报错。官方在 Issue #4239 中深入讨论了如何适配 Protobuf 4.21+。
- 结论 ：如果你必须使用旧版 ONNX，请务必锁定
pip install protobuf==3.20.3。
2. Python 3.12 时代的强制升级 (ONNX 1.16.0+)
随着 Python 3.12 成为主流，旧版的 Protobuf 3.x 在编译时会出现兼容性问题。
- 依据 ：在 GitHub PR #6198 中，维护者提升了最小依赖版本至 4.25.1，以确保在现代编译器和 Python 版本下的稳定性。
四、 避坑指南：如何配置你的环境？
场景 A：追求最稳（生产环境）
如果你希望兼容大多数现有的 PyTorch/TensorFlow 转换工具：
例如
pip install onnx==1.14.0 protobuf==3.20.2或
pip install onnx==1.14.1 protobuf==3.20.3场景 B：使用较新 Python (3.12+)
必须拥抱新版本，新版本通常有大量修复，但也不能过新，否则会出现未适配等编译错误：
pip install onnx>=1.16.0 protobuf>=4.25.1场景 C：遇到 Descriptors 报错的紧急修复
如果环境已乱，无法重装，可尝试设置环境变量（临时开启兼容模式）：
# Linux/Mac
export PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=python
# Windows Powershell
$env:PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION="python"五、 总结与引用资料
配置环境时，最权威的依据永远是 ONNX 源码仓库中的 Tag 分支。
参考链接：
-
ONNX 官方版本发布日志 : GitHub Releases
-
Protobuf 升级适配讨论 : ONNX Issue #4239
-
Python 依赖定义文件 : ONNX requirements.txt
博主提示 ：在多 AI 框架共存的环境（如同时安装了 TensorFlow, PyTorch, PaddlePaddle）中，建议优先查看各框架对 Protobuf 的共同要求，通常 3.20.3 是目前兼容性跨度最广的"神仙版本"。