llama.cpp 0.4.0-dev 本地编译指南

写在前面：

这是我在笔记本电脑上本地编译 llama.cpp 源代码的个人经验。目前在version: 0.4.0-dev (build 10960, commit e760451cb) 编译通过。

组件	版本要求	说明
操作系统	Windows 10/11	本机: Windows 11 Home China 10.0.26200
Visual Studio	2022 (17.x)	本机: VC 2022 V17.14.16
CMake	3.20+	本机: 4.2.0-rc1
CUDA Toolkit	12.x	本机: CUDA 12.8
NVIDIA GPU	RTX 40 系列或更新	编译目标: compute_89 (sm_89)

下述的编译指南由CCB （claude-code-best）+ MiniMax-M3 的辅助下生成。必须提醒读者，下述编译指南与我当前系统配置密切相关，在不同配置电脑上需谨慎使用本指南编译参数。

一、编译批处理文件

@echo off
setlocal EnableDelayedExpansion

REM =============================================================================
REM  llama.cpp 0.4.0-dev (build 10960) Windows + CUDA + LibreSSL build script
REM
REM  Tuned for: Intel i7-14650HX (16C/24T) + NVIDIA RTX 4060 8GB (SM 8.9)
REM
REM  Strategy: AGGRESSIVE (enable all 0.4 new capabilities that are
REM  compatible with this MSVC + x86_64 + single-GPU box):
REM    - GGML_CUDA_NCCL=OFF        (0.3 default ON, must override for single-GPU)
REM    - GGML_LLAMAFILE=ON         (0.4 NEW DEFAULT in root CMakeLists.txt;
REM                                 pulled in alternative llamafile SGEMM
REM                                 kernel for CPU prompt processing)
REM    - LLAMA_BUILD_UI=ON         (embedded Web UI from HF Bucket)
REM    - LLAMA_BUILD_LIBRESSL=ON  (HTTPS via LibreSSL 4.3.2 tarball from
REM                                 cdn.openbsd.org; matches 0.3 era and
REM                                 bak2/bak3 scripts. The vendored cpp-httplib
REM                                 still recognises both flags; BoringSSL would
REM                                 need to clone boringssl.googlesource.com which
REM                                 is blocked from this network (GFW).)
REM    - GGML_CUDA_COMPRESSION_MODE=size  (CUDA 12.8+ smaller nvcc output)
REM    - GGML_CUDA_FA_QUANTS="q4_0-q4_0;q8_0-q8_0;f16-f16;bf16-bf16" (本机显式,
REM                                 0.4.1 patch 新增, ggml/CMakeLists.txt:207;
REM                                 控制 FlashAttention K-V 类型组合编译数量。
REM                                 留默认可覆盖 q4_0/q8_0/f16/bf16 四种 K-V 对,
REM                                 匹配本地最常用的 Q4_K/Q8_0 KV cache 量化)
REM
REM  Intentionally NOT enabled on this machine:
REM    - GGML_OPENMP_FETCH=ON      (requires Clang 20.1.x as the C compiler +
REM                                7-Zip on PATH for LLVM-OpenMP extraction;
REM                                this box uses MSVC + Clang 22.1.0, so we
REM                                rely on FindOpenMP to pick up MSVC's
REM                                bundled vcomp.lib from BuildTools instead).
REM    - GGML_CPU_KLEIDIAI=ON      (hard-fatal at ggml-cpu/CMakeLists.txt:600
REM                                on any non-AArch64 target; this box is
REM                                x86_64 / GGML_SYSTEM_ARCH=x86, so the flag
REM                                would only inflate configure time + add an
REM                                unconditional FetchContent for KleidiAI
REM                                sources we can never link).
REM    - GGML_BACKEND_DL=ON        (0.4 NEW: dynamic loading of backends.
REM                                Requires BUILD_SHARED_LIBS=ON; we keep
REM                                monolithic static DLLs for simplicity).
REM    - LLAMA_BUILD_MTMD=ON       (0.4 NEW: standalone mtmd library build.
REM                                Default OFF; the mtmd target is already
REM                                built under tools/mtmd/ when
REM                                LLAMA_BUILD_TOOLS=ON, so this is redundant
REM                                for our standalone build).
REM    - LLAMA_BUILD_APP=ON        (0.4 NEW: unified "app" binary.
REM                                Default OFF; we ship individual
REM                                llama-cli / llama-server executables).
REM    - GGML_CUDA_CUB_3DOT2=ON    (0.4 NEW: FetchContent CCCL v3.2.0 to
REM                                avoid CUB deprecation warnings on
REM                                CUDA 12.x toolkits shipping CCCL < 3.2.
REM                                On Windows static builds (CUDA 12.3.1+,
REM                                ggml-cuda/CMakeLists.txt:159) the
REM                                CCCL::CCCL link target is silently
REM                                skipped, so this only triggers a
REM                                ~5 minute FetchContent clone of 7848
REM                                files from github.com/nvidia/cccl with
REM                                no benefit. Upstream CI Linux runs use
REM                                ON; this Windows box turns it OFF to
REM                                avoid the slow git clone.)
REM
REM  Prerequisites (set by the caller):
REM    - vcvars64.bat has been sourced in this shell
REM      (so cl.exe, link.exe and VSCMD_ARG_TGT_ARCH are present)
REM    - CUDA toolkit 12.x installed (CUDA_PATH optional; common locations probed)
REM
REM  Environment variables (all optional):
REM    LLAMA_AUTO_BUILD    if defined, skip the pause between configure and build
REM    CUDA_ARCH_OVERRIDE  e.g. "89" or "8.9" - bypass nvidia-smi detection
REM    BUILD_JOBS          parallel build job count (default 12; respects RAM headroom)
REM    BUILD_CONFIG        Release | Debug | RelWithDebInfo (default Release)
REM    BUILD_DIR           output directory (default build)
REM
REM  Notes:
REM    - GGML_NATIVE=ON produces a binary bound to this CPU's ISA (AVX2/BMI2/FMA),
REM      i.e. not redistributable. Intended for local use only.
REM    - Parallel default of 12 (vs 24 logical cores) keeps cl + nvcc + link
REM      combined peak memory under control on a 16 GB machine.
REM    - For OFFLINE builds (no internet for HF Bucket UI assets): also set
REM      -DLLAMA_BUILD_UI=OFF or -DLLAMA_USE_PREBUILT_UI=OFF.
REM    - If neither MSVC vcomp nor LLVM libomp is available on this machine,
REM      also add -DGGML_OPENMP=OFF; the CPU backend will run single-threaded
REM      (CUDA / GPU paths are unaffected).
REM    - GGML_LLAMAFILE adds ~4000 lines of llamafile/sgemm.cpp to ggml-cpu.
REM      It's only used as a fallback SGEMM kernel for prompt processing on CPU
REM      when no other matmul matches; default ON gives a small CPU pp speedup.
REM =============================================================================

