WhisperLiveKit Python API教程：30行代码集成实时语音识别功能

【免费下载链接】WhisperLiveKit Real-time, Fully Local Speech-to-Text and Speaker Diarization. FastAPI Server & Web Interface 项目地址: https://gitcode.com/GitHub_Trending/wh/WhisperLiveKit

你是否还在为实时语音识别功能的复杂集成而烦恼？是否需要一个轻量级、本地化的解决方案来处理语音转文本任务？本文将带你通过30行代码，快速集成WhisperLiveKit的实时语音识别功能，无需复杂配置，即可实现高效准确的语音转文字。读完本文后，你将能够：搭建本地语音识别服务、自定义识别参数、处理实时语音流数据，并将结果集成到自己的应用中。

项目简介

WhisperLiveKit是一个专注于实时、全本地化的语音转文本和说话人分离工具包，提供FastAPI服务器和Web界面，支持本地部署，保护数据隐私。其核心功能包括实时语音识别（ASR）、说话人分离（Speaker Diarization）和语音活动检测（VAD），适用于会议记录、实时字幕生成、语音助手等场景。

项目架构如图所示：

主要模块说明：

• 核心引擎：whisperlivekit/core.py - 负责初始化语音识别、说话人分离等核心组件
• 服务器实现：whisperlivekit/basic_server.py - 提供FastAPI接口和WebSocket通信
• 语音处理：whisperlivekit/audio_processor.py - 处理音频流和识别结果
• 实时识别：whisperlivekit/simul_whisper/ - 实现实时流式语音识别
• 说话人分离：whisperlivekit/diarization/ - 支持多种说话人分离后端

环境准备

安装步骤

首先克隆项目仓库：

git clone https://gitcode.com/GitHub_Trending/wh/WhisperLiveKit
cd WhisperLiveKit

使用pip安装依赖：

pip install .

如需支持GPU加速，建议安装额外依赖：

pip install .[gpu]

系统要求

• Python 3.8+
• 推荐8GB以上内存
• 可选：NVIDIA GPU（支持CUDA加速）

快速开始：30行代码实现实时语音识别

基础示例：启动本地服务器

创建一个simple_server.py文件，输入以下代码：

from whisperlivekit.core import TranscriptionEngine
from whisperlivekit.basic_server import app, main as run_server
import uvicorn

# 初始化转录引擎
engine = TranscriptionEngine(
    model_size="base",  # 模型大小：tiny/base/small/medium/large
    lan="auto",         # 自动检测语言
    vad=True,           # 启用语音活动检测
    diarization=False   # 禁用说话人分离（简化示例）
)

# 启动FastAPI服务器
if __name__ == "__main__":
    uvicorn.run(
        app,
        host="0.0.0.0",  # 允许外部访问
        port=8000,       # 服务端口
        log_level="info"
    )

运行服务器：

python simple_server.py

打开浏览器访问http://localhost:8000，即可看到Web界面，点击"开始录音"按钮测试实时语音识别功能。

代码解析

上述代码主要完成了三个核心步骤：

1. 初始化转录引擎：通过TranscriptionEngine类配置语音识别参数，包括模型大小、语言设置、VAD等。支持的模型大小可参考可用模型文档。

2. 创建FastAPI应用：复用项目内置的FastAPI应用实例，该实例已实现WebSocket接口（/asr端点）用于实时音频流传输。

3. 启动Web服务器：使用uvicorn运行FastAPI应用，监听指定端口，提供Web服务和WebSocket通信能力。

自定义配置

模型选择

WhisperLiveKit支持多种模型大小和格式，可根据需求选择：

# 使用小型模型（更快，精度较低）
engine = TranscriptionEngine(model_size="small")

# 使用英文专用模型（更小更快）
engine = TranscriptionEngine(model_size="base.en", lan="en")

# 指定模型缓存目录
engine = TranscriptionEngine(
    model_size="medium",
    model_cache_dir="/path/to/cache"
)

支持的模型格式和兼容性详情参见模型格式文档。

