3行代码跑通Vosk离线语音识别：零基础从安装到出字幕完整攻略

3行代码跑通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 是一个完全离线的开源语音识别工具包：音频在本地转文字，不上传任何数据，支持 20 多种语言，模型只有约 50MB。它适合想在自己设备、树莓派或服务器上嵌入语音转文字的开发者，以及不想把会议录音、采访音频交给云端处理的你。

它到底解决什么问题

一句话：把"音频→文字"做成一个可以在树莓派上跑的本地库。

和云端识别 API 相比，区别在于三点：

• 断网可用，音频不出内网，隐私可控
• 流式接口，边说边出结果，延迟接近零
• 模型约 50MB（小模型），加载快、部署轻

代价是识别精度略低于大型云端服务，专有名词、强口音场景要多做调优。

五分钟装好

三步：装包、下模型、跑示例。

第 1 步，装 Python 包：

pip install vosk

第 2 步，准备模型。你不用手动下载：Model(lang="en-us")会按语言名自动查找本地缓存（~/.cache/vosk），找不到就自动下载解压。中文对应lang="zh-cn"，全部可选模型名可以查仓库里 python/vosk/init.py 中的模型列表逻辑。

第 3 步，跑最小示例。准备一个 16kHz、单声道、16bit 的 WAV 文件，然后：

import wave from vosk import Model, KaldiRecognizer model = Model(lang="en-us") wf = wave.open("test.wav", "rb") rec = KaldiRecognizer(model, wf.getframerate()) while True: data = wf.readframes(4000) if len(data) == 0: break if rec.AcceptWaveform(data): print(rec.Result()) print(rec.FinalResult())

运行后，每识别完一句就打印一段 JSON，rec.Result()返回{"result": ["word", "word"]}，最后一句在循环外由FinalResult()兜底——这个细节很多人漏掉，导致结尾丢字。

最常用功能逐个过

流式识别与实时中间结果

AcceptWaveform返回 0 时，用rec.PartialResult()拿当前半句话，就能做"边说边显示"的交互界面；返回 1 表示一句话结束，取Result()。麦克风实时转写的完整写法在 python/example/test_microphone.py，依赖pip install sounddevice，音频块通过队列喂给识别器，结构可以直接抄。

顺手生成 SRT 字幕

SrtResult内置了按词时间戳切字幕的逻辑，配合 ffmpeg 把任意视频音频流成 16kHz 单声道，十几行就能出 .srt 文件：

import subprocess from vosk import Model, KaldiRecognizer model = Model(lang="en-us") rec = KaldiRecognizer(model, 16000) rec.SetWords(True) # 字幕依赖逐词时间戳，必须开启 cmd = ["ffmpeg", "-loglevel", "quiet", "-i", "video.mp4", "-ar", "16000", "-ac", "1", "-f", "s16le", "-"] with subprocess.Popen(cmd, stdout=subprocess.PIPE).stdout as stream: print(rec.SrtResult(stream))

仓库里的 python/example/test_srt.py 就是这段的完整版。想批量处理整个目录、输出 txt/srt/json，可以看 python/vosk/transcriber/ 里的 Transcriber 实现，它已经写好了 ffmpeg 重采样和多任务并行。

用语法锁住识别范围

自由识别之外，KaldiRecognizer支持传入 JSON 词表做受限识别，适合命令词场景（如"上/下/暂停"）：

rec = KaldiRecognizer(model, rate, '["one two three", "[unk]"]')

只接受词表里的短语，加[unk]兜底识别表外内容；运行时还能用rec.SetGrammar()换词表，做动态菜单。

说话人识别

加载一个说话人模型SpkModel(path)后，识别结果里会多出一个spk向量，用余弦距离判断"是不是同一个人"，可做免唤醒的身份确认。参考 python/example/test_speaker.py。注意短于 4 秒的语句 x-vector 不可靠。

多语言与多平台

20 多种语言模型按需加载，切语言就是Model(lang="xx")换个参数。除 Python 外，仓库自带 Java/Kotlin（含 Android 语音服务）、Node.js、C#、Go、C 的绑定和示例，手机侧入口在 android/lib/src/main/java/org/vosk/。GPU 批量推理有GpuInit()+BatchModel接口，适合服务器场景。

踩过坑才知道的实用技巧

• 采样率必须和识别器声明的一致。KaldiRecognizer(model, 16000)就喂 16kHz 音频，不一致时识别全乱且无报错，先查wf.getframerate()。
• 非标准格式先转码。Vosk 只吃 WAV 单声道 16bit PCM，MP3/48kHz 立体声先用 ffmpeg 转，别指望它自动兼容。
• 静音太长会误判句尾。长停顿被当成句子结束，可用rec.SetEndpointerMode()调成LONG模式放宽判定。
• 小模型优先。50MB 的 small 模型覆盖大多数场景，别一上来就选大模型拖慢加载。

高频问题，一句话答

现象：Failed to create a model→ 原因：模型路径不存在或没下载完 → 解法：改用Model(lang="xx")让它自动下载，或检查网络后重试。

现象：识别结果全空或乱码→ 原因：音频不是 16kHz 单声道 16bit → 解法：ffmpeg -i in.mp3 -ar 16000 -ac 1 -f s16le out.wav转码后再喂。

现象：句子末尾丢字→ 原因：没取最终结果 → 解法：音频读完后再调一次rec.FinalResult()。

总结

Vosk 用"约 50MB 模型 + 流式 API + 多语言绑定"换来了断网环境里可用的完整离线语音识别链路。下一步：pip install vosk，clone 仓库（git clone https://gitcode.com/GitHub_Trending/vo/vosk-api）后打开 python/example/，先跑通 test_simple.py，再换你的音频。

【免费下载链接】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