Metadata-Version: 2.3
Name: fasr-asr-paraformer
Version: 0.5.1
Summary: paraformer asr model for fasr
Author: osc
Author-email: osc <790990241@qq.com>
Requires-Dist: fasr
Requires-Dist: funasr
Requires-Dist: funasr-onnx
Requires-Dist: torch
Requires-Dist: torchaudio
Requires-Python: >=3.10, <3.13
Description-Content-Type: text/markdown

# fasr-asr-paraformer

基于 [Paraformer](https://github.com/modelscope/FunASR) 的语音识别模型插件，为 fasr 提供离线 ASR 能力，支持带时间戳输出和热词偏置。

## 安装

```bash
pip install fasr-asr-paraformer
```

## 注册模型

| 注册名 | 类 | 默认 checkpoint | 说明 |
|---|---|---|---|
| `paraformer` | `ParaformerForASR` | `iic/speech_paraformer-large-vad-punc_asr_nat-zh-cn-16k-common-vocab8404-pytorch` | 离线 Paraformer，输出带时间戳的 token |
| `seaco_paraformer` | `SeacoParaformerForASR` | `iic/speech_seaco_paraformer_large_asr_nat-zh-cn-16k-common-vocab8404-pytorch` | 支持热词偏置的 Paraformer |

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

## 使用方式

### 在流水线中使用

```python
from fasr import AudioPipeline

# 标准 Paraformer
pipeline = (
    AudioPipeline()
    .add_pipe("detector", model="fsmn")
    .add_pipe("recognizer", model="paraformer")
    .add_pipe("sentencizer", model="ct_transformer")
)

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

### 热词识别

```python
pipeline = (
    AudioPipeline()
    .add_pipe("detector", model="fsmn")
    .add_pipe("recognizer", model="seaco_paraformer")
    .add_pipe("sentencizer", model="ct_transformer")
)

audio = pipeline("meeting.wav", hotwords=["Paraformer", "语音识别"])
```

### 单独使用模型

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

```python
from fasr.config import registry

model = registry.asr_models.get("paraformer")()
tokens = model.transcribe([waveform_array], sample_rate=16000)
for tok in tokens[0]:
    print(f"{tok.text} [{tok.start_ms}-{tok.end_ms}ms]")

# 使用自定义权重目录
model.load_checkpoint("/path/to/custom/paraformer")
```

## 运行期 / 会话参数

### 公共字段（离线 `paraformer` / `seaco_paraformer`）

| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `checkpoint` | `str \| None` | 子类各自默认 | 远程 repo_id；非空时实例化会自动下载 |
| `cache_dir` | `str \| Path \| None` | `None` | 缓存目录，`None` 使用 `fasr.utils.get_cache_dir()` |
| `endpoint` | `Literal["modelscope", "huggingface", "hf-mirror"]` | `"modelscope"` | 下载端点 |
| `disable_update` | `bool` | `True` | 禁用 FunASR 自动更新检查 |
| `disable_log` | `bool` | `True` | 禁用 FunASR 日志输出 |
| `disable_pbar` | `bool` | `True` | 禁用进度条 |
| `batch_size` | `int` | `10000` | 推理批次大小 |

### `transcribe` 额外参数

| 参数 | 说明 |
|---|---|
| `sample_rate` | 输入音频采样率，默认 `16000` |
| `hotwords`（仅 seaco） | 热词列表，如 `["Paraformer", "语音识别"]` |

## 依赖

- `fasr`
- `funasr`、`funasr-onnx`
- `torch`、`torchaudio`
- Python 3.10–3.12
