Sherpa(Next Gen Kaldi)部署在Rockchip的不同SOC上 on Potter的个人笔记

第一章：RK3588S平台 Sherpa ASR 模块化部署(C/S架构)

Thu, 21 Aug 2025 00:00:00 +0000

项目复盘报告 (After-Action Review) - 优化版

项目属性	内容
项目名称	RK3588S平台 Sherpa ASR 模块化部署(C/S架构)
项目周期	2025-04-25 ~ 2025-06-24
复盘日期	2025-06-24
核心人员	Potter White
总计工时	34 个工作日

1. 目标回顾 (What was supposed to happen?)

1.1 项目目标

核心功能： 构建一个生产级的、支持高并发的离线语音识别（ASR）服务。
性能预期：
- 显性要求： 实时率 (RTF) 显著优于 1.0。
- 隐性要求： 推理延迟在可接受范围内（目标 < 1秒），用户体验流畅。
质量与稳定性预期：
- 显性要求： 服务可模块化部署，与主应用解耦。
- 隐性要求： 7x24 小时稳定运行，无内存泄漏、死锁或数据竞争。

1.2 初始方案与假设

核心技术栈： C++17, CMake, std::thread, 自研 LibSocket(IPC)
架构演进思路：
- 阶段一 (原型驱动)： 鉴于技术选型不确定，初期采用快速原型法，验证核心技术（Whisper vs. Sherpa）的可行性。
- 阶段二 (架构定型)： 原型验证成功后，确立 IPC + C/S 架构。该设计旨在实现 ASR 服务的独立部署、测试和升级，降低系统耦合度。
关键假设 (后被证伪)：
- 假设 1 (错误)： 模型加载成本低。 误认为可以为每个新连接的会话动态加载 ASR 模型，而无需考虑其高昂的 I/O 和内存开销。
- 假设 2 (错误)： 并发管理简单。 误认为简单的线程分离 (std::thread::detach) 或缺乏同步机制的线程管理足以应对生产环境的并发请求。

2. 实际结果 (What actually happened?)

2.1 最终成果

性能表现：
- 实时率 (RTF) 达到 0.2，意味着处理1秒音频仅需0.2秒，性能远超预期，为系统提供了充足的性能裕量。
功能完整性：
- 实现了非追加式（Non-Appending）文本流输出，显著提升了实时字幕的用户体验。
- 成功构建了模块化的 C/S 架构，ASR 服务作为独立的 Server 进程运行，稳定性高，易于维护。
- 通过 helgrind 压力测试，系统性地识别并修复了所有数据竞争与死锁隐患，保证了并发安全性。
可复用资产：
- 封装了三个高质量的 C++ 库： LibASR, LibSocket, LibUtils，实现了功能的高度内聚和代码复用。

2.2 关键事件与过程（时间线）

迭代一 (技术预研 - 4天): 调研 Whisper，因其转换部署流程复杂而转向 Sherpa。
迭代二 (原型验证 - 4天): 成功运行 Sherpa C++ Demo，解决了硬件环境（ALSA 配置）问题，验证了核心方案可行性。
迭代三 (核心逻辑开发 - 7天): 重构 Demo 代码，初步实现 wav 和 mic 输入的解码逻辑，为后续开发奠定基础。
迭代四 (高级功能探索 - 6天): 成功集成 VAD (Voice Activity Detection) 功能，并解决了关键的用户体验问题——如何打断追加式输出，最终通过 Endpointing 机制部分解决。
迭代五 (架构重构与库封装 - 5天): 项目关键转折点。将原型代码重构为三个独立的库（ASR、Socket、Utils），实现了代码的模块化、正规化和高复用性。此阶段深入掌握了 POSIX Socket API 和单例（Singleton）模式。
迭代六 (集成与测试 - 6.5天): 将库与 App 层集成，并构建了全面的测试体系。
- 解决了服务端连接处理的生命周期问题，实现了对多客户端连接的健壮处理。
- 优化了模型加载策略，意识到为每个 Worker 加载模型的性能瓶颈（待优化项）。
- 构建了 gtest 单元测试、集成测试和压力测试，系统性地保障了代码质量。
迭代七 (并发调试与加固 - 1.5天):
- 使用 Valgrind 和 helgrind 进行深度内存与并发问题分析。
- 定位并修复了关键的并发 bug，为共享资源（如 Worker 列表、Socket 连接）添加了互斥锁 (std::lock_guard) 保护。

