VoiceStreamAI

VoiceStreamAI 是一个基于 Python 3 的服务器与 JavaScript 客户端解决方案，通过 WebSocket 实现近实时的音频流传输和转录。该系统采用 Hugging Face 的语音活动检测（VAD）以及 OpenAI 的 Whisper 模型（默认使用 faster-whisper）来实现精准的语音识别与处理。

功能特性

• 通过 WebSocket 进行实时音频流传输。
• 模块化设计，便于集成不同的 VAD 和 ASR 技术。
• 使用工厂模式和策略模式实现灵活的组件管理。
• 提供单元测试框架，确保开发的健壮性。
• 可自定义的音频分块处理策略。
• 支持多语言转录。
• 支持安全套接字，并可选择性地指定证书和密钥文件。

演示视频

https://github.com/alesaccoia/VoiceStreamAI/assets/1385023/9b5f2602-fe0b-4c9d-af9e-4662e42e23df

客户端演示

使用 Docker 运行

本指南不会详细说明如何在 Docker 中使用 CUDA，请参阅例如 这里。

不过，以下是适用于 Linux 的命令：

distribution=$(. /etc/os-release;echo $ID$VERSION_ID) \
&& curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
&& curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo nvidia-ctk runtime configure --runtime=docker

sudo systemctl restart docker

您可以使用以下命令构建容器镜像：

sudo docker build -t voicestreamai .

获取 VAD 令牌后（见后续章节），运行：

sudo docker volume create huggingface_models

sudo docker run --gpus all -p 8765:8765 -v huggingface_models:/root/.cache/huggingface  -e PYANNOTE_AUTH_TOKEN='VAD_TOKEN_HERE' voicestreamai

使用卷可以避免每次重新运行容器时都重新下载 Hugging Face 模型。如果不需此功能，只需执行：

sudo docker run --gpus all -p 8765:8765 -e PYANNOTE_AUTH_TOKEN='VAD_TOKEN_HERE' voicestreamai

常规手动安装

要搭建 VoiceStreamAI 服务器，您需要 Python 3.8 或更高版本，以及以下软件包：

1. transformers
2. pyannote.core
3. pyannote.audio
4. websockets
5. asyncio
6. sentence-transformers
7. faster-whisper

使用 pip 安装这些依赖：

pip install -r requirements.txt

客户端方面，您需要支持 JavaScript 的现代 Web 浏览器。

配置与使用

服务器配置

VoiceStreamAI 服务器可通过命令行参数进行自定义，允许您根据需求指定组件、主机和端口设置。

• --vad-type：指定要使用的语音活动检测（VAD）管道类型（默认为 pyannote）。
• --vad-args：包含 VAD 管道附加参数的 JSON 字符串。（对于 pyannote 必须提供：'{"auth_token": "VAD_AUTH_HERE"}'）
• --asr-type：指定要使用的自动语音识别（ASR）管道类型（默认为 faster_whisper）。
• --asr-args：包含 ASR 管道附加参数的 JSON 字符串（例如，可以更改 Whisper 的 model_name）。
• --host：设置 WebSocket 服务器的主机地址（默认为 127.0.0.1）。
• --port：设置服务器监听的端口（默认为 8765）。
• --certfile：如果使用安全 WebSocket，则指定 SSL 证书文件路径（默认为 None）。
• --keyfile：如果使用安全 WebSocket，则指定 SSL 密钥文件路径（默认为 None）。

以标准配置运行服务器：

1. 在 https://huggingface.co/pyannote/segmentation 获取语音活动检测模型的密钥。
2. 使用 Python 3.x 运行服务器，并在命令行中添加 VAD 密钥：

python3 -m src.main --vad-args '{"auth_token": "vad token here"}'

您可以通过以下命令查看所有命令行选项：

python3 -m src.main --help

客户端使用

1. 在 Web 浏览器中打开 client/index.html 文件。
2. 输入 WebSocket 地址（默认为 ws://localhost:8765）。
3. 配置音频分块长度和偏移量，详见下文。
4. 选择转录的语言。
5. 点击“连接”以建立 WebSocket 连接。
6. 使用“开始流”和“停止流”控制音频采集。

技术概览

• Python 服务器：管理 WebSocket 连接，处理音频流，并负责语音活动检测和转录。
• WebSockets：用于服务器与客户端之间的实时通信。
• 语音活动检测（VAD）：检测音频流中的语音活动，以优化处理效率。
• 语音转文本： 使用 Faster Whisper 或 OpenAI 的 Whisper 模型（openai/whisper-large-v3）实现精准转录。默认使用 Faster Whisper，因为它速度更快。

技术概述

