更新记录

1.0.1（2026-03-31） 下载此版本

localAsrEngine

基于 sherpa-onnx 的 uni-app x Android 离线语音识别插件。

当前版本已经满足：

• Android 调试基座可直接运行
• 插件内置模型，项目接入后可直接初始化使用
• 支持实时流式麦克风识别
• 支持结果回调和结果轮询兜底

平台兼容性

uni-app(5.0)

uni-app x(5.0)

localAsrEngine

基于 sherpa-onnx 的 uni-app x Android 离线语音识别插件。

当前版本已经满足：

• Android 调试基座可直接运行
• 插件内置模型，项目接入后可直接初始化使用
• 支持实时流式麦克风识别
• 支持结果回调和结果轮询兜底

当前不包含：

• iOS
• 文件识别
• 自定义基座必需依赖

安装

将插件目录放到项目的 uni_modules/localAsrEngine。

当前项目采用的是外部开发目录映射：

D:\HBuilderProjects\asr-demo\uni_modules\localAsrEngine -> D:\project\localAsrEngine

使用

import {
  init,
  startListening,
  stopListening,
  release,
  getState,
  getLatestResult
} from '@/uni_modules/localAsrEngine'

await init({
  modelPath: '/uni_modules/localAsrEngine/static/models/zh/encoder.int8.onnx',
  decoderPath: '/uni_modules/localAsrEngine/static/models/zh/decoder.int8.onnx',
  tokensPath: '/uni_modules/localAsrEngine/static/models/zh/tokens.txt',
  numThreads: 4,
  provider: 'cpu',
  debug: false
})

await startListening({
  onResult: (result) => {
    console.log(result.text, result.isFinal)
  }
})

await stopListening()

const latest = getLatestResult()
console.log(latest?.text)

await release()

API

init(config)

初始化识别器。

可用配置：

• modelPath
• decoderPath
• tokensPath
• numThreads
• provider
• debug
• dither

说明：

• debug: true 时会输出更详细的插件日志
• 默认推理提供者为 cpu

startListening(handlers)

开始麦克风流式识别。

支持回调：

• onStart
• onResult
• onError
• onStop

stopListening()

停止识别并输出最终结果。

getLatestResult()

获取插件内部缓存的最新识别结果。

适合在页面层做轮询兜底，避免个别环境下回调显示不稳定。

getState()

返回：

{
  isInitialized: boolean,
  isListening: boolean
}

release()

释放识别器、录音器和流对象。

目录说明

localAsrEngine/
├── package.json
├── readme.md
├── changelog.md
├── index.uts
├── static/
│   ├── models/zh/
│   └── native-libs-bin/
└── utssdk/
    └── app-android/
        ├── index.uts
        ├── libs/
        └── com/k2fsa/sherpa/onnx/

说明：

• static/models/zh 是内置识别模型
• static/native-libs-bin 是调试基座场景下的本地库分发资源
• utssdk/app-android/libs 是 Android 原生 .so 源目录

已做的兼容处理

• 兼容 HBuilder 调试基座下 .so 不在 APK lib/ 目录的场景
• 兼容结果回调显示不稳定时的结果轮询
• 兼容日志文本在 Windows 下查看时的编码问题，日志输出改为 ASCII 安全格式

调优建议

• numThreads 建议 2~4
• debug 默认保持 false，只在排查问题时打开
• 中文识别效果依赖当前内置模型，若后续更换模型，需要同时校验 tokens.txt

后续优化建议

当前版本已经可用于 Android 离线实时识别，后续如果继续提升效果，建议按下面顺序推进：

1. 线程数自适应

根据设备 CPU 核数动态设置 numThreads，避免低端机线程过多、高端机线程利用不足。

2. 模型 A/B 对比

当前内置模型偏向实时流式和工程稳定性。若要继续提高中文口语识别准确率，建议增加新模型配置入口，和当前模型做同场景对比测试。

3. 端点与去重策略优化

当前已经能正常返回连续结果。后续可以继续优化端点判定、重复片段抑制和最终结果稳定策略，减少中间文本抖动。

4. 结果展示与诊断分层

页面展示已经有回调和轮询兜底。后续可以把调试日志、用户展示文本、开发诊断信息进一步分层，减少调试代码对正式使用的干扰。