h2 data-id="heading-">工地无信号？我用端侧AI实现了离线语音识别

从一个真实的痛点说起

作为一名移动端开发者，我负责一款工程质检类 App 的开发。这款应用的主要场景是：质检员在施工现场巡检时需要快速记录发现的问题——钢筋间距不合规、混凝土浇筑质量问题、安全隐患等。

传统的做法是手动输入文字，但在工地环境下这几乎是一种折磨：

• 戴着安全手套操作手机键盘。效率极低
• 灰尘、噪音、光线等环境因素干扰
• 质检员往往需要同时观察、拍照、记录，腾不出双手

语音输入是的方法。只是当我兴冲冲地接入某云厂商的语音识别 API 后现实给了我当头一棒：

工地没有信号。

是的。无论是高层建筑的电梯井道、地下室基坑，还是偏远郊区的新建工地，网络信号都是一个奢侈品。我们的使用者反馈里"语音功能不可用"成了高频词。按理说，

技术选型这方面。端侧 AI 的崛起

既然云端不可靠，那就把 AI 搬到端侧。

的语音识别模型，具备以下特点：

无需网络，本地推理针对普通话深度调整。识别准确率高量化后约 70MB，移动端可接受Apache 协议，商用友好

特性	说明
离线运行
中文调整
模型轻量
开源免费

配合 sherpa-onnx 推理引擎，可以在 iOS/Android 双网站实现高性能的本地语音识别。

至于架构设计，不只是能用。还要好用

技术可行性验证通过后我开始思考如何设计一个对开发者友好、对使用者体验友好的组件架构。

分层架构

┌─────────────────────────────────────────────┐
│ UI 组件层 │
│ VoiceRecordButton │ VoiceRecordOverlay │
├─────────────────────────────────────────────┤
│ 服务管理层 │
│ VoiceRecognizerRegistry │
├─────────────────────────────────────────────┤
│ 主要服务层 │
│ AudioRecorderService │ ParaformerRecognizer│
├─────────────────────────────────────────────┤
│ 推理引擎层 │
│ sherpa-onnx │
└─────────────────────────────────────────────┘

UI 组件层开箱即用的长按录音按钮和语音输入弹窗，类似微信的交互体验。

服务管理层这是我后来重构加入的一层，解决了一个关键的使用者体验问题——下文详述。

主要服务层音频采集与语音识别的主要原因。

推理引擎层sherpa-onnx 提供的跨网站 ONNX 推理能力。

一个被忽视的体验问题

组件的第一版很快完成了功能测试一切正常。只是在实际使用中，我发现了一个严重的体验问题：

每次打开语音功能。都要等待 - 秒的初始化时间。

这是因为 ONNX 模型需要从 assets 复制到沙盒目录，接下来加载到内存。 对于心急的质检员这几秒钟的等待足以消磨他们的耐心。

于是我设计了 VoiceRecognizerRegistry —— 一个全局的服务注册中心：

// 应用启动时异步预加载
void main async {
WidgetsFlutterBinding.ensureInitialized;// 后台静默初始化语音识别服务
VoiceRecognizerRegistry.instance.preInitialize;runApp)，}

主要思想很简单：把初始化前置到应用启动时。使用者从打开 App 到真正使用语音功能。通常会有几秒到几十秒的间隔，足够完成模型加载。当使用者真正点击麦克风按钮时服务已经就绪，即点即用。

class VoiceRecognizerRegistry extends ChangeNotifier {
static VoiceRecognizerRegistry?_instance，static VoiceRecognizerRegistry get instance {
_instance?，= VoiceRecognizerRegistry._;return _instance!，}
// 初始化状态
InitializationStatus _status = InitializationStatus.notStarted;其实，// 预初始化
Future preInitialize async {
if return true;if {
return _initCompleter!按理说，.future，其实，}
_status = InitializationStatus.initializing;// ... 加载模型
}}