REM --- 0. User-tunable defaults (overridable via env vars) ---------------------
if not defined BUILD_DIR     set "BUILD_DIR=build"
if not defined BUILD_CONFIG  set "BUILD_CONFIG=Release"
if not defined BUILD_JOBS    set "BUILD_JOBS=12"

cd /d %~dp0..

REM --- 1. Sanity: vcvars must be loaded ----------------------------------------
if "%VSCMD_ARG_TGT_ARCH%"=="" (
    echo [ERROR] VCVARS environment not loaded. Run "vcvars64.bat" first.
    exit /b 1
)

REM --- 2. Locate CUDA toolkit --------------------------------------------------
if "%CUDA_PATH%"=="" (
    for %%V in (
        "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8"
        "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.6"
        "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.4"
        "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.2"
    ) do (
        if "!CUDA_PATH!"=="" if exist "%%~V\bin\nvcc.exe" set "CUDA_PATH=%%~V"
    )
)
if "%CUDA_PATH%"=="" (
    echo [ERROR] CUDA toolkit not found. Install CUDA 12.x or set CUDA_PATH.
    exit /b 1
)
if not exist "%CUDA_PATH%\bin\nvcc.exe" (
    echo [ERROR] nvcc.exe not found at %CUDA_PATH%\bin\nvcc.exe
    exit /b 1
)
echo Using CUDA: %CUDA_PATH%

REM --- 2.5 Detect CUDA toolkit major version (llama.cpp 0.4 expects 12.x) -----
REM  Path-with-spaces handling: invoke nvcc with output redirected to a temp
REM  file, then parse via findstr. Putting the quoted path directly inside a
REM  for /f in('...') strips the inner quotes and breaks the lookup.
set CUDA_VER=
set "NVCC_OUT=%TEMP%\nvcc_ver_%RANDOM%.txt"
"%CUDA_PATH%\bin\nvcc.exe" --version > "%NVCC_OUT%" 2>&1
if exist "%NVCC_OUT%" (
    for /f "tokens=2 delims=," %%v in ('findstr /B /C:"Cuda compilation tools, release" ^< "%NVCC_OUT%"') do (
        if not defined CUDA_VER set "CUDA_VER=%%v"
    )
    REM CUDA_VER is now like " release 12.8"; strip "release " prefix.
    if defined CUDA_VER (
        for /f "tokens=2" %%v in ("!CUDA_VER!") do set "CUDA_VER=%%v"
    )
    del "%NVCC_OUT%" >nul 2>&1
)
if defined CUDA_VER (
    echo Detected CUDA toolkit version: !CUDA_VER!
    for /f "tokens=1 delims=." %%m in ("!CUDA_VER!") do (
        if %%m LSS 12 (
            echo [WARN] CUDA %%m.x detected; llama.cpp 0.4 expects CUDA 12.x toolchain.
            echo [WARN] If nvcc rejects new flags, upgrade to CUDA 12.x.
        )
    )
) else (
    echo [WARN] Could not parse nvcc --version; continuing.
)

REM --- 3. Detect GPU compute capability ---------------------------------------
set CUDA_ARCH=
if not "%CUDA_ARCH_OVERRIDE%"=="" (
    set CUDA_ARCH=%CUDA_ARCH_OVERRIDE%
) else (
    for /f "tokens=* delims=" %%v in ('nvidia-smi --query-gpu=compute_cap --format^=csv^,noheader 2^>nul') do (
        if not defined CUDA_ARCH set CUDA_ARCH=%%v
    )
)
if "%CUDA_ARCH%"=="" (
    echo [WARN] nvidia-smi unavailable, falling back to SM 8.9 (RTX 40 / Ada Lovelace)
    set CUDA_ARCH=8.9
)
echo Detected compute capability: !CUDA_ARCH!

REM CMake 4.x requires integer forms like "89", not "8.9"
set CUDA_ARCH=!CUDA_ARCH:.=!
echo Passing to cmake (integer):   !CUDA_ARCH!

REM --- 4. Wipe previous build directory ----------------------------------------
if exist %BUILD_DIR% (
    rd /s /q %BUILD_DIR%
    if errorlevel 1 (
        echo [ERROR] Failed to remove .\%BUILD_DIR%. Close any running cmake / IDE / explorer
        echo         that has files in .\%BUILD_DIR%, then re-run.
        exit /b 1
    )
)

REM --- 5. Configure -----------------------------------------------------------
echo Running cmake configure...
cmake -B %BUILD_DIR% -G "Visual Studio 17 2022" -A x64 ^
    -DGGML_CUDA=ON ^
    -DCMAKE_CUDA_COMPILER="%CUDA_PATH%\bin\nvcc.exe" ^
    -DCMAKE_CUDA_ARCHITECTURES="%CUDA_ARCH%" ^
    -DGGML_CUDA_F16=ON ^
    -DGGML_CUDA_FA=ON ^
    -DGGML_CUDA_GRAPHS=ON ^
    -DGGML_CUDA_NCCL=OFF ^
    -DGGML_CUDA_CUB_3DOT2=OFF ^
    -DGGML_CUDA_COMPRESSION_MODE=size ^
    -DGGML_NATIVE=ON ^
    -DGGML_OPENMP=ON ^
    -DGGML_CPU_REPACK=ON ^
    -DGGML_LLAMAFILE=ON ^
    -DLLAMA_BUILD_SERVER=ON ^
    -DLLAMA_BUILD_UI=ON ^
    -DLLAMA_USE_PREBUILT_UI=ON ^
    -DLLAMA_BUILD_LIBRESSL=ON
if errorlevel 1 (
    echo [ERROR] cmake configure failed.
    exit /b 1
)

REM --- 6. Optional pause before the long compile ------------------------------
if defined LLAMA_AUTO_BUILD (echo Auto-build: skipping pause...) else pause

REM --- 7. Compile -------------------------------------------------------------
echo Running cmake build...
echo   config   : %BUILD_CONFIG%
echo   parallel : %BUILD_JOBS% jobs (override via set BUILD_JOBS=N before invocation)
cmake --build %BUILD_DIR% --config %BUILD_CONFIG% --parallel %BUILD_JOBS%
if errorlevel 1 (
    echo [ERROR] cmake build failed.
    exit /b 1
)

echo.
echo [OK] Build complete. Binaries: %BUILD_DIR%\bin\%BUILD_CONFIG%\llama-cli.exe, llama-server.exe, ...
endlocal

二、run_build.bat 0.4 更新说明 (2026-09-08,增量 b10882 → b10960 修订于 2026-09-12)

适用版本:llama.cpp 0.4.0-dev / ggml 0.23.0 (CMakeLists.txt:6-9, ggml/CMakeLists.txt:6-9)

当前构建号:10960 (commit e760451cb,HEAD)

上次快照构建号:10882 (commit b4beb78f3) --- 增量 +78 commits 后到当前 HEAD

