Merge pull request #3233 from modelscope/codex/llamacpp-download-variant

LauraGPT · web-flow · commit e327ade1b4b6 · 2026-07-15T12:36:49.000+08:00
fix(llama.cpp): download one GGUF variant by default
diff --git a/.github/workflows/build-llamacpp-binaries.yml b/.github/workflows/build-llamacpp-binaries.yml
@@ -129,7 +129,10 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
-          gh release create "${{ github.ref_name }}" dist/* \
+          tag="${{ github.ref_name }}"
+          version="${tag#runtime-llamacpp-}"
+          docs="https://github.com/${{ github.repository }}/blob/$tag/runtime/llama.cpp/README.md"
+          gh release create "$tag" dist/* \
             --repo "${{ github.repository }}" \
-            --title "FunASR llama.cpp runtime ${{ github.ref_name }}" \
-            --notes "Prebuilt self-contained binaries for the FunASR llama.cpp / GGUF runtime — SenseVoice, Paraformer and Fun-ASR-Nano with built-in FSMN-VAD (a whisper.cpp-style on-device ASR, strong on Chinese). Get a model with \`bash download-funasr-model.sh <sensevoice|paraformer|nano>\`, then run \`llama-funasr-cli\` / \`llama-funasr-sensevoice\` / \`llama-funasr-paraformer\`. Use the default x64 asset for maximum CPU compatibility; use the x64-avx2 asset on CPUs with AVX2/FMA/F16C/BMI2 for higher throughput. No Python, no build. Docs: runtime/llama.cpp/README.md"
+            --title "FunASR llama.cpp runtime $version" \
+            --notes "Prebuilt self-contained binaries for the FunASR llama.cpp / GGUF runtime: SenseVoice, Paraformer and Fun-ASR-Nano with built-in FSMN-VAD. Download the default quantized model with \`bash download-funasr-model.sh <sensevoice|paraformer|nano>\` (the helper requires the Hugging Face CLI: \`pip install -U huggingface_hub\`), then run \`llama-funasr-cli\` / \`llama-funasr-sensevoice\` / \`llama-funasr-paraformer\`. Use the default x64 asset for maximum CPU compatibility; use the x64-avx2 asset on CPUs with AVX2/FMA/F16C/BMI2 for higher throughput. No Python ASR runtime or local build is required. Docs: $docs"
diff --git a/runtime/llama.cpp/README.md b/runtime/llama.cpp/README.md
@@ -29,9 +29,28 @@ and the audio embeddings are injected into it via `llama_decode`'s embedding inp
 build/convert/run quickstart, validation numbers, and gotchas.
 
 ## Download pre-built GGUF (fastest — no Python ML env)
+
+The helper requires the Hugging Face CLI (`pip install -U huggingface_hub`). By
+default it downloads one practical quantized variant plus FSMN-VAD, rather than
+every GGUF in the repository:
+
 ```bash
-./download-funasr-model.sh sensevoice          # or: paraformer | nano | fsmn-vad
+./download-funasr-model.sh sensevoice          # q8 (default) + FSMN-VAD
+./download-funasr-model.sh paraformer          # q8 (default) + FSMN-VAD
+./download-funasr-model.sh nano                 # encoder-f16 + q8_0 (default) + FSMN-VAD
+./download-funasr-model.sh fsmn-vad             # FSMN-VAD only
 ```
+
+Use the optional third argument to choose another variant. SenseVoice and
+Paraformer support `q8`, `f16`, `f32`, or `all`; Nano supports `q8_0`, `q4km`,
+`q5km`, or `all`. The optional second argument is the output directory:
+
+```bash
+./download-funasr-model.sh sensevoice funasr-gguf f16
+./download-funasr-model.sh nano funasr-gguf q4km
+./download-funasr-model.sh paraformer funasr-gguf all  # explicitly download every GGUF
+```
+
 Pre-converted GGUF on Hugging Face: [SenseVoiceSmall-GGUF](https://huggingface.co/FunAudioLLM/SenseVoiceSmall-GGUF) · [Paraformer-GGUF](https://huggingface.co/FunAudioLLM/Paraformer-GGUF) · [Fun-ASR-Nano-GGUF](https://huggingface.co/FunAudioLLM/Fun-ASR-Nano-GGUF) · [fsmn-vad-GGUF](https://huggingface.co/FunAudioLLM/fsmn-vad-GGUF). Or convert yourself with `convert-funasr-to-gguf.py`.
 
 ## Build (standalone, CI-friendly)
diff --git a/runtime/llama.cpp/download-funasr-model.sh b/runtime/llama.cpp/download-funasr-model.sh
@@ -1,26 +1,80 @@
 #!/usr/bin/env bash
-# Download pre-converted FunASR GGUF models from Hugging Face — one command, no Python ML env.
-#   ./download-funasr-model.sh sensevoice [outdir]
-#   ./download-funasr-model.sh paraformer | nano | fsmn-vad
+# Download pre-converted FunASR GGUF models from Hugging Face in one command.
+#   ./download-funasr-model.sh sensevoice [outdir] [q8|f16|f32|all]
+#   ./download-funasr-model.sh paraformer [outdir] [q8|f16|f32|all]
+#   ./download-funasr-model.sh nano [outdir] [q8_0|q4km|q5km|all]
+#   ./download-funasr-model.sh fsmn-vad [outdir]
 # ASR models also pull fsmn-vad.gguf (needed for built-in --vad long-audio segmentation).
 set -euo pipefail
-usage(){ echo "usage: $0 {sensevoice|paraformer|nano|fsmn-vad} [outdir]"; exit 1; }
-[ $# -ge 1 ] || usage
-MODEL="$1"; OUT="${2:-funasr-gguf}"
+usage(){
+  cat >&2 <<EOF
+usage: $0 {sensevoice|paraformer|nano|fsmn-vad} [outdir] [variant]
+  sensevoice/paraformer variants: q8 (default), f16, f32, all
+  nano variants: q8_0 (default), q4km, q5km, all
+EOF
+  exit 1
+}
+[ $# -ge 1 ] && [ $# -le 3 ] || usage
+MODEL="$1"; OUT="${2:-funasr-gguf}"; VARIANT="${3:-}"
 case "$MODEL" in
-  sensevoice) REPO="FunAudioLLM/SenseVoiceSmall-GGUF" ;;
-  paraformer) REPO="FunAudioLLM/Paraformer-GGUF" ;;
-  nano)       REPO="FunAudioLLM/Fun-ASR-Nano-GGUF" ;;
-  fsmn-vad|vad) REPO="FunAudioLLM/fsmn-vad-GGUF" ;;
+  sensevoice)
+    REPO="FunAudioLLM/SenseVoiceSmall-GGUF"
+    case "${VARIANT:-q8}" in
+      q8)  FILES=(sensevoice-small-q8.gguf) ;;
+      f16) FILES=(sensevoice-small-f16.gguf) ;;
+      f32) FILES=(sensevoice-small.gguf) ;;
+      all) FILES=() ;;
+      *) usage ;;
+    esac
+    ;;
+  paraformer)
+    REPO="FunAudioLLM/Paraformer-GGUF"
+    case "${VARIANT:-q8}" in
+      q8)  FILES=(paraformer-q8.gguf) ;;
+      f16) FILES=(paraformer-f16.gguf) ;;
+      f32) FILES=(paraformer.gguf) ;;
+      all) FILES=() ;;
+      *) usage ;;
+    esac
+    ;;
+  nano)
+    REPO="FunAudioLLM/Fun-ASR-Nano-GGUF"
+    case "${VARIANT:-q8_0}" in
+      q8|q8_0) FILES=(funasr-encoder-f16.gguf qwen3-0.6b-q8_0.gguf) ;;
+      q4|q4km) FILES=(funasr-encoder-f16.gguf qwen3-0.6b-q4km.gguf) ;;
+      q5|q5km) FILES=(funasr-encoder-f16.gguf qwen3-0.6b-q5km.gguf) ;;
+      all) FILES=() ;;
+      *) usage ;;
+    esac
+    ;;
+  fsmn-vad|vad)
+    [ -z "$VARIANT" ] || usage
+    REPO="FunAudioLLM/fsmn-vad-GGUF"
+    FILES=(fsmn-vad.gguf)
+    ;;
   *) usage ;;
 esac
 # huggingface_hub ships `hf` (new CLI); older versions only have `huggingface-cli` (deprecated). Use whichever exists.
 if   command -v hf              >/dev/null 2>&1; then HF=hf
 elif command -v huggingface-cli >/dev/null 2>&1; then HF=huggingface-cli
-else echo "need the Hugging Face CLI: pip install -U huggingface_hub"; exit 1; fi
+else echo "error: need the Hugging Face CLI: pip install -U huggingface_hub" >&2; exit 1; fi
 mkdir -p "$OUT"
-echo "downloading $REPO ..."; "$HF" download "$REPO" --include "*.gguf" --local-dir "$OUT"
+echo "downloading $REPO ..."
+if [ ${#FILES[@]} -eq 0 ]; then
+  "$HF" download "$REPO" --include "*.gguf" --local-dir "$OUT"
+else
+  "$HF" download "$REPO" "${FILES[@]}" --local-dir "$OUT"
+fi
 if [ "$MODEL" != "fsmn-vad" ] && [ "$MODEL" != "vad" ]; then
-  echo "downloading FSMN-VAD (for --vad) ..."; "$HF" download FunAudioLLM/fsmn-vad-GGUF --include "*.gguf" --local-dir "$OUT"
+  echo "downloading FSMN-VAD (for --vad) ..."
+  "$HF" download FunAudioLLM/fsmn-vad-GGUF fsmn-vad.gguf --local-dir "$OUT"
+fi
+shopt -s nullglob
+GGUF_FILES=("$OUT"/*.gguf)
+shopt -u nullglob
+if [ ${#GGUF_FILES[@]} -eq 0 ]; then
+  echo "error: no GGUF files found in $OUT" >&2
+  exit 1
 fi
-echo "done -> $OUT"; ls -1 "$OUT"/*.gguf
+echo "done -> $OUT"
+printf '%s\n' "${GGUF_FILES[@]}"
diff --git a/runtime/llama.cpp/tests/run_regression.sh b/runtime/llama.cpp/tests/run_regression.sh
@@ -24,7 +24,12 @@ ensure_models(){ local key="$1"; shift
   local missing=0; for f in "$@"; do [ -f "$MODELS/$f" ] || missing=1; done
   [ "$missing" = 0 ] && return 0
   { [ "$key" = fsmn-vad ] || [ "$RUN_FULL" = 1 ]; } || return 1   # only auto-fetch the tiny VAD unless RUN_FULL
-  "$RT/download-funasr-model.sh" "$key" "$MODELS" >/dev/null 2>&1 || return 1
+  local args=("$key" "$MODELS")
+  case "$key" in
+    sensevoice|paraformer) args+=(f16) ;;
+    nano) args+=(q8_0) ;;
+  esac
+  "$RT/download-funasr-model.sh" "${args[@]}" >/dev/null 2>&1 || return 1
   for f in "$@"; do [ -f "$MODELS/$f" ] || return 1; done; return 0
 }
 check(){ local name="$1" golden="$2" got="$3"
diff --git a/runtime/llama.cpp/tests/test_download_funasr_model.sh b/runtime/llama.cpp/tests/test_download_funasr_model.sh
@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+SCRIPT="$ROOT/download-funasr-model.sh"
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+
+mkdir -p "$TMP/bin"
+cat >"$TMP/bin/hf" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+
+printf '%s\n' "$*" >>"$HF_LOG"
+
+if [[ "${HF_SKIP_CREATE:-0}" == 1 ]]; then
+  exit 0
+fi
+
+out=
+args=("$@")
+for ((i = 0; i < ${#args[@]}; i++)); do
+  if [[ "${args[$i]}" == "--local-dir" ]]; then
+    out="${args[$((i + 1))]}"
+    break
+  fi
+done
+
+[[ -n "$out" ]]
+mkdir -p "$out"
+for arg in "${args[@]}"; do
+  case "$arg" in
+    '*.gguf') : >"$out/all.gguf" ;;
+    *.gguf) : >"$out/$arg" ;;
+  esac
+done
+EOF
+chmod +x "$TMP/bin/hf"
+
+export PATH="$TMP/bin:$PATH"
+export HF_LOG="$TMP/hf.log"
+
+reset_case() {
+  : >"$HF_LOG"
+  rm -rf "$TMP/out"
+}
+
+assert_log() {
+  grep -F -- "$1" "$HF_LOG" >/dev/null
+}
+
+assert_no_log() {
+  if grep -F -- "$1" "$HF_LOG" >/dev/null; then
+    printf 'unexpected log entry: %s\n' "$1" >&2
+    cat "$HF_LOG" >&2
+    exit 1
+  fi
+}
+
+reset_case
+bash "$SCRIPT" sensevoice "$TMP/out" >/dev/null
+assert_log "download FunAudioLLM/SenseVoiceSmall-GGUF sensevoice-small-q8.gguf --local-dir $TMP/out"
+assert_log "download FunAudioLLM/fsmn-vad-GGUF fsmn-vad.gguf --local-dir $TMP/out"
+assert_no_log "--include *.gguf"
+
+reset_case
+bash "$SCRIPT" paraformer "$TMP/out" f16 >/dev/null
+assert_log "download FunAudioLLM/Paraformer-GGUF paraformer-f16.gguf --local-dir $TMP/out"
+
+reset_case
+bash "$SCRIPT" nano "$TMP/out" >/dev/null
+assert_log "download FunAudioLLM/Fun-ASR-Nano-GGUF funasr-encoder-f16.gguf qwen3-0.6b-q8_0.gguf --local-dir $TMP/out"
+
+reset_case
+bash "$SCRIPT" nano "$TMP/out" q4km >/dev/null
+assert_log "download FunAudioLLM/Fun-ASR-Nano-GGUF funasr-encoder-f16.gguf qwen3-0.6b-q4km.gguf --local-dir $TMP/out"
+
+reset_case
+bash "$SCRIPT" sensevoice "$TMP/out" all >/dev/null
+assert_log "download FunAudioLLM/SenseVoiceSmall-GGUF --include *.gguf --local-dir $TMP/out"
+
+reset_case
+bash "$SCRIPT" fsmn-vad "$TMP/out" >/dev/null
+assert_log "download FunAudioLLM/fsmn-vad-GGUF fsmn-vad.gguf --local-dir $TMP/out"
+[[ $(wc -l <"$HF_LOG") -eq 1 ]]
+
+reset_case
+if bash "$SCRIPT" sensevoice "$TMP/out" q4km >/dev/null 2>&1; then
+  echo "sensevoice accepted an unsupported q4km variant" >&2
+  exit 1
+fi
+[[ ! -s "$HF_LOG" ]]
+
+mkdir -p "$TMP/empty-bin"
+if PATH="$TMP/empty-bin" /bin/bash "$SCRIPT" sensevoice "$TMP/out" >"$TMP/stdout" 2>"$TMP/stderr"; then
+  echo "download succeeded without a Hugging Face CLI" >&2
+  exit 1
+fi
+[[ ! -s "$TMP/stdout" ]]
+grep -F "need the Hugging Face CLI" "$TMP/stderr" >/dev/null
+
+reset_case
+if HF_SKIP_CREATE=1 bash "$SCRIPT" sensevoice "$TMP/out" >"$TMP/stdout" 2>"$TMP/stderr"; then
+  echo "download succeeded without producing a GGUF file" >&2
+  exit 1
+fi
+grep -F "no GGUF files found in $TMP/out" "$TMP/stderr" >/dev/null
+
+echo "download-funasr-model contract tests passed"
