Skip to content

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

fix(llama.cpp): download one GGUF variant by default

游雁9c1793164570
diff --git a/.github/workflows/build-llamacpp-binaries.yml b/.github/workflows/build-llamacpp-binaries.yml
index 56d6b4d7c..0f46c69b6 100644
--- 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
index ca8645cd8..c007e30cd 100644
--- 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
index fc676b82f..0658a8fdc 100755
--- a/runtime/llama.cpp/download-funasr-model.sh
+++ b/runtime/llama.cpp/download-funasr-model.sh
@@ -1,17 +1,57 @@
#!/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.
@@ -19,8 +59,14 @@ 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
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
echo "done -> $OUT"; ls -1 "$OUT"/*.gguf
diff --git a/runtime/llama.cpp/tests/run_regression.sh b/runtime/llama.cpp/tests/run_regression.sh
index 50eab5d5e..9b97d05cc 100755
--- 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
new file mode 100755
index 000000000..7c583170c
--- /dev/null
+++ b/runtime/llama.cpp/tests/test_download_funasr_model.sh
@@ -0,0 +1,90 @@
+#!/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"
+
+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" ]]
+
+echo "download-funasr-model contract tests passed"