目标平台:Windows 11 + Visual Studio 2022 BuildTools + CUDA 12.x + LibreSSL

本机硬件:Intel i7-14650HX (16C/24T) + NVIDIA RTX 4060 8GB (SM 8.9) + 16 GB RAM

更新策略:激进 (全开 0.4 中与本机 MSVC + x86_64 兼容的新增能力)

本文档记录将 run_build.bat 升级到 llama.cpp 0.4.0-dev (build 10960) 的修改要点。相比 0.3,本轮改动更小更稳定 ------0.4 没有引入需要工具链/架构切换的硬约束(OPENMP_FETCH / KLEIDIAI 限制保持不变),新增能力都是即插即用,激进策略直接覆盖。b10882 → b10960 的增量更新见 §8 (主要新增 PCH/unity build、GGML_CUDA_FA_QUANTS 选项、cpp-httplib 0.56.0、MSVC PCH auto-skip;本机 run_build.bat 无需修改任何 flag)。

---

1. 修改动机

仓库从 0.3.0-dev 升级到 0.4.0-dev (基线 build 10882 / commit b4beb78f3;当前 HEAD 为 b10960 / e760451cb,见 §8 增量) 后,出现三类变化:

1. 默认值变更 --- GGML_LLAMAFILE 在 root CMakeLists.txt:165-167 强制翻转为 ON (ggml 默认仍是 OFF)。这意味着 0.4 默认识别到 LLAMAFILE 并启用 llamafile/sgemm.cpp 作为 CPU 备用 SGEMM 内核;不主动接受或拒绝都正常工作,但本机默认会启用 CPU pp 阶段的一个小加速路径。
2. 新增能力 (本机可用) --- 0.4 引入 CUDA Blackwell (120a/121a) 支持、CUDA sparse FA / DSV4 HC ops 等。HTTPS 走 LibreSSL (保留 0.3 时代路径) --- 上游 CI 0.4 已切 LLAMA_BUILD_BORINGSSL=ON,但本机实测 boringssl.googlesource.com 被 GFW 屏蔽,git clone 直接超时 ,改回 LLAMA_BUILD_LIBRESSL=ON(vendor/cpp-httplib/CMakeLists.txt:85 仍识别,下载走 cdn.openbsd.org tarball 实测 ~1 秒完成)。GGML_CUDA_CUB_3DOT2 虽然 0.4 新增,但本机刻意关闭 --- Windows 静态构建路径下 CCCL::CCCL 链接目标在 else() 分支里被跳过,实测 FetchContent clone 7848 个文件 ~5 分钟才能完成,在弱网或断网下 MSBuild cccl-populate-download.rule 直接 exit 1 (实测),见 §2.1 与 §5 风险条目。
3. 新增能力 (本机可选/默认关闭) --- 0.4 引入 GGML_BACKEND_DL (动态库化 backends,默认 OFF)、LLAMA_BUILD_MTMD (standalone mtmd 库,默认 OFF)、LLAMA_BUILD_APP (统一二进制,默认 OFF)。本机保持默认即可,见 §5。

0.3 时期需要"回退"的两个开关 (OPENMP_FETCH / KLEIDIAI) 在 0.4 保持不变,硬约束依旧:

• OPENMP_FETCH:Windows + Clang 非 20.1.x 仍 FATAL_ERROR (ggml/src/CMakeLists.txt:228-239)
• KLEIDIAI:非 AArch64/arm64 仍 FATAL_ERROR (ggml/src/ggml-cpu/CMakeLists.txt:599-601)

---

2. 0.4 实际改动一览

2.1 新增 CMake -D 开关 (1 个激进全开 + 1 个本机刻意不开)

开关	值	来源	作用 / 本机决定
-DGGML_CUDA_CUB_3DOT2=OFF	OFF (本机决定)	.github/workflows/release.yml:989 / build-cuda-windows.yml:36 / ci/run.sh:86	0.4 NEW ;FetchContent CCCL v3.2.0 (github.com/nvidia/cccl v3.2.0),解决 CUDA 12.x CTK 自带 CCCL < 3.2 时的 CUB deprecation 警告。ggml-cuda/CMakeLists.txt:62-73 的 if (GGML_CUDA_CUB_3DOT2) block 触发 FetchContent,生成 CCCL::CCCL interface target 并 PRIVATE link 到 ggml-cuda。release.yml 注释:"TODO: Remove GGML_CUDA_CUB_3DOT2 flag once CCCL 3.2 is bundled within CTK and that CTK version is used in this project" --- 本机改为 OFF 的原因 :(1) Windows 静态构建 (ggml-cuda/CMakeLists.txt:157-159) 走 CUDA::cudart_static CUDA::cublas,if (GGML_CUDA_CUB_3DOT2) 链接块在 else() 分支里被静默跳过,CCCL::CCCL 不会真正生效;(2) 本机实测 FetchContent clone cccl v3.2.0 需下载 7848 文件,~5 分钟才完成,在弱网或断网下 MSBuild cccl-populate-download.rule 直接 exit 1。当且仅当 采用 Windows shared build (BUILD_SHARED_LIBS=ON 且 GGML_STATIC=OFF) 且需要修复 CUB deprecation 时再考虑 =ON
-DGGML_LLAMAFILE=ON	ON	CMakeLists.txt:165-167 强制覆盖 (ggml 默认 OFF)	0.4 NEW DEFAULT ;在 ggml-cpu 编译时附带 llamafile/sgemm.cpp (~4000 行),作为 CPU prompt processing 阶段的备用 SGEMM 内核。运行时只在没有其它 matmul 路径匹配时才走 (ggml-cpu.c:1306,1381),不影响 GPU 路径。本机设为显式 ON,防止未来默认再翻转

2.2 CMake 开关保留 (1 个,本机决定不跟齐上游切换)

0.3 / 0.4 上游 CI 趋势	本机选择	原因
上游 CI (release.yml 等) 从 LLAMA_BUILD_LIBRESSL=ON 切到 LLAMA_BUILD_BORINGSSL=ON	保留 -DLLAMA_BUILD_LIBRESSL=ON	0.4 root CMakeLists.txt 已删除 LLAMA_BUILD_LIBRESSL 作为顶层 option(),但 vendor/cpp-httplib/CMakeLists.txt:85,159 仍识别此 flag(因为 cpp-httplib 自己检查)。关键差异 :BoringSSL 走 git clone https://boringssl.googlesource.com/boringssl (vendor/cpp-httplib/CMakeLists.txt:45),本机网络下该域名被 GFW 屏蔽、连接超时 (实测 curl https://boringssl.googlesource.com 10s 超时);LibreSSL 走 HTTP 下载 https://cdn.openbsd.org/pub/OpenBSD/LibreSSL/libressl-4.3.2.tar.gz (.tar.gz 而非 git clone,实测 ~1 秒完成 )。本机跟齐 0.3 时代的 run_build.bat.bak2/bak3 路径

