98 lines
3.4 KiB
Markdown
98 lines
3.4 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 启动服务
|
||
├── WEBSOCKET_API.md # WebSocket API 详细使用文档和示例
|
||
├── 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 路由
|
||
│ └── ...
|
||
└── 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
|
||
```
|
||
|