3. 差异分析：根因探究 (Why was there a difference?)

3.1 成功之处 (What went well, and why?)

成功点 1：采用了面向对象的结构化并发设计。
- 现象： 将 ASR 任务 (ASRTaskSherpa) 与其执行线程 (std::thread) 封装为统一的生命周期管理单元 (TaskHandler)，并用 std::vector 统一管理。
- 根本原因： 这本质上是应用了 RAII (Resource Acquisition Is Initialization) 思想来管理线程资源。通过将线程的生命周期与任务对象的生命周期绑定，避免了手动管理线程 join 或 detach 的复杂性和风险，从设计上根除了资源泄漏和“僵尸线程”问题。这从“面向过程”的线程管理思路，跃迁到了“面向对象”的并发实体管理，极大地降低了心智负担和出错率。
成功点 2：果断进行架构重构，实现了高度模块化。
- 现象： 在项目中期，将耦合在一起的原型代码拆分为三个独立的库。
- 根本原因： 认识到底层能力的稳定性和可复用性是上层业务逻辑快速迭代的基础。 通过封装基础库（通信、日志、ASR 核心 API），使得主应用（App）的逻辑变得极为清晰，只专注于业务流程编排。这体现了**“关注点分离” (Separation of Concerns)** 的核心设计原则，是项目从“能用”到“好用、易维护”的关键一步。

3.2 不足之处 (What could be improved, and why?)

问题点 1：对阻塞式 I/O 的并发中断处理考虑不周，导致无法优雅停机。
- 现象： 在主线程中尝试通过 stop_flag_ 停止工作线程时，若工作线程正阻塞在 ::recv() 上，则线程无法响应停止信号，导致 join() 无限等待，程序卡死。
- 根本原因： 缺乏对“异步中断”机制的理解。 atomic 标志位只能在线程的轮询逻辑中被检查，但无法唤醒一个深度睡眠在内核态（如 recv 阻塞）的线程。这是同步编程思维在异步并发环境下的典型误用。正确的解决方案应采用非阻塞 I/O + I/O 多路复用（如 epoll, select）或为 socket 设置超时 (setsockopt)，让 recv 能在指定时间后返回，从而有机会检查 stop_flag_。
问题点 2：在多线程环境下，对共享资源的所有权和访问控制不明确。
- 现象： 在主线程的 stop_me() 中直接操作工作线程正在使用的 client_ (unique_ptr)，引发 helgrind 报数据竞争。
- 根本原因： 对 C++ 内存所有权和线程安全边界的认知存在盲区。 即使是 unique_ptr 这种看似安全的智能指针，其指针本身（而非其指向的对象）在多个线程间共享和修改时，同样需要同步机制（如 mutex）来保护。问题的核心在于，任何跨线程共享的可变状态，都必须被显式地保护起来，这是并发编程的铁律。

架构待优化点 1：模型加载策略与会话生命周期耦合。
- 现象： 每个新的客户端连接都会触发一次模型的重新加载，造成巨大的 I/O 和性能开销。
- 根本原因： 未能将“重量级资源”（模型）与“轻量级会话”（客户端连接）的生命周期分离。这是初期设计假设错误（假设1）的直接后果。
架构待优化点 2：缺乏对不同 ASR 模型的抽象。
- 现象： 当前的 ASRTaskSherpa 类与 Sherpa 的具体实现强耦合，若要切换到其他 ASR 方案（如 Whisper），需要大量修改代码。
- 根本原因： 未能应用**“面向接口编程”**的设计思想。缺乏一个抽象的 IASRTask 接口层。

4. 行动计划：未来如何做 (What will we do next time?)

4.1 个人能力提升 (Personal Growth)

技术栈深化：
- C++ 并发编程： 系统学习 std::future, std::promise, std::async，掌握更现代的异步任务编程范式。深入研究非阻塞 I/O 与 epoll。
- 设计模式： 将本次实践的“建造者模式 (Builder)”和“单例模式 (Singleton)”内化，并主动学习“策略模式”、“观察者模式”等，以应对更复杂的业务场景。
- C++ 核心准则： 深入理解“RAII”、“零规则 (Rule of Zero/Five)”，让代码天然地安全和高效。
思维模式转变：
- 并发优先思维： 在设计任何类或函数时，都要先问一句：“这个对象或数据会被多个线程访问吗？”将线程安全作为一等公民来考虑。
- 设计先于实现： 对于复杂模块，强制要求自己先绘制简单的时序图、状态机图或组件交互图，梳理清楚生命周期和数据流，再开始编码。

