Metadata-Version: 2.4
Name: fasr-asr-firered
Version: 0.5.1
Summary: FireRed ASR for fasr (bundled fireredasr2 inference)
Author-email: fasr <wangmengdi06@58.com>
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
Requires-Dist: fasr
Requires-Dist: kaldiio>=2.18.0
Requires-Dist: kaldi-native-fbank>=1.19.0
Requires-Dist: librosa>=0.10.0
Requires-Dist: numpy>=1.24
Requires-Dist: torch>=2.0.0
Requires-Dist: torchaudio
Requires-Dist: transformers>=4.36

# 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)
```

### 单独使用模型

模型实例化时会自动执行 `download_checkpoint()` + `load_checkpoint()`：

```python
from fasr.config import registry

# AED 模式（可直接构造字段来覆盖解码参数）
model = registry.asr_models.get("firered_aed")(beam_size=3, return_timestamp=True)
tokens = model.transcribe([waveform_array], sample_rate=16000)

# 使用自定义权重目录
model.load_checkpoint("/path/to/FireRedASR2-AED")

# LLM 模式
model = registry.asr_models.get("firered_llm")(temperature=1.0)
tokens = model.transcribe([waveform_array], sample_rate=16000)
```

## 运行期 / 会话参数

### 公共字段

| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `checkpoint` | `str \| None` | 子类各自默认 | 远程 repo_id；非空时实例化会自动下载 |
| `cache_dir` | `str \| Path \| None` | `None` | 缓存目录，`None` 使用 `fasr.utils.get_cache_dir()` |
| `endpoint` | `Literal["modelscope", "huggingface", "hf-mirror"]` | `"modelscope"` | 下载端点 |
| `device` | `str \| None` | `None`（自动检测 CUDA） | 设备，`"cpu"` 或 `"cuda"` |
| `beam_size` | `int` | `3` | 束搜索宽度 |
| `decode_max_len` | `int` | `0` | 最大解码长度，`0` 不限制 |

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

| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `use_half` | `bool` | `True` | 是否使用 FP16 推理 |
| `nbest` | `int` | `1` | N-best 输出数量 |
| `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`）

| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `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
