Brave：「# WhisperLiveKit：低延迟、自托管的语音转文本与说话人识别工具 [trilium_note…」

Brave

@47c132035ed7a1105a867946b99d67af 人工智能研究 26 December 2025 公开

WhisperLiveKit：低延迟、自托管的语音转文本与说话人识别工具

在语音识别领域，OpenAI 的 Whisper 模型虽然精准，但它主要是为处理完整音频片段而设计的（Batch Processing），并不适合实时的流式传输。简单地将音频切块输入 Whisper 往往会导致上下文丢失、单词被截断以及识别准确率的显著下降。

WhisperLiveKit (WLK) 应运而生。这是一个专为超低延迟、自托管场景设计的语音转文本（STT）解决方案。它集成了 2025 年最前沿的研究成果，不仅解决了流式传输的痛点，还支持实时说话人识别（Diarization）和多语言互译。

🚀 核心技术：为什么选择 WLK？

WhisperLiveKit 并非简单的 Whisper API 封装，它采用了多项 SOTA (State-of-the-Art) 技术来攻克实时流式处理的难题：

⚡ 极速转录 (SOTA 2025)

基于 Simul-Whisper 和 AlignAtt 策略，实现了毫秒级的超低延迟转录。同时也支持 LocalAgreement 策略的 WhisperStreaming。

🍎 Apple Silicon 原生加速

针对 Mac 用户，深度集成了 MLX 框架，直接调用 Apple 神经引擎 (ANE) 和 GPU。

🌐 实时翻译 (SOTA 2025)

集成了 NLLW（基于蒸馏版 NLLB），支持 200 种语言之间的实时互译。

👥 说话人识别 (SOTA 2025)

利用 Streaming Sortformer 和 Diart 技术，能够在实时转录的同时精准区分不同的说话人。

🛑 企业级 VAD

内置 Silero VAD (2024)，有效检测语音活动，大幅减少静音片段的资源消耗。

🧠 智能缓冲

采用智能缓冲和增量处理机制，而非简单的批处理，确保了流式传输时的上下文完整性和识别精度。

🛠️ 部署指南：根据硬件选择最佳方案

为了获得最佳性能，请根据您的硬件环境选择对应的安装方式。

🍎 方案一：Apple Silicon (M1/M2/M3/M4) 专属极速方案

> ⚠️ 重要提示：不要在 macOS 上使用 Docker 部署！ > > 原因：Docker 在 macOS 上运行于 Linux 虚拟机中，无法直接调用 Apple 的 GPU (Metal) 或神经引擎 (ANE)。如果强行使用 Docker，模型将只能在纯 CPU 模式下运行，速度极慢，完全无法达到“超低延迟”的效果。

最佳实践：请使用以下原生安装 (Native) 方案，利用 mlx-whisper 库彻底释放 Apple Silicon 的性能。

1. 准备工作

确保已安装 Homebrew 和 Python (建议 3.10 或 3.11)。首先安装音频处理必备工具 ffmpeg：

brew install ffmpeg

2. 创建虚拟环境并安装

为了防止污染系统环境，强烈建议创建一个独立的虚拟环境：

# 1. 创建名为 wlk_env 的虚拟环境
python3 -m venv wlk_env

# 2. 激活环境
source wlk_env/bin/activate

# 3. 安装 Apple MLX 加速库
pip install mlx mlx-whisper

# 4. 从 GitHub 安装最新版 WhisperLiveKit
pip install git+https://github.com/QuentinFuxa/WhisperLiveKit.git

3. 启动服务 (MLX 模式)

使用 --backend mlx-whisper 参数启动，即可享受丝滑的实时转录：

# 启动 Small 模型，识别中文，监听 9000 端口
wlk --model small --language zh --backend mlx-whisper --host 0.0.0.0 --port 9000

每次启动时需要输入：

source wlk_env/bin/activate
wlk --model small --language zh --backend mlx-whisper --host 0.0.0.0 --port 9000

