FunASR HTTP 离线转写运行时：依赖安装与编译环境配置实战指南

FunASR HTTP 离线转写运行时：依赖安装与编译环境配置实战指南

【免费下载链接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR

本文以 FunASR 仓库runtime/http目录下的依赖安装文档 requirements_install.md 为核心，系统讲解如何为 HTTP 语音转写服务（funasr-http-server）准备完整的编译环境：包括 onnxruntime 推理引擎、ffmpeg 媒体库的下载方式，OpenBLAS 与 OpenSSL 等系统级开发库在 Ubuntu/CentOS 下的安装命令。读完本文，你能独立完成 C++ HTTP 推理服务从依赖安装、CMake 构建到启动冒烟测试的全流程。

一、文档定位：这份文档解决什么问题

FunASR 的 C++ 运行时按服务形态分为多个目录（http、websocket、grpc、onnxruntime、triton_gpu等），其中 runtime/http 提供的是离线文件转写 HTTP 服务——客户端通过 HTTP POST 上传音频文件，服务端完成 VAD + ASR + 标点处理后返回识别文本。runtime/http/readme.md 顶部链接到离线转写与实时听写两份开发指南（SDK_advanced_guide_offline.md、SDK_advanced_guide_online.md），并明确提示：“如果您想自己编译文件，可以参考下述步骤”。

requirements_install.md正是“自己编译”路线的第一环：在运行 CMake 之前，必须先在系统上准备好三类手动依赖。它的价值在于给出了最小的手工准备清单：

需要注意文档中命令的一个路径细节：文档里写的是bash third_party/download_onnxruntime.sh，而这两个脚本在仓库中的实际存放位置是 runtime/onnxruntime/third_party/download_onnxruntime.sh 和 runtime/onnxruntime/third_party/download_ffmpeg.sh。从脚本位置与 grpc/Readme.md 的引用方式看，third_party/指向的是runtime/onnxruntime下的第三方依赖目录——执行时建议先cd runtime/onnxruntime，或直接使用完整路径bash third_party/download_*.sh（在 onnxruntime 目录下）。另外，同一份安装说明也以 runtime/websocket/requirements_install.md 的形式服务 websocket 运行时，内容完全一致，说明这是一套在 C++ 运行时之间复用的标准依赖模板。

二、步骤一：下载 onnxruntime 推理引擎

文档给出的原始操作：

bash third_party/download_onnxruntime.sh

脚本内部实际做了什么

查看 download_onnxruntime.sh，其逻辑只有两条命令：

1. 通过wget拉取 onnxruntime 官方v1.14.0的 linux-x64 预编译发布包onnxruntime-linux-x64-1.14.0.tgz（脚本注释明确指向 onnxruntime 的 v1.14.0 发布版本）；
2. tar -zxvf解包，得到onnxruntime-linux-x64-1.14.0/目录（内含include/、lib/、lib64/等）。

也就是说，版本被锁定在 1.14.0，不需要（也不建议）自行升级到其他版本，以保证与 FunASR C++ 源码的 API 兼容性。

为什么必须手动准备 onnxruntime

onnxruntime 没有走 CMake 源码编译路线，而是以“预编译二进制 + 头文件”的方式注入构建。从 runtime/http/CMakeLists.txt 可以看到：

link_directories(${ONNXRUNTIME_DIR}/lib) link_directories(${FFMPEG_DIR}/lib)

这里的${ONNXRUNTIME_DIR}就是你在配置 CMake 时必须传入的、指向解包后目录（onnxruntime-linux-x64-1.14.0）的路径变量。核心的推理逻辑库funasr（由 runtime/onnxruntime/CMakeLists.txt 中同样的link_directories(${ONNXRUNTIME_DIR}/lib)/link_directories(${FFMPEG_DIR}/lib)驱动构建）负责加载.onnx模型并调用 onnxruntime C++ API 执行推理，因此这个依赖是编译链的硬性前提。

备选方式：如果从脚本的下载源无法访问，runtime/http/readme.md 还给出了从阿里云 OSS 镜像下载同版本onnxruntime-linux-x64-1.14.0.tgz的等价wget+tar命令，两条路线产物一致。

三、步骤二：下载 ffmpeg 媒体库

文档给出的原始操作：

bash third_party/download_ffmpeg.sh

脚本内部实际做了什么

download_ffmpeg.sh 同样只有两条命令：

