站点图标 高效码农

无需联网！本地实时语音转文字系统搭建指南（支持说话人分离）

高效码农

WhisperLiveKit：把实时语音转文字装进本地浏览器

“

“我能不能在不上传任何音频文件的情况下，把会议内容实时转成文字，并且知道是谁在说话？”
WhisperLiveKit 的回答是：可以，而且只需要一条命令。

1. 它到底是什么？

WhisperLiveKit 是一个开源的“后端 + 前端”组合包，用一句话概括：
在浏览器里说话，立刻看到文字，还能区分说话人——所有计算都在本地完成，无需联网上传。

核心能力一览

功能 说明 典型场景
实时语音识别 边说边出字，延迟可低至几百毫秒 会议速记、课堂笔记
说话人分离（Diarization） 自动标注“谁说了哪句话” 访谈整理、客服质检
语音活动检测（VAD） 没有声音时不浪费计算 长时间录音
超低延迟选项 SimulStreaming 2025 年 SOTA 研究，对齐注意力策略 直播字幕
多人并发 一台服务器供多人同时使用 小型企业内部部署

2. 十分钟无痛上手

2.1 先装系统依赖：FFmpeg

FFmpeg 负责把麦克风采集到的原始音频转成模型能懂的格式。

操作系统 命令或方式
Ubuntu / Debian sudo apt install ffmpeg
macOS brew install ffmpeg
Windows 官网 下载 exe，并把路径加入环境变量

2.2 一键装 Python 包

pip install whisperlivekit

如果你还想体验说话人分离，再多装一个扩展：

pip install whisperlivekit[diarization]

2.3 启动服务器

whisperlivekit-server --model tiny.en

看到日志提示 Uvicorn running on http://localhost:8000 即可。

2.4 打开浏览器

在地址栏输入 http://localhost:8000，允许麦克风权限，开始说话——文字会实时出现在屏幕上。

“

第一次用？系统会自动下载 tiny.en 模型，大约 75 MB，耐心等待几秒即可。

3. 进阶用法：把参数玩出花

3.1 命令行参数速查表

常用参数 默认值 作用
--model tiny 模型体积越大，精度越高，延迟也越高：tiny < base < small < medium < large
--language en 设为 auto 可自动检测语言
--diarization False 开启后需要 Hugging Face 授权，详见下文
--backend faster-whisper 可选 simulstreaming 获得极限低延迟
--host / --port localhost / 8000 局域网部署时改成 0.0.0.0 即可

完整列表请见官方文档或运行 whisperlivekit-server --help。

3.2 低延迟场景：SimulStreaming 后端

whisperlivekit-server \
  --backend simulstreaming \
  --model large-v3 \
  --frame-threshold 20
  • frame-threshold 越小，反应越快，但可能牺牲一点准确性。
  • 注意：*.en 单语言模型不支持 SimulStreaming。

4. 说话人分离（Diarization）三步走

“谁在说话”功能需要 pyannote 的预训练模型，这些模型托管在 Hugging Face 并设置了用户协议。流程如下：

  1. 用你的 Hugging Face 账号分别点击接受以下模型页面：

    • pyannote/segmentation
    • pyannote/segmentation-3.0
    • pyannote/embedding

  2. 在终端登录

    huggingface-cli login

  3. 启动服务

    whisperlivekit-server --model medium --diarization

成功后，返回的字典里会多出 speaker 字段，例如：

{"text": "明天下午三点开会。", "speaker": "A"}

5. 用 Python 把它嵌进自己的项目

官方仓库里的 basic_server.py 提供了完整示例，核心思路只有四步：

  1. 创建一个全局的 TranscriptionEngine 实例（很重，只建一次）。
  2. 每个 WebSocket 连接对应一个 AudioProcessor 实例，负责把原始音频切片喂给引擎。
  3. 用 async for 循环把识别结果实时推给前端。
  4. 前端用 WebSocket 接收 JSON，渲染即可。

