docs: make Paraformer-en model card directly usable

README.md

@@ -2,190 +2,154 @@
 license: other
 license_name: model-license
 license_link: https://github.com/alibaba-damo-academy/FunASR
+language:
+- en
+pipeline_tag: automatic-speech-recognition
+tags:
+- FunASR
+- Paraformer
+- ASR
+- automatic-speech-recognition
+- non-autoregressive
+- speech-recognition
+library_name: funasr
 ---
 
 <div align="center">
 
-### ⭐ Powered by [FunASR](https://github.com/modelscope/FunASR) — please give us a GitHub Star!
+# Paraformer-en
 
-This model is part of the **FunASR** ecosystem — one industrial-grade open-source toolkit for **ASR · VAD · punctuation · speaker diarization · emotion / event · LLM-ASR**. A Star really helps the project (and keeps you updated):
+**A 220M offline, non-autoregressive English speech recognition model for 16 kHz audio.**
 
-[**🌟 FunASR**](https://github.com/modelscope/FunASR)  ·  [**🌟 SenseVoice**](https://github.com/FunAudioLLM/SenseVoice)  ·  [**🌟 Fun-ASR**](https://github.com/FunAudioLLM/Fun-ASR)  ·  [**🌟 FunClip**](https://github.com/modelscope/FunClip)
+Powered by [FunASR](https://github.com/modelscope/FunASR). Follow the project or give it a star to receive new model, runtime, and deployment updates.
 
-</div>
-
-
-
-
-# FunASR: A Fundamental End-to-End Speech Recognition Toolkit
+[FunASR](https://github.com/modelscope/FunASR) · [Fun-ASR](https://github.com/QwenAudio/Fun-ASR) · [SenseVoice](https://github.com/QwenAudio/SenseVoice) · [FunClip](https://github.com/modelscope/FunClip)
 
+</div>
 
-[![PyPI](https://img.shields.io/pypi/v/funasr)](https://pypi.org/project/funasr/)
+Paraformer predicts output tokens in parallel instead of decoding them one by one. This checkpoint is intended for high-throughput English transcription where complete utterances or files are available before decoding.
 
+## Quick start
 
-<strong>FunASR</strong> hopes to build a bridge between academic research and industrial applications on speech recognition. By supporting the training & finetuning of the industrial-grade speech recognition model, researchers and developers can conduct research and production of speech recognition models more conveniently, and promote the development of speech recognition ecology. ASR for Fun！
+Install PyTorch and FunASR:
 
-[**Highlights**](#highlights)
-| [**News**](https://github.com/alibaba-damo-academy/FunASR#whats-new) 
-| [**Installation**](#installation)
-| [**Quick Start**](#quick-start)
-| [**Runtime**](./runtime/readme.md)
-| [**Model Zoo**](#model-zoo)
-| [**Contact**](#contact)
+```bash
+python -m pip install -U torch torchaudio funasr
+```
 
+For CUDA-specific PyTorch wheels, select the command for your platform in the [PyTorch installation guide](https://pytorch.org/get-started/locally/), then install `funasr`.
 
-<a name="highlights"></a>
-## Highlights
-- FunASR is a fundamental speech recognition toolkit that offers a variety of features, including speech recognition (ASR), Voice Activity Detection (VAD), Punctuation Restoration, Language Models, Speaker Verification, Speaker Diarization and multi-talker ASR. FunASR provides convenient scripts and tutorials, supporting inference and fine-tuning of pre-trained models.
-- We have released a vast collection of academic and industrial pretrained models on the [ModelScope](https://www.modelscope.cn/models?page=1&tasks=auto-speech-recognition) and [huggingface](https://huggingface.co/FunASR), which can be accessed through our [Model Zoo](https://github.com/alibaba-damo-academy/FunASR/blob/main/docs/model_zoo/modelscope_models.md). The representative [Paraformer-large](https://www.modelscope.cn/models/damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-pytorch/summary), a non-autoregressive end-to-end speech recognition model, has the advantages of high accuracy, high efficiency, and convenient deployment, supporting the rapid construction of speech recognition services. For more details on service deployment, please refer to the [service deployment document](runtime/readme_cn.md). 
+Run the audio example included in this repository:
 
+```python
+from funasr import AutoModel
 
-<a name="Installation"></a>
-## Installation
+model = AutoModel(
+    model="funasr/paraformer-en",
+    hub="hf",
+    device="cpu",  # Change to "cuda:0" for NVIDIA GPU inference.
+)
 
-```shell
-pip3 install -U funasr
-```
-Or install from source code
-``` sh
-git clone https://github.com/alibaba/FunASR.git && cd FunASR
-pip3 install -e ./
+audio = f"{model.model_path}/example/asr_example.wav"
+result = model.generate(input=audio)
+print(result[0]["text"])
 ```
-Install modelscope for the pretrained models (Optional)
 
-```shell
-pip3 install -U modelscope
-```
-
-## Model Zoo
-FunASR has open-sourced a large number of pre-trained models on industrial data. You are free to use, copy, modify, and share FunASR models under the [Model License Agreement](./MODEL_LICENSE). Below are some representative models, for more models please refer to the [Model Zoo]().
-
-(Note: 🤗 represents the Huggingface model zoo link, ⭐ represents the ModelScope model zoo link)
-
-
-|                                                                             Model Name                                                                             |                    Task Details                    |          Training Data           | Parameters |
-|:------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:--------------------------------------------------:|:--------------------------------:|:----------:|
-|    paraformer-zh <br> ([⭐](https://www.modelscope.cn/models/damo/speech_paraformer-large-vad-punc_asr_nat-zh-cn-16k-common-vocab8404-pytorch/summary)  [🤗]() )    | speech recognition, with timestamps, non-streaming |      60000 hours, Mandarin       |    220M    |
-| <nobr>paraformer-zh-streaming <br> ( [⭐](https://modelscope.cn/models/damo/speech_paraformer-large_asr_nat-zh-cn-16k-common-vocab8404-online/summary) [🤗]() )</nobr> |           speech recognition, streaming            |      60000 hours, Mandarin       |    220M    |
-|         paraformer-en <br> ( [⭐](https://www.modelscope.cn/models/damo/speech_paraformer-large-vad-punc_asr_nat-en-16k-common-vocab10020/summary) [🤗]() )         | speech recognition, with timestamps, non-streaming |       50000 hours, English       |    220M    |
-|                     conformer-en <br> ( [⭐](https://modelscope.cn/models/damo/speech_conformer_asr-en-16k-vocab4199-pytorch/summary) [🤗]() )                      |         speech recognition, non-streaming          |       50000 hours, English       |    220M    |
-|                     ct-punc <br> ( [⭐](https://modelscope.cn/models/damo/punc_ct-transformer_cn-en-common-vocab471067-large/summary) [🤗]() )                      |              punctuation restoration               |    100M, Mandarin and English    |    1.1G    | 
-|                          fsmn-vad <br> ( [⭐](https://modelscope.cn/models/damo/speech_fsmn_vad_zh-cn-16k-common-pytorch/summary) [🤗]() )                          |              voice activity detection              | 5000 hours, Mandarin and English |    0.4M    | 
-|                          fa-zh <br> ( [⭐](https://modelscope.cn/models/damo/speech_timestamp_prediction-v1-16k-offline/summary) [🤗]() )                           |                timestamp prediction                |       5000 hours, Mandarin       |    38M     | 
-|                cam++ <br> ( [⭐](https://modelscope.cn/models/iic/speech_campplus_sv_zh-cn_16k-common/summary) [🤗]() )                                             |        speaker verification/diarization            |            5000 hours            |    7.2M    | 
+Using the full repository ID is recommended. It selects this English checkpoint directly and avoids ambiguity with similarly named Paraformer models.
 
+## Long audio pipeline
 
+Add voice activity detection to split long recordings and punctuation restoration to produce readable text:
 
+```python
+from funasr import AutoModel
 
-[//]: # ()
-[//]: # (FunASR supports pre-trained or further fine-tuned models for deployment as a service. The CPU version of the Chinese offline file conversion service has been released, details can be found in [docs]&#40;funasr/runtime/docs/SDK_tutorial.md&#41;. More detailed information about service deployment can be found in the [deployment roadmap]&#40;funasr/runtime/readme_cn.md&#41;.)
+model = AutoModel(
+    model="funasr/paraformer-en",
+    hub="hf",
+    vad_model="funasr/fsmn-vad",
+    punc_model="funasr/ct-punc",
+    device="cuda:0",
+)
+
+result = model.generate(
+    input="meeting.wav",
+    batch_size_s=300,
+)
+print(result[0]["text"])
+```
 
+The pipeline accepts common audio file paths and 16 kHz waveform input. Resample other sample rates to 16 kHz for predictable results.
 
-<a name="quick-start"></a>
-## Quick Start
+## OpenAI-compatible serving
 
-Below is a quick start tutorial. Test audio files ([Mandarin](https://isv-data.oss-cn-hangzhou.aliyuncs.com/ics/MaaS/ASR/test_audio/vad_example.wav), [English]()).
+Expose the model behind a local `/v1/audio/transcriptions` endpoint:
 
-### Command-line usage
+```bash
+python -m pip install -U torch torchaudio funasr fastapi uvicorn python-multipart
+funasr-server --model-path funasr/paraformer-en --hub hf --device cuda
+```
 
-```shell
-funasr +model=paraformer-zh +vad_model="fsmn-vad" +punc_model="ct-punc" +input=asr_example_zh.wav
+```bash
+curl http://localhost:8000/v1/audio/transcriptions \
+  -F file=@audio.wav \
+  -F model=custom
 ```
 
-Notes: Support recognition of single audio file, as well as file list in Kaldi-style wav.scp format: `wav_id wav_pat`
+`funasr-server` registers a checkpoint supplied through `--model-path` under the API model name `custom`.
 
-### Speech Recognition (Non-streaming)
-```python
-from funasr import AutoModel
-# paraformer-zh is a multi-functional asr model
-# use vad, punc, spk or not as you need
-model = AutoModel(model="paraformer-zh", model_revision="v2.0.4",
-                  vad_model="fsmn-vad", vad_model_revision="v2.0.4",
-                  punc_model="ct-punc-c", punc_model_revision="v2.0.4",
-                  # spk_model="cam++", spk_model_revision="v2.0.2",
-                  )
-res = model.generate(input=f"{model.model_path}/example/asr_example.wav", 
-                     batch_size_s=300, 
-                     hotword='魔搭')
-print(res)
-```
-Note: `model_hub`: represents the model repository, `ms` stands for selecting ModelScope download, `hf` stands for selecting Huggingface download.
+See the [OpenAI-compatible API examples](https://github.com/modelscope/FunASR/tree/main/examples/openai_api), [deployment matrix](https://github.com/modelscope/FunASR/blob/main/docs/deployment_matrix.md), and [FunASR deployment hub](https://www.funasr.com/) for clients, containers, security guidance, and production topologies.
 
-### Speech Recognition (Streaming)
-```python
-from funasr import AutoModel
+## Model details
 
-chunk_size = [0, 10, 5] #[0, 10, 5] 600ms, [0, 8, 4] 480ms
-encoder_chunk_look_back = 4 #number of chunks to lookback for encoder self-attention
-decoder_chunk_look_back = 1 #number of encoder chunks to lookback for decoder cross-attention
+| Property | Value |
+| --- | --- |
+| Architecture | Paraformer, non-autoregressive ASR |
+| Parameters | 220M |
+| Language | English |
+| Input | 16 kHz speech audio |
+| Mode | Offline / non-streaming |
+| Framework | PyTorch through FunASR |
+| Vocabulary | 10,020 tokens |
 
-model = AutoModel(model="paraformer-zh-streaming", model_revision="v2.0.4")
+### Artifact provenance
 
-import soundfile
-import os
+This Hugging Face repository mirrors the PyTorch checkpoint published as [`iic/speech_paraformer-large-vad-punc_asr_nat-en-16k-common-vocab10020`](https://www.modelscope.cn/models/iic/speech_paraformer-large-vad-punc_asr_nat-en-16k-common-vocab10020) on ModelScope. It is not a TensorFlow 1.x Paraformer variant.
 
-wav_file = os.path.join(model.model_path, "example/asr_example.wav")
-speech, sample_rate = soundfile.read(wav_file)
-chunk_stride = chunk_size[1] * 960 # 600ms
+For reproducibility, the `model.pt` artifact in revision `d043d60434a65ae49b2b2462a09660049871b8e9` has:
 
-cache = {}
-total_chunk_num = int(len((speech)-1)/chunk_stride+1)
-for i in range(total_chunk_num):
-    speech_chunk = speech[i*chunk_stride:(i+1)*chunk_stride]
-    is_final = i == total_chunk_num - 1
-    res = model.generate(input=speech_chunk, cache=cache, is_final=is_final, chunk_size=chunk_size, encoder_chunk_look_back=encoder_chunk_look_back, decoder_chunk_look_back=decoder_chunk_look_back)
-    print(res)
-```
-Note: `chunk_size` is the configuration for streaming latency.` [0,10,5]` indicates that the real-time display granularity is `10*60=600ms`, and the lookahead information is `5*60=300ms`. Each inference input is `600ms` (sample points are `16000*0.6=960`), and the output is the corresponding text. For the last speech segment input, `is_final=True` needs to be set to force the output of the last word.
+- size: `887,289,223` bytes
+- SHA-256: `e11203abf1f449b4c6515dee494c017ee27a4b716730378473d827ad3c7fe41c`
 
-### Voice Activity Detection (Non-Streaming)
-```python
-from funasr import AutoModel
+## Intended use and limitations
 
-model = AutoModel(model="fsmn-vad", model_revision="v2.0.4")
-wav_file = f"{model.model_path}/example/asr_example.wav"
-res = model.generate(input=wav_file)
-print(res)
-```
-### Voice Activity Detection (Streaming)
-```python
-from funasr import AutoModel
+This model is suitable for offline English transcription, subtitle preparation, call or meeting processing, and batch speech pipelines. It is not a streaming checkpoint; use a streaming Paraformer model when partial low-latency results are required.
 
-chunk_size = 200 # ms
-model = AutoModel(model="fsmn-vad", model_revision="v2.0.4")
+Recognition quality can degrade with heavy noise, overlapping speakers, strong accents, uncommon proper nouns, or domain-specific terminology. Validate accuracy on representative audio before production use, and review transcripts before using them in safety-critical or high-impact decisions.
 
-import soundfile
+## Related models
 
-wav_file = f"{model.model_path}/example/vad_example.wav"
-speech, sample_rate = soundfile.read(wav_file)
-chunk_stride = int(chunk_size * sample_rate / 1000)
+| Model | Purpose |
+| --- | --- |
+| [funasr/fsmn-vad](https://huggingface.co/funasr/fsmn-vad) | Voice activity detection for long audio |
+| [funasr/ct-punc](https://huggingface.co/funasr/ct-punc) | Chinese and English punctuation restoration |
+| [funasr/paraformer-zh](https://huggingface.co/funasr/paraformer-zh) | Offline Mandarin and English ASR |
+| [funasr/paraformer-zh-streaming](https://huggingface.co/funasr/paraformer-zh-streaming) | Streaming Paraformer ASR |
 
-cache = {}
-total_chunk_num = int(len((speech)-1)/chunk_stride+1)
-for i in range(total_chunk_num):
-    speech_chunk = speech[i*chunk_stride:(i+1)*chunk_stride]
-    is_final = i == total_chunk_num - 1
-    res = model.generate(input=speech_chunk, cache=cache, is_final=is_final, chunk_size=chunk_size)
-    if len(res[0]["value"]):
-        print(res)
-```
-### Punctuation Restoration
-```python
-from funasr import AutoModel
+## Resources
 
-model = AutoModel(model="ct-punc", model_revision="v2.0.4")
-res = model.generate(input="那今天的会就到这里吧 happy new year 明年见")
-print(res)
-```
-### Timestamp Prediction
-```python
-from funasr import AutoModel
+- [FunASR GitHub repository](https://github.com/modelscope/FunASR)
+- [FunASR documentation](https://modelscope.github.io/FunASR/)
+- [Paraformer paper](https://arxiv.org/abs/2206.08317)
+- [Issue tracker](https://github.com/modelscope/FunASR/issues)
 
-model = AutoModel(model="fa-zh", model_revision="v2.0.4")
-wav_file = f"{model.model_path}/example/asr_example.wav"
-text_file = f"{model.model_path}/example/text.txt"
-res = model.generate(input=(wav_file, text_file), data_type=("sound", "text"))
-print(res)
-```
+## Citation
 
-More examples ref to [docs](https://github.com/alibaba-damo-academy/FunASR/tree/main/examples/industrial_data_pretraining)
+```bibtex
+@inproceedings{gao2022paraformer,
+  title={Paraformer: Fast and Accurate Parallel Transformer for Non-autoregressive End-to-End Speech Recognition},
+  author={Gao, Zhifu and Zhang, Shiliang and McLoughlin, Ian and Yan, Zhijie},
+  booktitle={INTERSPEECH},
+  year={2022}
+}
+```