这个设计带来了几个好处：

1. 零等待体验使用者感知不到初始化
2. 资源复用全局单例避免重复加载模型
3. 优雅降级如果使用者很快使用语音功能。也能正常等待
4. 状态观测提供完整的 API

至于交互设计，向微信学习

在交互层面我选择了使用者熟悉的模式——长按说话，松开识别。这种交互有几个优点：

1. 符合直觉微信教育了使用者
2. 明确的开始/结束不需要唤醒词或手动停止
3. 取消手指滑开即可。容错性好

配合丰富的视觉反馈：

• 🔵 脉冲动画：表示正在监听
• 🌊 波纹扩散：提高"录中"的感知
• 📊 实时音量：让使用者知道声音被采集到了
• ⏱️ 录音时长：显示多少时间

VoiceRecordButton(
maxDuration:,showRipple: true,showDuration: true,enableHaptic: true,// 触感反馈
onResult: {
// 识别结果
})

实际效果

经过两个迭代，这套离线语音识别已经在生产环境稳定。来看一些数据的观点是，

~2s/ 0ms<500ms~%/ ~~150MB增加~70MB

指标	数值
模型加载时间
识别延迟
识别率
内存使用
包体积

在工地的实际测试中。即使在地下层、完全无信号的环境，语音识别功能依然正常使用。质检员的记录效率了约 %。

集成踩坑实录

这部分是我花了最多的地方。sherpa-onnx + Paraformer 的组合虽然强大，但集成过程中遇到了不少"坑"。希望我的经验帮你少走弯路。

坑1的观点是。音频格式转换——PCM 16bit 到 Float2

问题现象录音能正常采集，但识别结果总是空的，或者输出一堆乱码。

原因分析Paraformer 模型要求的音频格式是16kHz、Float32、单声道。而 record 插件输出的是PCM 16bit 有符号整数。如果直接把 PCM 数据喂给模型，识别结果必然是错。

方法手动做格式转换，将 Int16 归一化到 的浮点数范围：

Float32List _pcm16ToFloat32 {
final length = pcm16.length ~/ 2;if return Float32List;// 将字节数组视为 Int16 数组
final int16Data = Int16List.view;final float32Data = Float32List;for {
// Int16 范围是 -32768 到 32767，归一化到 -1 ~ 1
float32Data = int16Data / 32768;}
return float32Data;}

注意事项除数是 32768 而不是 32767，因为负数的范围比正数多一个。按理说，用 32768 可以保证归一化后的范围对称。

从坑2来看，模型文件加载——Assets 到沙盒的复制

问题现象sherpa-onnx 初始化失败。报错 "file not found" 或 "invalid model"。老实说，

原因分析Flutter 的 assets 文件不能直接通过文件方法访问。必须通过 rootBundle.load 读取，接下来写入到应用沙盒目录。sherpa-onnx 需要的是真实的文件程序方法。

方法

Future _prepareModelFiles async {
try {
final tempDir = await getTemporaryDirectory;final modelDir = Directory;// 确保目录存在
if ) {
await modelDir.create;}
// 复制模型文件
await _copyAssetToFile(
'packages/voice_recognizer/assets/audio_model/model.int8.onnx'。'${modelDir.path}/model.int8.onnx',);// 复制词表
await _copyAssetToFile(
'packages/voice_recognizer/assets/audio_model/tokens.txt'。'${modelDir.path}/tokens.txt',);return modelDir.path;} catch {
debugPrint;怎么说呢，return null;}
}
Future _copyAssetToFile async {
final file = File;// 避免重复复制
if ) {
final data = await rootBundle.load;await file.writeAsBytes);}
}

踩坑

• 方法前缀要用 packages/ 而不是 assets/，这是一个独立的 package
• 首次复制 70MB 的模型需要时间。做好加载提示
• 建议在开发阶段清除缓存旧模型干扰

至于坑3，流式识别 vs 非流式识别——模型选择

