Open-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.
Python asraudiochineseemotion-recognitionfunasrmcp-servermultilingual-asropenai-compatible-apiparaformerpunctuationpytorchreal-time-asrspeaker-diarizationspeech-recognitionspeech-to-textstreaming-asrtranscriptionvllmvoice-activity-detectionwhisper-alternative
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.ymlindex 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.mdindex 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 inpbuild/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.shindex 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=hfelif command -v huggingface-cli >/dev/null 2>&1; then HF=huggingface-clielse echo "need the Hugging Face CLI: pip install -U huggingface_hub"; exit 1; fimkdir -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"+fiif [ "$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"fiecho "done -> $OUT"; ls -1 "$OUT"/*.ggufdiff --git a/runtime/llama.cpp/tests/run_regression.sh b/runtime/llama.cpp/tests/run_regression.shindex 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"; shiftlocal 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 1for 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.shnew file mode 100755index 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"