Metadata-Version: 2.4
Name: fasr
Version: 0.5.8
Summary: FASR: Fast Automatic Speech Recognition Pipeline
Author-email: osc <790990241@qq.com>
Requires-Python: <3.13,>=3.10
Requires-Dist: aiohttp>=3.10.10
Requires-Dist: catalogue>=2.0.10
Requires-Dist: confection<2,>=1.3.3
Requires-Dist: docarray==0.40
Requires-Dist: editdistance>=0.8.1
Requires-Dist: huggingface-hub<1.0,>=0.27.0
Requires-Dist: joblib>=1.4.2
Requires-Dist: kaldifst>=1.7.14
Requires-Dist: loguru>=0.7.2
Requires-Dist: modelscope>=1.19.1
Requires-Dist: nest-asyncio>=1.6.0
Requires-Dist: numpy>=1.24
Requires-Dist: protobuf>=3.20.0
Requires-Dist: pydantic>=2.9.2
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: requests>=2.32.0
Requires-Dist: rich>=13.9.4
Requires-Dist: soundfile>=0.12.1
Requires-Dist: soxr>=0.5.0
Requires-Dist: typer>=0.16.0
Requires-Dist: typing-extensions>=4.10.0
Provides-Extra: aic
Requires-Dist: fasr-enhancement-aic; extra == 'aic'
Provides-Extra: deepfilternet
Requires-Dist: fasr-enhancement-deepfilternet; extra == 'deepfilternet'
Provides-Extra: dtln
Requires-Dist: fasr-enhancement-dtln; extra == 'dtln'
Provides-Extra: gtcrn
Requires-Dist: fasr-enhancement-gtcrn; extra == 'gtcrn'
Provides-Extra: hush
Requires-Dist: fasr-enhancement-hush; extra == 'hush'
Provides-Extra: litdata
Requires-Dist: litdata>=0.2.46; extra == 'litdata'
Provides-Extra: mega-asr
Requires-Dist: fasr-asr-mega; extra == 'mega-asr'
Provides-Extra: rnnoise
Requires-Dist: fasr-enhancement-rnnoise; extra == 'rnnoise'
Provides-Extra: service
Requires-Dist: fasr-service-realtime; extra == 'service'
Requires-Dist: fasr-service-transcribe; extra == 'service'
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/logo.svg" alt="fasr logo" width="180">
</p>

# fasr

`fasr` 是一个面向生产场景的 Python 语音推理框架，重点提供插件化模型生态、
高效离线流水线，以及可高并发部署的实时语音识别服务能力。

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

## 主要特征

- 插件化模型生态与自由组合：VAD、ASR、降噪、标点、语种识别等能力都以插件包提供，通过统一 registry 按需安装、按需加载、按需组合，同一套框架可以快速切换不同模型搭配。
- 异步执行组件，离线识别效率高：流水线组件以独立线程和队列协同执行，适合离线批量转写、预处理和多阶段推理，能够更高效地利用 CPU / GPU 资源完成长音频处理。
- 实时语音识别支持高并发：realtime service 基于 WebSocket 和异步处理链路构建，适合多会话并发接入，并且可以组合流式 VAD、流式 ASR 与实时降噪模型完成在线识别。
- 统一的批量与流式抽象：核心数据结构和模型接口同时覆盖 offline / streaming / service 场景，便于从本地推理平滑扩展到服务部署。

## 快速开始

先判断你的场景：

- 如果你要处理麦克风、会议、电话等实时音频流，请看下面的 `实时语音识别服务`
- 如果你要处理本地录音、远程音频文件或批量转写任务，请看下面的 `离线语音识别服务`

快速开始优先使用扁平 CLI 参数，先把服务跑起来；如果后续需要细调模型参数，
再切换到 `cfg` 模式。示例里的模型组合只是一个可直接验证链路的起点，你也可以
替换成下方“支持的模型插件”里任意支持同类能力的模型。

### 实时语音识别服务

realtime service 至少需要一个支持 streaming 的 `VAD` 模型和一个支持
streaming 的 `ASR` 模型，以及一个支持 streaming 的 `enhance` 模型。
如果觉得降噪后人声被削薄、太闷，或者有一点金属感，可以在 service 层把
`enhancement_strength` 调低一些，把部分原音混回来。

1. 安装服务和对应的流式模型插件：

```bash
pip install fasr-service-realtime fasr-vad-fsmn fasr-asr-paraformer fasr-enhancement-deepfilternet
```

2. 一行命令启动带有实时降噪的语音识别服务：

```bash
fasr-service-realtime serve \
  --vad fsmn_online \
  --asr paraformer_online \
  --enhance deepfilternet \
  --host 0.0.0.0 \
  --port 8000
```

服务启动后，你可以直接打开 `http://127.0.0.1:8000/demo` 使用内置网页 demo。
这个 demo 现在既支持上传音频文件测试 `/enhance`，也支持在 realtime 页直接用
本地音频文件走 WebSocket 实时识别链路，并调节 VAD 参数和 `enhancement_strength`。

3. 如果需要详细控制模型参数，再生成配置文件：

```bash
fasr-service-realtime init \
  --cfg realtime.cfg \
  --vad silero \
  --asr paraformer_online \
  --enhance deepfilternet
fasr-service-realtime serve --cfg realtime.cfg
```

`init` 默认会按 `silero` / `paraformer_online` / `deepfilternet` 生成配置，
并把 service 默认配置和所选模型的默认参数写入 `realtime.cfg`。如果要替换模型
或调节模型细项，请直接编辑这个配置文件。realtime service 的
`[service.enhancement_model]` 中的 `enhancement_strength` 默认是
`1.0`，表示使用纯增强输出。