1. wget下载预编译的 ffmpeg 共享库包，包名为ffmpeg-N-111383-g20b8688092-linux64-gpl-shared.tar.xz（GPL 授权、linux64、动态链接版）；
2. tar -xvf解包，得到ffmpeg-...-gpl-shared/目录（内含bin/、include/、lib/）。

ffmpeg 在转写链路中的角色

HTTP 服务接收到的音频文件可能是 wav、mp3 等多种容器格式，服务端需要在推理前完成解码与重采样到模型要求的 16kHz 单声道输入。从源码结构看，onnxruntime 核心库的编译源中包含resample.cpp（runtime/onnxruntime/src 目录，且在 Windows 构建中被显式并入关联源文件列表，见 runtime/http/bin/CMakeLists.txt 中的RELATION_SOURCE），音频重采样与解码能力正是依赖 ffmpeg 提供的 libavcodec/libavformat 等共享库。这也是FFMPEG_DIR/lib被写入链接目录的原因。

与 onnxruntime 一样，ffmpeg 目录通过-DFFMPEG_DIR=/path/to/ffmpeg-...-gpl-shared传入 CMake，指向解包后的根目录。

四、步骤三：安装系统级开发库（OpenBLAS 与 OpenSSL）

文档给出的原始操作：

sudo apt-get install libopenblas-dev libssl-dev #ubuntu # sudo yum -y install openblas-devel openssl-devel #centos

这一小节覆盖两类“系统包管理器才能提供”的依赖，CMake 会自动搜索它们：

OpenSSL：HTTP 服务的硬性链接依赖

OpenSSL 是 CMake 中显式REQUIRED的查找目标。runtime/http/CMakeLists.txt 中写道：

# install openssl first apt-get install libssl-dev find_package(OpenSSL REQUIRED)

注意这行中文注释——CMake 作者自己提示了“先安装 openssl”。最终可执行文件也确实链接了它，runtime/http/bin/CMakeLists.txt 中：

target_link_libraries(funasr-http-server PUBLIC funasr ${OPENSSL_CRYPTO_LIBRARY} ${OPENSSL_SSL_LIBRARY})

OPENSSL_SSL_LIBRARY支撑服务端 TLS/HTTPS 能力，OPENSSL_CRYPTO_LIBRARY提供基础加密原语。若系统缺少libssl-dev，CMake 配置阶段就会因find_package(OpenSSL REQUIRED)失败而直接报错，这是新环境上最常见的第一个报错点。

OpenBLAS：CPU 数值计算依赖

libopenblas-dev提供 BLAS 数值线性代数库。从源码结构看，仓库 CMake 文件中没有对 openblas 的直接find_package调用，可以推断它是 onnxruntime 预编译 CPU 包在运行/链接期的数值计算依赖，由文档统一纳入安装清单，保证推理引擎的矩阵运算性能与链接完整性。

补充：ZLIB 与 Boost

除文档列出的三项外，阅读构建脚本还能发现两个隐含的系统依赖，建议在装环境时一并确认：

• ZLIB：runtime/http/bin/CMakeLists.txt 中有find_package(ZLIB REQUIRED)，可执行文件直接链接它。若系统缺 zlib 开发文件，需额外安装对应的 zlib 开发包（Ubuntu 上通常称zlib1g-dev）。
• Boost：runtime/http/readme.md 的 “Install deps” 一节额外要求apt install libboost-dev libboost-system-dev（CentOS 对应 yum 安装 boost-devel）。requirements_install.md未列出它，但以 readme 的完整依赖清单为准更稳妥。

五、无需手动准备的依赖：CMake 自动处理

为避免“装依赖”范围失控，有必要区分手动依赖与自动依赖。runtime/http/CMakeLists.txt 表明，以下依赖会在cmake配置阶段由 FetchContent 机制自动下载或从仓库内置源码构建，不需要你手动安装：

其中 openfst 与文档执行参数相关：ENABLE_FST选项默认为 ON，注释说明 “ITN need openfst compiled”（ITN 逆文本正则化需要 openfst）。虽然 readme.md 的运行示例中传--itn-dir ''禁用了 ITN，但 CMake 层面默认仍会编译 openfst，编译时间会相应增加。

构建环境的基线要求同样来自该文件：cmake_minimum_required(VERSION 3.16)、CMAKE_CXX_STANDARD 14（CMakeLists.txt）。也就是说，系统需要 CMake ≥ 3.16 与 C++14 编译器（GCC/Clang 均可），这属于隐式前置条件，文档未单独列出。