最小可运行片段：

from whisperlivekit import TranscriptionEngine, AudioProcessor
from fastapi import FastAPI, WebSocket

engine = TranscriptionEngine(model="medium", diarization=True)

@app.websocket("/asr")
async def asr(websocket: WebSocket):
    await websocket.accept()
    audio_proc = AudioProcessor(transcription_engine=engine)
    async for msg in audio_proc.start():
        await websocket.send_json(msg)

6. 前端：拿来即用的 HTML

项目自带 live_transcription.html，支持：

  • 麦克风权限申请
  • WebSocket 自动重连
  • 实时字幕样式
  • 说话人颜色标记（开启 diarization 后）

你也可以在 Python 里直接拿到 HTML 字符串：

from whisperlivekit import get_web_interface_html
html = get_web_interface_html()

7. 生产部署：从笔记本到服务器

7.1 用 Gunicorn 开多进程

pip install uvicorn gunicorn
gunicorn -k uvicorn.workers.UvicornWorker -w 4 main:app

其中 -w 4 表示 4 个 worker，适合 4 核 CPU。

7.2 Nginx 反向代理（推荐）

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

如需 HTTPS，把证书路径填进 --ssl-certfile 与 --ssl-keyfile 即可。

8. Docker 一条命令跑起来

官方 Dockerfile 已内置常用依赖，示例：

# 构建镜像
docker build -t whisperlivekit .

# 运行（带 GPU）
docker run --gpus all -p 8000:8000 whisperlivekit --model base

# 纯 CPU 机器请去掉 --gpus all

构建参数

参数 示例 用途
EXTRAS whisper-timestamped 额外 Python 依赖
HF_PRECACHE_DIR ./.cache/ 预下载模型，缩短冷启动
HF_TKN_FILE ./token 提前放入 Hugging Face token，免去交互式登录

9. 常见疑问解答（FAQ）

Q1：必须联网吗？
不需要。模型和代码全部在本地运行，除非你要下载模型权重或 Hugging Face 授权。

Q2：支持哪些语言？
Whisper 官方支持 99 种语言，只要模型名称里没有 .en，都可以用 --language auto 自动识别。

Q3：延迟到底有多少？

  • faster-whisper + tiny：台式机约 300–500 ms
  • simulstreaming + large-v3：可压到 200 ms 以下
  • 影响因素：模型大小、CPU/GPU、音频块大小（--min-chunk-size）。

Q4：为什么没有检测到人声？
检查麦克风权限，或加上 --no-vad 关闭 VAD 做对比测试。
也可能是 --min-chunk-size 设得太大，尝试调到 0.5 秒。

Q5：能否离线安装？
可以。在一台联网机器先运行一次，把 ~/.cache/huggingface 和 ~/.cache/whisper 整个目录打包，复制到目标机即可。

Q6：商用收费吗？
代码 MIT 许可证；SimulStreaming 后端采用双许可证，闭源需要商业授权，开源项目不受影响。

10. 场景灵感：把技术落地

场景 如何配置 额外提醒
小型会议室 --model medium --diarization 配一只 360° 麦克风，准确率更高
直播字幕 --backend simulstreaming --frame-threshold 15 字幕提前量 200 ms，观众几乎无感
客服质检 --language zh --diarization 结合业务系统，把 speaker 字段入库
语音笔记 App 把 HTML 嵌入 Flutter WebView 用 WebSocket 桥接原生录音 API

11. 小结：为什么值得试

  • 零门槛：一条命令启动，浏览器就能用。
  • 全本地：数据不出电脑，隐私风险降到最低。
  • 可扩展：Python API、Docker、Nginx，任意组合。
  • 紧跟前沿：2025 年最新 SimulStreaming、Streaming Sortformer 直接可用。

如果你正在寻找“听得懂、分得清、跑得快”的本地语音转文字方案，WhisperLiveKit 已经替你搭好了桥，剩下的只是开口说话。

退出移动版