Simplify usage examples and link training recipes

README.md

@@ -9,240 +9,86 @@ base_model:
 tags:
 - wenetspeech-min
 - minnan
-- southern-min
 - speech-recognition
 - paired-transcript-asr
-- qwen3-asr
 ---
 
 # WenetSpeech-Min ASR Models
 
-These ASR models accompany
-[WenetSpeech-Min: A Large-Scale Minnan Speech Corpus with Dual Transcriptions for Dialectal Speech Processing](https://arxiv.org/abs/2609.36834).
-WenetSpeech-Min comprises around **10,000 hours of Minnan speech** from online
-media, pairing each utterance with a Minnan transcript and a Mandarin transcript.
-
-The models support **Minnan transcription**, **Mandarin transcription**, and
-**paired-transcript recognition**. Minnan transcripts retain dialectal wording;
-Mandarin transcripts express the same content in written Mandarin, without
-requiring word-by-word alignment with the spoken Minnan.
-
-[Code](https://github.com/ASLP-lab/WenetSpeech-Min-Repo) |
-[Paper](https://arxiv.org/abs/2609.36834) |
-[Qwen3-ASR](https://huggingface.co/Qwen/Qwen3-ASR-1.7B) |
-[FireRedASR2-AED](https://huggingface.co/FireRedTeam/FireRedASR2-AED)
+ASR models for Minnan transcription, Mandarin transcription, and paired-transcript
+recognition, described in [WenetSpeech-Min](https://arxiv.org/abs/2609.36834).
+The corpus contains around 10,000 hours of Minnan speech, with paired Minnan
+and Mandarin transcripts for each utterance.
 
 ## Available Models
 
-| Model | Task | Fine-tuning framework |
+| Model | Task | Framework |
 | --- | --- | --- |
 | [Qwen3-ASR-WSM-Min](https://huggingface.co/ASLP-lab/WS-Min-ASR/tree/main/Qwen3-ASR-WSM-Min) | Minnan transcription | ms-swift |
 | [Qwen3-ASR-WSM-Mandarin](https://huggingface.co/ASLP-lab/WS-Min-ASR/tree/main/Qwen3-ASR-WSM-Mandarin) | Mandarin transcription | ms-swift |
 | [FireRedASR2-AED-WSM](https://huggingface.co/ASLP-lab/WS-Min-ASR/tree/main/FireRedASR2-AED-WSM) | Paired-transcript recognition | WeNet |
 
-All three models take Minnan speech as input. Each Qwen checkpoint provides one
-transcription target; FireRedASR2-AED-WSM supports both targets in one model.
-
-## Install
-
-Follow the official installation instructions for the relevant framework:
-
-- [Qwen3-ASR environment setup](https://github.com/QwenLM/Qwen3-ASR#environment-setup) for Qwen inference, including the vLLM backend.
-- [ms-swift installation](https://swift.readthedocs.io/en/latest/GetStarted/SWIFT-installation.html) for Qwen fine-tuning.
-- [WeNet installation for training and deployment](https://github.com/wenet-e2e/wenet#install-for-training--deployment) for FireRed fine-tuning and inference.
+## Installation
 
-Clone the training and inference recipes:
+Follow the official installation guides:
 
-```bash
-git clone https://github.com/ASLP-lab/WenetSpeech-Min-Repo.git
-cd WenetSpeech-Min-Repo
-```
-
-For FireRed paired-transcript recognition, run
-`bash FireRedASR2-AED-WSM/setup_wenet.sh` to prepare the matching WeNet task-embedding implementation.
-
-### Model download
-
-Download only the selected model's inference assets, excluding optimizer and
-trainer state files:
-
-```python
-from huggingface_hub import snapshot_download
-
-model_subdir = "Qwen3-ASR-WSM-Min"
-# For Mandarin output instead, use: model_subdir = "Qwen3-ASR-WSM-Mandarin"
-
-inference_files = [
-    "config.json", "generation_config.json", "preprocessor_config.json",
-    "tokenizer_config.json", "tokenizer.json", "vocab.json", "merges.txt",
-    "added_tokens.json", "special_tokens_map.json", "chat_template.jinja",
-    "chat_template.json", "model*.safetensors", "model*.safetensors.index.json",
-]
-snapshot_download(
-    repo_id="ASLP-lab/WS-Min-ASR",
-    allow_patterns=[f"{model_subdir}/{name}" for name in inference_files]
-                   + ["examples/G1216S0004.wav"],
-    local_dir="pretrained_models/WS-Min-ASR",
-)
-```
-
-The model files will be placed in
-`pretrained_models/WS-Min-ASR/Qwen3-ASR-WSM-Min/` (or the Mandarin subdirectory).
-Use a specific `revision` commit when a fixed checkpoint revision is required.
+- [Qwen3-ASR](https://github.com/QwenLM/Qwen3-ASR#environment-setup), including the vLLM backend for inference.
+- [ms-swift](https://swift.readthedocs.io/en/latest/GetStarted/SWIFT-installation.html) for Qwen fine-tuning.
+- [WeNet](https://github.com/wenet-e2e/wenet#install-for-training--deployment) for FireRed fine-tuning and inference.
 
 ## Usage
 
-### Qwen inference with vLLM
+### Qwen3-ASR
 
-After the download above, this example transcribes the supplied demonstration
-audio. No reference transcript is needed:
+Select `Qwen3-ASR-WSM-Min` for Minnan output or `Qwen3-ASR-WSM-Mandarin`
+for Mandarin output. Both take Minnan audio as input.
 
 ```python
+from huggingface_hub import snapshot_download
 from qwen_asr import Qwen3ASRModel
 
-model_dir = "pretrained_models/WS-Min-ASR/Qwen3-ASR-WSM-Min"
-# For Mandarin output, change the model directory to Qwen3-ASR-WSM-Mandarin.
-audio_path = "pretrained_models/WS-Min-ASR/examples/G1216S0004.wav"
-
-# Keep vLLM initialization under the main guard for multiprocessing.
 if __name__ == "__main__":
+    subfolder = "Qwen3-ASR-WSM-Min"  # Or "Qwen3-ASR-WSM-Mandarin"
+    model_root = snapshot_download(
+        repo_id="ASLP-lab/WS-Min-ASR",
+        allow_patterns=[f"{subfolder}/*.safetensors", f"{subfolder}/*.json",
+                        f"{subfolder}/*.txt", f"{subfolder}/*.jinja",
+                        "examples/G1216S0004.wav"],
+    )
     model = Qwen3ASRModel.LLM(
-        model=model_dir,
+        model=f"{model_root}/{subfolder}",
         gpu_memory_utilization=0.8,
         max_model_len=8192,
-        max_inference_batch_size=8,
         max_new_tokens=1024,
     )
     results = model.transcribe(
-        audio=audio_path,
+        audio=f"{model_root}/examples/G1216S0004.wav",  # Or your audio path
         language=None,
-        return_time_stamps=False,
     )
     print(results[0].text)
 ```
 
-The checkpoint selects the transcription target; changing `language` is not a
-replacement for switching the Minnan and Mandarin checkpoints.
+### FireRedASR2-AED-WSM
 
-The GitHub recipes also provide ready-to-run inference commands that download
-the correct model automatically:
-
-```bash
-# Run from the GitHub repository root. Each directory includes the sample audio.
-CUDA_VISIBLE_DEVICES=0 bash Qwen3-ASR-Min/infer.sh
-CUDA_VISIBLE_DEVICES=0 bash Qwen3-ASR-Mandarin/infer.sh
-
-# User-provided audio and JSONL output:
-bash Qwen3-ASR-Min/infer.sh --audio /path/to/audio.wav --output /path/to/new-result.jsonl
-
-# Optional Transformers backend:
-bash Qwen3-ASR-Min/infer.sh --backend transformers
-```
-
-The output contains the audio identifier, path, transcription target, language,
-and recognized text. Several audio paths may follow `--audio` for batch inference.
-
-### FireRed paired-transcript recognition
-
-Download the FireRed checkpoint and its tokenizer/CMVN assets:
-
-```python
-from huggingface_hub import snapshot_download
-
-snapshot_download(
-    repo_id="ASLP-lab/WS-Min-ASR",
-    allow_patterns=["FireRedASR2-AED-WSM/*"],
-    local_dir="pretrained_models/WS-Min-ASR",
-)
-```
-
-Run inference from the GitHub repository root:
+Download the model and run paired-transcript recognition with the GitHub recipe:
 
 ```bash
+git clone https://github.com/ASLP-lab/WenetSpeech-Min-Repo.git
+cd WenetSpeech-Min-Repo
+bash FireRedASR2-AED-WSM/setup_wenet.sh
+hf download ASLP-lab/WS-Min-ASR --include "FireRedASR2-AED-WSM/*" \
+  --local-dir pretrained_models/WS-Min-ASR
 CUDA_VISIBLE_DEVICES=0 bash FireRedASR2-AED-WSM/infer.sh \
   --model-dir pretrained_models/WS-Min-ASR/FireRedASR2-AED-WSM \
   --task both
 ```
 
-Use `--task minnan` for the Minnan transcript or `--task mandarin` for the
-Mandarin transcript. `--task both` returns `text_minnan` and `text_mandarin`.
-Override the included sample with `--audio /path/to/audio.wav`.
+Use `--task minnan` or `--task mandarin` for a single transcript.
+Add `--audio /path/to/audio.wav` to use your own audio; otherwise the included
+example is used. Paired output contains `text_minnan` and `text_mandarin`.
 
 ## Training
 
-The [GitHub repository](https://github.com/ASLP-lab/WenetSpeech-Min-Repo) contains
-the training recipes for all three models. Each recipe reads a JSONL manifest,
-with one training example per line. Use the corresponding format below for
-both training and validation manifests. Audio paths must resolve on the
-training machine.
-
-### Qwen3-ASR-WSM-Min: Minnan transcription
-
-[Training code](https://github.com/ASLP-lab/WenetSpeech-Min-Repo/tree/main/Qwen3-ASR-Min)
-
-Supervision uses the Minnan transcripts of WenetSpeech-Min. The ms-swift
-training format is:
-
-```json
-{"key":"example_001","messages":[{"role":"user","content":"<audio>"},{"role":"assistant","content":"language Chinese<asr_text>你欲食啥物？"}],"audios":["/path/to/audio/example_001.wav"]}
-```
-
-```bash
-TRAIN_DATA=/path/to/train.minnan.jsonl \
-VAL_DATA=/path/to/validation.minnan.jsonl \
-bash Qwen3-ASR-Min/train.sh
-```
-
-### Qwen3-ASR-WSM-Mandarin: Mandarin transcription
-
-[Training code](https://github.com/ASLP-lab/WenetSpeech-Min-Repo/tree/main/Qwen3-ASR-Mandarin)
-
-Training combines MinSpeech with the Mandarin transcripts of WenetSpeech-Min.
-Use the same ms-swift schema with the Mandarin transcript as the assistant target:
-
-```json
-{"key":"example_001","messages":[{"role":"user","content":"<audio>"},{"role":"assistant","content":"language Chinese<asr_text>你想吃什么？"}],"audios":["/path/to/audio/example_001.wav"]}
-```
-
-```bash
-TRAIN_DATA=/path/to/train.mandarin.jsonl \
-VAL_DATA=/path/to/validation.mandarin.jsonl \
-bash Qwen3-ASR-Mandarin/train.sh
-```
-
-### FireRedASR2-AED-WSM: paired-transcript recognition
-
-[Training code](https://github.com/ASLP-lab/WenetSpeech-Min-Repo/tree/main/FireRedASR2-AED-WSM)
-
-Paired transcripts supervise one model; two learnable task embeddings select
-the output target, and CTC loss is disabled. Represent each recording as two
-WeNet raw JSONL examples sharing the same audio path:
-
-```json
-{"key":"example_001_transcribe_minnan","wav":"/path/to/audio/example_001.wav","txt":"你欲食啥物？","task":"transcribe_minnan","lang":"zh"}
-{"key":"example_001_translate_zh","wav":"/path/to/audio/example_001.wav","txt":"你想吃什么？","task":"translate_zh","lang":"zh"}
-```
-
-`transcribe_minnan` selects the Minnan transcript; `translate_zh` selects the
-Mandarin transcript. These are the task identifiers used by the implementation.
-
-```bash
-BASE_MODEL_DIR=/path/to/wenet-converted-FireRedASR2-AED \
-TRAIN_DATA=/path/to/train.paired.jsonl \
-VAL_DATA=/path/to/validation.paired.jsonl \
-bash FireRedASR2-AED-WSM/train.sh
-```
-
-`BASE_MODEL_DIR` contains the converted base checkpoint `wenet_firered.pt`,
-`global_cmvn`, `train_bpe1000.model`, and `units.txt`. See the
-[FireRed training recipe](https://github.com/ASLP-lab/WenetSpeech-Min-Repo/tree/main/FireRedASR2-AED-WSM)
-for base-model conversion. Each recipe directory also includes `prepare_data.py`
-for converting paired audio/transcript manifests to its training format.
-
-## Acknowledgements
-
-This work builds on [Qwen3-ASR](https://github.com/QwenLM/Qwen3-ASR),
-[ms-swift](https://github.com/modelscope/ms-swift),
-[FireRedASR2S](https://github.com/FireRedTeam/FireRedASR2S), and
-[WeNet](https://github.com/wenet-e2e/wenet). Please retain upstream license and
-attribution notices when using or redistributing their components.
+- [Minnan transcription: Qwen3-ASR-WSM-Min](https://github.com/ASLP-lab/WenetSpeech-Min-Repo/tree/main/Qwen3-ASR-Min)
+- [Mandarin transcription: Qwen3-ASR-WSM-Mandarin](https://github.com/ASLP-lab/WenetSpeech-Min-Repo/tree/main/Qwen3-ASR-Mandarin)
+- [Paired-transcript recognition: FireRedASR2-AED-WSM](https://github.com/ASLP-lab/WenetSpeech-Min-Repo/tree/main/FireRedASR2-AED-WSM)