如果需要将 WhisperLiveKit 配置为 macOS 的后台守护进程，实现开机即用，则需要进一步进行如下配置：

第一步：定位您的环境路径

在配置之前，请确认您的虚拟环境路径。一般为：
/Users/[您的用户名]/wlk_env/bin/wlk

第二步：创建必要的系统目录

macOS 的用户级启动项存放在特定的隐藏文件夹中，如果该文件夹不存在，后续操作会报错。

打开 终端 (Terminal)。
输入以下命令并回车：
```
mkdir -p ~/Library/LaunchAgents
```

第三步：创建自动化配置文件 (plist)

我们将利用 macOS 原生的 launchd 服务。请在终端中完整复制以下命令块并运行：

注意： 请将代码中第三行的 [您的用户名] 替换为您真实的系统用户名（例如 kola）。

cat <<EOF > ~/Library/LaunchAgents/com.wlk.server.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "www.apple.com">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.wlk.server</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/[您的用户名]/wlk_env/bin/wlk</string>
        <string>--model</string>
        <string>small</string>
        <string>--language</string>
        <string>zh</string>
        <string>--backend</string>
        <string>mlx-whisper</string>
        <string>--host</string>
        <string>0.0.0.0</string>
        <string>--port</string>
        <string>9000</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/wlk.log</string>
    <key>StandardErrorPath</key>   
    <string>/tmp/wlk.err</string>
</dict>
</plist>
EOF

第四步：激活自动化服务

运行以下命令，告诉系统立即加载并启动这个配置：

launchctl load ~/Library/LaunchAgents/com.wlk.server.plist

第五步：日常管理与隐私提示

1. 如何确认服务已启动？

您无需打开任何窗口。只需在终端输入以下命令查看端口 9000 是否被占用：

如果看到 wlk 或 python 相关进程，说明服务已在后台静默运行。

2. 如何临时停止或重启？

停止服务（不再开机自启）：
launchctl unload ~/Library/LaunchAgents/com.wlk.server.plist
重新启动（修改参数后）：
先执行 unload 再执行 load。

3. 隐私保护建议

日志文件：本配置将运行日志存储在 /tmp/wlk.log 中。/tmp 文件夹在 macOS 重启时会自动清空，有效保护了您的短期运行记录不被长期留存。
局域网安全：当前配置使用 --host 0.0.0.0，这意味着局域网内的其他设备也可以访问您的 Whisper 服务。如果您仅希望本机使用，请将配置文件中的 0.0.0.0 改为 127.0.0.1。
路径脱敏：在向他人展示您的配置文件时，请务必手动删除或替换 /Users/ 后的真实用户名。

常见问题排查

如果发现服务没有正常工作，请在终端输入：
cat /tmp/wlk.err
这将显示程序启动失败的具体原因（通常是路径拼写错误或权限问题）。

🐧 方案二：Linux / Windows (NVIDIA GPU) 方案

对于拥有 NVIDIA 显卡的服务器或 PC，Docker 是最简单且推荐的部署方式，或者使用 faster-whisper 后端进行原生安装。

方式 A：Docker 部署 (推荐)

# 启动支持 GPU 的容器
docker run --gpus all -p 8000:8000 --name wlk wlk

# 自定义启动参数（例如：法语识别的大模型）
docker run --gpus all -p 8000:8000 --name wlk wlk --model large-v3 --language fr

也可以使用docker compose来部署：

