Skip to content

Open-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.

docs: connect native Transformers guides to tested CUDA recipe (#3697)

zhifu gao486b4b7ceb27
diff --git a/docs/transformers_native.md b/docs/transformers_native.md
index 51548a5e2..b902c478a 100644
--- a/docs/transformers_native.md
+++ b/docs/transformers_native.md
@@ -103,6 +103,30 @@ truncation; increasing the limit does not prove coverage of a long recording.
The CLI reports `reached_eos` and exits unsuccessfully for missing EOS or empty
text. EOS itself is not proof that all words were recognized.
+## Run the CLI on CUDA
+
+Follow the [isolated CUDA installation](https://github.com/QwenAudio/Fun-ASR/tree/main/examples/transformers#cuda-an-isolated-tested-recipe),
+including its separate `requirements-gpu.txt`, before running this from the
+QwenAudio/Fun-ASR code repository with your local audio files:
+
+```bash
+python examples/transformers/transcribe.py chinese.wav english.wav --language zh en --device cuda --dtype bfloat16
+```
+
+On **2026-09-10**, Linux/Python 3.12, H100 80 GB, driver **550.127.08**,
+torch/torchaudio **2.11.0+cu128** and Transformers **5.17.0** passed eight
+float32/BF16 English, Chinese, keyword and padded mixed-batch functional cases.
+The updated CLI also passed GPU single-file/batch and default CPU regression.
+These are not accuracy, minimum-VRAM or serving-capacity benchmarks; the Chinese
+keyword error described above remains. Other GPUs and float16 were not tested.
+
+No device flags still means CPU float32. Explicit CUDA fails when unavailable,
+and BF16 requires device support; no silent CPU fallback. The model and inputs
+move together without casting integer token IDs. Output records device and dtype.
+An attention-dispatch warning was observed; successful inference does not verify
+every component's kernel or imply Flash Attention performance. Hosted GPU
+Space/Colab execution has not been verified by these local checks.
+
## From an example to a service
| Need | Checkpoint and interface |
diff --git a/docs/transformers_native_zh.md b/docs/transformers_native_zh.md
index ba34ea2b7..515621f2e 100644
--- a/docs/transformers_native_zh.md
+++ b/docs/transformers_native_zh.md
@@ -94,6 +94,28 @@ python examples/transformers/transcribe.py chinese.wav english.wav --language zh
上限不等于长录音已完整覆盖。CLI 输出 `reached_eos`,缺少 EOS 或文本为空时
以非零状态结束;出现 EOS 也不代表每个字都识别正确。
+## 用 CUDA 运行 CLI
+
+先按[独立 CUDA 安装指南](https://github.com/QwenAudio/Fun-ASR/tree/main/examples/transformers#cuda-an-isolated-tested-recipe)
+安装专用的 `requirements-gpu.txt`,不要混入 CPU 环境。在 QwenAudio/Fun-ASR
+代码仓库根目录,用自己的本地录音运行:
+
+```bash
+python examples/transformers/transcribe.py chinese.wav english.wav --language zh en --device cuda --dtype bfloat16
+```
+
+**2026-09-10** 在 Linux/Python 3.12、H100 80 GB、驱动 **550.127.08**、
+torch/torchaudio **2.11.0+cu128**、Transformers **5.17.0** 上完成八项功能检查:
+float32/BF16 各覆盖英文、中文、关键词和中英 padding 批次。修改后的 CLI 也通过
+GPU 单文件、批次与默认 CPU 回归。这不是准确率、最低显存或服务容量评测;
+前述中文关键词识别错误仍存在。其他 GPU 和 float16 尚未测试。
+
+不传设备参数仍使用 CPU float32。显式请求 CUDA 但设备不可用时直接报错,
+BF16 也会检查设备支持,不会静默回退 CPU。模型和输入一起迁移设备,不把整数
+token ID 转成浮点数;输出记录实际设备与精度。测试中出现过 attention 分派警告,
+功能通过不代表每个组件的内核已验证,也不意味着 Flash Attention 性能已验证。
+这些本地检查不覆盖托管 GPU Space 或 Colab 的实际运行。
+
## 从示例走向服务
| 需求 | checkpoint 与接口 |
diff --git a/web-pages/product-site/tests/test_native_transformers_docs.py b/web-pages/product-site/tests/test_native_transformers_docs.py
index b09f44fce..023bd5007 100644
--- a/web-pages/product-site/tests/test_native_transformers_docs.py
+++ b/web-pages/product-site/tests/test_native_transformers_docs.py
@@ -95,6 +95,16 @@ def test_all_language_entry_points_reach_native_examples(suffix):
assert "fun_asr_nano_transformers.ipynb" in text
[email protected]("suffix", ["", "_zh"])
+def test_cuda_route_is_explicit_bounded_and_reaches_canonical_recipe(suffix):
+ text = guide(suffix)
+ for expected in ("--device cuda --dtype bfloat16", "H100", "550.127.08",
+ "2.11.0+cu128", "2026-09-10", "requirements-gpu.txt"):
+ assert expected in text
+ assert "https://github.com/QwenAudio/Fun-ASR/tree/main/examples/transformers#cuda-an-isolated-tested-recipe" in text
+ assert "torch==2.10.0+cpu" in text
+
+
def test_hf_catalogue_and_sphinx_reach_native_model():
text = (ROOT / "model_zoo/huggingface_models.md").read_text()
assert MODEL in text and "transformers_native.md" in text