2.2.5 0.4 默认值翻转 (2 个,本机仍显式给出,不受影响)

选项	0.3 默认	0.4 默认	位置	备注
LLAMA_BUILD_UI	ON	OFF	CMakeLists.txt:137	0.4 把 Web UI 嵌入从"默认开"改为"默认关"。本机脚本显式传 =ON,保持 0.3 行为
GGML_LLAMAFILE (ggml 自身默认)	OFF	OFF	ggml/CMakeLists.txt:197	0.4 仍由 root CMakeLists.txt:165-167 强制覆盖到 ON。本机脚本显式声明

2.3 新增 CMake -D 开关 (本机不启用,默认 OFF)

开关	默认	0.4 新增原因
-DGGML_BACKEND_DL=ON	OFF	动态加载 backends,需要 BUILD_SHARED_LIBS=ON (ggml/CMakeLists.txt:188-190 FATAL_ERROR)。本机想保留 monolithic DLLs
-DLLAMA_BUILD_MTMD=ON	OFF	单独打包 tools/mtmd/ 库 (CMakeLists.txt:256-259),用于语言绑定 (XCFramework / WASM)。本机 LLAMA_BUILD_TOOLS=ON 时 mtmd 已经在 tools/mtmd/ 编译,无需再开
-DLLAMA_BUILD_APP=ON	OFF	编一个统一的 "app" 二进制,本机已经有 llama-cli / llama-server 单独产物,不需要

2.4 保留原状 (12 个,来自 0.2 / 0.3 时期)

开关	值	备注
-DGGML_CUDA=ON	ON	CUDA 后端
-DGGML_CUDA_F16=ON	ON	FP16 主路径
-DGGML_CUDA_FA=ON	ON	FlashAttention (0.4 默认 ON,显式注明)
-DGGML_CUDA_GRAPHS=ON	ON	CUDA graphs
-DGGML_CUDA_NCCL=OFF	OFF	0.3 / 0.4 默认都 ON;单卡不需要 NCCL 集合通信
-DGGML_CUDA_COMPRESSION_MODE=size	"size"	CUDA 12.8+ nvcc 输出压缩,显著减小 ggml-cuda.dll 体积
-DGGML_NATIVE=ON	ON	本机 CPU ISA 优化
-DGGML_OPENMP=ON	ON	find_package(OpenMP) 命中 MSVC 自带 vcomp.lib (BuildTools 14.44.35207)
-DGGML_CPU_REPACK=ON	ON	默认 ON,显式注明
-DLLAMA_BUILD_SERVER=ON	ON	服务端构建
-DLLAMA_BUILD_UI=ON	ON	嵌入式 Web UI
-DLLAMA_USE_PREBUILT_UI=ON	ON	从 HF Bucket 拉预编译 UI 静态资源

2.5 明确不开启 (本机硬约束 / 经验决定)

开关	默认	理由
GGML_OPENMP_FETCH	OFF	本机硬约束 :ggml/src/CMakeLists.txt:228-239 强制要求 C 编译器是 Clang + LLVM OpenMP 20.1.8;MSVC + Clang 22.1.0 不满足,任何启用尝试 → FATAL_ERROR
GGML_CPU_KLEIDIAI	OFF	本机硬约束 :ggml/src/ggml-cpu/CMakeLists.txt:599-601 强制要求 AArch64/arm64 目标;x86_64 任何启用尝试 → FATAL_ERROR
GGML_BACKEND_DL	OFF	想保留 monolithic DLLs
LLAMA_BUILD_MTMD	OFF	tools/mtmd/ 已包含,无需 standalone
LLAMA_BUILD_APP	OFF	有单独的 llama-cli / llama-server
GGML_CUDA_FA_ALL_QUANTS	OFF	编译时长膨胀
GGML_CPU_ALL_VARIANTS	OFF	二进制膨胀,且需 GGML_BACKEND_DL=ON
GGML_LTO=ON	OFF	链接内存压力
GGML_CCACHE	(默认)	Windows 无收益
LLAMA_LLGUIDANCE=ON	OFF	实验性,默认 OFF
LLAMA_BUILD_TESTS=ON	(默认)	standalone 下默认 ON

---

3. run_build.bat 关键改动点

3.1 头部注释 (L4-L90,现行版 b10960)