4.2 流程与规范改进 (Process & Standards Improvement)

强制性设计关口：
- 并发设计评审： 对于任何涉及多线程的模块，必须输出一份简要的并发模型说明，明确：共享资源、同步机制（用什么锁）、线程生命周期管理策略。
自动化质量保障：
- 集成静态/动态分析工具： 将 Clang-Tidy (静态分析)、ThreadSanitizer (数据竞争检测)、MemorySanitizer (内存问题检测) 集成到 CMake 和 CI/CD 流程中，实现问题的早期自动化发现。
编码规范标准化：
- 建立团队统一的 C++ 编码规范 (可基于 Google Style Guide)，并使用 clang-format 强制执行，覆盖命名、头文件管理、注释等。
- 目录结构规范： 固化 include/, src/, test/, libs/ 等项目结构，并推广为团队的项目模板。

4.3 知识沉淀与复用 (Knowledge Management & Reuse)

资产化成果：
- C++ 服务器项目模板： 将本次项目的结构、CMake 配置、日志库、测试框架集成为一个 Git 模板仓库，新项目可一键启动。
- 文档化最佳实践： 撰写一份 “C++ 并发服务器常见陷阱与最佳实践” 的内部文档，包含本次复盘中关于优雅停机、数据竞争的案例分析。
分享计划：
- 内部技术分享： 组织一次以“从单线程到高并发：一个 C++ ASR 服务器的演进与陷阱”为题的技术分享会。
- 发布个人博客/文章： 将本次复盘的精华部分（特别是“差异分析”和“行动计划”）整理成文章，分享到技术社区。

第二章：RV1126平台 Sherpa ASR 部署技术评估与实现

Thu, 21 Aug 2025 00:00:00 +0000

[项目复盘报告] RV1126平台 Sherpa ASR 部署技术评估与实现

项目属性	内容
项目名称	第二部分：RV1126平台 Sherpa ASR 部署技术评估与实现
项目周期	2025-07-26 ~ 2025-08-06 (估算)
项目用时	50.17小时 (约6.3人天)
复盘日期	2025-08-20
核心人员	Potter White

1. 项目背景与初始目标

1.1 项目启动背景

本项目旨在为公司产品线在 Rockchip RV1126b 嵌入式平台上集成高性能的实时语音识别（ASR）功能。鉴于 V1.0 项目在 RK3588s 平台上成功部署 sherpa-onnx 并利用 NPU 取得了卓越性能，本次项目的初始规划旨在复刻这一成功路径，以期在成本更低的 RV1126b 平台上实现兼具性能与成本效益的 AI 功能落地。

1.2 核心技术目标

功能目标： 成功部署 Sherpa ASR 引擎，并将其集成为一个稳定可靠的服务模块。
性能目标： 实现远低于 1.0 的实时率（RTF），确保实时字幕等功能的流畅用户体验。

1.3 初始技术方案与假设

基于前序项目的经验，我制定了以 sherpa-onnx 框架为核心的技术方案。该方案的优势在于能够直接利用 Rockchip 平台的 RKNN 工具链进行 NPU 硬件加速，理论上是性能最优解。此方案建立在以下关键假设之上：

假设一：工具链兼容性。 我假设 sherpa-onnx 的源码可以与 RV1126b 平台提供的原生交叉编译工具链（GCC 8.3）兼容。
假设二：SDK API兼容性。 我假设 RV1126b 平台搭载的 librknnrt 运行时库，其 API 版本能够满足 sherpa-onnx 框架中对 RKNN 功能的调用需求。

然而，在项目推进过程中，上述两个核心假设均被证伪，迫使项目进行了重大的技术路径调整。

第三章：RV1126BP平台 Sherpa ASR RKNN自主模型转换

Thu, 21 Aug 2025 00:00:00 +0000

[项目复盘报告 V3.0] 自主模型转换：攻克动态ONNX模型至RKNN的技术难题

项目属性	内容
项目名称	第三部分：RV1126BP平台 Sherpa ASR RKNN自主模型转换
项目周期	2025-07-31 ~ 2025-08-09 (估算)
项目用时	31.5(约3.9人天)
复盘日期	2025-08-20
核心人员	Potter White