六、把依赖接入构建：CMake 配置参数

依赖就位后，用 CMake 把它们绑定进构建系统。按 runtime/http/readme.md 的官方步骤：

cd FunASR/runtime/http mkdir build && cd build cmake -DCMAKE_BUILD_TYPE=release .. \ -DONNXRUNTIME_DIR=/path/to/onnxruntime-linux-x64-1.14.0 \ -DFFMPEG_DIR=/path/to/ffmpeg-master-latest-linux64-gpl-shared make -j 4

参数说明：

• -DCMAKE_BUILD_TYPE=release：release 构建，开启优化；
• -DONNXRUNTIME_DIR：指向 onnxruntime 解包后的目录，CMake 从中取include/与lib/；
• -DFFMPEG_DIR：指向 ffmpeg 解包后的目录，CMake 从中取include/与lib/；
• 两个路径参数是必填的——link_directories(${ONNXRUNTIME_DIR}/lib)与link_directories(${FFMPEG_DIR}/lib)在配置阶段即被展开，传错路径会在链接期表现为找不到libonnxruntime.so/ ffmpeg 库符号。

构建成功后，产物输出到build/bin/funasr-http-server（由CMAKE_RUNTIME_OUTPUT_DIRECTORY控制，见 CMakeLists.txt）。最终可执行文件由 runtime/http/bin 下的源码（funasr-http-main.cpp、server.cpp、connection.cpp、asr_sessions.h、model-decoder.cpp等）编译，链接funasr核心库、OpenSSL 与 ZLIB。

七、验证环境：启动服务与冒烟测试

依赖安装是否完整，最终以服务能否编译并正常响应为判据。

启动转写服务

readme.md 给出的运行命令：

./funasr-http-server \ --vad-dir damo/speech_fsmn_vad_zh-cn-16k-common-onnx \ --model-dir damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-onnx \ --punc-dir damo/punc_ct-transformer_cn-en-common-vocab471067-large-onnx \ --itn-dir '' \ --lm-dir '' \ --port 10001

各参数含义：--vad-dir为 FSMN VAD 的 ONNX 模型目录，--model-dir为 Paraformer-large 中文 ASR ONNX 模型目录，--punc-dir为标点恢复模型目录，--itn-dir ''与--lm-dir ''表示禁用 ITN 与语言模型，--port指定 HTTP 监听端口（示例为 10001，测试命令则用默认 80 端口）。模型目录需事先从 FunASR 模型仓库下载对应 ONNX 版本模型并放置到给定路径。

curl 冒烟测试

curl -F "file=@example.wav" 127.0.0.1:80

以 multipart 表单上传一个 wav 文件，服务返回识别文本。能收到完整 JSON 结果，即证明 onnxruntime（推理）、ffmpeg（解码）、OpenSSL（服务层）三类依赖全部正确装配。

八、实操要点小结

1. 依赖版本已锁定：onnxruntime 固定 1.14.0、ffmpeg 固定官方预编译 linux64-gpl-shared 包，不要擅自替换版本；
2. 两条下载路线：优先用仓库脚本（runtime/onnxruntime/third_party/download_*.sh），网络受限时用 readme 中的 OSS 镜像wget命令；
3. CMake 必填两个目录参数：ONNXRUNTIME_DIR与FFMPEG_DIR，指向解包后的目录本身而非其lib/子目录；
4. 系统开发包一次装齐：Ubuntu 下libopenblas-dev libssl-dev（文档要求）+libboost-dev libboost-system-dev（readme 要求）+ zlib 开发包（CMake 隐含要求）；CentOS 下对应openblas-devel、openssl-devel、boost-devel、zlib-devel；
5. 环境基线：CMake ≥ 3.16、C++14 编译器、Linux/Unix 平台；Windows 构建路径在 CMakeLists 中有单独分支，但本文档清单针对 Linux 发行版；
6. 自动依赖不要重复手动安装：asio、json、portaudio 由 FetchContent 下载，glog、openfst、yaml-cpp 等由仓库内置源码编译。

完成以上步骤后，runtime/http的 C++ 转写服务即可在本机编译、启动并接受 HTTP 请求，为后续按 SDK_advanced_guide_offline.md 扩展服务功能打下完整的环境基础。

【免费下载链接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR