解决 ImportError: cannot import name 'builder' from 'google.protobuf.internal'

问题描述

在使用 Python 的 Protocol Buffers (protobuf) 库时，用户遇到了以下导入错误：

ImportError: cannot import name 'builder' from 'google.protobuf.internal'

这个错误通常出现在以下场景中：

• 使用 TensorFlow 进行对象检测任务时
• 运行 TensorFlow 记录生成脚本时
• 安装或升级 protobuf 库后

典型的错误堆栈跟踪如下：

Traceback (most recent call last):
  File "generate_tfrecord.py", line 29, in <module>
    from object_detection.utils import dataset_util, label_map_util
  File "...\label_map_util.py", line 29, in <module>
    from object_detection.protos import string_int_label_map_pb2
  File "...\string_int_label_map_pb2.py", line 5, in <module>
    from google.protobuf.internal import builder as _builder
ImportError: cannot import name 'builder' from 'google.protobuf.internal'

问题根源

这个错误的主要原因与 protobuf 库的版本兼容性有关。从 protobuf v3.20.0 开始，Python 类的生成方式进行了重构，使用动态创建的方式来生成描述符和消息类定义，而这些功能现在位于 internal/builder.py 文件中。

当 protobuf 库的版本与生成的 .pb2.py 文件不兼容时，就会出现找不到 builder 模块的错误。

解决方案

方法一：升级 protobuf 版本（推荐）

最简单直接的解决方法是升级到最新版本的 protobuf：

pip install --upgrade protobuf

或者使用 Python 模块方式安装：

python -m pip install --upgrade protobuf

TIP

这是最推荐的解决方案，因为它确保您使用的是最新且兼容的版本。

方法二：重新安装 protobuf

如果升级不起作用，尝试完全卸载后重新安装：

pip uninstall protobuf
pip install protobuf

方法三：安装特定版本

某些 TensorFlow 版本可能需要特定版本的 protobuf。常见的工作版本包括：

# 方案 1
pip uninstall protobuf
pip install protobuf==3.20.1

# 方案 2
pip uninstall protobuf
pip install protobuf==3.20.3

# 方案 3
pip uninstall protobuf
pip install protobuf==4.21

pip

pip install protobuf==3.20.3

conda

conda install protobuf=3.20.3

方法四：手动添加 builder.py 文件

如果上述方法都不起作用，可以手动添加缺失的 builder.py 文件：

1. 首先下载最新版本的 builder.py 文件：

wget https://raw.githubusercontent.com/protocolbuffers/protobuf/main/python/google/protobuf/internal/builder.py

2. 然后将其复制到 protobuf 的安装目录：

# 通常路径为（请根据您的实际环境调整）：
# {Python或Conda环境路径}/lib/pythonX.X/site-packages/google/protobuf/internal/

或者使用 Python 代码确定路径：

import google.protobuf.internal
print(google.protobuf.internal.__file__)

方法五：确保 protoc 编译器兼容性

确保您使用的 protoc 编译器版本与 protobuf Python 库版本兼容：

1. 从 protobuf 发布页面下载合适版本的 protoc 编译器
2. 确保 protoc 版本 ≤ protobuf Python 库版本

预防措施

为了避免将来出现类似问题：

1. 保持环境一致性：在虚拟环境中工作，确保依赖项版本一致
2. 使用固定版本：在 requirements.txt 中固定关键依赖的版本
3. 先安装系统级依赖：先安装系统级的 protobuf，再安装 Python 包
4. 避免混合使用包管理器：不要同时使用 pip 和 conda 安装同一个包

总结

ImportError: cannot import name 'builder' from 'google.protobuf.internal' 错误通常是由于 protobuf 版本不兼容引起的。推荐按照以下顺序尝试解决方案：

1. 首先尝试升级 protobuf 到最新版本
2. 如果不行，尝试重新安装 protobuf
3. 考虑安装特定兼容版本（如 3.20.x）
4. 作为最后手段，手动添加 builder.py 文件

遵循这些步骤，您应该能够成功解决这个导入错误并继续您的 TensorFlow 或 protobuf 相关项目。

INFO

如果您在使用 TensorFlow 对象检测 API，请确保所有相关包（TensorFlow、protobuf 等）的版本兼容性，这可以避免许多常见问题。