深入解析 coremltools 捆绑的 Protocol Buffers:序列化原理、protoc 安装与多语言运行时集成

原创2026-10-12 18:31:501,860 阅读
文章标签:AI 应用机器学习模型优化

深入解析 coremltools 捆绑的 Protocol Buffers:序列化原理、protoc 安装与多语言运行时集成

导读

本文以 deps/protobuf/README.md 为核心脉络,系统讲解 Google Protocol Buffers(protobuf)这套语言中立、平台中立、可扩展的结构化数据序列化机制:从 protoc 协议编译器与各语言运行时的安装方式,到其在本仓库 coremltools 中的真实落地——Core ML 模型规范(.proto 定义)正是依赖它完成 C++ 与 Python 两侧的代码生成、模型规格的序列化与反序列化。读完本文,你将掌握 protoc 的安装与源码构建、Python 运行时及 C++ 加速实现的使用,并理解 protobuf 如何支撑 coremltools 的模型转换与保存链路。

Protocol Buffers 是什么

Protocol Buffers(简称 protobuf)是 Google 设计的一种语言中立(language-neutral)、平台中立(platform-neutral)、可扩展(extensible)的结构化数据序列化机制。开发者先用 .proto 文件描述数据结构(message),再通过协议编译器 protoc 为不同编程语言生成读写代码;生成的代码可以把结构化对象高效地序列化为紧凑的二进制字节流,或从字节流反序列化还原。

protobuf 的典型工作流程分为两步:

  1. 编译期:用 protoc 编译 .proto 文件,为选定语言生成数据访问类;
  2. 运行期:使用对应语言的 protobuf 运行时库(runtime),调用生成的类完成序列化/反序列化。

因此,安装 protobuf 需要同时安装两部分:协议编译器 protoc(用于编译 .proto 文件)和所选编程语言的运行时库。

仓库捆绑版本与布局

本仓库在 deps/protobuf 目录下完整捆绑了一份 protobuf 源码。从 deps/protobuf/configure.ac 的 AC_INIT 与 deps/protobuf/protobuf_version.bzl 可以确认,捆绑版本为 protobuf 3.19.0。它包含:

在 coremltools 中,这份捆绑源码并不是孤立的第三方代码:它被顶层构建系统直接消费,用于生成 Core ML 模型规范所需的 C++ 与 Python 代码(详见后文"protobuf 在 coremltools 中的深度集成")。

安装 Protocol Compiler(protoc)

protoc 编译器本身用 C++ 编写。安装它有两种途径:下载预编译二进制,或从源码自行构建。

方式一:下载预编译二进制(非 C++ 用户推荐)

对于不使用 C++ 的用户,最简单的方式是从 protobuf 官方发布页下载预编译二进制。每个 release 的下载区都提供了 zip 包 protoc-$VERSION-$PLATFORM.zip,其中既包含 protoc 可执行文件,也包含随 protobuf 分发的标准 .proto 文件(如 google/protobuf/timestamp.proto、descriptor.proto 等,供 .proto 文件中的 import 使用)。

若所需旧版本不在发布页,可到 Maven 仓库的 com.google.protobuf/protoc 目录查找。需要说明:预编译二进制只为已发布版本提供。如果要用未发布的 master 分支(HEAD)代码、需要修改 protobuf 源码,或本身就是 C++ 用户,则推荐从源码自行构建 protoc。

方式二:从源码构建 C++ 版本(Unix)

完整构建步骤记录在 deps/protobuf/src/README.md 中。首先需要以下工具:

  • autoconf、automake、libtool、make、g++、unzip

在 Ubuntu/Debian 上,可用一条命令装齐:

sudo apt-get install autoconf automake libtool curl make g++ unzip

其他平台请用对应的包管理工具安装后再继续。

获取源码有两种途径:下载发布页的 protobuf-cpp-[VERSION].tar.gz(仅 C++)、protobuf-java-[VERSION].tar.gz(含 C++ 与 Java,每个包都已包含 C++ 源码)或 protobuf-all-[VERSION].tar.gz(C++ 与多种语言);或直接 git clone 仓库并补齐子模块、生成 configure 脚本:

git clone https://github.com/protocolbuffers/protobuf.git
cd protobuf
git submodule update --init --recursive
./autogen.sh

使用 release 的 .tar.gz / .zip 包时无需执行 autogen.sh。