设置

工厂模式与策略模式

无论是 VAD 还是 ASR 组件，都可以轻松扩展以集成新技术，并使用与 Hugging Face 管道接口不同的模型。新的处理/分块策略可以在 server.py 中添加，并由特定客户端通过在配置中设置 “processing_strategy” 键来使用。

语音活动检测（VAD）

VoiceStreamAI 中的语音活动检测（VAD）使系统能够区分音频流中的语音段和非语音段。实施 VAD 的主要目的是提高语音转文本过程的效率和准确性：

• 降低计算负载：通过仅识别并处理包含语音的片段，VAD 显著减少了转录所需的计算资源。考虑到在 Tesla T4（16Gb）上，语音识别管道需要 7 秒钟才能完成一次处理，在设置分块长度时应充分考虑这一点。
• 提高转录准确性：只处理语音片段可以最大限度地减少非语音噪声被误认为语音的可能性，从而提升整体转录的准确性。
• 优化网络利用率：在流式传输场景中，仅发送语音片段而非整个音频流，可以更有效地利用带宽。

VoiceStreamAI 使用 Hugging Face 的 VAD 模型，以确保在各种音频条件下都能可靠地检测到语音。

处理策略“SilenceAtEndOfChunk”

缓冲策略旨在在近实时处理与确保语音片段完整、准确捕获之间取得平衡。以下是缓冲的管理方式：

• 基于分块的处理：音频流被分割成每个客户端可自定义长度的分块（默认为5秒）。
• 静音处理：定义了一个最小静音偏移量，允许在单个分块结束之后继续监听和捕获音频。这样可以确保分块边界处的词语不会被截断，从而保持语音的上下文和完整性。不过，对于语速非常快的部分，这会引入额外的延迟，因为转录要等到检测到停顿时才会进行。
• 动态缓冲管理：系统会为每个客户端动态管理缓冲区。当新的音频数据到达时，会被追加到该客户端的临时缓冲区中。一旦缓冲区达到分块长度，就会被处理，并清空缓冲区以准备接收新数据。

客户端特定配置的消息传递

在VoiceStreamAI中，每个客户端都可以拥有独特的配置，以根据其具体需求定制转录流程。这种个性化设置通过消息传递系统实现，即JavaScript客户端将配置信息发送到Python服务器。本节将说明这些配置是如何构建和传输的。

客户端配置可以包括多种参数，例如语言偏好、分块长度和分块偏移量。例如：

• language：指定转录的语言。如果设置为“multilanguage”以外的值，则会强制Whisper推理使用该语言。
• processing_strategy：指定该客户端的处理类型，类似于策略模式。目前这些策略并未采用面向对象编程，而是通过server.py中的if/else语句实现。
• chunk_length_seconds：定义每个待处理音频分块的长度。
• chunk_offset_seconds：决定每个分块末尾用于处理音频所需的静音时间（由处理策略1使用）。

配置的传输

1. 初始化：当客户端与服务器建立连接时，可以选择性地发送一条配置消息。该消息是一个JSON对象，包含代表客户端首选设置的键值对。

2. JavaScript客户端设置：在演示客户端中，配置信息是从用户界面元素（如下拉菜单和输入框）收集的。一旦音频开始流动，就会创建一个JSON对象并通过WebSocket发送到服务器。例如：

function sendAudioConfig() {
    const audioConfig = {
        type: "config",
        data: {
            chunk_length_seconds: 5,
            chunk_offset_seconds: 1,
            processing_strategy: 1,
            language: language,
        },
    };
    websocket.send(JSON.stringify(audioConfig));
}

测试

在实现新的ASR、VAD或缓冲策略时，可以使用以下命令进行测试：

pip install -r requirements-dev.txt
export PYANNOTE_AUTH_TOKEN=<VAD_TOKEN_HERE>
ASR_TYPE=faster_whisper python -m unittest test.server.test_server

请确保相关环境变量已正确设置，例如VAD认证令牌。此外，还有其他针对独立ASR等模块的测试用例。

改进方向

Whisper处理小音频分块的挑战

• 上下文丢失：较短的音频片段可能缺乏足够的上下文，导致Whisper误解语音内容或无法捕捉对话中的细微差别。
• 准确性波动：转录的准确性会随音频分块长度的变化而变化。相比较长的分块，较小的分块可能导致转录结果不够可靠。

对音频文件的依赖

目前，VoiceStreamAI通过将分块保存为文件，再将这些文件输入模型来进行音频处理。

开发

请先fork并克隆本仓库，然后安装依赖及相关工具。

pip install -r requirements.txt
pip install -r requirements-dev.txt
npm install -g jshint@2.13.6 eslint@8.57.0