启用说话人分离

通过简单配置即可启用说话人分离功能：

engine = TranscriptionEngine(
    model_size="base",
    diarization=True,              # 启用说话人分离
    diarization_backend="sortformer"  # 使用Sortformer后端
)

支持的说话人分离后端包括sortformer和diart，可根据硬件条件选择。

语音活动检测配置

自定义语音活动检测参数：

engine = TranscriptionEngine(
    model_size="base",
    vad=True,
    vac_onnx=True,  # 使用ONNX加速VAD模型
    vac_chunk_size=0.04  # 设置VAD检测块大小（秒）
)

集成到现有应用

WebSocket客户端示例

以下是一个Python WebSocket客户端示例，用于接收实时识别结果：

import asyncio
import websockets
import json

async def connect_to_asr_server():
    uri = "ws://localhost:8000/asr"
    async with websockets.connect(uri) as websocket:
        # 接收配置信息
        config = await websocket.recv()
        print("服务器配置:", json.loads(config))
        
        # 接收识别结果
        while True:
            result = await websocket.recv()
            data = json.loads(result)
            if data["type"] == "transcription":
                print(f"识别结果: {data['text']}")
            elif data["type"] == "speaker":
                print(f"说话人 {data['speaker']}: {data['text']}")

asyncio.run(connect_to_asr_server())

处理音频文件

除了实时流处理，WhisperLiveKit也支持处理本地音频文件：

from whisperlivekit.audio_processor import AudioProcessor
import asyncio

async def process_audio_file(file_path):
    # 初始化引擎和处理器
    engine = TranscriptionEngine(model_size="base")
    processor = AudioProcessor(transcription_engine=engine)
    
    # 读取音频文件
    with open(file_path, "rb") as f:
        audio_data = f.read()
    
    # 处理音频并获取结果
    results_generator = await processor.create_tasks()
    processor.process_audio(audio_data)
    
    # 输出结果
    async for result in results_generator:
        print(result.to_dict())

# 处理示例音频文件
asyncio.run(process_audio_file("example.wav"))

高级功能

多语言支持

WhisperLiveKit支持多种语言的实时识别，完整语言列表参见支持语言文档。指定识别语言：

# 中文识别
engine = TranscriptionEngine(model_size="base", lan="zh")

# 中英文混合识别
engine = TranscriptionEngine(model_size="base", lan="zh", task="transcribe")

API接口

项目提供完整的API接口，详情参见API文档。主要接口包括：

• GET /：Web界面
• WS /asr：实时语音识别WebSocket接口

常见问题解决

模型下载缓慢

设置国内模型下载源：

engine = TranscriptionEngine(
    model_size="base",
    model_cache_dir="~/.cache/whisper",
    # 如需使用国内镜像，可设置环境变量
    # os.environ["TRANSFORMERS_OFFLINE"] = "1"
)

性能优化

对于资源受限的设备，可通过以下方式优化性能：

# 使用更小的模型
engine = TranscriptionEngine(model_size="tiny")

# 禁用不必要的功能
engine = TranscriptionEngine(
    model_size="base",
    diarization=False,  # 禁用说话人分离
    disable_fast_encoder=True  # 禁用快速编码器
)

总结

本文介绍了如何使用WhisperLiveKit快速集成实时语音识别功能，包括环境准备、基础示例、自定义配置和高级应用。通过简单的API调用，即可在30行代码内实现一个功能完善的实时语音识别服务。

WhisperLiveKit的本地化部署特性使其特别适合对数据隐私有要求的场景，而其高效的实时处理能力则适用于各种实时交互应用。更多高级功能和配置选项，请参考项目官方文档。

官方文档：docs/ 核心代码：whisperlivekit/core.py 服务器实现：whisperlivekit/basic_server.py

【免费下载链接】WhisperLiveKit Real-time, Fully Local Speech-to-Text and Speaker Diarization. FastAPI Server & Web Interface 项目地址: https://gitcode.com/GitHub_Trending/wh/WhisperLiveKit