Metadata-Version: 2.4
Name: fasr-asr-qwen3asr
Version: 0.5.7
Summary: Qwen3 ASR model for fasr
Author-email: fasr <790990241@qq.com>
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
Requires-Dist: fasr
Requires-Dist: transformers==4.57.6
Requires-Dist: huggingface-hub<1.0,>=0.34.0
Requires-Dist: nagisa==0.2.11
Requires-Dist: soynlp==0.0.493
Requires-Dist: accelerate==1.12.0
Requires-Dist: vllm==0.14.0
Requires-Dist: librosa
Requires-Dist: soundfile

# fasr-asr-qwen3asr

英文文档地址: [README_EN.md](README_EN.md)

Qwen3-ASR 语音识别插件，使用内置的 Qwen3-ASR vLLM 后端。同一个模型实例支持离线批量识别和累计式流式识别。

## 安装

```bash
pip install fasr-asr-qwen3asr
```

## 注册模型

| 注册名 | `size` 选择的类 | 适用场景 |
|---|---|---|
| `qwen3asr` | `Qwen3ASRSmall` 或 `Qwen3ASRLarge` | GPU ASR，无词级时间戳 |

`size="small"` 使用 `Qwen/Qwen3-ASR-0.6B`，`size="large"` 使用 `Qwen/Qwen3-ASR-1.7B`。

## 流水线使用

```python
from fasr import AudioPipeline

pipeline = (
    AudioPipeline()
    .add_pipe("detector", model="fsmn")
    .add_pipe(
        "recognizer",
        model="qwen3asr",
        size="small",
        gpu_memory_utilization=0.7,
        max_new_tokens=2048,
    )
    .add_pipe("sentencizer", model="ct_transformer")
)
```

| 目标 | 写法 | 效果 |
|---|---|---|
| 降低显存 | `size="small"` | 使用 0.6B checkpoint |
| 提高能力 | `size="large"` | 使用 1.7B checkpoint，需要更多显存 |
| 给 GPU 留余量 | `gpu_memory_utilization=0.6` | vLLM 预留更少显存 |
| 长文本输出 | `max_new_tokens=4096` 或更高 | 允许生成更长文本 |
| 偏置专有名词 | `hotwords=[...]` | 通过 Qwen3-ASR 官方 context 通道提供热词 |
| 固定语言 | `language="zh"` | 使用固定语言提示 |

## Confection 配置

```toml
[asr_model]
@asr_models = "qwen3asr"
size = "small"
gpu_memory_utilization = 0.7
max_new_tokens = 2048
language = "Chinese"
hotwords = ["fasr", "Qwen3-ASR"]
```

放在流水线里：

```toml
[pipeline]
@pipelines = "AudioPipeline.v1"
pipe_order = ["recognizer"]

[pipeline.pipes]

[pipeline.pipes.recognizer]
@pipes = "thread_pipe"
batch_size = 1

[pipeline.pipes.recognizer.component]
@components = "recognizer"

[pipeline.pipes.recognizer.component.model]
@asr_models = "qwen3asr"
size = "small"
gpu_memory_utilization = 0.7
max_new_tokens = 2048
language = "Chinese"
hotwords = ["fasr", "Qwen3-ASR"]
```

## 单独使用

```python
from fasr.config import registry

model = registry.asr_models.get("qwen3asr")(
    size="small",
    gpu_memory_utilization=0.7,
)

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

流式模式返回累计文本，上层应覆盖显示最新文本，不要拼接 delta：

```python
model = registry.asr_models.get("qwen3asr")(
    size="small",
    chunk_size_ms=2000,
    language="zh",
)

for chunk in audio_chunks:
    span = model.push_chunk(chunk)
    if span is not None:
        print(span.text)
```

## 参数

| 参数 | 类型 / 范围 | 默认值 | 调高 / 开启时 | 调低 / 关闭时 | 什么时候改 |
|---|---|---|---|---|---|
| `size` | `"small"` 或 `"large"` | `"small"` | `"large"` 能力更强，显存更高 | `"small"` 更省资源 | 精度或资源预算变化 |
| `gpu_memory_utilization` | `float`，`(0, 1]` | `0.8` | vLLM 预留更多显存 | 给其它进程留更多显存 | vLLM OOM 或显存未充分使用 |
| `max_new_tokens` | `int >= 1` | `4096` | 允许更长输出 | 计算和显存更省 | 文本截断或资源紧张 |
| `max_inference_batch_size` | `int`，`-1` 或正数 | `-1` | `-1` 交给后端 | 更低峰值显存 | 批量推理 OOM |
| `max_model_len` | `int` 或 `None` | `None` | 更长 prompt+输出上下文 | 更省内存 | 长上下文或 OOM |
| `language` | `str` 或 `None` | `None` | 固定语言提示 | 自动语言行为 | 已知语言 |
| `hotwords` | `list[str]` | `[]` | 更强热词偏置 | 更少 prompt 偏置 | 专有名词漏识别 |
| `chunk_size_ms` | `int` 或 `None` | `None` | 流式解码更少，输出更晚 | 更实时，开销更高 | 流式延迟/吞吐调优 |

## 输出

- 离线模式写入 `span.raw_text`。
- 流式模式返回累计 `AudioSpan(raw_text=...)`。
- 当前插件不返回词级或字级时间戳。

## 依赖

- `fasr`
- `transformers == 4.57.6`
- `huggingface-hub >= 0.34.0, < 1.0`
- `vllm == 0.14.0`
- `accelerate == 1.12.0`
- `librosa`
- `soundfile`
- Python 3.10-3.12