问题现象使用 OnlineRecognizer初始化失败，或者识别效果很差。话说回来，

原因分析Paraformer 模型分为两种：

• Paraformer-large：非流式，准确率高。但必须等段音频录完
• Paraformer-streaming：流式，可以边录边识别，但需要专门流式模型

我最初下载的是非流式模型，却用流式 API 加载，自然会问题。

方法类型选择：

// 非流式识别
final config = sherpa.OfflineRecognizerConfig(
model的观点是。sherpa.OfflineParaformerConfig(
至于model，'${modelDir.path}/model.int8.onnx',),tokens: '${modelDir.path}/tokens.txt',numThreads: 4,provider: 'cpu',);final recognizer = sherpa.OfflineRecognizer;// 使用时：先录完，再一次识别
final stream = recognizer.createStream;stream.acceptWaveform;recognizer.decode;final result = recognizer.getResult;

我的选择最终采用非流式识别。虽然不能边录边出，对于质检场景。使用者说完句话通常也就几秒，等待是可以接受的。

再看坑4。Tokens 文件格式——JSON vs TXT

问题现象模型加载成功，识别结果全是乱码或者空白。

原因分析sherpa-onnx要求的 tokens 文件是纯文本格式有些模型下载下来 JSON 格式。

错误的格式

{"你": "","好": "","世": ""。"界": ""}

正确的格式

你好世界...

方法写个脚本转换一下或者直接去 ModelScope/HuggingFace 下载正确格式的 tokens.txt。

说到坑5，iOS 真机调试——动态库签名问题

问题现象模拟器运行正常。真机运行崩溃，报错 "code signature invalid"。

原因分析sherpa-onnx 的 iOS 动态库需要正确签名才能在真机运行。

1. 在 Xcode 中选择正确的开发者证书
2. 确保 Podfile 中配置了动态库嵌入：

post_install do |installer|
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
config.build_settings = 'YES'
end
end
end

1. Clean Build Folder 后重新编译

再看坑6。Android 64位兼容——armeabi-v7a 的缺失

问题现象部分 Android 设备启动崩溃，报错 "couldn't find libsherpa-onnx-jni.so"。

原因分析sherpa-onnx 默认只提供 arm64-v8a 的 so 库，而一些老设备是 32 位的。

方法在 android/app/build.gradle 中限制 ABI：

android {
defaultConfig {
ndk { abiFilters 'armeabi-v7a'。'arm64-v8a' }
}
}

说到坑7，内存泄漏——Stream 对象未释放

问题现象频繁调用语音功能，内存一直增加，直到崩溃。

原因分析没有正确释放 recognizer 对象。其实，

方法在不再使用时手动 dispose：

// 在组件销毁或切换时
recognizer?.dispose，

说到坑8。调试——如何定位失败

问题现象识别结果为空，不知道是录音问题还是模型问题。

方法我加了一套完整的调试日志：

// 检查音频数据
print;// 检查数据范围
double minVal = 32768,maxVal = -32768;for {
if minVal = sample;if maxVal = sample;}
print，// 保存 W 文件用于人工检查

终极调试手段把录制的音频保存成 W 文件，用电脑听一下。怎么说呢，如果人耳都听不清，那模型肯定不了。

写在最终

端侧 AI 正在重塑移动应用的能力。曾经必须依赖云端的能力——语音识别、图像识别、自然语言处理——现在都可以在使用者的设备上运行。

对于我们这种特定场景的应用。端侧 AI 不是"可选项"，而是"必选项"。它让技术真正服务于使用者，而不是让使用者迁就技术的局限。

如果你也在开发类似场景的应用，希望这篇文章能给你一些启发。完整的组件代码已开源，欢迎 Star 和 PR。

pub.dev链接

技术栈：Flutter + Dart + sherpa-onnx + Paraformer-zh

写于 年 月，一个终于不用担心"无信号"的夜晚。

---