
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
参数声明自己的角色(sender
或 receiver
)。
详细的 API 说明、URL 格式以及 Python 和 JavaScript 的客户端连接示例,请参阅:
🔬 测试
项目提供了两种测试方式来验证其功能。
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