# 语音识别服务项目文档

## 项目概述

### 项目简介

这是一个基于Flask框架开发的语音识别服务，支持阿里云ASR和FunASR两种引擎，提供RESTful API接口进行语音识别。系统包含用户管理、权限控制、调用量统计等功能，适用于企业级语音识别应用场景。

### 主要功能

- 语音识别：支持PCM和WAV格式音频文件识别

- 用户管理：支持多级用户体系（超级管理员、代理商、终端用户）

- 权限控制：基于角色的访问控制（RBAC）

- 调用量统计：按日、按月、按用户统计调用量

- 白名单机制：支持IP白名单访问控制

- 多引擎支持：可切换阿里云ASR和FunASR引擎

- 异步处理：支持异步API调用，提高并发能力

## 目录结构

```

/home/asr_server/

├── .venv/                  # Python虚拟环境

├── 222.wav                 # 测试音频文件

├── app/                    # 应用主目录

│   ├── __init__.py

│   ├── api/                # API接口路由

│   │   ├── async_routes.py # 异步API路由

│   │   └── routes.py       # 同步API路由

│   ├── auth/               # 身份验证相关

│   │   └── auth.py

│   ├── config/             # 配置文件

│   │   └── settings.py

│   ├── models/             # 数据模型

│   │   ├── async_data_manager.py # 异步数据管理器

│   │   ├── billing_manager.py   # 账单管理器

│   │   └── data_manager.py      # 数据管理器

│   ├── services/           # 业务服务

│   │   ├── aliyun_token_manager.py # 阿里云Token管理器

│   │   ├── asr_service.py         # 同步ASR服务

│   │   └── async_asr_service.py   # 异步ASR服务

│   ├── utils/              # 工具类

│   │   ├── audio_processor.py  # 音频处理工具

│   │   └── encryption_manager.py # 加密工具

│   └── web/                # Web界面相关

│       ├── routes.py       # Web路由

│       ├── static/         # 静态资源

│       └── templates/      # HTML模板

├── app.py                  # 应用入口文件

├── create_dirs.py          # 创建目录脚本

├── data/                   # 数据存储目录

│   ├── admin.json          # 管理员信息

│   ├── aliyun_token_cache.json # 阿里云Token缓存

│   ├── asr_engines_config.json # ASR引擎配置

│   ├── audio/              # 音频存储

│   ├── counts.json         # 调用量统计

│   ├── encryption_key.key  # 加密密钥

│   ├── hierarchy.json      # 用户层级关系

│   ├── save_audio_config.json # 音频保存配置

│   ├── service_config.json # 服务配置

│   ├── tokens.json         # Token信息

│   ├── user_calls.json     # 用户调用量

│   └── whitelist.json      # IP白名单

├── generate_secret_key.py  # 生成密钥脚本

├── requirements.txt        # 依赖包列表

├── reset_admin_password.py # 重置管理员密码脚本

├── reset_calls.py          # 重置调用量脚本

├── server.log              # 服务器日志

├── stress_test.py          # 压力测试脚本

├── test_*.py               # 各种测试脚本

└── uploads/                # 上传文件临时存储

```

## 核心功能模块

### 1. API接口

#### 同步API

- `/asr`：语音识别代理接口，支持PCM格式音频上传

  

  - 返回：JSON格式，包含识别结果、错误码和消息

#### 异步API

- `/async/asr`：异步语音识别接口

  - 参数：`token`（用户Token）、`音频文件、`engine`（可选，ASR引擎选择）

  - 返回：JSON格式，包含识别结果、错误码和消息

#### 开放平台API

### 2. ASR服务

- `ASRService`：同步ASR服务类

  - `call_aliyun_asr`：调用阿里云ASR引擎

  - `call_funasr`：调用FunASR引擎

- `AsyncASRService`：异步ASR服务类

  - `call_aliyun_asr`：异步调用阿里云ASR引擎

  - `call_funasr`：异步调用FunASR引擎

### 3. 数据管理

- `DataManager`：同步数据管理类

  - 用户管理：添加、查询、更新用户信息

  - Token管理：生成、验证Token

  - 调用量管理：统计、消耗调用量

  - 白名单管理：维护IP白名单

- `AsyncDataManager`：异步数据管理类

  - 提供与DataManager类似的功能，但支持异步操作

### 4. 身份验证

- 身份验证装饰器：

  - `login_required`：要求登录

  - `super_admin_required`：要求超级管理员权限

  - `agent_required`：要求代理商权限

  - `admin_required`：要求管理员权限

- 登录流程：

  1. 用户提交用户名和密码

  2. 系统验证身份，生成会话

  3. 根据用户角色控制访问权限

## 使用方法

### 环境搭建

1 . 克隆项目代码到本地

2. 生成加密密钥：

```bash

python generate_secret_key.py

```

### 启动服务

#### 开发环境

```bash

python app.py --env development

```

#### 生产环境

```bash

python app.py --env production

```

服务默认运行在 `http://0.0.0.0:5000`。

### 测试接口

#### 获取JWT令牌

```bash

curl -X POST http://127.0.0.1:5000/auth/v2/ip-token \

  -H "Content-Type: application/json" \

  -d '{"appKey": "your_app_key", "appSecret": "your_app_secret"}'

```

## 配置文件

### 主要配置文件

- `app/config/settings.py`：主配置文件

- `data/service_config.json`：服务配置

- `data/asr_engines_config.json`：ASR引擎配置

- `data/save_audio_config.json`：音频保存配置

### 关键配置项说明

#### settings.py

```python

# 项目根目录

BASE_DIR = Path(__file__).resolve().parent.parent.parent

# 数据目录

DATA_DIR = os.path.join(BASE_DIR, 'data')

# 服务器配置

HOST = '0.0.0.0'

PORT = 5000

DEBUG = False

# 安全配置

SECRET_KEY = 'your-secret-key-here'

# 默认ASR引擎配置

DEFAULT_ASR_ENGINES_CONFIG = {

    'aliyun': {

        'appkey': ',

        'access_key_id': '',

        'access_key_secret': ',

        'api_url': 'https://nls-gateway-cn-shanghai.aliyuncs.com/stream/v1/asr'

    },

    'funasr': {

        'api_url': 'http://127.0.0.1:5001/asr'

    }

}

```

## 常见问题

1. **如何切换ASR引擎？**

   修改 `data/service_config.json` 文件中的 `active_service` 字段，可选值为 `aliyun` 或 `funasr`。

2. **如何添加新用户？**

   超级管理员登录Web界面，在"用户管理"页面添加新用户。

3. **如何查看调用量统计？**

   登录Web界面，在"仪表盘"页面查看调用量统计图表。

4. **如何配置IP白名单？**

   超级管理员或代理商登录Web界面，在"白名单管理"页面配置IP白名单。