1. 项目背景与启动

在 V2.0 项目中，我们验证了 sherpa-onnx 框架因目标平台 RKNN SDK 版本过低而无法直接使用 NPU 加速，同时 sherpa-ncnn 的纯 CPU 方案也已达到性能瓶颈。因此，为了充分利用 RV1126b 平台的 NPU 硬件，本项目（V3.0）的核心目标是绕开 sherpa-onnx 的编译限制，自主完成从 ONNX 模型到 RKNN 模型的转换工作。

这项工作的起点，是处理 Sherpa ASR 模型中普遍存在的动态输入维度问题。

2. 基础问题分析与通用转换策略

2.1 理解动态维度 `[N, ...]`

在 ONNX 模型中，维度 N 通常作为一个占位符，代表动态的批处理大小（Batch Size）。例如，一个 [N, 39, 80] 的输入形状意味着模型可以一次性处理 N 个输入样本。然而，为了在嵌入式 NPU 上实现最高效的运算，RKNN 工具链通常要求模型的输入形状是固定的、静态的。

第五章：嵌入式平台 (RV1126B) 流式 ASR 模型 (Zipformer) INT8 端到端量化与部署

Sat, 27 Sep 2025 00:00:00 +0000

[项目复盘报告 V5.0] 嵌入式平台 (RV1126B) 流式 ASR 模型 (Zipformer) INT8 端到端量化与部署

项目属性	内容
项目名称	第五部分：RV1126BP平台 Sherpa ASR RKNN量化
项目周期	2025-08-21 ~ 2025-09-23
项目用时	40(约5人天)
复盘日期	2025-09-27
核心人员	Potter White

1. 项目目标 (Project Objective)

为基于 Rockchip RV1126B SoC 的嵌入式设备，将一个 FP32 精度的流式 Zipformer ASR (Automatic Speech Recognition) ONNX 模型，转换为 INT8 精度的 RKNN 模型，并在 sherpa-onnx C++ 推理框架中完成部署与验证，以满足低延迟和低功耗的运行要求。

2. 执行方法与流程 (Methodology & Workflow)

本项目采用了一套系统性的方法，覆盖从模型分析、运行时环境改造、量化数据生成到最终模型验证的全过程。

graph TD
 classDef main fill:#2c3e50,color:white,stroke:#8e9eab;
 classDef task fill:#4b3e58,color:white,stroke:#b8a3d3;
 classDef check fill:#27ae60,color:white,stroke:#88d1a1;
 classDef fail fill:#c0392b,color:white,stroke:#e69a93;
 classDef success fill:#16a085,color:white,stroke:#72d6c1;
 classDef note fill:#f39c12,color:white,stroke:#f8c471;

 S[<b>开始: FP32 ONNX 模型</b>]:::main
 A["<div style='text-align:left; padding:10px;'><b>1. 初始模型分析与转换</b><br>- 使用预量化的 INT8 ONNX 模型进行直接转换</div>"]:::task

 %% --- THIS IS THE MISSING LINE THAT FIXES THE CONNECTION ---
 S --> A

 A --> R1{"<div style='text-align:center'>转换是否成功?</div>"}:::check
 R1 -- "否: 存在 `DynamicQuantizeLinear` 算子" --> B

 B["<div style='text-align:left; padding:10px;'><b>2. C++ 运行时适配</b><br>- 分析 `sherpa-onnx` RKNN 后端代码<br>- 增加对 `RKNN_TENSOR_INT8` 类型的处理分支<br>- 实现 INT8 输出到 FP32 的手动反量化逻辑</div>"]:::task
 B --> C

 C["<div style='text-align:left; padding:10px;'><b>3. 校准数据集迭代</b><br><b>3.1 (快照法):</b> 提取特征帧, 状态张量补零<br><b>3.2 (流式模拟):</b> 使用 `onnxruntime` 模拟流式推理, 捕获真实的非零状态张量</div>"]:::task
 C --> R2{"<div style='text-align:center'>INT8 模型推理结果?</div>"}:::check

 R2 -- "3.1 -> Garbled Output" --> C
 R2 -- "3.2 (`interval=1`) -> <b>First Success</b>" --> D

 D["<div style='text-align:left; padding:10px;'><b>4. 量化策略调优</b><br>- <b>算法:</b> 测试 `normal` (默认) 与 `kl_divergence` 算法<br>- <b>混合精度:</b> 尝试手动及自动混合量化</div>"]:::task
 D --> E

 E["<div style='text-align:left; padding:10px;'><b>5. 最终方案验证</b><br>- 对比不同策略下的模型精度与性能 (RTF)</div>"]:::task
 E --> F[<b>完成: 产出可部署的 INT8 RKNN 模型</b>]:::success

 subgraph "关键技术点"
 K1[静态图 vs. 动态图]:::note
 K2[有状态模型的校准]:::note
 K3[量化算法内存分析]:::note
 K4[混合精度量化]:::note
 end

 A --> K1
 C --> K2
 D --> K3 & K4

