# fasr-asr-firered

基于 [FireRedASR2](https://github.com/FireRedTeam/FireRedASR) 的语音识别模型插件，为 fasr 提供 AED（CTC + Transformer 解码）和 LLM（语音编码 + 大模型解码）两种推理模式。

## 安装

```bash
pip install fasr-asr-firered
```

## 注册模型

| 注册名 | 类 | 默认 checkpoint | 说明 |
|---|---|---|---|
| `firered` / `firered_aed` | `FireRedAEDForASR` | `FireRedTeam/FireRedASR2-AED` | AED 模式，支持时间戳，CTC + Transformer 解码 |
| `firered_llm` | `FireRedLLMForASR` | `FireRedTeam/FireRedASR2-LLM` | LLM 模式，语音编码 + 大模型解码，更高精度 |

模型权重默认从 ModelScope 自动下载。

## 使用方式

### 在流水线中使用

```python
from fasr import AudioPipeline

pipeline = (
    AudioPipeline()
    .add_pipe("detector", model="fsmn")
    .add_pipe("recognizer", model="firered_aed", checkpoint_dir="/path/to/aed-ckpt")
    .add_pipe("sentencizer", model="ct_transformer")
)

audio = pipeline("example.wav")
print(audio.text)
```

### 单独使用模型

```python
from fasr.config import registry

# AED 模式
model = registry.asr_models.get("firered_aed")()
model.from_checkpoint(
    checkpoint_dir="/path/to/FireRedASR2-AED",
    beam_size=3,
    return_timestamp=True,
)
tokens = model.transcribe([waveform_array], sample_rate=16000)

# LLM 模式
model = registry.asr_models.get("firered_llm")()
model.from_checkpoint(checkpoint_dir="/path/to/FireRedASR2-LLM")
tokens = model.transcribe([waveform_array], sample_rate=16000)
```

## `from_checkpoint` 参数

### FireRedAEDForASR（`firered` / `firered_aed`）

| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `checkpoint_dir` | `str \| Path \| None` | `None`（自动下载） | 模型权重目录 |
| `device` | `str \| None` | `None`（自动检测 CUDA） | 设备，`"cpu"` 或 `"cuda"` |
| `use_half` | `bool` | `True` | 是否使用 FP16 推理 |
| `beam_size` | `int` | `3` | 束搜索宽度 |
| `nbest` | `int` | `1` | N-best 输出数量 |
| `decode_max_len` | `int` | `0` | 最大解码长度，0 为不限制 |
| `softmax_smoothing` | `float` | `1.25` | Softmax 平滑系数 |
| `aed_length_penalty` | `float` | `0.6` | AED 长度惩罚 |
| `eos_penalty` | `float` | `1.0` | EOS 惩罚系数 |
| `return_timestamp` | `bool` | `True` | 是否返回字级时间戳 |
| `elm_dir` | `str` | `""` | 外部语言模型目录 |
| `elm_weight` | `float` | `0.0` | 外部语言模型权重 |

### FireRedLLMForASR（`firered_llm`）

| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `checkpoint_dir` | `str \| Path \| None` | `None`（自动下载） | 模型权重目录 |
| `device` | `str \| None` | `None`（自动检测 CUDA） | 设备，`"cpu"` 或 `"cuda"` |
| `beam_size` | `int` | `3` | 束搜索宽度 |
| `decode_max_len` | `int` | `0` | 最大解码长度，0 为不限制 |
| `decode_min_len` | `int` | `0` | 最小解码长度 |
| `repetition_penalty` | `float` | `1.2` | 重复惩罚系数 |
| `llm_length_penalty` | `float` | `0.0` | LLM 长度惩罚 |
| `temperature` | `float` | `1.0` | 采样温度 |

## 依赖

- `fasr`
- `torch >= 2.0.0`、`torchaudio`
- `transformers >= 4.36`
- `librosa >= 0.10.0`
- `kaldiio >= 2.18.0`、`kaldi-native-fbank >= 1.19.0`
- Python 3.10–3.12
