feat(runtime): publish Windows Vulkan binary (#3398)

* feat(runtime): add Windows Vulkan release asset * fix(ci): install SPIR-V headers for Windows Vulkan * fix(runtime): make Windows Vulkan package standalone
2026-10-12 02:19:18 +00:00 · 2026-07-23 18:49:28 +08:00
parent eff1080856
commit 9b918d74d7
4 changed files with 144 additions and 2 deletions
@@ -100,6 +100,27 @@ jobs:
              -DGGML_FMA=ON
              -DGGML_F16C=ON
              -DGGML_BMI2=ON
+          - os: windows-latest
+            name: windows-x64-vulkan
+            vulkan: true
+            windows_vulkan: true
+            build_target: llama-funasr-sensevoice
+            timeout_minutes: 90
+            cmake_flags: >-
+              -DGGML_NATIVE=OFF
+              -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded
+              -DGGML_VULKAN=ON
+              -DGGML_OPENMP=OFF
+              -DGGML_AVX=OFF
+              -DGGML_AVX2=OFF
+              -DGGML_AVX_VNNI=OFF
+              -DGGML_AVX512=OFF
+              -DGGML_AVX512_VBMI=OFF
+              -DGGML_AVX512_VNNI=OFF
+              -DGGML_AVX512_BF16=OFF
+              -DGGML_FMA=OFF
+              -DGGML_F16C=OFF
+              -DGGML_BMI2=OFF
          - os: windows-latest
            name: windows-x64-cuda
            cuda: true
@@ -143,11 +164,38 @@ jobs:
        if: matrix.cuda
        run: nvcc --version
      - name: Install Vulkan SDK packages
-        if: matrix.vulkan
+        if: matrix.vulkan && runner.os == 'Linux'
        run: |
          sudo apt-get update
          sudo apt-get install -y libvulkan-dev glslc spirv-headers vulkan-tools
          vulkaninfo --summary || true
+      - name: Install Vulkan SDK
+        if: matrix.windows_vulkan
+        uses: humbletim/install-vulkan-sdk@30ba978f977e81b72d091fc8888feb1fb26f9aff
+        with:
+          version: '1.4.309.0'
+          cache: true
+      - name: Show Vulkan shader compiler
+        if: matrix.windows_vulkan
+        run: glslc --version
+      - name: Install SPIR-V Headers CMake package
+        if: matrix.windows_vulkan
+        run: |
+          runner_temp="$(cygpath -u "$RUNNER_TEMP")"
+          headers_src="$runner_temp/SPIRV-Headers"
+          headers_build="$runner_temp/SPIRV-Headers-build"
+          headers_prefix="$runner_temp/SPIRV-Headers-install"
+          git init -q "$headers_src"
+          git -C "$headers_src" remote add origin https://github.com/KhronosGroup/SPIRV-Headers.git
+          git -C "$headers_src" fetch --depth 1 origin 09913f088a1197aba4aefd300a876b2ebbaa3391
+          git -C "$headers_src" checkout --detach FETCH_HEAD
+          cmake -S "$headers_src" -B "$headers_build" \
+            -DSPIRV_HEADERS_ENABLE_INSTALL=ON \
+            -DSPIRV_HEADERS_ENABLE_TESTS=OFF \
+            -DCMAKE_INSTALL_PREFIX="$headers_prefix"
+          cmake --install "$headers_build" --config Release
+          cmake_prefix_path="$(cygpath -m "$headers_prefix")"
+          echo "CMAKE_PREFIX_PATH=$cmake_prefix_path" >> "$GITHUB_ENV"
      - name: Configure and build
        run: |
          # Release binaries must be portable across user machines, not tuned to
@@ -209,4 +257,4 @@ jobs:
          gh release create "$tag" dist/* \
            --repo "${{ github.repository }}" \
            --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. The Linux Vulkan asset is \`linux-x64-vulkan\`; it requires a working Vulkan driver/ICD and enables SenseVoiceSmall graph execution with \`llama-funasr-sensevoice ... --backend vulkan\`. Build from source with \`-DGGML_VULKAN=ON\` to validate distro-specific GPU stacks. The Windows CUDA asset is \`windows-x64-cuda\`; it requires an NVIDIA driver compatible with the CUDA Toolkit version configured by the release workflow, targets CUDA architecture 86, and enables SenseVoiceSmall graph execution with \`llama-funasr-sensevoice ... --backend cuda\`. Build from source for other GPU architectures. No Python ASR runtime or local build is required. Docs: $docs"
+            --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. The Vulkan assets are \`linux-x64-vulkan\` and \`windows-x64-vulkan\`; they require a working Vulkan driver/ICD and enable SenseVoiceSmall graph execution with \`llama-funasr-sensevoice ... --backend vulkan\`. Build from source with \`-DGGML_VULKAN=ON\` to validate platform-specific GPU stacks. The Windows CUDA asset is \`windows-x64-cuda\`; it requires an NVIDIA driver compatible with the CUDA Toolkit version configured by the release workflow, targets CUDA architecture 86, and enables SenseVoiceSmall graph execution with \`llama-funasr-sensevoice ... --backend cuda\`. Build from source for other GPU architectures. No Python ASR runtime or local build is required. Docs: $docs"
@@ -275,6 +275,8 @@ bash download-funasr-model.sh sensevoice ./gguf        # or: paraformer | nano
 hf download FunAudioLLM/SenseVoiceSmall-GGUF sensevoice-small-q8.gguf --local-dir .\gguf
 hf download FunAudioLLM/fsmn-vad-GGUF fsmn-vad.gguf --local-dir .\gguf
 .\llama-funasr-sensevoice.exe -m .\gguf\sensevoice-small-q8.gguf --vad .\gguf\fsmn-vad.gguf -a audio.wav
+# Use the windows-x64-vulkan package with a current AMD, Intel, or NVIDIA Vulkan driver:
+.\llama-funasr-sensevoice.exe -m .\gguf\sensevoice-small-q8.gguf --vad .\gguf\fsmn-vad.gguf -a audio.wav --backend vulkan
 # Use the windows-x64-cuda package on RTX 30-class GPUs:
 .\llama-funasr-sensevoice.exe -m .\gguf\sensevoice-small-q8.gguf --vad .\gguf\fsmn-vad.gguf -a audio.wav --backend cuda
 ```
@@ -286,6 +288,10 @@ working Vulkan driver/ICD:
 ./llama-funasr-sensevoice -m ./gguf/sensevoice-small-q8.gguf --vad ./gguf/fsmn-vad.gguf -a audio.wav --backend vulkan
 ```

+The Windows Vulkan ZIP uses the system Vulkan loader supplied by the GPU driver;
+installing the Vulkan SDK is only necessary when building from source. Both
+Vulkan packages currently accelerate SenseVoiceSmall.
+
 The current Windows CUDA package targets CUDA architecture 86. RTX 50 / Blackwell
 GPUs report compute capability 12.0 (`sm_120`) and should use the CPU package or
 build from source with `-DCMAKE_CUDA_ARCHITECTURES=120` until a dedicated CUDA
@@ -126,6 +126,48 @@ clear message if `--backend vulkan` is requested. Vulkan performance and device
 availability depend on the installed GPU driver/ICD rather than on CUDA compute
 capability.

+### Optional Windows Vulkan backend for SenseVoiceSmall
+
+Tagged releases publish `funasr-llamacpp-windows-x64-vulkan.zip` for the same
+SenseVoiceSmall Vulkan graph execution on Windows. The prebuilt package does not
+require the Vulkan SDK. It does require a current AMD, Intel, or NVIDIA graphics
+driver that provides a working Vulkan loader and device:
+
+```powershell
+# From the extracted windows-x64-vulkan package:
+vulkaninfo --summary  # Optional driver check when vulkaninfo is installed.
+.\llama-funasr-sensevoice.exe `
+  -m sensevoice-small-q8.gguf --vad fsmn-vad.gguf -a sample.wav --backend vulkan
+```
+
+If the command reports that no Vulkan device is available, update the vendor GPU
+driver first. The package intentionally relies on the system `vulkan-1.dll`
+installed by that driver instead of shipping an SDK copy.
+
+To build on Windows, install the
+[LunarG Vulkan SDK](https://vulkan.lunarg.com/sdk/home#windows) with `glslc`,
+open a Developer PowerShell where `VULKAN_SDK` is set, and install the
+`SPIRV-Headers` CMake package expected by the pinned llama.cpp revision:
+
+```powershell
+glslc --version
+git clone https://github.com/KhronosGroup/SPIRV-Headers.git
+git -C SPIRV-Headers checkout 09913f088a1197aba4aefd300a876b2ebbaa3391
+cmake -S SPIRV-Headers -B SPIRV-Headers-build `
+  -DSPIRV_HEADERS_ENABLE_INSTALL=ON -DSPIRV_HEADERS_ENABLE_TESTS=OFF `
+  -DCMAKE_INSTALL_PREFIX="$PWD/SPIRV-Headers-install"
+cmake --install SPIRV-Headers-build --config Release
+$env:CMAKE_PREFIX_PATH = "$PWD/SPIRV-Headers-install"
+
+cmake -B build-vulkan -A x64 -DCMAKE_BUILD_TYPE=Release -DGGML_VULKAN=ON
+cmake --build build-vulkan --config Release --target llama-funasr-sensevoice
+.\build-vulkan\bin\Release\llama-funasr-sensevoice.exe `
+  -m sensevoice-small-f16.gguf -a sample.wav --backend vulkan
+```
+
+`--backend cpu` remains the default. The Windows Vulkan package currently
+accelerates SenseVoiceSmall only, matching the Linux Vulkan package.
+
 ## Build (shared)
 ```bash
 git clone https://github.com/ggml-org/llama.cpp && cd llama.cpp
@@ -25,6 +25,21 @@ def test_linux_vulkan_release_asset_is_in_matrix():
    assert "timeout_minutes: 90" in workflow


+def test_windows_vulkan_release_asset_is_in_matrix():
+    workflow = WORKFLOW.read_text(encoding="utf-8")
+    entry = workflow.split("name: windows-x64-vulkan", maxsplit=1)[1].split(
+        "          - os:", maxsplit=1
+    )[0]
+
+    assert "vulkan: true" in entry
+    assert "windows_vulkan: true" in entry
+    assert "build_target: llama-funasr-sensevoice" in entry
+    assert "timeout_minutes: 90" in entry
+    assert "-DGGML_VULKAN=ON" in entry
+    assert "-DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded" in entry
+    assert "-DGGML_OPENMP=OFF" in entry
+
+
 def test_windows_cuda_build_uses_cuda_toolkit_and_flags():
    workflow = WORKFLOW.read_text(encoding="utf-8")

@@ -48,6 +63,24 @@ def test_linux_vulkan_build_uses_vulkan_sdk_and_flags():
    assert "-DGGML_VULKAN=ON" in workflow


+def test_windows_vulkan_build_uses_pinned_full_sdk():
+    workflow = WORKFLOW.read_text(encoding="utf-8")
+
+    assert "if: matrix.vulkan && runner.os == 'Linux'" in workflow
+    assert (
+        "humbletim/install-vulkan-sdk@30ba978f977e81b72d091fc8888feb1fb26f9aff"
+        in workflow
+    )
+    assert "if: matrix.windows_vulkan" in workflow
+    assert "version: '1.4.309.0'" in workflow
+    assert "glslc --version" in workflow
+    assert "KhronosGroup/SPIRV-Headers.git" in workflow
+    assert "09913f088a1197aba4aefd300a876b2ebbaa3391" in workflow
+    assert "-DSPIRV_HEADERS_ENABLE_INSTALL=ON" in workflow
+    assert "-DSPIRV_HEADERS_ENABLE_TESTS=OFF" in workflow
+    assert "CMAKE_PREFIX_PATH=" in workflow
+
+
 def test_release_notes_explain_cpu_and_cuda_windows_assets():
    readme = (ROOT / "runtime" / "llama.cpp" / "README.md").read_text(encoding="utf-8")

@@ -70,12 +103,25 @@ def test_release_notes_explain_vulkan_linux_asset():
    assert "GGML_VULKAN=ON" in readme


+def test_release_notes_explain_vulkan_windows_asset():
+    readme = (ROOT / "runtime" / "llama.cpp" / "README.md").read_text(encoding="utf-8")
+    root_readme = (ROOT / "README.md").read_text(encoding="utf-8")
+
+    assert "windows-x64-vulkan" in readme
+    assert "Windows Vulkan" in readme
+    assert "Vulkan SDK" in readme
+    assert "SPIRV-Headers" in readme
+    assert "--backend vulkan" in readme
+    assert "windows-x64-vulkan" in root_readme
+
+

 def test_github_release_notes_mention_vulkan_asset():
    workflow = WORKFLOW.read_text(encoding="utf-8")
    release_notes = workflow.split('--notes "', maxsplit=1)[1]

    assert "linux-x64-vulkan" in release_notes
+    assert "windows-x64-vulkan" in release_notes
    assert "--backend vulkan" in release_notes
    assert "GGML_VULKAN=ON" in release_notes