### 离线语音识别服务

transcribe service 至少需要 `VAD` 和 `ASR`；`punc` 与 `enhance` 都是可选的，
可以按场景叠加到同一条离线流水线里。

1. 安装服务和对应的离线模型插件：

```bash
pip install fasr-service-transcribe fasr-vad-marblenet fasr-asr-paraformer fasr-punc-ct-transformer
```

2. 一行命令启动离线语音识别服务：

```bash
fasr-service-transcribe serve \
  --vad marblenet \
  --asr paraformer \
  --punc ct_transformer \
  --host 0.0.0.0 \
  --port 8000
```

服务启动后，会暴露 `POST /transcribe` 与 `POST /inference` 接口；你也可以直接
打开 `http://127.0.0.1:8000/demo` 使用内置网页 demo 测试转写链路。

3. 如果需要详细控制模型参数，再生成配置文件：

```bash
fasr-service-transcribe init \
  --cfg transcribe.cfg \
  --vad marblenet \
  --asr paraformer \
  --enhance deepfilternet \
  --punc ct_transformer
fasr-service-transcribe serve --cfg transcribe.cfg
```

`init` 会把 service 默认配置和所选模型的默认参数写入 `transcribe.cfg`。如果
要替换模型或调整模型参数，请直接编辑这个配置文件。`--punc` 和 `--enhance`
都不是必选项，只有在你需要标点恢复或转写前增强时才需要传。


## 支持的模型插件

`fasr` 通过模型插件发现并加载模型。当前仓库内置的模型插件如下：

| 能力 | 插件包 | 配置写法 | 模式 | 设备 | 说明 |
|---|---|---|---|---|---|
| 语音活动检测（VAD） | `fasr-vad-marblenet` | `@vad_models = "marblenet"` | Batch | CPU only | CPU 友好的 ONNX VAD |
| 语音活动检测（VAD） | `fasr-vad-fsmn` | `@vad_models = "fsmn"` | Batch | CPU / GPU | 离线 FSMN VAD |
| 语音活动检测（VAD） | `fasr-vad-fsmn` | `@vad_models = "fsmn_online"` | Streaming | CPU / GPU | 实时 FSMN VAD |
| 语音活动检测（VAD） | `fasr-vad-firered` | `@vad_models = "firered"` | Batch | CPU / GPU | FireRed 离线 VAD |
| 语音活动检测（VAD） | `fasr-vad-silero` | `@vad_models = "silero"` | Batch + streaming | CPU / GPU | 本地内置 TorchScript 权重的 Silero VAD |
| 语音增强（Enhancement） | `fasr-enhancement-rnnoise` | `@enhancement_models = "rnnoise"` | Batch + streaming | CPU only | 轻量 RNNoise 降噪 |
| 语音增强（Enhancement） | `fasr-enhancement-deepfilternet` | `@enhancement_models = "deepfilternet"` | Batch + streaming | CPU only | Rust 后端 DeepFilterNet 降噪 |
| 语音增强（Enhancement） | `fasr-enhancement-gtcrn` | `@enhancement_models = "gtcrn"` | Batch + streaming | CPU only | GTCRN 降噪 |
| 语音增强（Enhancement） | `fasr-enhancement-dtln` | `@enhancement_models = "dtln"` | Batch + streaming | CPU only | 内置双 ONNX 的 DTLN 降噪 |
| 语音识别（ASR） | `fasr-asr-paraformer` | `@asr_models = "paraformer"` | Batch | CPU / GPU | 离线 paraformer |
| 语音识别（ASR） | `fasr-asr-paraformer` | `@asr_models = "seaco_paraformer"` | Batch | CPU / GPU | paraformer热词模型 |
| 语音识别（ASR） | `fasr-asr-paraformer` | `@asr_models = "paraformer_online"` | Streaming | CPU / GPU | 实时 paraformer |
| 语音识别（ASR） | `fasr-asr-qwen3asr` | `@asr_models = "qwen3asr"` | Batch + streaming | GPU only | Qwen3-ASR 统一入口，可在插件配置中选择 `0.6B` 或 `1.7B` 尺寸 |
| 语音识别（ASR） | `fasr-asr-mega` | `@asr_models = "mega_asr"` | Batch | GPU only | Mega-ASR 官方离线推理接口适配 |
| 语音识别（ASR） | `fasr-asr-firered` | `@asr_models = "firered_aed"` / `@asr_models = "firered_llm"` | Batch | CPU / GPU | FireRed ASR 变体 |
| 语音识别（ASR） | `fasr-asr-funasr` | `@asr_models = "fun_asr_nano"` | Batch | CPU / GPU | FunASR Nano |
| 标点恢复（Punc） | `fasr-punc-ct-transformer` | `@punc_models = "ct_transformer"` | Batch | CPU / GPU | 中文标点恢复 |
| 语种识别（LID） | `fasr-lid-firered` | `@lid_models = "firered"` | Batch | CPU / GPU | FireRed 语种识别 |

## 接口文档

- 离线语音识别 HTTP 接口
  - 路径：`POST /transcribe`、`POST /inference`
  - API 文档：[services/fasr-service-transcribe/TRANSCRIBE_API_ZH.md](services/fasr-service-transcribe/TRANSCRIBE_API_ZH.md)
- 实时语音识别 WebSocket 接口
  - 路径：`GET /v1/realtime`、`GET /api-ws/v1/realtime`
  - 中文事件协议：[services/fasr-service-realtime/REALTIME_API_ZH.md](services/fasr-service-realtime/REALTIME_API_ZH.md)
