FunASR FastAPI WebSocket Service

一个基于 FunASR 和 FastAPI 构建的高性能、实时的语音识别 WebSocket 服务。该项目核心特色是支持"一发多收"的广播模式,适用于会议实时字幕、在线教育、直播转写等需要将单一音源的识别结果分发给多个客户端的场景。

功能特性

  • 实时语音处理: 集成 FunASR 的语音活动检测VAD、语音识别ASR和声纹识别SPK模型。
  • WebSocket 流式 API: 提供低延迟、双向的实时通信接口。
  • "一发多收"架构:
    • 发送者 (Sender): 单一客户端作为音频来源,向服务器持续发送音频流。
    • 接收者 (Receiver): 多个客户端可以订阅同一个会话,实时接收广播的识别结果。
  • 异步核心: 基于 FastAPI 和 asyncio 构建,可处理大量并发连接。
  • 模块化设计: 清晰地分离了服务层 (server.py)、会话管理层 (ASRRunner) 和核心处理流水线 (ASRPipeline)。

📂 项目结构

.
├── main.py                     # 应用程序主入口,使用 uvicorn 启动服务
├── docker
│   ├── Dockerfile            # Docker 镜像构建文件
│   ├── docker-compose.yml    # Docker 容器编排文件
├── docs
│   ├── WEBSOCKET_API.md      # WebSocket API 详细使用文档和示例
│   ├── SystemArchitecture.md      # 系统架构文档
├── src
│   ├── server.py               # FastAPI 应用核心,管理生命周期和全局资源
│   ├── runner
│   │   └── ASRRunner.py        # 核心会话管理器,负责创建和协调识别会话 (SAR)
│   ├── pipeline
│   │   └── ASRpipeline.py      # 同步的、基于线程的语音处理流水线
│   ├── functor                   # VAD, ASR, SPK 等原子操作的实现
│   ├── websockets
│   │   ├── adapter.py          # WebSocket 适配器,处理数据格式转换
│   │   ├── endpoint
│   │   │   └── asr_endpoint.py # WebSocket 的业务逻辑端点
│   │   └── router.py           # WebSocket 路由
│   ├── core
│   │   └── model_loader.py           # 模型加载器
│   ├── utils
│   │   └── logger.py           # 日志记录器
│   │   └── data_format.py      # 数据格式转换
│   │   └── mock_websocket.py   # 模拟 WebSocket 客户端
├── tests
│   ├── runner
│   │   └── asr_runner_test.py  # ASRRunner 的单元测试 (异步)
│   ├── websocket
│   │   └── websocket_asr.py    # WebSocket 服务的端到端测试

🚀 快速开始

1. 环境与依赖

  • Python 3.8+
  • 项目依赖项记录在 requirements.txt 文件中。

2. 安装

建议在虚拟环境中安装依赖。在项目根目录下,运行:

pip install -r requirements.txt

3. 运行服务

执行主入口文件来启动 FastAPI 服务:

python main.py

服务启动后,将监听 http://0.0.0.0:8000

💡 如何使用

服务通过 WebSocket 提供,客户端通过 session_id 来创建或加入一个识别会话,并通过 mode 参数声明自己的角色(senderreceiver)。

详细的 API 说明、URL 格式以及 Python 和 JavaScript 的客户端连接示例,请参阅:

➡️ WEBSOCKET_API.md

🔬 测试

项目提供了两种测试方式来验证其功能。

1. 端到端 WebSocket 测试

此测试会模拟一个 sender 和一个 receiver,完整地测试一次识别会话。

前提: 确保 FastAPI 服务正在运行。

python main.py

在项目根目录下执行:

python tests/websocket/websocket_asr.py

2. ASRRunner 单元测试

此测试针对核心的 ASRRunner 组件进行,验证其异步逻辑。

执行测试:

python test_main.py

🐳 使用 Docker 部署

1. 构建 Docker 镜像

在项目根目录下,运行:

docker build -t asr-server:x.x.x -f docker/Dockerfile .

2. 运行 Docker 容器

  docker run -d -p 11096:11096 --name asr-server -v ~/.cache/modelscope:/root/.cache/modelscope asr-server:x.x.x

环境变量说明

  • SPEAKERS_URL: 说话人数据库 API 的 URL。

    示例/默认 SPEAKERS_URL="http://172.23.30.120:11200/api/v1/speakers/"

    此url为后端api提供的查询所有数据库中说话人信息的接口

  • LOG_LEVEL: 日志等级。

    示例/默认 LOG_LEVEL="INFO"

    LOG_LEVEL 为总项目日志等级,

  • LOG_LEVEL_ASR_SERVER: 日志等级。

    示例/默认 LOG_LEVEL_ASR_SERVER="INFO"

    LOG_LEVEL_ASR_SERVER 为 ASR 服务日志等级,优先级高于 LOG_LEVEL

Description
Keeeer自用STT_Server模板
Readme 7.5 MiB
Languages
Python 98.3%
Dockerfile 1.7%