3. 工程实施细节与关键问题记录 (Implementation & Key Findings)

3.1 初始模型转换

执行动作: 尝试使用 rknn-toolkit2 直接转换模型提供方发布的 int8.onnx 模型。
观察结果: 转换失败。工具链报错，指出模型中包含 DynamicQuantizeLinear 算子，该算子与 RKNN NPU 的静态图 (Static Graph) 计算模式不兼容。
采取措施: 确定了必须使用 FP32 ONNX 模型作为输入源，并利用 rknn-toolkit2 自身的静态量化 (Static Quantization) 功能进行转换。

3.2 C++ 推理框架 (sherpa-onnx) 适配

执行动作: 在使用 FP32 模型成功转换为 INT8 RKNN 模型后，在 sherpa-onnx 中进行推理。
观察结果: 运行时报错，提示 Unsupported tensor type: 2, INT8。
采取措施:
1. 修改了 sherpa-onnx 的 RKNN 后端 C++ 源码，在模型输入、输出及状态 (states) 处理逻辑中，增加了对 RKNN_TENSOR_INT8 数据类型的分支处理。
2. 在获取模型输出后，根据 rknn_tensor_attr 中的 scale 和 zp (zero_point) 参数，实现了手动的反量化 (Dequantization) 步骤，将 INT8 输出转换为后续解码逻辑所需的 FP32 数据。

3.3 量化校准数据集的迭代与优化

此阶段是项目核心，通过多次迭代确定了有效的校准数据生成方案。

Sherpa(Next Gen Kaldi)部署在Rockchip的不同SOC上 on Potter的个人笔记

第一章：RK3588S平台 Sherpa ASR 模块化部署(C/S架构)

项目复盘报告 (After-Action Review) - 优化版

1. 目标回顾 (What was supposed to happen?)

1.1 项目目标

1.2 初始方案与假设

2. 实际结果 (What actually happened?)

2.1 最终成果

2.2 关键事件与过程（时间线）

3. 差异分析：根因探究 (Why was there a difference?)

3.1 成功之处 (What went well, and why?)

3.2 不足之处 (What could be improved, and why?)

4. 行动计划：未来如何做 (What will we do next time?)

4.1 个人能力提升 (Personal Growth)

4.2 流程与规范改进 (Process & Standards Improvement)

4.3 知识沉淀与复用 (Knowledge Management & Reuse)

第二章：RV1126平台 Sherpa ASR 部署技术评估与实现

[项目复盘报告] RV1126平台 Sherpa ASR 部署技术评估与实现

1. 项目背景与初始目标

1.1 项目启动背景

1.2 核心技术目标

1.3 初始技术方案与假设

第三章：RV1126BP平台 Sherpa ASR RKNN自主模型转换

[项目复盘报告 V3.0] 自主模型转换：攻克动态ONNX模型至RKNN的技术难题

1. 项目背景与启动

2. 基础问题分析与通用转换策略

2.1 理解动态维度 [N, ...]

第五章：嵌入式平台 (RV1126B) 流式 ASR 模型 (Zipformer) INT8 端到端量化与部署

[项目复盘报告 V5.0] 嵌入式平台 (RV1126B) 流式 ASR 模型 (Zipformer) INT8 端到端量化与部署

1. 项目目标 (Project Objective)

2. 执行方法与流程 (Methodology & Workflow)

3. 工程实施细节与关键问题记录 (Implementation & Key Findings)

3.1 初始模型转换

3.2 C++ 推理框架 (sherpa-onnx) 适配

3.3 量化校准数据集的迭代与优化

2.1 理解动态维度 `[N, ...]`