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

Connect bilingual source guides to the tested canonical GPU example without changing CPU recipes or model capabilities.

Signed-off-by: LauraGPT <18321252+LauraGPT@users.noreply.github.com>

Author: LauraGPT

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 |

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 与接口 |

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
 
 
+@pytest.mark.parametrize("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