Metadata-Version: 2.4
Name: fasr-asr-firered
Version: 0.5.8
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: sentencepiece>=0.2.0
Requires-Dist: torch>=2.0.0
Requires-Dist: torchaudio
Requires-Dist: transformers>=4.36

# fasr-asr-firered

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

FireRedASR2 语音识别插件，提供 AED 解码和 LLM 解码。AED 可返回 token 时间戳，LLM 更偏向整段文本识别，不返回时间戳。

## 安装

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

## 注册模型

| 注册名 | 类 | 适用场景 |
|---|---|---|
| `firered` | `FireRedAEDForASR` | AED 模式默认别名 |
| `firered_aed` | `FireRedAEDForASR` | 带时间戳 AED 识别 |
| `firered_llm` | `FireRedLLMForASR` | LLM 解码，无时间戳 |

## 流水线使用

```python
from fasr import AudioPipeline

pipeline = (
    AudioPipeline()
    .add_pipe("detector", model="fsmn")
    .add_pipe(
        "recognizer",
        model="firered_aed",
        device="cuda",
        beam_size=3,
        return_timestamp=True,
    )
    .add_pipe("sentencizer", model="ct_transformer")
)
```

| 目标 | 写法 | 效果 |
|---|---|---|
| 需要 token 时间戳 | `model="firered_aed", return_timestamp=True` | 填充 `span.tokens` |
| 只要整段文本 | `model="firered_llm"` | 填充 `span.raw_text`，无时间戳 |
| 降低 AED 显存 | `use_half=True` | GPU 上 FP16 推理 |
| CPU 推理 | `device="cpu"` | 不依赖 CUDA，但更慢 |
| 更宽搜索 | `beam_size=5` | 可能更准，但更慢 |

## Confection 配置

```toml
[asr_model]
@asr_models = "firered_aed"
device = "cuda"
beam_size = 3
return_timestamp = true
use_half = true
```

放在流水线里：

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

[pipeline.pipes]

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

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

[pipeline.pipes.recognizer.component.model]
@asr_models = "firered_aed"
device = "cuda"
beam_size = 3
return_timestamp = true
```

## 参数

### 公共参数

| 参数 | 类型 / 范围 | 默认值 | 调高 / 开启时 | 调低 / 关闭时 | 什么时候改 |
|---|---|---|---|---|---|
| `device` | `str` 或 `None` | `None` | `"cuda"` 使用 GPU | `"cpu"` 使用 CPU | 部署设备变化 |
| `beam_size` | `int >= 1` | `3` | 搜索更宽，更慢更耗内存 | 更快，可能精度下降 | 精度/速度取舍 |
| `decode_max_len` | `int >= 0` | `0` | 允许更长输出 | 更短上限；`0` 交给后端 | 输出被截断或过长 |

### AED 参数

| 参数 | 类型 / 范围 | 默认值 | 调高 / 开启时 | 调低 / 关闭时 | 什么时候改 |
|---|---|---|---|---|---|
| `use_half` | `bool` | `True` | 显存更低，GPU 更快 | FP32 更稳定 | 显存或数值稳定性问题 |
| `return_timestamp` | `bool` | `True` | 返回 token 时间戳 | 只返回文本 | 是否需要时间戳 |
| `nbest` | `int >= 1` | `1` | 返回更多候选 | 只返回最佳结果 | 需要候选结果 |
| `elm_weight` | `float` | `0.0` | 外部语言模型影响更强 | `0.0` 关闭外部 LM | 提供 `elm_dir` 时 |

### LLM 参数

| 参数 | 类型 / 范围 | 默认值 | 调高时 | 调低时 | 什么时候改 |
|---|---|---|---|---|---|
| `decode_min_len` | `int >= 0` | `0` | 强制更长最小输出 | 允许更短输出 | 输出过早结束 |
| `repetition_penalty` | `float` | `1.2` | 更强重复抑制 | 更允许重复 | 出现重复短语 |
| `temperature` | `float >= 0` | `1.0` | 更发散 | 更确定 | 需要稳定或多样性 |

## 输出

- AED 写入 `span.raw_text`。
- `return_timestamp=True` 时 AED 也填充 `span.tokens`。
- LLM 只写入 `span.raw_text`。

## 依赖

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