143 lines
4.7 KiB
Markdown
143 lines
4.7 KiB
Markdown
# 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. 安装
|
||
|
||
建议在虚拟环境中安装依赖。在项目根目录下，运行：
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 3. 运行服务
|
||
|
||
执行主入口文件来启动 FastAPI 服务：
|
||
```bash
|
||
python main.py
|
||
```
|
||
服务启动后，将监听 `http://0.0.0.0:8000`。
|
||
|
||
## 💡 如何使用
|
||
|
||
服务通过 WebSocket 提供，客户端通过 `session_id` 来创建或加入一个识别会话，并通过 `mode` 参数声明自己的角色（`sender` 或 `receiver`）。
|
||
|
||
**详细的 API 说明、URL 格式以及 Python 和 JavaScript 的客户端连接示例，请参阅：**
|
||
|
||
➡️ **[WEBSOCKET_API.md](./docs/WEBSOCKET_API.md)**
|
||
|
||
## 🔬 测试
|
||
|
||
项目提供了两种测试方式来验证其功能。
|
||
|
||
### 1. 端到端 WebSocket 测试
|
||
|
||
此测试会模拟一个 `sender` 和一个 `receiver`，完整地测试一次识别会话。
|
||
|
||
**前提**: 确保 FastAPI 服务正在运行。
|
||
```bash
|
||
python main.py
|
||
```
|
||
|
||
在项目根目录下执行：
|
||
```bash
|
||
python tests/websocket/websocket_asr.py
|
||
```
|
||
|
||
### 2. ASRRunner 单元测试
|
||
|
||
此测试针对核心的 `ASRRunner` 组件进行，验证其异步逻辑。
|
||
|
||
执行测试：
|
||
```bash
|
||
python test_main.py
|
||
```
|
||
|
||
## 🐳 使用 Docker 部署
|
||
|
||
### 1. 构建 Docker 镜像
|
||
|
||
在项目根目录下，运行：
|
||
|
||
```bash
|
||
docker build -t asr-server:x.x.x -f docker/Dockerfile .
|
||
```
|
||
|
||
### 2. 运行 Docker 容器
|
||
|
||
```bash
|
||
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`
|