# FunASR Dual-Mode API

这是一个基于 FastAPI 构建的语音识别（ASR）服务，集成了 FunASR 的两种推理模式，旨在提供灵活的语音转写能力。

## 功能特性

服务提供了两个主要的推理接口：

1.  **AutoModel 模式 (`/inference/funasr`)**:
    *   使用 `funasr.AutoModel` 高级接口。
    *   集成 VAD（语音活动检测）。
    *   支持热词（Hotwords）增强。
    *   支持 ITN（逆文本标准化）。
    *   支持多语言配置。

2.  **Direct Model 模式 (`/inference/direct`)**:
    *   直接调用底层 `FunASRNano` 模型。
    *   支持普通全量推理。
    *   支持模拟流式/分片推理（Chunk Mode），用于测试模型的增量解码能力。

## 环境准备

### 依赖安装

本项目使用 `uv` 进行依赖管理。请确保已安装 `uv`，然后在项目根目录下运行：

```bash
uv sync
```

### 模型配置

默认模型路径配置为 `/models/Fun-ASR-Nano-2512`。如果你的模型在其他位置，请设置环境变量 `MODEL_DIR`：

```bash
export MODEL_DIR="/你的/模型/绝对路径"
```

## 启动服务

可以直接运行 uv 脚本启动（默认端口 5000）：

```bash
uv run api.py
```

服务启动时会自动检测计算设备（CUDA > MPS > CPU）。

### Docker 启动

若使用 Docker 部署，可参考以下命令。如需自定义模型路径，可通过 `-e MODEL_DIR` 指定：

```bash
docker run -d --restart always -p 5000:5000 --gpus "device=1" \
  -e MODEL_DIR="/models/Fun-ASR-Nano-2512" \
  --mount type=bind,source=/your/path/model/Fun-ASR-Nano-2512,target=/models/Fun-ASR-Nano-2512 \
  harbor.bwgdi.com/library/fun-asr:0.0.1
```

## 接口文档

### 1. FunASR 标准推理接口

*   **URL**: `/inference/funasr`
*   **Method**: `POST`
*   **Content-Type**: `multipart/form-data`

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
| :--- | :--- | :--- | :--- | :--- |
| `file` | File | 是 | - | 音频文件 |
| `language` | String | 否 | "中文" | 目标语言 |
| `itn` | String | 否 | "true" | 是否开启逆文本标准化 (true/false) |
| `hotwords` | String | 否 | "" | 热词列表，用于提升特定词汇识别率 |

**示例**:
```bash
curl -X POST "http://127.0.0.1:5000/inference/funasr" \
  -F "file=@/path/to/audio.wav" \
  -F "hotwords=开放时间"
```

### 2. Direct 底层推理接口

*   **URL**: `/inference/direct`
*   **Method**: `POST`
*   **Content-Type**: `multipart/form-data`

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
| :--- | :--- | :--- | :--- | :--- |
| `file` | File | 是 | - | 音频文件 |
| `chunk_mode` | Boolean | 否 | False | 是否开启分片模拟模式 (true/false) |

**示例**:
```bash
# 开启分片模拟模式
curl -X POST "http://127.0.0.1:5000/inference/direct" \
  -F "file=@/path/to/audio.wav" \
  -F "chunk_mode=true"
```
**返回**:
```json
{
    "status": "success",
    "mode": "direct",
    "text": {
        "key": "rand_key_WgNZq6ITZM5jt",
        "text": "你好。",
        "text_tn": "你好",
        "label": "null",
        "ctc_text": "你好",
        "ctc_timestamps": [
            {
                "token": "你",
                "start_time": 1.8,
                "end_time": 1.86,
                "score": 0.908
            },
            {
                "token": "好",
                "start_time": 2.16,
                "end_time": 2.22,
                "score": 0.988
            }
        ],
        "timestamps": [
            {
                "token": "你",
                "start_time": 1.8,
                "end_time": 1.86,
                "score": 0.908
            },
            {
                "token": "好",
                "start_time": 2.16,
                "end_time": 2.22,
                "score": 0.988
            },
            {
                "token": "。",
                "start_time": 2.88,
                "end_time": 2.94,
                "score": 0.0
            }
        ]
    }
}
```