feat: api

2026-02-10 17:56:37 +08:00
parent d9ba359ddf
commit 7879751126
8 changed files with 550 additions and 2 deletions
--- a/readme_bw_zh.md
+++ b/readme_bw_zh.md
@ -0,0 +1,147 @@
+# 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
+            }
+        ]
+    }
+}
+```