PaddleSpeech C++ 推理引擎（runtime）构建指南：环境准备、CMake 构建流程与常见编译错误排查

• 人工智能
• 语音
• 音频
• NLP
• 媒体生成

本文以 PaddleSpeech 仓库runtime/目录的部署文档为骨架，完整讲解如何在 Docker 环境中准备构建依赖、通过build.sh编译 C++ 推理引擎与示例程序、在 Android/iOS 平台交叉编译，并针对文档 FAQ 中列出的五类典型错误（No module named 'paddle'、libpaddle.so加载失败、libgfortran缺失等）给出基于源码的定位原理与可复制的解决方案。读完本文，你可以独立完成从环境创建到运行u2pp_ol流式 ASR 示例的完整部署流程，并能自行排查编译/运行期的链接问题。

一、runtime 模块的定位与整体构建结构

PaddleSpeech 的runtime/目录是纯 C++ 部署侧代码，负责把 Python 训练得到的声学模型（.pdmodel等）编译为可在服务端和移动端运行的可执行程序。从源码结构看，runtime/的核心组成如下：

• runtime/CMakeLists.txt：顶层 CMake 入口，负责探测 Paddle 链接参数、拉取第三方库（gflags、glog、pybind、FastDeploy、openfst 等）并汇总构建选项；
• runtime/engine/：引擎源码，其中engine/asr/包含解码器（CTC 前缀束搜索、TLG 解码器）、神经网络推理模块（u2_nnet、u2_onnx_nnet）、识别器（recognizer）与 WebSocket 服务端（asr/server/websocket/）；engine/common/frontend/包含流式特征前端（Fbank、CMVN、db_norm分贝归一化、音频组装器assembler等）；engine/kaldi/内置了 Kaldi 风格的矩阵、Lattice、FST 工具代码；engine/audio_classification/与engine/vad/分别对应音频分类（PANNs）与 VAD 推理。各子模块按 CMake 开关独立参与编译；
• runtime/examples/：可运行的示例工程，官方推荐u2pp_ol（u2++ 流式 ASR，基于 aishell-1 测试集），另有ds2_ol、vad/、android/、audio_classification/、custom_asr/、text_lm/等；
• runtime/tools/：构建辅助脚本，包括venv.sh（创建 Python 虚拟环境）、setup_valgrind.sh（源码安装 Valgrind）、clang-format.sh；
• runtime/cmake/：第三方库的 FetchContent 封装与构建摘要输出；
• runtime/build.sh、runtime/build_android.sh、runtime/build_ios.sh：x86 Linux、Android、iOS 三套构建脚本。

