VOSK语音识别API使用教程：从基础到进阶的完整指南

引言：VOSK的技术优势与适用场景

VOSK作为开源语音识别工具包，凭借其轻量化、离线运行、支持多语言（含中文）及领域定制能力，在智能家居、医疗记录、客服系统等场景中广受开发者青睐。其核心优势在于：

离线识别：无需依赖网络，保障数据隐私；
多模型支持：提供通用、医疗、金融等垂直领域模型；
跨平台兼容：支持Windows/Linux/macOS及嵌入式设备。

本文将系统讲解VOSK API的调用流程，帮助开发者快速实现语音转文本功能。

一、环境准备与依赖安装

1.1 基础环境要求

操作系统：Windows 10+/Linux（Ubuntu 20.04+）/macOS 11+
硬件：CPU需支持SSE4.1指令集（2012年后主流CPU均满足）
内存：通用模型需≥2GB空闲内存，大词汇量模型建议≥4GB

1.2 依赖库安装（Python示例）

# 创建虚拟环境（推荐）
python -m venv vosk_env
source vosk_env/bin/activate  # Linux/macOS
# vosk_env\Scripts\activate  # Windows
# 安装VOSK Python包
pip install vosk
# 可选：安装音频处理库（处理WAV/MP3等格式）
pip install pydub soundfile

1.3 模型下载与配置

VOSK提供预训练模型，需根据语言和场景选择：

中文模型：vosk-model-cn（通用）或vosk-model-cn-spn（带标点）
英文模型：vosk-model-small-en-us-0.15（轻量）或vosk-model-en-us-0.22（高精度）

下载后解压至项目目录，例如：

/project
  ├── models/
  │   └── vosk-model-cn/  # 中文模型目录
  └── main.py

二、基础API调用流程

2.1 初始化识别器

from vosk import Model, KaldiRecognizer
import json
# 加载模型（首次加载较慢）
model = Model("models/vosk-model-cn")
# 创建识别器（参数：采样率16000Hz，单声道）
recognizer = KaldiRecognizer(model, 16000)

2.2 实时音频流处理

方案1：从麦克风实时识别

import pyaudio  # 需安装：pip install pyaudio
p = pyaudio.PyAudio()
stream = p.open(format=pyaudio.paInt16, channels=1,
                rate=16000, input=True, frames_per_buffer=4096)
while True:
    data = stream.read(4096)
    if recognizer.AcceptWaveForm(data):
        result = json.loads(recognizer.Result())
        print("识别结果:", result["text"])

方案2：处理预录音频文件

import wave
def recognize_file(wav_path):
    wf = wave.open(wav_path, "rb")
    recognizer = KaldiRecognizer(model, wf.getframerate())
    while True:
        data = wf.readframes(4096)
        if not data:
            break
        if recognizer.AcceptWaveForm(data):
            print(json.loads(recognizer.Result())["text"])
    # 处理最终结果（可能包含部分结果）
    print("最终结果:", json.loads(recognizer.FinalResult())["text"])
recognize_file("test.wav")

三、高级功能实现

3.1 标点符号与大小写恢复

使用vosk-model-cn-spn模型可自动添加标点：

model_spn = Model("models/vosk-model-cn-spn")
recognizer_spn = KaldiRecognizer(model_spn, 16000)
# 后续处理流程与基础调用一致

3.2 说话人分离（Diarization）

VOSK支持通过SpeakerDiarization模块实现多人对话分离：

from vosk import SpeakerDiarization
diarization = SpeakerDiarization(model, 16000)
with open("audio.wav", "rb") as f:
    while True:
        data = f.read(4096)
        if not data:
            break
        diarization.AcceptWaveForm(data)
    # 获取说话人分段信息
    segments = json.loads(diarization.FinalResult())["segments"]
    for seg in segments:
        print(f"说话人{seg['speaker']}: {seg['start']:.2f}s-{seg['end']:.2f}s")

3.3 自定义词汇表

通过set_words方法添加领域专用词汇：

recognizer.SetWords("肺炎 抗生素 血常规")
# 或从文件加载
with open("medical_terms.txt") as f:
    terms = f.read().splitlines()
recognizer.SetWords("\n".join(terms))

四、性能优化与常见问题

4.1 实时性优化技巧

批量处理：增大frames_per_buffer（如8192）减少回调次数
模型裁剪：使用vosk-model-tiny-cn（体积仅50MB）
硬件加速：在ARM设备上启用NEON指令集

4.2 常见错误处理

错误现象	可能原因	解决方案
`RuntimeError: Sample rate mismatch`	音频采样率非16kHz	使用`sox`转换：`sox input.wav -r 16000 output.wav`
识别结果为空	音频能量过低	调整麦克风增益或使用`pydub`归一化：`sound.normalize()`
内存不足	模型过大	切换至`small`或`tiny`版本模型

五、跨语言集成示例

5.1 Java调用示例

// 需添加依赖：implementation 'org.vosk:vosk:0.3.45'
import org.vosk.*;
public class VoskDemo {
    public static void main(String[] args) {
        Model model = new Model("models/vosk-model-cn");
        Recognizer recognizer = new Recognizer(model, 16000);
        try (InputStream ais = AudioSystem.getAudioInputStream(new File("test.wav"))) {
            byte[] buffer = new byte[4096];
            int bytesRead;
            while ((bytesRead = ais.read(buffer)) > 0) {
                if (recognizer.acceptWaveForm(buffer, bytesRead)) {
                    System.out.println(recognizer.getResult());
                }
            }
            System.out.println(recognizer.getFinalResult());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

5.2 C++调用示例

#include <vosk/model.h>
#include <vosk/recognizer.h>
#include <sndfile.hh>
int main() {
    vosk::Model model("models/vosk-model-cn");
    vosk::Recognizer recognizer(model, 16000);
    SF_INFO sfinfo;
    SNDFILE *infile = sf_open("test.wav", SFM_READ, &sfinfo);
    if (!infile) {
        fprintf(stderr, "无法打开文件\n");
        return 1;
    }
    const int buffer_size = 4096;
    float buffer[buffer_size];
    size_t nread;
    while ((nread = sf_readf_float(infile, buffer, buffer_size)) > 0) {
        if (recognizer.acceptWaveForm(buffer, nread)) {
            fprintf(stdout, "%s\n", recognizer.Result().c_str());
        }
    }
    fprintf(stdout, "%s\n", recognizer.FinalResult().c_str());
    sf_close(infile);
    return 0;
}

六、最佳实践建议

模型选择：通用场景用small模型，专业领域下载对应模型

预处理优化：对含噪音频使用pydub进行降噪：

from pydub import AudioSegment
sound = AudioSegment.from_wav("noisy.wav")
clean = sound.low_pass_filter(3000)  # 滤除高频噪声
clean.export("clean.wav", format="wav")

结果后处理：结合正则表达式修正常见错误，如数字格式化：

import re
text = "一二三四"
corrected = re.sub(r'一二三四', '1234', text)  # 实际需更复杂的规则

结语

VOSK API通过其灵活的设计和高效的实现，为开发者提供了强大的语音识别能力。从本文的示例代码可以看出，无论是Python脚本开发、Java企业应用集成，还是C++嵌入式部署，VOSK都能提供良好的支持。建议开发者根据实际场景选择合适的模型，并通过预处理和后处理进一步提升识别效果。

VOSK语音识别API使用全攻略：从入门到精通