将您的修改添加到仓库中，并手动运行代码风格检查，或者将其集成到您的IDE/编辑器中。

# 对于Python
flake8 src/ test/
black --line-length 79 src/ test/
isort src/ test/

# 对于JavaScript
jshint client/*.js
eslint client/*.js

最后，提交更改并创建一个pull request。

贡献者

• Alessandro Saccoia - alessandro.saccoia@gmail.com

本项目欢迎贡献。您可以随意fork仓库并提交pull request。

VoiceStreamAI 快速上手指南

VoiceStreamAI 是一个基于 Python 服务端和 JavaScript 客户端的解决方案，支持通过 WebSocket 进行近实时的音频流传输和语音转录。系统集成了 Huggingface 的语音活动检测（VAD）和 OpenAI 的 Whisper 模型（默认使用 faster-whisper），以实现高精度的语音识别。

环境准备

系统要求

• 操作系统: Linux (推荐，特别是使用 Docker + GPU 时), macOS, Windows
• Python: 3.8 或更高版本
• 浏览器: 现代浏览器（Chrome, Firefox, Edge 等），需支持 JavaScript 和 WebSocket
• 硬件加速 (可选): 若需高性能转录，建议配备 NVIDIA GPU 并安装 CUDA 驱动

前置依赖

1. Huggingface Token:
   • 访问 pyannote/segmentation 获取 VAD 模型的认证 Token (PYANNOTE_AUTH_TOKEN)。
2. Python 依赖包:
   • transformers, pyannote.core, pyannote.audio, websockets, asyncio, sentence-transformers, faster-whisper
3. Node.js 工具 (开发可选):
   • jshint, eslint (用于前端代码检查)

国内加速提示: 若下载 Huggingface 模型缓慢，可配置镜像环境变量：

export HF_ENDPOINT=https://hf-mirror.com

安装步骤

你可以选择 Docker 部署（推荐，环境隔离好）或 手动安装。

方案一：Docker 部署 (推荐)

此方案适合快速启动，特别是需要调用 GPU 的场景。

1. 配置 Docker 支持 NVIDIA GPU (Linux):

   distribution=$(. /etc/os-release;echo $ID$VERSION_ID) \
   && curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
   && curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
   sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
   sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
   
   sudo nvidia-ctk runtime configure --runtime=docker
   sudo systemctl restart docker
   

2. 构建镜像:

   sudo docker build -t voicestreamai .
   

3. 运行容器: 创建持久化卷以避免重复下载模型，并填入你的 VAD Token：

   sudo docker volume create huggingface_models
   
   sudo docker run --gpus all -p 8765:8765 -v huggingface_models:/root/.cache/huggingface -e PYANNOTE_AUTH_TOKEN='你的_VAD_TOKEN_在这里' voicestreamai
   

   注：若不需要持久化模型，可省略 -v 参数。

方案二：手动安装

1. 安装 Python 依赖:

   pip install -r requirements.txt
   

   (国内用户建议使用清华源：pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple)

2. 安装前端开发工具 (可选):

   npm install -g jshint@2.13.6 eslint@8.57.0
   

基本使用

1. 启动服务端

在终端中运行以下命令启动服务器。必须替换 <你的_VAD_TOKEN> 为你从 Huggingface 获取的 Token。

python3 -m src.main --vad-args '{"auth_token": "<你的_VAD_TOKEN>"}'

默认监听地址为 127.0.0.1:8765。如需修改端口或启用 SSL，可添加 --port 或 --certfile 等参数。

2. 连接客户端

1. 在浏览器中打开项目目录下的 client/index.html 文件。
2. WebSocket 地址: 保持默认 ws://localhost:8765 (若服务器远程部署，请改为对应 IP)。
3. 配置参数:
   • Chunk Length: 音频切片长度（秒），默认 5 秒。
   • Chunk Offset: 切片末尾的静音缓冲时间（秒），用于防止截断单词。
   • Language: 选择转录语言（如 "zh", "en" 或 "multilanguage"）。
4. 点击 Connect 建立连接。
5. 点击 Start Streaming 开始录音并实时查看转录结果，点击 Stop Streaming 停止。

3. 客户端配置示例 (代码层面)

如果你正在开发自定义 JS 客户端，可通过 WebSocket 发送如下 JSON 配置：

function sendAudioConfig() {
    const audioConfig = {
        type: "config",
        data: {
            chunk_length_seconds: 5,
            chunk_offset_seconds: 1,
            processing_strategy: 1,
            language: "zh", // 指定中文转录
        },
    };
    websocket.send(JSON.stringify(audioConfig));
}