随后构建并安装 C++ 运行时与 protoc:

./configure
make
make check
sudo make install
sudo ldconfig   # 刷新共享库缓存

如果 make check 失败,仍然可以安装,但该库的部分功能很可能无法在你的系统上正常工作,建议谨慎对待。

关于安装位置的提示:默认安装到 /usr/local,但很多平台上 /usr/local/lib 不在 LD_LIBRARY_PATH 中。可以手动加入,也可以直接装到 /usr:

./configure --prefix=/usr

注意:若此前用其他 prefix 构建过,需先执行 make clean 再重新构建。

用 pkg-config 编译依赖 protobuf 的包:自 protobuf 2.2.0 起支持 pkg-config 集成,可用它获取编译/链接参数:

pkg-config --cflags protobuf         # 打印编译器参数
pkg-config --libs protobuf           # 打印链接器参数
pkg-config --cflags --libs protobuf  # 两者都打印

示例:

c++ my_program.cc my_proto.pb.cc `pkg-config --cflags --libs protobuf`

对于 autoconf 系的项目,可在其 configure 时强制传入正确参数:

configure CXXFLAGS="$(pkg-config --cflags protobuf)" \
          LIBS="$(pkg-config --libs protobuf)"

或在其 configure.ac 中使用 PKG_CHECK_MODULES([protobuf], [protobuf]) 宏。若只想使用精简版 protobuf-lite,把上述命令中的 protobuf 替换为 protobuf-lite 即可。

Windows 构建

只想要 protoc 二进制时,可从发布页下载 protoc-$VERSION-win32.zip,内含 protoc 可执行文件与 protobuf 公共 proto 文件。若使用 vcpkg,可直接安装:

>vcpkg install protobuf protobuf:x64-windows

需要 zlib 支持时追加特性:

>vcpkg install protobuf[zlib] protobuf[zlib]:x64-windows

用 Visual C++ 从源码构建的具体步骤见 deps/protobuf/cmake/README.md(含 VS 命令提示符环境准备、mkdir install、安装目录规划等细节);Cygwin 或 MinGW 用户则遵循上文 Unix 安装步骤。

交叉编译注意事项

makefile 默认会直接执行刚构建出的 protoc 来构建测试。交叉编译时,刚生成的 protoc 可能无法在宿主机器上运行,此时需要先在宿主机构建一份 protoc,再用 --with-protoc 告诉 configure 使用它:

./configure --with-protoc=protoc          # 使用 $PATH 中已安装的 protoc
./configure --with-protoc=../host/src/protoc  # 或使用宿主机构建的未安装版本

关键约束:所用 protoc 的版本必须与要编译的 protobuf 源码版本一致。

各语言运行时安装速查

protobuf 支持多种编程语言,每种语言在对应源码目录下都有独立安装说明。下表整理了本仓库各语言的运行时源码位置:

语言 源码目录
C++(含 C++ 运行时与 protoc) deps/protobuf/src
Java deps/protobuf/java
Python deps/protobuf/python
Objective-C deps/protobuf/objectivec
C# deps/protobuf/csharp
JavaScript deps/protobuf/js
Ruby deps/protobuf/ruby
Go 独立项目 protocolbuffers/protobuf-go(不随本仓库分发)
PHP deps/protobuf/php
Dart 独立项目 dart-lang/protobuf(不随本仓库分发)

Go 与 Dart 的运行时由各自独立项目维护,需要另行获取,本仓库捆绑目录中不包含这两者的实现源码。

Python 运行时安装与 C++ 加速实现

Python 运行时的完整安装说明在 deps/protobuf/python/README.md。该目录通常随 protobuf 完整包一起分发;如果是从 PyPI 等仅含 Python 部分的渠道下载,则需要另行获取 protoc 才能使用(因为生成代码依赖编译器)。

安装步骤如下:

  1. 确认 Python 3.5 或更新版本:python -V;
  2. setuptools 会在运行 setup.py 时自动下载安装(也可手动安装);
  3. 构建 C++ 代码,或安装与包版本完全一致的 protoc 二进制,可用 protoc --version 核对;
  4. 构建并运行测试:
python setup.py build
python setup.py test
  1. 安装:
python setup.py install

关于 C++ 实现(性能关键)

纯 Python 实现性能较慢,文档明确建议使用 Python 的 C++ 实现以获得更好性能。C++ 实现是作为 Python 扩展构建的,前提是先编译出 libprotobuf.so:

(cd .. && make)

在 OS X 上若使用 Homebrew 提供的 Python,需要先处理 /usr/local/lib 中可能已安装的旧 protobuf(否则 Python 会优先搜索到它而非刚构建的 ../src/.libs):

brew unlink protobuf
# 或
(cd .. && make install)

在其他 *nix 上,可通过安装刚构建的 libprotobuf 或设置环境变量来使其动态可见:

export LD_LIBRARY_PATH=../src/.libs

随后构建并测试 C++ 实现:

python setup.py build --cpp_implementation
python setup.py test --cpp_implementation

安装时同样带上对应选项:

(cd .. && make install)
python setup.py install --cpp_implementation

使用 C++ 实现前必须导出环境变量,运行时库才会实际采用 C++ 后端(详见该目录 README 的 "C++ Implementation" 一节)。

快速上手:跨语言地址簿示例

学习 protobuf 最有效的方式是动手跑官方示例。deps/protobuf/examples 目录提供了一套地址簿(address book)示例:add_person 程序交互式地把一个人写入地址簿,list_people 程序读出并打印所有人。所有语言共用同一份数据格式,因此可以用 Java 版写入、再用 Python 版读取,这正是 protobuf 跨语言特性的直观体现。

核心定义在 deps/protobuf/examples/addressbook.proto:

syntax = "proto3";
package tutorial;

import "google/protobuf/timestamp.proto";

message Person {
  string name = 1;
  int32 id = 2;
  string email = 3;

  enum PhoneType {
    MOBILE = 0;
    HOME = 1;
    WORK = 2;
  }

  message PhoneNumber {
    string number = 1;
    PhoneType type = 2;
  }

  repeated PhoneNumber phones = 4;
  google.protobuf.Timestamp last_updated = 5;
}

message AddressBook {
  repeated Person people = 1;
}

其中 repeated 表示可重复字段(对应数组/列表),= 1/2/3... 是字段编号(序列化时用于标识字段)。注意顶部的 import "google/protobuf/timestamp.proto",使用标准类型时编译器需要能找到随 protobuf 分发的公共 proto 文件——这也是上文强调预编译 zip 附带标准 .proto 文件的原因。

以 deps/protobuf/examples/add_person.py 为例,写入数据的两条核心 API 是 ParseFromString(从字节流读取)与 SerializeToString(序列化为字节流):

# Read the existing address book.
with open(sys.argv[1], "rb") as f:
    address_book.ParseFromString(f.read())

# Add an address.
PromptForAddress(address_book.people.add())

# Write the new address book back to disk.
with open(sys.argv[1], "wb") as f:
    f.write(address_book.SerializeToString())

对应地,deps/protobuf/examples/list_people.py 遍历 address_book.people 并按 PhoneType 枚举区分移动/家庭/工作电话。这两个脚本展示了 protobuf 运行时的核心使用模式:生成类 + ParseFromString/SerializeToString——这一模式与 coremltools 内部对模型规格的读写方式完全一致(见下文)。

protobuf 在 coremltools 中的深度集成

捆绑这份 protobuf 源码并非偶然,它是 coremltools 构建链路的基石。Core ML 模型文件(.mlmodel / .mlpackage)本质上就是 protobuf 序列化后的模型规格,整个转换、保存、校验流程都建立在 protobuf 之上。

构建系统集成:作为子项目编译

deps/CMakeLists.txt 将 protobuf 的 CMake 目录以子项目方式纳入构建:

set(protobuf_BUILD_TESTS OFF CACHE BOOL "Build tests")
add_subdirectory(protobuf/cmake EXCLUDE_FROM_ALL)
set_property(TARGET libprotobuf PROPERTY POSITION_INDEPENDENT_CODE ON)
set_property(TARGET libprotobuf-lite PROPERTY POSITION_INDEPENDENT_CODE ON)

这里关闭了 protobuf 自带的测试构建,并显式把 libprotobuf、libprotobuf-lite 设为位置无关代码(PIC),以便它们能被链接进共享库。顶层 CMakeLists.txt 随后将 deps/protobuf/src 加入头文件搜索路径并链接 libprotobuf。

模型规范:仓库中的 .proto 定义

coremltools 的模型格式定义在 mlmodel/format 目录,包含 30 余个 .proto 文件,例如:

从源码结构看,这些 proto3 文件是模型文件二进制布局的"真源":protoc 从它们生成 C++ 与 Python 两侧代码,保证两端看到的是同一份规范。

代码生成流水线:protoc 的实战用法

mlmodel/CMakeLists.txt 中列出了全部需要编译的 proto 文件(set(proto_files ...),共 33 个),随后对每个文件调用 cmake/coreml-utils.cmake 中定义的 coreml_add_build_proto 函数。该函数展示了 protoc 三种典型输出模式:

COMMAND ${CMAKE_BINARY_DIR}/deps/protobuf/cmake/protoc
    --cpp_out=${CMAKE_CURRENT_BINARY_DIR}/format/        # C++ 代码
    -I${CMAKE_CURRENT_SOURCE_DIR}/format
    ${CMAKE_CURRENT_SOURCE_DIR}/format/${proto_fn}.proto

COMMAND ${CMAKE_BINARY_DIR}/deps/protobuf/cmake/protoc
    --plugin=protoc-gen-enum=mlmodel/enumgen              # 自定义插件生成枚举头
    --enum_out=${CMAKE_CURRENT_BINARY_DIR}/format/

COMMAND ${CMAKE_BINARY_DIR}/deps/protobuf/cmake/protoc
    --python_out=${CMAKE_BINARY_DIR}/coremltools.../proto # Python 代码
    -I${CMAKE_CURRENT_SOURCE_DIR}/format/

三个命令分别生成:.pb.cc/.pb.h(C++ 运行时类)、_enum.h(借助自定义插件 protoc-gen-enum 生成 C++ 枚举)、_pb2.py(Python 类)。C++ 侧生成结果被 mlmodel/src/Format.hpp 直接引用:

#include <google/protobuf/text_format.h>
#include <google/protobuf/io/coded_stream.h>
#include <google/protobuf/io/zero_copy_stream_impl.h>
#include "../build/format/Model.pb.h"
#include "../build/format/Model_enums.h"

此外还定义了 OVERWRITE_PB_SOURCE 选项(默认 OFF)与 protosrc 目标:开启后除构建目录外,还会把生成代码回写到源码树,便于 Core ML framework 侧直接读取源文件位置。

Python 侧消费:模型规格的读写

Python 侧生成的代码位于 coremltools/proto,例如 Model_pb2.py、MIL_pb2.py、FeatureTypes_pb2.py 等,由 coremltools/proto/init.py 统一导入。它们被广泛用于转换与模型 API:

与 PyPI protobuf 包的版本约定

作为 Python 包,setup.py 的 install_requires 声明了 protobuf >= 3.1.0,即运行时依赖用户环境中已安装的 protobuf Python 包(编译安装 coremltools 时生成的 _pb2.py 在运行期由该包解释执行)。这与捆绑的 C++ 源码(供构建期生成代码、链接原生库)形成"构建期捆绑 + 运行期依赖"的双轨结构,值得读者注意。

二进制兼容性警告

deps/protobuf/src/README.md 给出了一个重要工程约束:由于 C++ 的 ABI 特性,任意两个版本的 protobuf C++ 运行时几乎不可能拥有兼容的 ABI。即:用旧版 libprotobuf 链接出的可执行文件,换用新版库运行时大概率需要重新编译,否则应用启动阶段就会检测到问题。若希望规避,可只安装静态库:

./configure --disable-shared

这一约束也是 coremltools 选择在 deps 中捆绑固定版本(3.19.0)的原因之一:保证构建产物与生成代码、原生库之间版本严格一致,避免 ABI 错配。

小结

从 deps/protobuf/README.md 出发可以看到:Protocol Buffers 是一套"定义一次、多语言生成"的序列化方案,安装 = 安装 protoc 编译器 + 安装目标语言运行时;而它在 coremltools 中并非普通依赖,而是模型文件格式本身。理解 protoc 的三种输出(C++、自定义插件、Python)、ParseFromString/SerializeToString 这对核心 API,以及构建系统中 deps/CMakeLists.txt、cmake/coreml-utils.cmake、mlmodel/CMakeLists.txt 的协作关系,你就能从"模型文件到底是什么"的层面深入 coremltools 的转换、保存与校验链路。若需进一步阅读,可继续深入 mlmodel/format 下的各个 .proto 规范,以及 BUILDING.md 中关于 proto 构建目标的说明。

登录后查看全文
coremltools