Speech Recognition Server

基于FunASR的语音识别服务端程序，使用FastAPI框架构建。

项目介绍

这是一个使用Python和FastAPI构建的语音识别服务端程序，集成了FunASR模型，提供HTTP/HTTPS接口，支持音频文件转录和实时流式识别。

经过全面优化，本项目具有以下增强特性：

• 语音端点检测与标点恢复：支持VAD（语音端点检测）和Punctuation Restoration（标点恢复），输出更符合标准的文本
• 自动设备检测：自动检测并优先使用CUDA（GPU），如果CUDA不可用则使用CPU
• 实时进度反馈：客户端可以实时跟踪音频转录进度
• 模型本地化管理：模型自动下载到项目目录，避免重复下载
• Linux平台优化：专为Linux系统优化，仅在Linux环境下测试通过
• 代码规范性：符合行业标准的代码风格
• 详细注释：所有代码都有详细注释，便于学习Python

功能特性

• 音频文件转录：支持上传音频文件进行语音识别
• 语音端点检测（VAD）：自动检测语音段落，忽略静音部分
• 标点恢复：为转录文本添加适当的标点符号
• 实时进度跟踪：可实时查询转录进度
• 实时流式识别：支持实时音频流识别
• 配置管理：支持通过配置文件管理服务参数
• 跨域支持：默认支持跨域请求
• Linux平台支持：专为Linux系统设计，仅在Linux环境下测试通过
• 自动设备选择：优先使用GPU（CUDA）进行计算加速

关于FunASR

本项目基于FunASR开发，FunASR是一个开源的端到端语音识别工具包。本项目仅使用FunASR的开源框架，使用的预训练模型可能遵循单独的模型许可协议。在使用预训练模型时，请确保遵守相应的模型许可证。

FunASR框架本身使用MIT许可证，与本项目的许可证兼容。

技术栈

• Python 3.11+
• FastAPI
• Uvicorn
• FunASR
• PyTorch (用于CUDA支持)
• Pydantic
• asyncio (异步处理)
• pathlib (跨平台路径处理)
• dataclasses (数据类)
• enums (枚举类型)

安装与运行

1. 环境准备

# 确保Python 3.11+已安装
python --version

# 克隆项目
git clone <repository-url>
cd sr-server

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# 或
.venv\Scripts\activate  # Windows

2. 安装依赖

pip install -r requirements.txt

3. 运行服务

# 开发模式（带自动重载）
python run_server.py --reload

# 生产模式
python run_server.py --host 0.0.0.0 --port 8000

# 指定其他参数
python run_server.py --host 0.0.0.0 --port 8000 --device cpu

API接口

健康检查

GET /
GET /health

音频转录

POST /v1/transcribe-file          # 上传音频文件并转录
GET  /v1/download/{filename}      # 下载转录结果
GET  /v1/transcribe-progress/{task_id}  # 查询转录进度

流式识别

WebSocket /v1/transcribe-stream  # 实时音频流识别

API文档

GET /docs  # Swagger UI
GET /redoc # ReDoc

配置

服务支持通过环境变量进行配置：

• SR_SERVER_HOST: 服务监听地址 (默认: 0.0.0.0)
• SR_SERVER_PORT: 服务监听端口 (默认: 8000)
• FUNASR_MODEL_PATH: FunASR模型路径 (默认: iic/SenseVoiceSmall)
• FUNASR_DEVICE: 计算设备 (默认: 自动检测CUDA可用性)
• MAX_FILE_SIZE: 最大文件上传大小 (默认: 209715200 字节 = 200MB)
• DEBUG: 调试模式 (默认: False)
• TEMP_DIR: 临时文件目录 (默认: 自动根据操作系统选择)
• OUTPUT_DIR: 输出文件目录 (默认: 自动根据操作系统选择)

项目结构

sr_server/
├── main.py              # 主应用入口
├── __init__.py          # 包初始化
├── api/                 # API路由定义
│   └── v1/
│       ├── __init__.py
│       └── routes.py
├── config/              # 配置管理
│   ├── config_manager.py
│   └── settings.py
├── models/              # 模型目录 (自动创建)
├── services/            # 业务逻辑服务
│   ├── funasr_service.py
│   ├── model_manager.py    # 模型管理服务
│   └── progress_service.py # 进度管理服务
└── utils/               # 工具函数
    ├── audio.py
    └── streaming.py

开发计划

• 阶段一：基本框架搭建
• 阶段二：基本框架功能测试
• 阶段三：文件到文件API接口功能
• 阶段四：文件到文件API接口测试
• 阶段五：实时流式转换API接口
• 阶段六：实时流式转换API接口测试
• 阶段七：配置文件管理功能
• 阶段八：配置文件功能测试
• 阶段九：添加代码，提供处理进度反馈，帮助客户端知道当前文件的处理进度
• 阶段十：对阶段九优化后的代码进行测试
• 阶段十一：将模型下载位置更改到项目地址，使部署时不必多次下载模型
• 阶段十二：对经过阶段十一优化的代码进行测试
• 阶段十三：对整个项目代码进行Linux平台优化
• 阶段十四：对经过阶段十三优化的项目进行Linux环境功能测试，确保代码无误
• 阶段十五：对全部代码进行代码风格检查，使其符合行业规范
• 阶段十六：对所有代码进行详细注释，帮助学习python
• 阶段十七：再次对项目功能进行全面测试，保证优化后的代码没有问题
• 阶段十八：对LEARNME.md README.md文档进行重写
• 阶段十九：添加语音端点检测与标点恢复功能
• 阶段二十：对语音端点检测与标点恢复功能进行测试
• 阶段二十一：实现CUDA设备自动检测与优先使用功能
• 阶段二十二：对CUDA自动检测功能进行测试
• 阶段二十三：进行Linux平台兼容性最终验证
• 阶段二十四：对全部代码进行最终测试
• 阶段二十五：对全部代码进行风格检查
• 阶段二十六：完善代码注释
• 阶段二十七：进行全面功能测试
• 阶段二十八：更新所有文档

使用示例

Python客户端示例

import requests

# 上传音频文件
with open('audio.wav', 'rb') as f:
    response = requests.post('http://localhost:8000/v1/transcribe-file', files={'audio_file': f})

result = response.json()
task_id = result['task_id']

# 查询进度
progress = requests.get(f'http://localhost:8000/v1/transcribe-progress/{task_id}')
print(progress.json())

许可证

本项目采用MIT许可证，详情请参见 LICENSE 文件。

重要说明：本项目使用FunASR作为语音识别框架，FunASR框架本身使用MIT许可证。但项目中使用的预训练模型可能有单独的许可协议，请在使用预训练模型时确保遵守相应模型的许可证要求。

学习资源

详细的学习指南请参考 LEARNME.md 文件，包含：

• 项目架构分析
• 代码注释说明
• Python编程概念
• 最佳实践指导