5 分钟跑通离线语音识别：Vosk 零基础上手指南-开发者社区

5 分钟跑通离线语音识别：Vosk 零基础上手指南

【免费下载链接】vosk-apiOffline speech recognition API for Android, iOS, Raspberry Pi and servers with Python, Java, C# and Node项目地址: https://gitcode.com/GitHub_Trending/vo/vosk-api

Vosk 是一个可以完全脱机运行的离线语音识别工具包，音频不用出网就能转成文字。这份指南写给第一次接触它的开发者：读完你能装好环境、跑通最小示例，并判断它适不适合你的场景。

为什么值得试它

市面上多数语音识别走云端 API，而 Vosk 把整套识别引擎打包到了本地：

模型小、能上树莓派。单语言模型约 50MB，手机、树莓派这类轻量设备能直接跑；服务器端则提供更大的模型和 GPU 批量识别（python/example/test_gpu_batch.py）。
流式识别，边说边出字。音频按小块喂给识别器，没说完就返回 partial（部分结果），句尾停顿立刻给最终结果，交互延迟几乎为零。
语言覆盖广。英语、中文、日语、德语、法语、西班牙语、俄语、阿拉伯语等 20 多种语言和方言，换模型就能切换语种。
多语言绑定齐全。Python、Java、C、Go、C#、Node.js、Ruby、Kotlin 都有现成封装，仓库里每个语言都有独立目录，如 go/example/ 和 c/test_vosk.c。

三步装好 vosk

你只需要 Python 3，其余由 pip 解决。执行下面这条命令，装好后from vosk import Model即可导入：

pip3 install vosk

模型不用手动准备：Python 模块第一次运行时会自动从官方源下载对应语言的小模型并解压到本地缓存（~/.cache/vosk），也可以先下载好模型目录后用路径加载。

5 分钟跑通第一个例子

准备一段单声道、16 位 PCM 的 WAV 音频（麦克风录的即可），保存为test.wav，然后运行：

import wave from vosk import Model, KaldiRecognizer, SetLogLevel SetLogLevel(-1) # 关闭调试日志，输出更干净 wf = wave.open("test.wav", "rb") model = Model(lang="en-us") # 自动下载英语小模型 rec = KaldiRecognizer(model, wf.getframerate()) while True: data = wf.readframes(4000) # 每次读 4000 帧音频 if len(data) == 0: break if rec.AcceptWaveform(data): # 返回 1 表示识别出一整句 print(rec.Result()) else: print(rec.PartialResult()) # 句中实时输出部分结果 print(rec.FinalResult())

预期效果：终端先滚动打印带partial字段的 JSON（你说到哪它打到哪），每停顿一句就打印一条完整结果的 JSON，最后一行是收尾的FinalResult。打开完整 JSON 能看到result数组，每个词都带start/end秒级时间戳。

四个最值得试的能力

1. 流式识别 + 实时部分结果。上面例子里AcceptWaveform返回 0 时调PartialResult()，做语音助手、听写输入就靠它，人还没说完字已经出来了。

2. 自动生成字幕。开启SetWords(True)拿到词级时间戳后，rec.SrtResult(stream)能直接把音频流转成标准 SRT 字幕文件。仓库里现成的做法是先用 ffmpeg 把任意视频抽成 16kHz 单声道再喂给识别器，参考 python/example/test_srt.py。

3. 说话人识别。加载一个SpkModel附加到识别器上，识别结果里会多出spk向量（说话人指纹）。用它算余弦距离就能判断"这段是不是同一个人说的"，适合做会议记录区分发言人，示例见 python/example/test_speaker.py。

4. 词表限定。初始化KaldiRecognizer时传一个 JSON 词表字符串，识别就被限制在这些词和短语之内。命令式交互（"打开客厅的灯"这类固定指令）用它又快又稳，还能用SetGrammar在运行中动态换词表，示例见 python/example/test_words.py。

三个典型落地场景

离线会议转录。做法：录下会议音频，用Model+KaldiRecognizer循环喂音频，配合SetEndpointerMode调整断句。收益：数据不出内网，合规敏感场景可用，长音频还能开多线程并行处理。

视频批量加字幕。做法：ffmpeg 抽 16kHz 单声道 → 流式喂给识别器 →SrtResult输出 SRT。收益：一部电影的字幕几分钟就能出初稿，再人工校对即可。

嵌入式语音助手。做法：仓库自带 Android/iOS 封装（android/、ios/），App 里把麦克风数据流直接传给识别器。收益：50MB 模型装进手机毫无压力，弱网、无网环境照常工作。

常见坑，先避开 🕳️

音频格式不对直接报错。必须是单声道、16 位 PCM 的 WAV；MP3、视频要先用 ffmpeg 转。
采样率不匹配。模型按 16kHz 训练，如果你的音频是 44.1kHz，先重采样再喂入，否则结果错乱。
说话人向量别用太短的音频算。官方示例里注明：少于 4 秒的语音算出的 x-vector 不太可靠。
想用 GPU 批量识别需要 GPU 版本的模型文件配合BatchModel，普通模型加载不进去。

周边生态与延伸阅读

Kaldi：Vosk 的识别引擎底座，学术血统的开源语音识别工具箱，想深挖声学模型可以看它。
仓库内的入口文档：python/README.md 说明模块能力，python/example/ 是官方示例合集（麦克风、Gradio 网页演示、NLSML 输出等都有），training/ 目录则放了训练自定义模型的脚本。

一句话总结：50MB 模型 + 流式 API，就是 Vosk 的核心卖点。下一步建议——今天就用上面那段代码转一段你手机里的语音，看看部分结果滚出来的速度。

【免费下载链接】vosk-apiOffline speech recognition API for Android, iOS, Raspberry Pi and servers with Python, Java, C# and Node项目地址: https://gitcode.com/GitHub_Trending/vo/vosk-api

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考