顶层CMakeLists.txt定义了引擎版本号PPS_VERSION = 1.0.0（见 runtime/CMakeLists.txt），统一使用 C++14、默认Release构建类型（Ninja 生成器例外），安装目录固定为build/*/install（CMAKE_INSTALL_PREFIX，见 runtime/CMakeLists.txt）。构建完成后还会通过 CPack 打包为paddlespeech_libraryTGZ 源码包。

engine/CMakeLists.txt展示了模块间的编译依赖关系：kaldi与common无条件构建，而asr、audio_classification、vad分别受WITH_ASR、WITH_CLS、WITH_VAD开关控制（见 runtime/engine/CMakeLists.txt）。这一点对交叉编译很关键——移动端构建通常只保留 VAD 模块。

二、开发环境要求（推荐 Docker）

runtime/README.md给出的开发环境基线为：

文档明确建议：所有构建在 PaddlePaddle 官方 Docker 镜像中验证通过，推荐在 Docker 中进行开发与部署。启动容器的命令为：

docker run --privileged --net=host --ipc=host -it --rm \ -v /path/to/paddlespeech:/workspace --name=dev \ registry.baidubce.com/paddlepaddle/paddle:2.2.2-gpu-cuda10.2-cudnn7 /bin/bash

几点需要注意：

1. --privileged参数在后续使用 Valgrind 时是必需的（见第六节），建议首次启动即带上；
2. 工作目录挂载为/workspace，与CMakeLists.txt中的路径注释保持一致；
3. 构建脚本本身并不要求 GPU，WITH_GPU选项默认为OFF（runtime/CMakeLists.txt），即 C++ 引擎默认按 CPU 推理编译。

2.1 创建 Python 虚拟环境

CMake 配置阶段需要调用 Python 解释器去查询已安装 PaddlePaddle 的头文件与库路径（原理见下一节），因此必须先创建虚拟环境并安装 Paddle。仓库中实际的创建脚本是 runtime/tools/venv.sh：

bash tools/venv.sh # 等价于：virtualenv -p python3.8 venv source venv/bin/activate

该脚本用python3.8创建名为venv的虚拟环境（已存在则跳过），与文档中 “Python >= 3.8” 的要求对应。

三、构建 C++ 引擎与示例（build.sh 详解）

3.1 安装 PaddlePaddle

文档提醒：由于使用了 Paddle 的特定特性，构建 C++ 引擎需要安装指定版本的paddlepaddle（文档 FAQ 中给出的最低要求是paddlepaddle >= 2.4rc，构建示例中安装 2.4.2）：

source venv/bin/activate python -m pip install paddlepaddle==2.4.2 -i https://mirror.baidu.com/pypi/simple ./build.sh

3.2 build.sh 的参数逐项说明

runtime/build.sh 的实际执行流程是“创建构建目录 → 配置 CMake → 并行编译”：

BUILD_TYPE=Release # 可改为 Debug BUILD_SO=OFF # -DBUILD_SHARED_LIBS=OFF，引擎编译为静态库/可执行程序 BUILD_ONNX=ON # u2 模型支持 ONNX Runtime BUILD_ASR=ON # 构建 ASR 引擎 BUILD_CLS=ON # 构建音频分类（PANNs）引擎 BUILD_VAD=ON # 构建 VAD 引擎 PPS_DEBUG=OFF # -DWITH_PPS_DEBUG，开启后定义 PPS_DEBUG 宏 FASTDEPLOY_INSTALL_DIR="" # 指向已构建的 FastDeploy 安装目录，留空则由 CMake 自行处理

CMake 配置命令为（runtime/build.sh）：

mkdir -p build/Linux/x86_64 cmake -B build/Linux/x86_64 \ -DCMAKE_BUILD_TYPE=Release \ -DBUILD_SHARED_LIBS=OFF \ -DWITH_ONNX=ON \ -DWITH_ASR=ON \ -DWITH_CLS=ON \ -DWITH_VAD=ON \ -DFASTDEPLOY_INSTALL_DIR="" \ -DWITH_PPS_DEBUG=OFF cmake --build build/Linux/x86_64 -j

顶层 runtime/CMakeLists.txt 中可选项的完整集合为：

配置完成后，runtime/cmake/summary.cmake 会打印一份 “PaddleSpeech Building Summary”，列出版本号、编译器、WITH_ASR/CLS/VAD、FASTDEPLOY_INSTALL_DIR及 Python 解释器等关键信息，方便确认开关是否按预期生效。

3.3 构建脚本如何自动探测 Paddle 库（理解 FAQ 1 的前提）

runtime/CMakeLists.txt 在WITH_ASR=ON时，通过execute_process执行三段内嵌 Python 代码来定位 PaddlePaddle 的产物：

1. import paddle后经paddle.sysconfig.get_include()得到头文件目录，拼出链接参数PADDLE_LINK_FLAGS，形如-L.../paddle/libs -L.../paddle/fluid -l:libpaddle.so -l:libdnnl.so.2 -l:libiomp5.so；
2. 同样方式得到编译宏PADDLE_COMPILE_FLAGS（-I.../paddle/include）；
3. 得到运行期LD_LIBRARY_PATH所需的PADDLE_LIB_DIRS。

关键点在于：这三步都以当前 PATH 中可用的python为前提。如果虚拟环境未激活、或 PaddlePaddle 未安装，import paddle抛ModuleNotFoundError，OUTPUT_VARIABLE拿到空串，随后string(STRIP ...)就报出string sub-command STRIP requires two arguments错误——这正是 FAQ 第 1 条中CMakeLists.txt:119/CMakeLists.txt:131报错的根因（行号随版本漂移，当前仓库对应 runtime/CMakeLists.txt）。解决方式就是文档给出的：先激活venv并安装paddlepaddle >= 2.4rc，再执行build.sh。

四、交叉编译：Android 与 iOS

除 x86 Linux 外，runtime/还提供了两套移动端构建脚本，可作为参数化构建的参考范本。

Android（runtime/build_android.sh）：通过 NDK r25b 的android.toolchain.cmake交叉编译，关键参数为ANDROID_ABI=arm64-v8a（也支持armeabi-v7a）、ANDROID_PLATFORM=android-21（API >= 21）、ANDROID_STL=c++_shared、构建类型MinSizeRel。注意其中-DWITH_ASR=OFF -DWITH_CLS=OFF -DWITH_VAD=ON的组合——移动端仅构建 VAD 引擎，且依赖指向本地 FastDeploy 的 Android 安装目录（FASTDEPLOY_INSTALL_DIR）。

iOS（runtime/build_ios.sh）：使用ios.toolchain.cmake，目标平台OS64（Apple Silicon）、BUILD_IN_MACOS=ON（该选项会额外定义OS_MACOSX宏，见 runtime/CMakeLists.txt），同样只构建 VAD 模块并链接 FastDeploy iOS arm64 产物；脚本支持传参clean仅做构建产物清理。

顶层 CMake 对交叉编译做了专门支持：ANDROID场景下把CMAKE_FIND_ROOT_PATH_MODE_*全部设为BOTH，保证find_library等命令在交叉环境下仍能查到宿主机上的工具（runtime/CMakeLists.txt）。

五、运行示例程序

构建完成后，文档指引进入examples/目录运行。runtime/examples/README.md 说明：

• 官方推荐示例为u2pp_ol（u2++ 流式 ASR，aishell-1 测试集），另有ds2_ol（Deepspeech2 流式）；
• 每个示例的入口是各自的run.sh，例如：

pushd u2pp_ol bash run.sh --stop_stage 4

• 运行前同样需要先source venv/bin/activate激活虚拟环境；
• 若需要查看模型计算图，可用 Netron：pip install netron后netron exp/.../avg_1.jit.pdmodel --port 8022；
• examples/codelab/仅面向引擎开发者做日志等组件自测，普通用户可忽略。

engine/asr/server/websocket/下还内置了 WebSocket 服务程序，对应examples/custom_asr/中“自定义 ASR 服务”的部署形态，可用于把编译好的引擎封装为网络服务。

六、Valgrind 内存调试（可选）

文档的 Valgrind 章节给出了两条要点，均可在脚本中得到印证：

1. Docker 容器必须带--privileged，否则 Valgrind 启动时报a function redirection which is mandatory for this platform-tool combination cannot be set up；
2. 出现该 fatal error 时，可先安装调试符号包：

apt-get install libc6-dbg

安装脚本 runtime/tools/setup_valgrind.sh 采用源码编译方式，固定 Valgrind 版本3.18.1：

pushd tools ./setup_valgrind.sh popd

脚本逻辑：若本地已存在valgrind-3.18.1.tar.bz2则复用，否则从 sourceware.org 断点续传下载，随后解压、./configure --prefix=$PWD/valgrind/install、make && make install。产物位于runtime/tools/valgrind/install，使用 PATH 指定该前缀即可对引擎可执行程序做内存检测。

七、FAQ：五类典型编译/运行错误的定位与解决

以下五问全部继承自 runtime/README.md，并结合当前仓库源码补充了出错位置。

7.1No module named 'paddle'与 CMakeSTRIP报错

现象（节选）：

CMake Error at CMakeLists.txt:119 (string): string sub-command STRIP requires two arguments. Traceback (most recent call last): File "<string>", line 1, in <module> ModuleNotFoundError: No module named 'paddle'

如 3.3 节所述，CMakeLists.txt中通过execute_process(COMMAND python -c "import paddle ...")探测 Paddle 安装信息，python中找不到paddle模块时输出为空，导致后续string(STRIP)缺参。解决：在激活的虚拟环境中安装 paddlepaddle >= 2.4rc，确保which python指向venv/bin/python且其中已装好 Paddle。

7.2error while loading shared libraries: liblibpaddle.so

u2_recognizer_main: error while loading shared libraries: liblibpaddle.so: cannot open shared object file: No such file or directory

原因是链接时写入了带-l:libpaddle.so生成的 SONAME 异常（liblibpaddle.so）。文档给出的修复方法是用patchelf修正已安装库的 soname：

cd $YOUR_ENV_PATH/lib/python3.8/site-packages/paddle/fluid patchelf --set-soname libpaddle.so libpaddle.so

另外，运行时需将 CMake 探测到的PADDLE_LIB_DIRS（paddle/fluid与paddle/libs目录）加入LD_LIBRARY_PATH，这也是CMakeLists.txt专门输出该变量的目的。

7.3 缺少libgfortran.so.5

u2_recognizer_main: error while loading shared libraries: libgfortran.so.5: cannot open shared object file

libgfortran.so.5对应 GCC 8 时代的 Fortran 运行时。文档以 GCC 8.2 为例，解决方案是安装同版本 gfortran：

apt-get install gfortran-8

7.4Undefined reference to '_gfortran_concat_string'

这是 GCC 8 引入的 Fortran 内部符号链接错误。解决：保持 gcc 与 gfortran 版本一致，均使用 8.2（gcc 8.2 + gfortran 8.2 组合），避免混用不同主次版本的工具链。

7.5fatal error: pyconfig.h: No such file or directory

./boost/python/detail/wrap_python.hpp:57:11: fatal error: pyconfig.h: No such file or directory

编译 pybind11 模块时需要 Python 开发头文件。解决：apt-get install python3-dev。

八、已知限制：流式分贝归一化的在线/离线差异

文档 TODO 章节记录了一个明确的已知差异：Deepspeech2 使用 linear 特征时，在线分贝归一化（DecibelNormalizer）与离线版本结果存在微小偏差，原因是在线计算按 chunk（分块）读取特征，导致归一化时samples.size()与离线整段计算不同。在当前仓库中，对应的实现位于 runtime/engine/common/frontend/db_norm.cc 的DecibelNormalizer::Compute()：其核心是统计输入样本的均方值得到rms_db，计算gain = target_db - rms_db（超过max_gain_db时直接返回错误），再对样本执行item *= 10^(gain/20)的原地缩放（见 db_norm.cc）。文档提示的normalizer.cc:73即该函数中mean_square /= samples.size()一行（当前源码为第 72 行附近，行号随代码演进略有漂移）。这一说明对需要在 C++ 引擎上复现离线识别结果的开发者有直接参考价值：chunk 边界不同会带来可预期的微小数值差异，属于设计使然而非 bug。

九、小结：从 clone 到运行的最小路径

综合以上各节，一份可直接复制的最小构建路径为（前提：已 clone 仓库、已启动带--privileged的 Paddle Docker 容器并挂载到/workspace）：

# 1. 创建并激活 Python 3.8 虚拟环境 bash tools/venv.sh source venv/bin/activate # 2. 安装满足版本要求的 PaddlePaddle python -m pip install paddlepaddle==2.4.2 -i https://mirror.baidu.com/pypi/simple # 3. 编译引擎与示例（输出于 build/Linux/x86_64，安装于其 install/ 子目录） ./build.sh # 4. 运行推荐示例 pushd examples/u2pp_ol bash run.sh --stop_stage 4

排障时按本文第七节顺序检查 Python/Paddle 环境、Paddle 共享库 SONAME、gfortran 版本匹配与 Python 开发头文件，即可覆盖文档记录的全部已知问题；若构建摘要（Building Summary）中的WITH_ASR/CLS/VAD、Python 解释器路径与预期不符，则回到build.sh的-D参数逐一核对。

• 人工智能
• 语音
• 音频
• NLP
• 媒体生成