fasr-asr-mega 0.5.8

Mega-ASR wrapper for fasr

fasr-asr-mega

English documentation: README_EN.md

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

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

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

安装

pip install fasr-asr-mega

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

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

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

注册模型

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

流水线使用

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 配置

[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 后端示例：

[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

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

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

单独使用

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。