services:
  whisperlivekit:
    build:
      context: .
      dockerfile_inline: >
        FROM python:3.11-slim

        RUN apt-get update && apt-get install -y --no-install-recommends \
            ffmpeg \
            git \
            build-essential \
            && rm -rf /var/lib/apt/lists/*
        RUN pip install --no-cache-dir torch --index-url https://download.pytorch.org/whl/cpu

        RUN pip install --no-cache-dir whisperlivekit

        WORKDIR /app

        EXPOSE 8000

        ENTRYPOINT ["wlk"]

        CMD ["--host", "0.0.0.0", "--port", "8000", "--model", "small", "--language", "auto"]
    container_name: whisperlivekit
    ports:
      - 9000:8000
    volumes:
      - whisper-cache:/root/.cache
    environment:
      - HF_HOME=/root/.cache/huggingface
    restart: unless-stopped
    networks:
      - app_network

volumes:
  whisper-cache: null

方式 B：原生安装 (pip)

# 安装核心库
pip install whisperlivekit

# 安装 NVIDIA 加速后端
pip install faster-whisper

# 启动服务
wlk --model base --language en --backend faster-whisper

💡 典型使用场景与命令

WLK 的命令行工具非常灵活，支持多种配置组合。

场景一：跨语言实时会议（法语转丹麦语）

wlk --model large-v3 --language fr --target-language da

场景二：多人会议记录（开启说话人识别） 需预先安装 NVIDIA NeMo 或 Diart 依赖

wlk --host 0.0.0.0 --port 80 --model medium --diarization --language fr

场景三：浏览器音频捕获 WLK 支持配合 Chrome 扩展使用，可以直接捕获并转录浏览器标签页内的音频（如在线会议、YouTube 直播）。

启动服务后，浏览器访问 http://localhost:8000 (或你设置的端口) 即可体验。

👨‍💻 开发者指南：Python API 集成

如果你想将 WLK 集成到自己的 Python 应用中（例如使用 FastAPI 构建后端），代码非常简洁：

# 初始化引擎（通常在应用启动时加载）
# 注意：在 Mac 上这里会自动适配，或可显式指定 backend="mlx-whisper"
transcription_engine = TranscriptionEngine(model="medium", diarization=True, lan="en")

@app.websocket("/asr")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()

    # 为每个连接创建一个处理器
    audioprocessor = AudioProcessor(transcriptionengine=transcription_engine)

    # 启动结果生成任务
    resultsgenerator = await audioprocessor.create_tasks()

    # 异步处理结果发送回客户端
    asyncio.createtask(handlewebsocketresults(websocket, resultsgenerator))

    try:
        while True:
            # 接收音频流并处理
            message = await websocket.receivebytes()
            await audioprocessor.process_audio(message)
    except Exception as e:
        print(f"Connection closed: {e}")

⚙️ 关键参数配置表

参数	说明	推荐值
`--model`	模型大小	`small` (速度快), `large-v3` (精度高)
`--backend`	推理后端	Mac 选 `mlx-whisper`，N卡选 `faster-whisper`
`--language`	源语言代码	`zh`, `en`, `fr`, `ja` 等
`--target-language`	翻译目标语言	设置后将输出翻译文本而非原文
`--diarization`	说话人识别开关	默认关闭，开启需额外资源
`--backend-policy`	流式策略	推荐默认 `simulstreaming` (AlignAtt)

🏭 生产环境建议

Web Server: 不要直接在生产环境裸跑 wlk 命令，建议使用 gunicorn 配合 uvicorn worker 运行。
反向代理: 推荐使用 Nginx 进行反向代理，并正确配置 WebSocket 的 Upgrade headers。
HTTPS: 为了安全以及浏览器权限（现代浏览器要求麦克风访问必须是 HTTPS），请务必配置 SSL 证书，客户端使用 wss:// 协议连接。

> 🔗 更多详细信息、故障排除及完整参数列表，请查阅 GitHub 仓库及官方文档。

🕵️ 前端适配插件

以下是BraveDAO开发的WordPress前端插件，供学习测试参考：

whisper-live-transcriber.zip

插件使用方法：

第一，上传至WordPress站点（建议使用localhost）；

第二，在后台（Whisper Live-设置）的Whisper Live Transcriber 设置中填写WebSocket URL；

第三，在任意页面或文章中添加短代码即可调用，短代码为[whisper_live]