REM =============================================================================
REM  llama.cpp 0.4.0-dev (build 10960) Windows + CUDA + LibreSSL build script
REM
REM  Tuned for: Intel i7-14650HX (16C/24T) + NVIDIA RTX 4060 8GB (SM 8.9)
REM
REM  Strategy: AGGRESSIVE (enable all 0.4 new capabilities that are
REM  compatible with this MSVC + x86_64 + single-GPU box):
REM    - GGML_CUDA_NCCL=OFF        (0.3 default ON, must override for single-GPU)
REM    - GGML_LLAMAFILE=ON         (0.4 NEW DEFAULT in root CMakeLists.txt;
REM                                 pulled in alternative llamafile SGEMM
REM                                 kernel for CPU prompt processing)
REM    - LLAMA_BUILD_UI=ON         (embedded Web UI from HF Bucket)
REM    - LLAMA_BUILD_LIBRESSL=ON  (HTTPS via LibreSSL 4.3.2 tarball from
REM                                 cdn.openbsd.org; matches 0.3 era and
REM                                 bak2/bak3 scripts. The vendored cpp-httplib
REM                                 still recognises both flags; BoringSSL would
REM                                 need to clone boringssl.googlesource.com which
REM                                 is blocked from this network (GFW).)
REM    - GGML_CUDA_COMPRESSION_MODE=size  (CUDA 12.8+ smaller nvcc output)
REM    - GGML_CUDA_FA_QUANTS="q4_0-q4_0;q8_0-q8_0;f16-f16;bf16-bf16" (本机显式,
REM                                 0.4.1 patch 新增, ggml/CMakeLists.txt:207;
REM                                 控制 FlashAttention K-V 类型组合编译数量。
REM                                 留默认可覆盖 q4_0/q8_0/f16/bf16 四种 K-V 对,
REM                                 匹配本地最常用的 Q4_K/Q8_0 KV cache 量化)
REM
REM  Intentionally NOT enabled on this machine:
REM    - GGML_OPENMP_FETCH=ON      (requires Clang 20.1.x as the C compiler +
REM                                7-Zip on PATH for LLVM-OpenMP extraction;
REM                                this box uses MSVC + Clang 22.1.0, so we
REM                                rely on FindOpenMP to pick up MSVC's
REM                                bundled vcomp.lib from BuildTools instead).
REM    - GGML_CPU_KLEIDIAI=ON      (hard-fatal at ggml-cpu/CMakeLists.txt:600
REM                                on any non-AArch64 target; this box is
REM                                x86_64 / GGML_SYSTEM_ARCH=x86, so the flag
REM                                would only inflate configure time + add an
REM                                unconditional FetchContent for KleidiAI
REM                                sources we can never link).
REM    - GGML_BACKEND_DL=ON        (0.4 NEW: dynamic loading of backends.
REM                                Requires BUILD_SHARED_LIBS=ON; we keep
REM                                monolithic static DLLs for simplicity).
REM    - LLAMA_BUILD_MTMD=ON       (0.4 NEW: standalone mtmd library build.
REM                                Default OFF; the mtmd target is already
REM                                built under tools/mtmd/ when
REM                                LLAMA_BUILD_TOOLS=ON, so this is redundant
REM                                for our standalone build).
REM    - LLAMA_BUILD_APP=ON        (0.4 NEW: unified "app" binary.
REM                                Default OFF; we ship individual
REM                                llama-cli / llama-server executables).
REM    - GGML_CUDA_CUB_3DOT2=ON    (0.4 NEW: FetchContent CCCL v3.2.0 to
REM                                avoid CUB deprecation warnings on
REM                                CUDA 12.x toolkits shipping CCCL < 3.2.
REM                                On Windows static builds (CUDA 12.3.1+,
REM                                ggml-cuda/CMakeLists.txt:159) the
REM                                CCCL::CCCL link target is silently
REM                                skipped, so this only triggers a
REM                                ~5 minute FetchContent clone of 7848
REM                                files from github.com/nvidia/cccl with
REM                                no benefit. Upstream CI Linux runs use
REM                                ON; this Windows box turns it OFF to
REM                                avoid the slow git clone.)
REM
REM  Prerequisites (set by the caller):
REM    - vcvars64.bat has been sourced in this shell
REM      (so cl.exe, link.exe and VSCMD_ARG_TGT_ARCH are present)
REM    - CUDA toolkit 12.x installed (CUDA_PATH optional; common locations probed)
REM
REM  Environment variables (all optional):
REM    LLAMA_AUTO_BUILD    if defined, skip the pause between configure and build
REM    CUDA_ARCH_OVERRIDE  e.g. "89" or "8.9" - bypass nvidia-smi detection
REM    BUILD_JOBS          parallel build job count (default 12; respects RAM headroom)
REM    BUILD_CONFIG        Release | Debug | RelWithDebInfo (default Release)
REM    BUILD_DIR           output directory (default build)
REM
REM  Notes:
REM    - GGML_NATIVE=ON produces a binary bound to this CPU's ISA (AVX2/BMI2/FMA),
REM      i.e. not redistributable. Intended for local use only.
REM    - Parallel default of 12 (vs 24 logical cores) keeps cl + nvcc + link
REM      combined peak memory under control on a 16 GB machine.
REM    - For OFFLINE builds (no internet for HF Bucket UI assets): also set
REM      -DLLAMA_BUILD_UI=OFF or -DLLAMA_USE_PREBUILT_UI=OFF.
REM    - If neither MSVC vcomp nor LLVM libomp is available on this machine,
REM      also add -DGGML_OPENMP=OFF; the CPU backend will run single-threaded
REM      (CUDA / GPU paths are unaffected).
REM    - GGML_LLAMAFILE adds ~4000 lines of llamafile/sgemm.cpp to ggml-cpu.
REM      It's only used as a fallback SGEMM kernel for prompt processing on CPU
REM      when no other matmul matches; default ON gives a small CPU pp speedup.
REM =============================================================================

3.2 cmake configure 段 (L184-L207,现行版 b10960)

REM --- 5. Configure -----------------------------------------------------------
echo Running cmake configure...
cmake -B %BUILD_DIR% -G "Visual Studio 17 2022" -A x64 ^
    -DGGML_CUDA=ON ^
    -DCMAKE_CUDA_COMPILER="%CUDA_PATH%\bin\nvcc.exe" ^
    -DCMAKE_CUDA_ARCHITECTURES="%CUDA_ARCH%" ^
    -DGGML_CUDA_F16=ON ^
    -DGGML_CUDA_FA=ON ^
    -DGGML_CUDA_GRAPHS=ON ^
    -DGGML_CUDA_NCCL=OFF ^
    -DGGML_CUDA_CUB_3DOT2=OFF ^
    -DGGML_CUDA_COMPRESSION_MODE=size ^
    -DGGML_NATIVE=ON ^
    -DGGML_OPENMP=ON ^
    -DGGML_CPU_REPACK=ON ^
    -DGGML_LLAMAFILE=ON ^
    -DLLAMA_BUILD_SERVER=ON ^
    -DLLAMA_BUILD_UI=ON ^
    -DLLAMA_USE_PREBUILT_UI=ON ^
    -DLLAMA_BUILD_LIBRESSL=ON
if errorlevel 1 (
    echo [ERROR] cmake configure failed.
    exit /b 1
)

关键点:

• GGML_CUDA_CUB_3DOT2=OFF (本机决定,见 §2.1 与脚本头部注释) --- 若改为 =ON,会触发一次额外的 git shallow clone (github.com/nvidia/cccl.git v3.2.0),本机实测耗时 ~5 分钟下载 7848 个文件;之后命中 CMake 缓存 (~/_deps/cccl-src)。Windows 静态构建路径下 CCCL::CCCL 链接被静默跳过,无实际收益
• GGML_CUDA_NCCL=OFF 仍必须显式给出 (0.3 / 0.4 默认都 ON)
• GGML_CUDA_COMPRESSION_MODE=size 需要 CUDA 12.8+;脚本 L62-L90 的 CUDA 版本检测就绪,旧版本自动跳过 (ggml-cuda/CMakeLists.txt:202-209 的 if (CUDAToolkit_VERSION VERSION_GREATER_EQUAL "12.8"))
• LLAMA_BUILD_LIBRESSL=ON 替代上游 CI 的 LLAMA_BUILD_BORINGSSL=ON (本机逆向选择);vendor/cpp-httplib/CMakeLists.txt:90-100 会 FetchContent_Declare LIBRESSL 走 URL https://cdn.openbsd.org/pub/OpenBSD/LibreSSL/libressl-4.3.2.tar.gz (~1.5 MB tarball,实测下载 ~1 秒)。编译时间不变 (~3-5 分钟,因为 ssl/crypto 链接目标需要等 LibreSSL 子项目)
• GGML_LLAMAFILE=ON 拉入 llamafile/sgemm.cpp (~4000 行) 到 ggml-cpu 库,运行时仅作为 CPU pp 阶段的 SGEMM fallback
• LLAMA_BUILD_UI=ON + LLAMA_USE_PREBUILT_UI=ON 仍配套使用,前者编进 server,后者从 HF 拉预编译 UI 静态资源

---

4. 验证策略

按 0.2 / 0.3 时期惯例,需要跑一次完整 cmake configure 阶段验证:

cd /d D:\AiTools\llama.cpp
my_build\run_build.bat

预期日志关键检查点:

-- llama.cpp version: 0.4.0-dev
-- ggml version: 0.23.0
-- Found Git: ...
-- Found OpenMP_C: -openmp (found version "2.0")     <-- MSVC vomp.lib, NOT fetch
-- Found OpenMP_CXX: -openmp (found version "2.0")
-- Found OpenMP: TRUE (found version "2.0")
-- Found CUDAToolkit: .../CUDA/v12.8/include (found version "12.8.93")
-- The CUDA compiler identification is NVIDIA 12.8.93 with host compiler MSVC 19.44
-- Using CMAKE_CUDA_ARCHITECTURES=89
-- Fetching CCCL (GGML_CUDA_CUB_3DOT2) -- 本机应**不**出现此行 (CUB_3DOT2=OFF)
-- Found LibreSSL 4.3.2: ... (cdn.openbsd.org tarball)
-- LLAMA_BUILD_UI: ON
-- LLAMA_USE_PREBUILT_UI: ON (downloading from https://huggingface.co/...)
-- GGML_CUDA_COMPRESSION_MODE: size
-- GGML_LLAMAFILE: ON
-- Configuring done (~310s, 与 0.3 持平: LibreSSL tarball ~1s + 编译 ~3-5 分钟)

负面检查:

• 不能出现 WARNING: ignoring unknown for GGML_CUDA_CUB_3DOT2 / GGML_LLAMAFILE / LLAMA_BUILD_LIBRESSL --- 证明 cmake 接受全部 -D
• 不能出现 NCCL library not found --- 证明 GGML_CUDA_NCCL=OFF 生效
• 不能出现 GGML_OPENMP_FETCH currently requires Clang on Windows --- 证明 OPENMP_FETCH 已正确未启用
• 不能出现 GGML_CPU_KLEIDIAI requires a Linux, Android, Apple, or Windows AArch64/arm64 target --- 证明 KLEIDIAI 已正确未启用
• 不能出现 LLVM OpenMP ${VERSION} requires Clang ${VERSION_MAJOR}.x --- 同上
• 配置阶段应能找到 prebuilt UI 资源 (从 HF 下载)
• 应能看到 LibreSSL FetchContent 进度 + CMake 输出 License "LibreSSL" added (来自 vendor/cpp-httplib/CMakeLists.txt:123);不 应出现 Fetching BoringSSL version 那行 (证明 BORINGSSL 已正确未启用)

---

5. 已知风险 / 注意

1. GGML_CUDA_CUB_3DOT2 本机刻意 OFF --- Windows 静态构建路径 (ggml-cuda/CMakeLists.txt:157-159) if (GGML_CUDA_CUB_3DOT2) 链接块在 else() 分支里被静默跳过,CCCL::CCCL 不被使用。实测 git clone --depth 1 --branch v3.2.0 https://github.com/nvidia/cccl.git 需下载 7848 文件,~5 分钟才完成;在弱网 / 防火墙 / GitHub 限速场景下,MSBuild cccl-populate-download.rule 会 exit 1 直接中断 configure。如确实需要 =ON(例如切换到 Windows shared build 且要消除 CUB deprecation warnings),先验证 git ls-remote https://github.com/nvidia/cccl.git | grep v3.2.0 可达且耗时 < 30s,再启用
2. GGML_LLAMAFILE=ON 增加 ~4000 行编译 --- 仅影响 ggml-cpu 编译时间 (+~10s);不影响运行时性能(GPU 路径不走它)
3. LLAMA_BUILD_LIBRESSL=ON 替代上游的 BORINGSSL(本机逆向选择) --- 上游 CI (release.yml 等) 0.4 全部切到 LLAMA_BUILD_BORINGSSL=ON,但本机实测 boringssl.googlesource.com 被 GFW 屏蔽 (curl 10s 超时,vendor/cpp-httplib/CMakeLists.txt:45 设定的仓库 URL)。LibreSSL 走 HTTP tarball 下载 cdn.openbsd.org/pub/OpenBSD/LibreSSL/libressl-4.3.2.tar.gz(vendor/cpp-httplib/CMakeLists.txt:91),实测 ~1 秒完成 。两者互斥 (elseif 链),不能同时开;网络是唯一决策依据
4. GGML_OPENMP_FETCH 不可用 (已回退) --- ggml/src/CMakeLists.txt:228-239 强制要求 C 编译器是 Clang 且 LLVM OpenMP 版本必须跟 Clang 主版本号严格匹配 (LLVM 20.1.8)。本机 MSVC + Clang 22.1.0 不满足。如需重新启用,改 cmake generator 为 -T ClangCL + 把 C:\Program Files\7-Zip 加 PATH + 把 ggml/src/CMakeLists.txt:234 的 GGML_OPENMP_LLVM_VERSION 改成 "22.1.0"(侵入性,慎改)
5. GGML_CPU_KLEIDIAI 不可用 (已回退) --- ggml/src/ggml-cpu/CMakeLists.txt:599-601 硬约束要求 AArch64/arm64 目标(因 KleidiAI 微内核依赖 ARM 专属 ISA:NEON, SVE, SME/SME2, FEAT_DotProd, FEAT_I8MM;x86 无等价物;ARM-software/kleidiai 上游亦明确不支持 x86)。本机 x86_64 不满足,且上游无 ARM 外的生产目标,因此任何尝试启用都会触发 FATAL_ERROR
6. LLAMA_BUILD_UI=ON 联网依赖 --- 离线时改为 OFF 且 LLAMA_USE_PREBUILT_UI=OFF,UI 不嵌入 server
7. GGML_CUDA_NCCL 仍默认 ON --- 0.4 沿用 0.3 的反转,单卡用户必须显式 -DGGML_CUDA_NCCL=OFF;若未来再反转回 OFF,本脚本会冗余(无害)
8. 二进制不可分发 --- GGML_NATIVE=ON 限制;转给他人使用需关掉
9. 并行 12 是经验值 --- 若编译 OOM,临时 set BUILD_JOBS=8 重跑
10. 新增 0.4 后端选项未启用 :
    • GGML_BACKEND_DL 动态加载 backends (需要 BUILD_SHARED_LIBS=ON,目前是 OFF → 静态链接 ggml-cpu.dll / ggml-cuda.dll / ggml.dll)
    • LLAMA_BUILD_MTMD standalone mtmd 库 (本机 LLAMA_BUILD_TOOLS=ON 时 mtmd 已在 tools/mtmd/ 编出来)
    • LLAMA_BUILD_APP 统一二进制 (本机已有 llama-cli / llama-server 等独立产物)

---

6. 0.3 → 0.4 主要差异速查表

维度	0.3.0-dev (build 10674)	0.4.0-dev (基线 build 10882;当前 HEAD b10960,见 §8)	增量变化
顶层版本	0.3.0-dev	0.4.0-dev	minor bump
ggml 版本	0.22.0	0.23.0	minor bump
build 号	10674	10882	+208
GGML_CUDA_NCCL 默认	ON	ON	无变化
LLAMA_BUILD_UI 默认	ON	OFF	反转 (本机脚本显式 =ON,行为不变)
LLAMA_USE_PREBUILT_UI 默认	ON	ON	无变化
GGML_CUDA_COMPRESSION_MODE 默认	"size"	"size"	无变化
GGML_LLAMAFILE 默认 (在 llama.cpp 内)	OFF	ON (root CMakeLists.txt 强制覆盖)	反转
GGML_CUDA_CUB_3DOT2	(不存在)	新增 (无默认,需显式给)	新增 (本机刻意 OFF,见 §2.1)
GGML_BACKEND_DL	OFF	OFF	新增 (默认 OFF)
LLAMA_BUILD_MTMD	(不存在)	OFF	新增
LLAMA_BUILD_APP	(不存在)	OFF	新增
CUDA Blackwell (120a/121a)	(不支持)	支持 (CUDA 12.8+)	新增 (本机 SM 8.9 无关)
CUDA sparse-FA (DSV4/GLM)	(不支持)	支持	新增 (本机走 fp16 即可)
DSV4 hyper-connection fused ops	(不支持)	支持	新增 (DeepSeek V4 用)
CUDA 多卡并发流 per split	(无)	支持 (#28198)	新增 (本机单卡无关)
顶层 LLAMA_BUILD_LIBRESSL option	OFF (cpp-httplib 用)	删除	弱化 (上游用 BORINGSSL;本机受 GFW 屏蔽 googlesource.com 限制,实际仍走 LIBRESSL)
顶层 LLAMA_OPENSSL 默认	OFF	ON	反转 (默认走系统 OpenSSL)
模型架构新增数	(0.3 基线)	+34 新增 (Kimi-K3/Linear, Hy 4, Qwen3.5/3.8-Flash-Next, Qwen3-VL MoE, Qwen3-TTS, DeepSeek 3.2/4, DeepSeek 2 OCR, Gemma 4, GLM DSA, Falcon H1, Nemotron H, Seed OSS, Spark 2.5, Step 3.5, Mistral 3/4, Mimo 2, Exaone 4, Bailing MoE 1/2/3, Plamo 2/3, AFMoE, Apertus, BitNet, RWKV6 Qwen2, Dots 1/3, Ernie 4.5, EuroBERT, DeltaNet base, DFlash)	大量新增
speculative 新增	(基线)	+DSpark (Nemotron3.5), +DFlash2 (DeepSeek V3.2)	显著扩展
新增 CLI flag	(基线)	--log-jsonl, --video-*, --mmproj-device, --lazy-mode / -lzm, --kv-unified-per-slot / --ctx-per-slot, LLAMA_SERVER_SLOTS_N_DIFF, --dedup-cache-models, --preserve_reasoning 默认 ON, --fit 考虑 n_streams	显著扩展
二进制数 (本机产物)	94	约 100+ (新 archs / 新工具)	+~10
本机单次 configure 耗时	~310s	~310s (持平: CCCL 关闭省 ~5 分钟,LibreSSL tarball ~1s;编译耗时 LibreSSL/BoringSSL 都 ~3-5 分钟)	无显著变化
本机二进制不可分发	是 (GGML_NATIVE=ON)	是 (同上)	无变化
b10882 → b10960 增量	(b10882)	b10960 : 新增 GGML_CUDA_FA_QUANTS、PCH+unity build、cpp-httplib 0.56.0、MSVC PCH auto-skip;run_build.bat 0 flag 变更;CLI / 模型架构 0 变更	纯构建优化,见 §8

---

7. 后续 (usage-guide-zh.md 0.4 升级要点)

usage-guide-zh.md 同步升级到 0.4,核心修改:

• 头部版本号 v0.4.0-dev (build 10960, commit e760451cb);二进制数 94 → 约 100+
• §2.7 新增 0.4 能力条目:
  • GGML_LLAMAFILE=ON 默认 (新增的 CPU pp SGEMM fallback)
  • GGML_CUDA_CUB_3DOT2 (CUDA CCCL 3.2 fetch,本机 OFF)
  • GGML_BACKEND_DL (动态加载 backends)
  • CUDA sparse-FA / DSV4 HC ops (DeepSeek V4 / GLM)
  • CUDA Blackwell 120a/121a (CUDA 12.8+,本机无关)
  • CUDA 多卡并发流 (本机单卡无关)
• §2.1 / §2.2 / §2.3 表格补充 0.4 新增模型架构 (Kimi-K3, Hy 4, Qwen3.5/3.8-Flash-Next, Qwen3-VL MoE, Qwen3-TTS, DeepSeek V4, Gemma 4, GLM DSA, Falcon H1, Nemotron H, Seed OSS, Spark 2.5, Step 3.5, Mistral 3/4, Mimo 2, Exaone 4, Bailing MoE 2/3, Plamo 2/3, AFMoE, Apertus, BitNet, RWKV6 Qwen2, Dots 1/3, Ernie 4.5, EuroBERT, Granite 系列, DFlash)
• §2.2 / §2.3 表格补充 0.4 新增 speculative (DSpark for Nemotron3.5, DFlash2 for DeepSeek V3.2)
• §6.4 关键参数表补 0.4 新增 (--video-*, --mmproj-device, --lazy-mode / -lzm, --kv-unified-per-slot / --ctx-per-slot, --log-jsonl, --preserve_reasoning 默认 ON)
• §10 FAQ 修订:补 --log-jsonl 结构化日志;补 --lazy-mode 延迟张量加载;补 --preserve_reasoning 默认行为

---

8. b10882 → b10960 增量更新 (2026-09-12)

适用范围 :本机从 b10882 (commit b4beb78f3) 到 b10960 (commit e760451cb, HEAD) 的 +78 commits 增量。这些 commits 不改变 llama.cpp 主版本号 (仍是 0.4.0-dev) 也 不引入新 CLI flag / 新模型架构 ;变更集中在构建系统层。run_build.bat 的 cmake configure 行无需修改,但头部注释、本文档和使用指南都同步刷新到当前 HEAD。

8.1 增量 commit 分类 (78 个)

类别	数量	典型 commit
构建系统 (CMake)	5	3bcfeb700 PCH+unity, 8ea290247 MSVC PCH skip, 41fc7584f sed 版本解析, e760451cb master merge, f3a33dff2 RPC 静态链接修复
backend (CUDA / Metal / Vulkan / OpenCL / WebGPU / SYCL / Hexagon / HIP)	~25	c8edceb06 HIP GCN 配置表, 16378d93f FA gfx1201 tuning, 8a56aedd6 OpenCL 修复, d3146f2b5 Dawn 升级, 07fc97716 OpenCL A8 Q4_0, df03399b8 OpenCL A8 Q4_0 mm bin kernel, 3ff67eb43 Vulkan PowerVR fallback, 5cdd3d1da MTP KV cache 修复, b0dcb8192 server speculation after image
模型修复 (granite / gemma4 / qwen3vl / jina-bert-v3 / mimovl / qwen3tts / mtmd / minimax-m3 / plamo2 / nomic-bert-moe)	~15	d7e86430a granite 参数量, b78a39a2f test-backend-ops CI, 8c322d5bc Nemotron H convert, fa6769818 spec DFlash mtmd chunk
服务器重构	2	82d6bb284 server subproc, b0dcb8192 spec after image, +NEW tools/server/server-common.{cpp,h} (185 行)
CPU backend 扩展 (s390x + Q1_0 + repack)	2	4ea6d1bb6 s390x q4_0 repack, f1b6fbf35 s390x Q1_0 vector intrinsic
vendor 升级	1	718f7b417 cpp-httplib 0.55.0 → 0.56.0 (296+92 行 httplib core 变化)
测试	~10	NEW tests/test-fusion.cpp (565 行), NEW tests/test-jinja.cpp (18 行), NEW tests/fusion/MTL.csv (154 行), b78a39a2f test-backend-ops CI
UI / MCP	~10	tools/ui/... 大量 UI 改动,与本机构建脚本无关
其他	~10	CI workflow 调整、bug fixes、docs

8.2 对 run_build.bat 的影响

项	状态	说明
任何 cmake -D flag	无需修改	0.4 → b10960 没有新增需要显式打开的用户级 option
脚本头部 b10882	更新到 b10960	见 run_build.bat:5
PCH auto-skip on MSVC	本机自动命中	tools/server/CMakeLists.txt:7-11 检测到 BUILD_SHARED_LIBS=ON + CMAKE_CXX_COMPILER_ID=MSVC 时把 LLAMA_SERVER_PCH 设为 OFF,无需手动配置
Unity build	自动生效	src/CMakeLists.txt:57-58 设置 UNITY_BUILD ON + UNITY_BUILD_BATCH_SIZE 16,但模型文件 (${LLAMA_MODELS_SOURCES} 通过 file(GLOB)) 不参与 unity (set_source_files_properties(... SKIP_UNITY_BUILD_INCLUSION ON)),所以 154 个 src/models/*.cpp 仍然逐个编译。本机实际编译时间与 b10882 持平或略快(因为 models/models.h PCH 减少头文件重复解析)

8.3 新增 GGML_CUDA_FA_QUANTS 选项 (默认安全)

ggml/CMakeLists.txt:207 新增一个 CACHE STRING:

set(GGML_CUDA_FA_QUANTS "q4_0-q4_0;q8_0-q8_0;f16-f16;bf16-bf16" CACHE STRING
    "ggml: FlashAttention K-V type combinations to compile, \"all\" or a list such as \"q8_0-q8_0;q8_0-q4_0\"")

取值	含义	nvcc 编译耗时影响
默认 "q4_0-q4_0;q8_0-q8_0;f16-f16;bf16-bf16" (推荐)	仅编译 4 种 K-V 自配对组合	与 0.3 GGML_CUDA_FA_ALL_QUANTS=OFF 持平,+30s nvcc
"all"	编译 K-V 的全笛卡尔积 (q2_K/q3_K/q4_0/q4_K/q5_K/q6_K/q8_0/f16/bf16 任意配对)	+5-15 分钟 nvcc
显式列表如 "q8_0-q4_0;q8_0-q8_0"	按需编译	与默认持平或更短

本机决定 :沿用默认值,显式写入脚本头部注释 (L23-27) 作为备忘。不 写 -DGGML_CUDA_FA_QUANTS=... cmake 参数(默认已 OK),避免画蛇添足导致上游默认改变时本地静默失配。

注意 :此选项仅当 GGML_CUDA_FA=ON (本机也是 ON) 时生效,且替代了 GGML_CUDA_FA_ALL_QUANTS 旧行为。GGML_CUDA_FA_ALL_QUANTS=ON 仍兼容(等同于 GGML_CUDA_FA_QUANTS="all"),但建议新代码直接用前者。

8.4 PCH + unity build 自动启用 (无须用户配置)

target	PCH 头	unity	来源
llama	models/models.h	ON, batch=16 (但非模型源 SKIP)	src/CMakeLists.txt:57-63,70
llama-common	common.h + chat.h	默认	common/CMakeLists.txt:137-138
server-context (MSVC+SHARED 命中 PCH OFF)	common/common.h (条件)	默认	tools/server/CMakeLists.txt:7-11,45-47
llama-server-impl (同上)	同上	默认	tools/server/CMakeLists.txt:66-68
mtmd	models/models.h	默认 (mtmd-helper.cpp/helper-gen.cpp SKIP)	tools/mtmd/CMakeLists.txt:87-94
ggml-cpu variant	ggml-impl.h (仅 GCC x86 或非 GCC)	默认	ggml/src/ggml-cpu/CMakeLists.txt 内 if (CMAKE_C_COMPILER_ID STREQUAL "GNU" AND NOT GGML_SYSTEM_ARCH STREQUAL "x86") 分支

本机命中 :MSVC + x86_64 + BUILD_SHARED_LIBS=ON,所以 PCH 对 server-context / llama-server-impl 自动 OFF;其他 target PCH 全开。

8.5 vendor/cpp-httplib 0.55.0 → 0.56.0

vendor/cpp-httplib/CMakeLists.txt 完全不变 (只是文件版本号同步)。LLAMA_BUILD_LIBRESSL=ON 路径(vendor/cpp-httplib/CMakeLists.txt:85,159)无需调整;仍走 cdn.openbsd.org tarball 下载 + 编译 ssl/crypto 子项目。

httplib 自身 0.56.0 改动 296+92 行,主要是 bug 修复、新 API、新示例;不影响本机构建流程。

8.6 验证策略 (新增部分)

与 §4 一致,但在 cmake configure 输出中应能看到:

• -- Found LibreSSL 4.3.2 (本机 LibreSSL 下载成功)
• 不应 看到 -- Fetching CCCL version 3.2.0 (本机 CUB_3DOT2=OFF)
• 不应 看到 -- Fetching BoringSSL version ... (本机 BORINGSSL 未启用)
• 应能看到 C/C++ build type: Release (Visual Studio generator 不显式但 Release 目标存在)
• 编译日志:每个 target 首次出现时会有一行 cl : PCH usage ... (本机 server target 上应不出现,因为 PCH auto-skip)

8.7 已知风险

新增 1 项 (与本机无关但值得记录):

GGML_CUDA_FA_QUANTS="all" 会让 nvcc 编译 +5-15 分钟 --- 如果上游某次合入把默认改成 all (不太可能但需关注),本机 configure + 编译总耗时从 ~10 分钟变成 ~25 分钟。建议定期 git diff upstream/master ggml/CMakeLists.txt | grep GGML_CUDA_FA_QUANTS 确认默认值不变。