# rain-ai

**Repository Path**: windsound/rain-ai

## Basic Information

- **Project Name**: rain-ai
- **Description**: Rain关于AI应用的Python的实现
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-19
- **Last Updated**: 2026-01-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## Rain AI Python（Vosk 语音识别服务）

### 简介

**Rain AI Python** 是一个基于 **Flask** + **Vosk** 的本地语音转文字（STT）服务 ，提供：

- **音频文件识别接口**：上传 `wav/mp3/m4a` 等文件，返回识别文本  
- **快速识别接口**：使用默认采样率与语言快速识别  
- **麦克风实时识别能力**：通过 `VoskSttService` 支持同步/异步麦克风识别与任意音频流识别  

项目主要用于本地化中文语音识别实验和集成验证，便于在不依赖云服务的情况下完成语音转文本能力接入。

---

### 目录结构

- **`src/app.py`**: Flask 应用入口，注册 Vosk 相关接口蓝图  
- **`src/api/vosk_api.py`**: 对外暴露的 HTTP 接口（蓝图 `vosk`）  
  - `POST /vosk/recognize/file`：上传音频文件并识别  
  - `POST /vosk/api/recognize/quick`：快速识别（使用默认参数）  
- **`src/base/constants.py`**: 配置常量（如 `VOSK_MODEL_PATH` 模型路径）  
- **`src/service/audio/listen/stt_service.py`**: 抽象的语音识别服务接口 `SttService`  
- **`src/service/audio/listen/impl/vosk_stt_service.py`**: 基于 Vosk 的实现 `VoskSttService`（文件/流/麦克风识别）  
- **`test/vosk_test.py`**: 使用 `unittest` 对 `VoskSttService` 进行单元测试  

---

### 主要技术栈

- **Web 框架**: Flask  
- **语音识别引擎**: Vosk (`vosk` Python 包 + 本地模型)  
- **音频处理**: `wave`、`pyaudio`  
- **并发**: `concurrent.futures.ThreadPoolExecutor`（实现异步识别）  
- **测试**: Python `unittest`  

---

### 环境准备

- Python 3.8+（建议）  
- 已下载的 Vosk 中文模型，例如：  
  - `vosk-model-cn-kaldi-multicn-0.15`（与你当前在 `VOSK_MODEL_PATH` 中配置的一致）  
- 系统已安装音频设备驱动（如需使用麦克风识别）  

**依赖示例（请根据你本地实际情况调整）：**

```bash
pip install flask vosk pyaudio
```

> 注：在 Windows 上安装 `pyaudio` 可能需要预编译的 whl 包，可从社区镜像下载。

---

### 配置 Vosk 模型路径

在 `src/base/constants.py` 中指定本地 Vosk 模型目录：

```python
VOSK_MODEL_PATH = r"G:\AIModule\vosk-model-cn-kaldi-multicn-0.15"
```

请根据你自己的模型存放路径修改为正确的绝对路径或相对路径。

---

### 启动服务

在项目根目录下运行：

```bash
python -m src.app
```

或：

```bash
python src/app.py
```

默认会在 `0.0.0.0:5000` 启动 Flask 服务（调试模式）。

---

### 接口说明

#### 1. 上传音频文件并识别

- **URL**: `POST /vosk/recognize/file`  
- **参数**（`multipart/form-data`）:
  - **file**: 必填，音频文件
  - **sample_rate**: 可选，采样率（如 `16000`），不填或 ≤0 表示自动检测  
  - **language**: 可选，语言标识，默认 `zh-CN`  

**示例（curl）：**

```bash
curl -X POST "http://localhost:5000/vosk/recognize/file" ^
  -F "file=@test.wav" ^
  -F "sample_rate=16000" ^
  -F "language=zh-CN"
```

返回示例：

```json
{
  "result": "识别出的文本"
}
```

出错时：

```json
{
  "error": "错误信息"
}
```

#### 2. 快速识别（默认参数）

- **URL**: `POST /vosk/api/recognize/quick`  
- **参数**（`multipart/form-data`）:
  - **file**: 必填，音频文件  

内部会调用 `stt_service.recognize_quick(audio_file)`，使用默认采样率 `16000` 和默认语言。

示例（curl 与上类似，只是 URL 路径不同）。

---

### 服务内部核心类说明

- **`SttService`（`src/service/audio/listen/stt_service.py`）**  
  - 抽象层，定义：  
    - `recognize` / `recognize_async`  
    - `recognize_quick`（默认实现）  
    - `start_microphone_recognition` / `start_microphone_recognition_async`  
    - `stop_microphone_recognition` / `is_microphone_recognizing`  
    - `recognize_stream`（任意音频流识别）  
  - 通过 `RecognitionException` 封装识别错误  

- **`VoskSttService`（`src/service/audio/listen/impl/vosk_stt_service.py`）**  
  - 使用 `vosk.Model` 和 `KaldiRecognizer` 完成具体识别逻辑  
  - 支持：  
    - 同步文件识别 `recognize`  
    - 线程池异步识别 `recognize_async`  
    - 麦克风实时识别（同步/异步）  
    - 任意音频流识别（`recognize_stream`）  

---

### 测试

`test/vosk_test.py` 提供了对 `VoskSttService` 的单元测试示例，包括：

- 文件识别成功/失败用例  
- 快速识别、异步识别、取消异步识别  
- 麦克风识别同步/异步流程  
- 任意音频流识别  

运行测试：

```bash
python -m unittest test/vosk_test.py -v
```

> 注意：测试文件中使用了本地模型路径和示例音频路径（如 `G:\AIModule\vosk-model-cn-0.22`、`F:\tool\ffmpeg\bin\vosk_test.wav`），请按需修改为你本机存在的实际路径，否则测试会被跳过或失败。

---

### 备注

- 当前项目主要用于本地开发/实验用途，如需对外提供正式服务，请增加：  
  - 配置管理（环境变量/配置文件）  
  - 日志、鉴权、限流等生产级能力  
- 如果你希望扩展其他识别引擎，只需继承 `SttService` 并在 API 层替换具体实现即可。