深入解析 coremltools 捆绑的 Protocol Buffers:序列化原理、protoc 安装与多语言运行时集成
深入解析 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 的典型工作流程分为两步:
- 编译期:用
protoc编译.proto文件,为选定语言生成数据访问类; - 运行期:使用对应语言的 protobuf 运行时库(runtime),调用生成的类完成序列化/反序列化。
因此,安装 protobuf 需要同时安装两部分:协议编译器 protoc(用于编译 .proto 文件)和所选编程语言的运行时库。
仓库捆绑版本与布局
本仓库在 deps/protobuf 目录下完整捆绑了一份 protobuf 源码。从 deps/protobuf/configure.ac 的 AC_INIT 与 deps/protobuf/protobuf_version.bzl 可以确认,捆绑版本为 protobuf 3.19.0。它包含:
- deps/protobuf/src:C++ 运行时源码与
protoc编译器源码(含全部google/protobuf/*.proto标准定义); - deps/protobuf/python:Python 运行时库源码;
- deps/protobuf/java、deps/protobuf/objectivec、deps/protobuf/csharp、deps/protobuf/js、deps/protobuf/ruby、deps/protobuf/php:其他语言的运行时;
- deps/protobuf/cmake:面向 MSVC/Windows 的 CMake 构建配置;
- deps/protobuf/examples:跨语言地址簿示例(
addressbook.proto及多种语言实现)。
在 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 才能使用(因为生成代码依赖编译器)。
安装步骤如下:
- 确认 Python 3.5 或更新版本:
python -V; setuptools会在运行setup.py时自动下载安装(也可手动安装);- 构建 C++ 代码,或安装与包版本完全一致的
protoc二进制,可用protoc --version核对; - 构建并运行测试:
python setup.py build
python setup.py test
- 安装:
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 文件,例如:
- mlmodel/format/Model.proto:模型容器,定义
Model、Pipeline、FeatureDescription等顶层消息,并import public引用了 CustomModel、LinkedModel 等子规范; - mlmodel/format/MIL.proto:ML Program 的中间语言定义,声明
Program、Function、Block、Operation等消息,并写明标识符必须匹配正则[A-Za-z\_][A-Za-z0-9\_@]*; - mlmodel/format/FeatureTypes.proto、mlmodel/format/NeuralNetwork.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:
- coremltools/models/model.py 中
MLModel构造时可接受Model_pb2对象(isinstance(model, _proto.Model_pb2.Model)分支),get_spec()返回模型规格的深拷贝; - 保存
.mlpackage时,coremltools/models/utils.py 用proto_spec.SerializeToString()把模型规格序列化后写入包内根模型文件; - coremltools/converters/mil/frontend/milproto/load.py 加载 ML Program 时逐层消费
MIL_pb2的Program/Function/Block/Operation消息,把二进制规格转录为 Python 侧的 MIL 中间表示。
与 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 构建目标的说明。