Metadata-Version: 2.4
Name: fasr-asr-mega
Version: 0.5.8
Summary: Mega-ASR wrapper for fasr
Author-email: fasr <790990241@qq.com>
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
Requires-Dist: fasr
Requires-Dist: numpy>=1.24
Requires-Dist: soundfile>=0.12.1
Requires-Dist: torch>=2.0.0
Requires-Dist: torchaudio>=2.0.0
Requires-Dist: safetensors>=0.4.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: qwen-asr
Requires-Dist: huggingface-hub>=0.27.0
Provides-Extra: vllm
Requires-Dist: qwen-asr[vllm]; extra == "vllm"

# fasr-asr-mega

English documentation: [README_EN.md](README_EN.md)

Mega-ASR 语音识别插件，封装官方 [xzf-thu/Mega-ASR](https://github.com/xzf-thu/Mega-ASR) 离线推理接口。插件包内已经包含官方 `src/MegaASR` 的推理源码，并裁剪掉训练、评测和数据下载代码。

首次使用时，插件会自动从 HuggingFace 下载权重（`zhifeixie/Mega-ASR`），无需手动准备。

当前插件只实现 FASR batch ASR 接口，不实现流式接口。

## 安装

```bash
pip install fasr-asr-mega
```

默认安装会带上 Transformers 推理后端所需的最小运行依赖，例如 `qwen-asr`、`torch`、`torchaudio`、`safetensors`、`scipy`、`soundfile` 和 `huggingface-hub`。不会安装官方仓库中训练、评测、Web UI 相关依赖。

如果需要使用 vLLM 后端，再安装 vLLM extra：

```bash
pip install "fasr-asr-mega[vllm]"
```

## 注册模型

| 注册名 | 类 | 适用场景 |
|---|---|---|
| `mega_asr` | `MegaASRForASR` | 离线 ASR，无词级时间戳 |

## 流水线使用

```python
from fasr import AudioPipeline

pipeline = (
    AudioPipeline()
    .add_pipe("detector", model="fsmn")
    .add_pipe(
        "recognizer",
        model="mega_asr",
        backend="transformers",
        routing_enabled=True,
    )
)

audios = pipeline.run("audio.wav")
print(audios[0].text)
```

首次运行时会自动下载权重到 `~/.cache/fasr/checkpoints/zhifeixie/Mega-ASR/`。

## Confection 配置

```toml
[asr_model]
@asr_models = "mega_asr"
backend = "transformers"
routing_enabled = true
quality_threshold = 0.5
language = null
device_map = null
quality_device = null
max_inference_batch_size = 32
max_new_tokens = 256
keep_delta_on_gpu = true
```

vLLM 后端示例：

```toml
[asr_model]
@asr_models = "mega_asr"
backend = "vllm"
routing_enabled = false
vllm_apply_lora_on_load = true
gpu_memory_utilization = 0.85
max_model_len = 8192
max_num_seqs = 1
max_num_batched_tokens = 2048
```

权重目录覆盖示例（不自动下载，使用本地已准备好的权重）：

```toml
[asr_model]
@asr_models = "mega_asr"
checkpoint = "/opt/mega-asr-ckpt"
endpoint = null
```

## 单独使用

```python
from fasr.config import registry

model = registry.asr_models.get("mega_asr")(
    language="Chinese",
)

spans = model.transcribe(audio_spans)
for span in spans:
    print(span.text)
```

## 参数

| 参数 | 类型 / 范围 | 默认值 | 调高 / 开启时 | 调低 / 关闭时 | 什么时候改 |
|---|---|---|---|---|---|
| `checkpoint` | `str` | `"zhifeixie/Mega-ASR"` | 指定本地权重路径或自定义 repo | 使用默认路径或自动下载 | 权重不在默认位置或使用不同 repo 时 |
| `endpoint` | `str \| null` | `"modelscope"` | 可设为 `"huggingface"` 或 `"hf-mirror"` | 使用 ModelScope 源 | 需要从 HuggingFace 下载时 |
| `model_path` | `str \| null` | `null` | 可指定自定义 Qwen3-ASR 基座目录 | 使用 checkpoint 下的 Qwen3-ASR-1.7B | 基座模型单独放置时 |
| `lora_dir` | `str \| null` | `null` | 可指定自定义 Mega-ASR LoRA 目录 | 使用 checkpoint 下的 mega-asr-merged | LoRA 目录单独放置时 |
| `router_checkpoint` | `str \| null` | `null` | 可指定自定义路由器权重 | 使用 checkpoint 下的 audio_quality_router 默认文件 | 路由器权重单独放置时 |
| `backend` | `"transformers"` 或 `"vllm"` | `"transformers"` | `vllm` 吞吐更高，但配置更严格 | `transformers` 更贴近官方默认路由逻辑 | 需要更高吞吐或更低延迟时 |
| `routing_enabled` | `bool` | `true` | 根据音频质量动态决定是否使用 LoRA | 固定使用后端默认路径 | 不需要质量路由或使用 vLLM 物化 LoRA 时 |
| `quality_threshold` | `float 0-1` | `0.5` | 更少触发 LoRA | 更积极使用 LoRA | 背景噪声场景识别差时可调低 |
| `language` | `str \| null` | `null` | 固定语言提示 | 使用官方自动行为 | 已知语种时 |
| `device_map` | `str \| null` | `null` | 控制 Transformers 设备放置 | 使用官方默认策略 | 想固定 cpu/cuda/auto 时 |
| `quality_device` | `str \| null` | `null` | 控制路由器设备 | 使用官方自动策略 | 路由器需要指定 CPU/GPU 时 |
| `max_inference_batch_size` | `int >= 1` | `32` | 吞吐更高、显存更高 | 更省显存 | 批量推理吞吐或 OOM 调优 |
| `max_new_tokens` | `int >= 1` | `256` | 支持更长输出，耗时和显存更高 | 更省资源，但可能截断 | 长音频输出被截断时 |
| `keep_delta_on_gpu` | `bool` | `true` | LoRA 切换更快，占用更多显存 | 更省显存，切换可能更慢 | Transformers 后端显存不足时 |
| `vllm_apply_lora_on_load` | `bool` | `false` | 启动时物化 LoRA，部署简单 | 保持官方默认 | vLLM 单模型部署时 |
| `gpu_memory_utilization` | `float 0-1 \| null` | `null` | vLLM 可用显存更多 | 给其他进程留更多显存 | vLLM OOM 或显存未充分使用 |
| `max_model_len` | `int \| null` | `null` | 支持更长上下文 | 更省显存 | vLLM 上下文或 OOM 调优 |
| `max_num_seqs` | `int \| null` | `null` | vLLM 并行序列更多 | 小显存更稳 | 8GB 等小显存可设为 1 |
| `max_num_batched_tokens` | `int \| null` | `null` | 吞吐更高 | 峰值显存更低 | 小显存部署时 |
| `source_dir` | `str \| null` | `null` | 使用外部 Mega-ASR checkout 覆盖内置源码 | 默认使用插件内置源码 | 只建议调试官方源码差异时使用 |

## 输出

- 插件会填充 `span.raw_text`。
- 当前不返回词级或字级时间戳。
- 每个 `AudioSpan` 会临时写成 wav 文件再调用官方 `MegaASR.infer()`，这是为了兼容官方路由器当前以文件路径读取音频的实现。

## 第三方源码许可

插件内置的 Mega-ASR 源码来自 `xzf-thu/Mega-ASR`，许可证见 `THIRD_PARTY_LICENSES/Mega-ASR_LICENSE`，安装后的包内也保留在 `fasr_asr_mega/_vendor/MegaASR/LICENSE`。
