llama.cpp 学习笔记

Appearance

学习日志 ​

进度总览 ​

模块状态笔记
01 项目概览与构建系统⬜ 未开始
02 GGML 张量库基础⬜ 未开始
03 GGML 后端与硬件抽象⬜ 未开始
04 模型加载与 GGUF 格式⬜ 未开始
05 分词与词表⬜ 未开始
06 Transformer 推理图⬜ 未开始
07 KV Cache 与批处理⬜ 未开始
08 采样、量化与部署⬜ 未开始

2026-09-09 ​

上游同步：693 commits, GGML 0.23.0, llama.cpp 0.4.0 ​

将 vendor/llama.cpp 子模块从 e9fa0781f (b9840) 更新至 9113cc188 (b11065)（上游 master 最新提交）。本窗口跨度约六周、693 个提交，是历次同步中最大的一次：GGML 跨六个小版本 0.17.0 → 0.23.0，llama.cpp 自身引入语义化版本并到 0.4.0。

关键变更：

版本与构建

  • llama.cpp 语义化版本（680a9ae63）— LLAMA_VERSION_MAJOR/MINOR/PATCH，本窗口内 0.2.0 → 0.3.0 → 0.4.0；新增公共 API llama_version()
  • 版本宏改为生成头（86b351fd6、d230ddd76）— ggml-version.h.in / llama-version.h.in 经 configure_file 生成，取代 compile definitions，commit 变化不再全量重编译
  • GGML 0.18.0/0.18.1 → 0.19.0 → 0.20.0-0.20.2 → 0.21.0 → 0.22.0 → 0.23.0，经八次 sync: ggml 子树合并
  • RPC 协议 4.0.3 → 6.0.0（tensor_memset → 5.0.0 f5b9bd39b；event/async backend API → 6.0.0 d0132a680）；Apple RDMA transport（b114b4739）
  • common/json.h 抽象层（d9f918d2d）— pimpl 封装 nlohmann/json，业务代码不再直接 include 第三方头
  • cpp-httplib 0.51.0 → 0.54.1（移入 vendor/cpp-httplib/）；BoringSSL → 0.20260903.0

GGML 核心：算子枚举不变，语义大改

  • GGML_OP_COUNT 维持 101、GGML_TYPE_COUNT 维持 43——无新算子枚举、无新张量类型、ggml-quants.c 零改动；变化全在 API 语义层
  • ggml_prec 规范重写（5a6caa05f）— 从 F32/DEFAULT 二值扩为数值等级（UNDEFINED/F32=10/BF16=15/F16=20/Q8=30/Q4=40）；新增 ggml_prec_set_acc()（MUL_MAT/MUL_MAT_ID/FLASH_ATTN_EXT 累加精度）与 ggml_prec_set_src()（src[1] 降精度）；旧 setter 标记 deprecated
  • ggml_clamp 拆分（6036c635e）— 默认非原地，原地版改名 ggml_clamp_inplace
  • ggml_rope_set_offset(a, n_offs)（fe8156f78）— 前 n_offs 维不旋转；多后端支持
  • ggml_ssm_scan 增第 9 参 K（1692f9e50）— 请求 K−1 份循环态回滚快照（Mamba/Kimi K3 推测解码回滚的基础）
  • ggml_swiglu_clamp（0190529ec）— GLU 子类型 GGML_GLU_OP_SWIGLU_CLAMP，各后端实现
  • 稀疏 Flash Attention（8e93a9773）— 经 ggml_flash_attn_ext_set_n_kv_max() 启用（非新算子）：mask 有限项即稀疏 K/V 集合，CUDA 压缩 mask 为索引表，Metal 跟进（7bb0fc18f）；服务 DSV4/GLM
  • ggml_build_forward_order()（c8e03ce81）— 只插节点不置 compute 标志（修 mtmd 音频 GEN_WAV 的 stale input assert）

模型加载（破坏性 API + 懒加载）

  • LLAMA_LOAD_MODE_AUTO = -1 新增且为默认（153d324bc）— 按设备 mmap_support 能力自动选择，iGPU 上避开 mmap；--mmap/--mlock/--direct-io 成为 deprecated 别名
  • 懒加载 enum llama_lazy_mode（fac889fb3 → bebc9350e 重命名 --lazy-mode/-lzm，默认 auto）— 架构以 TENSOR_READ_LAZY 标记张量（gemma4 per_layer_tok_embd、qwen4exp PLE 嵌入表），loader 记录文件字节区间，mmap 后 MADV_RANDOM/不预取/不 mlock，推理图只做 ggml_get_rows 靠缺页逐行读入；AUTO 档仅对 >4 GiB 标记张量生效
  • llama_model_params::load_mtp（82dbc4f01）— MTP/nextn 张量默认不加载
  • LLAMA_SESSION_VERSION 9 → 10、LLAMA_STATE_SEQ_VERSION 2 → 3（多输出采样状态 + recurrent 回滚）
  • hparams 逐层化（c61b98b87、9a4843cf2）— n_ff_exp/n_expert_used 变 per-layer 数组（Nemotron-3-Puzzle 有 5 种 expert 宽度/7 种 top-k），新增 n_expert_used_max()；n_layer_nextn 加载上收（9d817213a）；LLAMA_MAX_EXPERTS 512 → 1024（Kimi K3）
  • 非 mmap 加载按大张量优先排序抑制 RAM 峰值；量化侧 unmap_weight() + max_buf_size（默认 8 GiB）
  • convert --fuse-qkv（465e49b9c）— 逐层 Q/K/V 拼成 attn_qkv（14 架构接线），运行时由新 build_qkv 消费；conversion/ 包 83 → 92 模块；gguf-py 读取加固（计数上限 2^30 等）

新模型架构（+12，共 150）

  • Qwen3.8-Flash-Next（qwen4exp：linear/gdn + MoE + 超连接 + PLE 逐层嵌入——lazy 加载旗舰）
  • Kimi K3（KDA/delta-net 混合 MoE；循环态回滚）
  • Tencent Hy 4（hy_v4 preview）、Spark2.5、BailingMoE-3（字节 Seed）、dots3-note（红书，MLA+SWA）
  • MiniMax-Text-01/M1（minimax-01，linear attention 混合；图简化 deae5ee13）
  • Granite-Switch（router KV 层选 token adapter）、GraniteSWA/MoeSWA
  • MuseGlimmer ViT（mmproj 视觉编码器）
  • Qwen3-TTS-0.6B / PocketTTS（走 mtmd 音频生成，非 vocab 架构）
  • 复用既有架构：Nemotron-3-Puzzle-75B（nemotron-h + per-layer MoE）、Nemotron3.5 DSpark、GLM-4.5-Air MTP、DeepSeek V4 视觉输入、Nanbeige4.2-3B

推理图与 KV Cache

  • MSA indexer 移出基类（67d5978bb）— get_k_idx/cpy_k_idx/msa_strict_slots 从 llama_kv_cache 移除；新组合类 llama_kv_cache_msa 持有 K/V + indexer 两个 cache 实例，图侧 llm_graph_input_attn_kv_msa
  • KV cell 记录 token id（925e11799）— llama_kv_cell_ext 增 tok 字段；seq_pos 改 std::set<pair<pos,cell>>；新增 get_prev_tokens()（n-gram 嵌入用）；cell_ext 纳入状态保存
  • 新 cache 类型 — llama_kv_cache_dsa_iswa（DSA+SWA 组合，dots3note）、llama_memory_hybrid_idx（hybrid + 第三条 QSA indexer 镜像 cache，qwen4exp）；dsv4 cache（现 ~2250 行）支持稀疏 FA 与 DFlash2
  • 状态恢复提速（2d8d612e4）— 非连续 cell 按连续段批量拷贝（原 140 万次微拷贝/25-63s）
  • build_attn_mha 增 n_kv_max 形参驱动稀疏 FA；新输入类 attn_k_iswa/attn_kv_msa/attn_k_dsa_iswa；llm_graph_params 携带采样器与 n_outputs 参与图复用；llm_graph_result 输出从 map 改 vector；build_qkv 新积木；graph_max_nodes 按架构特化（Kimi K3 ×160/tokens）并计入采样器节点
  • 循环态回滚（9dcf84e5a）— llm_graph_input_rs 增 restore/snapshot 索引张量；llama_memory_recurrent 状态加宽 (1+n_rs_seq) 组；Kimi K3 conv1d 写多份快照

采样：多输出后端采样（本窗口最大特性）

  • dd1ea5243 (#25532) — 采样器链可逐序列挂到 context（llama_context_params::samplers / llama_set_sampler()），在解码图内 GPU 上执行，一次 decode 每序列多输出（n_outputs_max_per_seq）；llama_get_sampled_token_ith() 等 _ith getter 按行读取；状态在 accept 时推进，被拒推测不消耗 RNG（连续前缀契约）；llama_sampler_sample 先查后端产出、无则回落 CPU 链；llama_sampler_i 新增 backend_* 钩子与 copy_state
  • 历史类采样器签名变化：common_sampler_init 去 n_ctx；penalty_last_n=-1 → 解析为 1024；init_penalties 增打头 n_vocab；init_dry 去 context_size
  • suppress_tokens 通用化（afeebe103）— 从 gemma4 图级 hack 改为 vocab 数据 + llama_vocab_get_suppress_tokens() + logit-bias 并入

推测解码

  • DFlash2（b10f9ca58）— 局部卷积 + candidate selector，噪声块扩散 n_max+1 位，后端采样；spec 类型从 draft GGUF 元数据自动检测（f65e568fd）
  • DFlash encoder 融合进 KV 注入图（662a0b012）— 不再单独 encode + 设备往返
  • DSpark 扩展至 LFM2 / Nemotron3.5 / bailingmoe3；DFlash/DSpark/MTP 接入多输出采样（0d0bfcd4f）
  • 合成接受选项（benchmark-only，2bb9bddaf）；单设备 drafter 用 meta backend 包装（415e909d8）

分词 / 多模态 / 语法

  • 预分词器 57 → 59：hy_v4（复用 DeepSeek3 正则）、spark2_5；vocab 类型枚举不变；GGUF scores 接受 INT32
  • mtmd_tokenize_from_parts()（733905474）— 分件（文本/位图）分词，不再要求媒体标记；位图时间维合并改 opt-in（mtmd_bitmap_set_mergeable）
  • TTS 音频生成子系统 — mtmd_gen_* API + clip_encode()（Qwen3-TTS / PocketTTS 图）；helper 拆出 mtmd-helper-gen.cpp；llama-tts 有破坏性变更
  • Pillow 级精确缩放（56db501e7）— resize 算法声明与 PIL 逐字节一致（新增 LANCZOS），overview/refined 分开配置；预处理器 const 化
  • unicode ~ 修复（afd439df1）— ~ 并入折叠符号类，修 DeepSeek V4 的 ~ 分词发散/KV 复用失效
  • grammar/json-schema — 不支持的 regex 降级为「接受任意字符串 + 告警」（dc64a1620）；空对象 schema 生成合法 GBNF（c5a5535e6）；重复上限超阈值降级为无界（9e0e22059）
  • chat parser 拆分（895c045fd）— 14 个专用 parser 从 common/chat.cpp（3915 → 1513 行）移入 common/parsers/

CLI / Server

  • --log-jsonl（7620399f5）结构化日志；build info 输出流可配置（c390d0abb）
  • server 队列重构（947fd9bb2）— worker 线程 + yield_to_queue，休眠期可服务 /metrics；server 测试改 pytest-xdist
  • 多模型 LRU（dff15d4ac 等）— 忙模型不逐出、懒加载；修同模型多请求 LRU 挂起（160bd031b）；checkpoint min-step 逐出仅在列表满时应用（5d806aa25）
  • MCP 工具隔离 — docker / ssh / podman rootless；read_media 工具
  • preserve_reasoning 默认开启（e750b887a）；UI 资产 CMake 内嵌（c457e3bf7）、对话从数据库导出（1863ac033）
  • --n-cpu-ffn/--n-cpu-moe 依靠新的 per-tensor buffer type override（c5fc7e348、7620399f5 窗口内相关）

后端（概览）

  • CUDA — 稀疏 FA、branchless Q4_K/Q5_K unpack + DGX Spark L2 prefetch（73ab7599b）、静态 cuBLAS workspace、gfx90c、删 GGML_CUDA_PEER_MAX_BATCH_SIZE、f16 FA divergent barrier 修复、SM87 MMVQ 交叉点调优
  • Metal — 单体 ggml-metal.metal 拆为 kernels/ 约 23 个 per-op 源文件、8 库并行编译（b615f5b4b）；M2 Max/M3/M3 Max fa-vec 调优；Mamba-2 chunked SSD MMA；稀疏 FA
  • Vulkan — UNARY(GELU/SILU/…)+MUL 融合（64e9bceb2）、TQ1_0、DSV4_HC 融合算子、rms_norm 融合、type-aligned GET_ROWS
  • SYCL — 批量 L2_NORM、rms_norm+mul+add / add+add 融合、MEMTRACE、oneMKL FA 全局变量化
  • OpenCL — lm_head 量化 GEMV/中批量 GEMM（推测解码）、conv2d 非连续输入、Adreno xmem SDPA、elementwise/data-movement 扩展
  • CPU — iqp.cpp（AVX2 i-quant 大批量）、ggml-feats.h 运行时特性检测、SME2 GEMV、KleidiAI 构建重构
  • Hexagon — RELU/LEAKY_RELU、F16 unary、hvx-quant / set-rows / allreduce、列入 ops.md
  • WebGPU — 重叠 src0/src1 mulmat（minimax-01）、binding alias 修复
  • 调度器 — split inputs 动态扩容（修 >30 输入的宽 MoE 崩溃 dbadb68ee）、输入数不再强制新 split（992cb503c）、split 跨后端 buffer 复用竞态修复（849798132）、graph_optimize 增 add_alloc_dep 回调

依赖

  • cpp-httplib 0.51.0 → 0.54.1（迁 vendor/）、BoringSSL 0.20260903.0

2026-07-29 ​

上游同步：332 commits, GGML 0.17.0 ​

将 vendor/llama.cpp 子模块从 25a1d63f4 (b9824) 更新至 e9fa0781f (b9840)（上游 master 最新提交）。本窗口跨度约一个月、改动量大，GGML 从 0.15.3 跨版本升至 0.17.0，并触及算子枚举、张量类型、公共 API 与多个新架构。

关键变更：

GGML 版本：0.15.3 → 0.17.0

经三次 sync: ggml 子树合并（Jul 10 #25517、Jul 10 0badc06ab、Jul 17 7d56da7e5，后者携带 ggml : bump version to 0.17.0）。本窗口新增 4 个算子枚举、1 个新张量类型 Q2_0、4 个新模型架构，并有一次破坏性公共 API 变更。

  • 新算子枚举（+4，GGML_OP_COUNT 97 → 101）
    • GGML_OP_LIGHTNING_INDEXER — DeepSeek V3.2/V4 的「lightning indexer」稀疏注意力算子，取 f16 mask（CUDA 实现 3b5321936）
    • GGML_OP_DSV4_HC_PRE / GGML_OP_DSV4_HC_COMB / GGML_OP_DSV4_HC_POST — DeepSeek V4 的三个**融合超连接（fused hyper-connection）**算子（0dc74e332），对应公开构造函数 ggml_dsv4_hc_pre/comb/post()
  • RPC 协议版本 4.0.1 → 4.0.3（为上述新算子各 +1），rpc-server 二进制需匹配
  • 新张量类型 GGML_TYPE_Q2_0 (=42) — block_q2_0 { ggml_half d; uint8_t qs[QK2_0/4] }，QK2_0=64，共 18 字节（2 bit/元素）；GGML_TYPE_COUNT 42 → 43，LLAMA_FTYPE_MOSTLY_Q2_0 = 41
  • 新连续性辅助函数 — ggml_is_contiguous_to_{1,2,3}() 检查「内层维度」连续性（新 GGML_API，a7312ae94）
  • GGML_FILE_VERSION / GGML_QNT_VERSION 维持 2 — Q2_0 插入既有类型 ID 空间，未改变既有类型的盘上布局，故 GGUF 文件版本与量化版本均未 bump

破坏性公共 API 变更（重点）

  • load_mode 重构（e6dd0e29a，#20834）— struct llama_model_params 中的三个布尔 use_mmap / use_mlock / use_direct_io 被移除，合并为单一 enum llama_load_mode load_mode（取值 NONE / MMAP / MLOCK / MMAP_MLOCK / DIRECT_IO），并新增 llama_load_mode_name() / llama_load_mode_from_str()。任何 params.use_mmap = true; 形式的旧代码均已失效
  • 新增 llama_model_ftype() / llama_ftype_name() — 以类型安全方式读取模型的量化 ftype（fdb1db877）

新模型架构（+4，各自新增 src/models/*.cpp）

  • Laguna（LLM_ARCH_LAGUNA / laguna）— Laguna XS.2 / M.1 / S-2.1（1f66c3ce1、HEAD e9fa0781f），带 Jinja 模板
  • Hy3（LLM_ARCH_HY_V3 / hy_v3）— 含 MTP 推测解码（2969d6d15）
  • MiniMax-M3（LLM_ARCH_MINIMAX_M3 / minimax-m3）— MSA（MiniMax Sparse Attention）（b1d4c6552），是本窗口 KV cache k_idx indexer 改动的驱动来源
  • Nanbeige（LLM_ARCH_NANBEIGE / nanbeige）— Nanbeige4.2（b77d64675）

DeepSeek V4 / GLM 5.2（扩展现有架构，非新架构）

  • DeepSeek V4（LLM_ARCH_DEEPSEEK4）消费上述 LIGHTNING_INDEXER + DSV4_HC_* 算子；图层面把所有 KQ mask 改为 f16（2ed3c1abb），并修复量化 KV cache 路径（024c46ae4）
  • GLM 5.2 Indexer（88bfee142，#25407）— 扩展现有 GLM 架构，复用 lightning indexer
  • LLM_ARCH_EAGLE3 不变；eagle3-v3（f87067841）仅新增超参 norm_before_fc，不新增架构

推理图

  • 融合算子链重构（90e0f5cfc，#24646）— 新增 struct llm_graph_fused_node（llama-graph.h:788）与 add_fused_node() / get_fused_nodes()；融合算子的构造从 llama-context.cpp（-131 行）移入 llama-graph.{cpp,h}
  • DeepSeek V4 / MSA 的 indexer 通过图内 cpy_k_idx 节点接入 KV cache

KV Cache（src/llama-kv-cache.cpp +323 行）

  • MSA indexer cache — 在 K/V 之外新增平行的 k_idx 缓存：get_k_idx() / cpy_k_idx()，以及 llama_kv_cache_context 上的同名包装；新增标志 msa_strict_slots（存在 k_idx 缓存且流布局支持 MSA 时置位）
  • recurrent 模型 n_keep_tail（230ea9d21，#25278）— split_equal 拆批时为循环 / 混合记忆类型保留尾部 token
  • KV cache 现已是「家族」：基类 llama_kv_cache + 专用 kv-cache-dsv4 / kv-cache-dsa / kv-cache-iswa，统一经 llama_memory 暴露

  • 注意：不存在 src/llama-kv-cache-unified.cpp——该前缀早在 #15467 即被去除，统一 cache 全在 src/llama-kv-cache.cpp/.h

推测解码

  • DSpark（DeepSpec, 2026，84075273c，#25173）— 在已合并的 DFlash draft 基础上新增低秩 Markov head（markov_w1/w2）；block 为 anchor-first（位置 0 即预测首个 draft），decoder 在图内施加「以前一 token 为条件」的半自回归 logit bias，逐块串联。复用 DFlash 的 verify/accept 路径，greedy 保持无损；无新公共 API。新增枚举 COMMON_SPECULATIVE_TYPE_DRAFT_DSPARK
  • DFlash draft 架构（d1b34251b，COMMON_SPECULATIVE_TYPE_DRAFT_DFLASH）落地
  • eagle3-v3（gpt-oss，f87067841）— 复用 EAGLE3，新增 norm_before_fc
  • DFlash / eagle3 的 HF sidecar 自动下载（635cdd5fc）、draft sidecar 解析（ddfc2288e）

  • 纠正：common/trie.{cpp,h}（910196f6b）是为 reasoning-budget sampler 的多 end-sequence 强制新增，不是推测解码基础设施

分词 / Jinja / 语法

  • minimax-m3 专用 chat parser（6ba5ef247）；cohere2-moe parser 强化（文本响应强制 JSON schema，8f5ab832c）
  • reasoning-budget sampler — 支持多个 end-sequence；common_params 新增 reasoning_budget_tokens / _start / _end(vector) / _forced / _message / reasoning_control 等字段（910196f6b）
  • Jinja --dump-prog（AST 导出）、min/max 对齐 Jinja2
  • UGM tokenizer 修复 — precompiled_charsmap 处理的越界读（4a7ee3126，#18750）
  • tokenize 工具移除 --stdin 互斥检查（aff6eb6e7）

采样 / 量化

  • Q2_0 量化 kernel — CPU 通用 + ARM（arch/arm/quants.c +74）+ x86；Vulkan 端经 sync: ggml 落地（788e07dc9）
  • NVFP4 dot-product kernel — x86 AVX2 UE4M3 LUT（6dbc1174b）与 ARM UE4M3 LUT（20a04b220）
  • ggml-et 新实验性 CPU 后端（082b326fc）— 「uberkernel」式 CPU 后端，把算子融合成 uber-kernel；实现 MUL_MAT / ROPE / RMS_NORM / GLU / SOFT_MAX / GET_ROWS 等；默认 OFF（option(GGML_ET ... OFF)），仅作实验

CLI / Server

  • llama-cli 改为 HTTP 客户端（c264f65ff，#24948）— 不再直接链接 libllama，而是作为客户端连接到运行中的 server（支持 router 模式），是一次概念性转变
  • server MCP stdio 传输（20455a4ad，#26062）、--cors-* 选项（6e52db5b7）、SSE replay buffer（断线重连）
  • common/subproc.{cpp,h} 包装（d2a818231）— 从 server pipe 处理中抽出，供 MCP stdio 使用（android/ios 禁用）

后端（概览）

  • CUDA — LIGHTNING_INDEXER kernel、Q2_0、CUDA graphs 放宽到 volta+turing（3f08ef2c5）、Virtual Devices（79bba02a6）、NVFP4 W4A4 激活量化、MoE gate/up 量化去重、sqrt_softplus in topk-moe（dsv4）
  • Vulkan — Q2_0（788e07dc9）、e2m1/mxfp4 native 转换、iq4_nl 回归 FA（816164100）、per-instance mutex 队列重构
  • Metal — FWHT kernel（f95de9776）、snake 激活融合（b3c9d1b84）、f16 leaky relu
  • OpenCL — ABS op、cl_program 编译缓存（ed7adbfef）、大量 Adreno（A7x / 850 / 810）优化与 workaround
  • SYCL / CPU / Hexagon — 见 sync: ggml 列表（PowerPC BF16 tiled gemm、Hexagon L2 cache dirty-bit 追踪等）

  • 注意：本窗口回退了上窗口引入的「split compute 少同步」优化（86b94708f Revert #20793，#25138）——调度器不再做该放宽同步

依赖

  • cpp-httplib 0.48.0 → 0.51.0

2026-06-29 ​

上游同步：12 commits, GGML 0.15.3 ​

将 vendor/llama.cpp 子模块从 27c8bb4f6 更新至 25a1d63f4（上游 master 最新提交，GGML 维持 0.15.3）。

关键变更：

GGML 版本：0.15.3（本窗口未变）

小幅同步（12 commits），未触发 sync: ggml 子树合并，GGML 版本维持 0.15.3，亦无新增算子枚举。重点：DeepSeek V4 架构、DFlash 块扩散推测解码、MiniCPM5 工具调用解析器及若干 Jinja / CLI 选项。

新模型架构（重点）

  • DeepSeek V4 — 全新架构 LLM_ARCH_DEEPSEEK4（dsv4）：新增专用 KV cache 类型 llama_kv_cache_dsv4（1800+ 行，llama.cpp 单文件最大之一），llm_graph_input_dsv4 推理图输入，save-load 状态，Sinkhorn eps 纠正，rope 修复，pro 模型支持；convert/deepseek.py 转换脚本 + DeepSeek V4 jinja 模板
  • DFlash — 全新推测解码架构 LLM_ARCH_DFLASH：块扩散（block diffusion）draft 模型，一次前向产出整块 draft token，并把目标模型隐藏状态注入 draft 的 attention（区别于 EAGLE3 的单层自回归 draft）；新增 src/models/dflash.cpp，按 layer_types 的滑动窗口注意力

推测解码

  • DFlash v2 — --spec-type draft-dflash；draft 通过 --target-model-dir 继承目标模型的 tokenizer 与 token embedding；--spec-draft-n-max 按训练块大小 clamp
  • dflash 转换重构 — draft 模型转换路径重构，顺带修复 eagle3 convert

分词 / Jinja / 语法

  • MiniCPM5 工具调用解析器 — 新增 MiniCPM5 PEG parser（XML 工具调用），修复 Jinja min/max API 对齐 Jinja2，新增 MiniCPM5 jinja 模板
  • --reasoning-preserve — jinja/chat caps 新增保留推理（reasoning）内容的开关
  • --dump-prog — jinja 调试选项，导出模板编译后的程序（AST）
  • regex-partial 移除 — 删除未使用的 common/regex-partial.cpp/.h 及其测试（-551 行）

App / CLI

  • llama download --offline — 将 --offline 暴露给 llama download 子命令，便于脚本探测模型是否已缓存可服务（不触网）；顺带修复 URL-task on_done 回调中的 use-after-free

后端

  • Vulkan — 图提交启发式（submission heuristic）从「按权重张量大小」改为「按 flops」判断阈值，更准确

Web UI

  • 单模型模式下修复 stop 与 reasoning skip；恢复忽略 worktree 中的 Tailwind scanning；revert 一处 a11y 修复

2026-06-28 ​

上游同步：169 commits, GGML 0.15.3 ​

将 vendor/llama.cpp 子模块从 7dad2f1a1 (b9659) 更新至 27c8bb4f6 (b9776)。

关键变更：

GGML 版本：0.15.1 → 0.15.3

经两次 sync: ggml 子树合并（0.15.2、0.15.3）。本窗口未新增算子枚举值、未新增模型架构，主要是已有算子的后端实现补全、新模型变体、推测解码扩展与 server 能力增强。

推测解码（重点）

  • EAGLE3 扩展 — 支持 Qwen3.5 / Qwen3.6 的 EAGLE3 draft；为混合模型新增延迟边界 checkpoint 恢复（deferred boundary checkpoint restore）
  • Step3.5 / 3.7 Flash MTP3 — 多头推测解码（multi-head draft），新增 llama_set_mtp_layer_offset()、llama_model_n_nextn_layer() API，nextn 标志纳入图复用
  • EAGLE3 后端采样 — draft 采样可下沉到设备端执行（spec: add backend sampling support for eagle3）
  • 推测解码指标 — 新增每位置平均接受长度（mean acceptance length）与接受率（acceptance rate）
  • 修复长 prompt 下 EAGLE3 段错误

GGML 算子 / CPU

  • col2im_1d 后端化 — 算子本身在上窗口已引入，本窗口补齐 CUDA 与 Vulkan 实现
  • rope_back — 补齐 Metal 后端实现
  • CPU AMX 优化、power10 Q8/Q4 MMA matmul 支持 K-tail、按编译器支持条件启用 power11 后端、修复 SVE vec_dot_f32 残留路径

新模型 / 加载（变体 + 多模态，非新架构）

  • Granite Speech Plus — 语音模型转换支持
  • LFM2.5-ColBERT-350M / LFM2.5-Embedding-350M — 检索与嵌入模型
  • mtmd unlimited-ocr — 无限 OCR 转换器 + 一致性测试
  • InternVL 批处理 — mtmd 对 InternVL 启用 batching；mtmd-cli 批处理 + 视频测试
  • mtmd 预处理器重构 — 新增 mtmd_image_preproc_out
  • glm-dsa — DSA indexer 张量按可选加载
  • common 模型处理重构

分词 / Jinja / 语法

  • Jinja call 语句 — 支持模板内的函数调用语句
  • PEG ac parser — 为更严格的语法生成新增 ac parser；until GBNF 语法生成重构
  • json-schema-to-grammar — 间距规则与各 parser 对齐

采样 / 量化

  • top-n-sigma — 移除多余的无条件 softmax + sort（先前是冗余的）
  • quantization_version / file_type 走 LLM_KV — 写 GGUF 时改用 LLM_KV_GENERAL_QUANTIZATION_VERSION / LLM_KV_GENERAL_FILE_TYPE（消除原 TODO）
  • NVFP4 边界修复 — 后 GEMM 的 MUL 移至 LoRA / bias-add 之前，确保完全反量化；限制 build_ffn 仅支持合法组合
  • convert rope_parameters — 统一 rope 参数处理；修复 moe+mtp 量化

Server / API

  • SSE Replay Buffer — 客户端断连后服务端继续缓冲，经 GET /v1/stream/:conv_id（配合 X-Conversation-Id 会话头）恢复流
  • schema + 校验 — 请求新增 schema 字段与校验
  • router 重构 — child↔router 通信、model 管理 API、模型下载移至独立进程
  • /models/sse — 实时模型加载进度（UI 同步消费）
  • tool call responses API 新增 id；无效 grammar 返回 HTTP 400；禁用功能返回 HTTP 403
  • --agent 参数；last-5-seconds 生成速度显示；batch 构造重构；每条 user message 建 checkpoint

App / CLI / 二进制

  • llama download 子命令 — 新增下载子命令
  • --version / --licenses / --help — 统一入口放开
  • rpc-server / export-graph-ops 命名改进；self-update 仅在用 llama-install.sh 构建时启用

后端

  • Vulkan — CONV_3D、GET_ROWS_BACK、gated_delta_net (S_v=16)、FA 中 softmax 前先加 bias 防溢出、更多 unary/norm 算子（SQR/SQRT/SIN/COS/CLAMP/LEAKY_RELU/NORM）、UMA 上优先 host-visible 内存、Intel Xe-LPG Plus coopmat1、shader 编译失败即 fail build、降低图提交批次避免超时
  • SYCL — F16 默认开启、bin_bcast + unary 支持 bf16、conv_2d / conv_2d_dw / conv2d_transpose / conv_3d、Q1_0 MUL_MAT+OUT_PROD、reordered Q4_K/Q5_K/Q6_K MoE MUL_MAT_ID、USM 系统分配、--split-mode tensor、修复 MoE prefill use-after-free
  • OpenCL — Flash Attention 改进、q8_0 gemv 精度、mul_mat_f16_f32_l4 decode 优化、非连续行 norm、关闭时刷新 profiling 批
  • CUDA — cublasSgemmBatched 映射到 HIP/MUSA、out_prod 广播 (dps2>1)、cpy.cu 修复、col2im_1d、binary ops 整数溢出修复、cudaMemcpy2DAsync 快路径
  • Metal — rope_back、concat 支持 f16/bf16、concat kernel BF16 检查
  • Hexagon — MUL_MAT/MUL_MAT_ID 重构（32×32 tiled repack + cached graphs）、HVX/HMX/DMA op-trace
  • WebGPU — MTP 小 batch 走 mat-vec 路径、Vulkan+NVIDIA 上 F16 适配器开关
  • OpenVINO — 升级 OV 2026.2.1，自包含 release 包、context-shift、Q5_1、gemma4 dense/embedding
  • Scheduler — 在 split compute 期间重新引入更少的同步（async CPU→CUDA 拷贝，放宽同步要求）

依赖

  • cpp-httplib 0.47.0 → 0.48.0、BoringSSL 0.20260616.0

KV Cache / Context

  • main_gpu 校验放宽 — 无设备时跳过 main_gpu 校验
  • n_discard 修复 — ctx shifting 时非绑定 n_discard 值修复

Web UI / 日志

  • 新 Logo + 导航清理 + 移动端 UX、SSE 传输检测、模型选择可访问性、对话导出 jsonl；日志 reduce v2、logging 强制 max_capacity + 队列重排优化

2026-06-16 ​

上游同步：116 commits, GGML 0.15.1 ​

将 vendor/llama.cpp 子模块从 98d5e8ba8 (b9544) 更新至 7dad2f1a1 (b9659)。

关键变更：

GGML 版本：0.13.1 → 0.15.1

跨越三个小版本（0.14.0、0.15.0、0.15.1），通过 sync: ggml 子树合并引入。

新模型架构

  • EAGLE3 — 全新推测解码（speculative decoding）架构 LLM_ARCH_EAGLE3，从目标模型抽取层输入特征（layer input extraction）作为 draft 输入
  • Cohere2 MoE — 新增 LLM_ARCH_COHERE2MOE（North Code / TINY_AYA），含专用 chat template parser
  • Gemma 4 MTP Assistant — LLM_ARCH_GEMMA4_ASSISTANT，支持 E2B / E4B 草稿助手

推理与推测解码

  • EAGLE3 — 继 EAGLE/EAGLE2 之后的第三代 EAGLE，draft 模型直接复用目标模型的隐藏状态
  • Gemma4 MTP — Gemma 4 接入 MTP 图基础设施
  • MTP 去冗余 — 移除 padding 和多余 D2D 拷贝，减少推测解码开销

GGML 算子

  • GGML_OP_COL2IM_1D — im2col 的逆运算（1D 版本），用于音频模型的反向梯度计算

KV Cache

  • 消除 KV cells 拷贝 — v_cells 重构为 std::shared_ptr<llama_kv_cells_vec> + 引用，共享 cache 时不再逐 cell 拷贝（[TAG_KV_CACHE_SHARE_CELLS]）
  • 跟随源 cache 大小 — 共享 cells 时沿用源 cache 的容量

分词与词表

  • normalizer_options 结构体 — 将小写等归一化标志重构为独立 options struct，新增 strip_accents
  • TemplateProcessing BOS — 自动采纳 leading special token 作为 BOS
  • 采样器名称匹配放宽 — --sampler 等参数名匹配更宽松
  • Cohere2MoE vocab — 为 TINY_AYA 新增

多模态 (mtmd)

  • 视频输入 — mtmd 支持视频输入（lazy bitmap API，server 端 base64 传入）
  • batching API — 新增 build_vit 批处理接口
  • post-decode callback — 解码后回调钩子

Server / API

  • --log-prompts-dir — 将每个 prompt 写入独立文本文件
  • router 模式日志精简 — 跳过无用的日志行
  • 跳过 pos_next 之后的 checkpoint — 推测解码优化
  • 无统一 KV cache 时不清空 slot；刷新 HTTP 头时不解析请求

后端

  • Vulkan — 更多 CONCAT 类型（含标量）、非连续 unary/GLU、memcpy pipeline barrier、连续 buffer transfer 快路径、Asahi 中等 matmul tile、v_dot2_f32_f16（matmul + FA）、降低 iq1 共享内存、mul_mat_id 使用 cm2 decode_vector
  • WebGPU — i-quants mul_mat 提速、prefill 加速（k-quants + matmul 重构为 Q4/Q5/Q8）、2D workgroups（scale/binary/unary）、concat buffer overlap/aliasing
  • SYCL — K-quant DMMV 使用 native subgroup size、soft_max 修复、reorder 支持 fp32/fp16、set_rows 支持 q1_0/mxfp4/nvfp4、pool_1d 抽离、移除逐分配 Level Zero 检查
  • CUDA — concat 标量类型、ssm_scan 数据竞争修复、读取显存后重置 context、REPEAT 仅支持 F32/F16、移除 Q4_K mvvq 路径
  • Metal — repeat bf16、im2col 1D 修复（音频模型）
  • OpenCL — Adreno 平台 q5_0/q5_1 gemm/gemv kernel
  • HIP — gfx1152/gfx1153 加入 RDNA3.5

Chat Template / Jinja

  • Cohere2MoE (North Code) parser
  • jinja — count/d/e 过滤器别名、负步长 slice 修复、split/replace 空 first arg 修复
  • LFM2/LFM2.5 — tool-call 双重转义、json_schema、reasoning round-trip、空白、grammar generator 修复

依赖

  • cpp-httplib 0.47.0、LibreSSL 4.3.2

Web UI

  • PWA 支持、构建时 gzip 压缩静态资源、HEIC/HEIF 图片、JPEG EXIF 朝向、SVG 渲染、thinking 块 markdown 渲染、置顶对话、移动端修复

2026-06-07 ​

上游同步：214 commits, GGML 0.13.1 ​

将 vendor/llama.cpp 子模块从 328874d05 (b9310) 更新至 98d5e8ba8 (b9544)。

关键变更：

新模型架构

  • DeepSeek V3.2 — 新增 LLM_ARCH_DEEPSEEK32，引入 DeepSeek Sparse Attention (DSA) lightning indexer，配备专用 KV cache 类型 llama_kv_cache_dsa
  • Gemma 4 — 支持 Gemma4ForCausalLM 架构及 Gemma 4 Vision 多模态
  • Mellum — 全新模型家族，含专用转换脚本
  • EXAONE 4.5 — 支持 GQA mmproj、视觉标记
  • Step3.7-Flash — 新增转换支持
  • Talkie-1930-13B — 新模型架构
  • Granite Multilingual Embeddings R2 — 嵌入模型支持
  • MiniCPM5 — 新增 tokenizer 支持
  • LFM2.5-8B-A1B — 新增 tokenizer 和 chat template

推理与注意力

  • Flash Attention f16 mask — KQ mask 从 float 改为模板化，支持 f16，大幅节省 VRAM
  • llm_graph_input_mtp — MTP 推理图的新输入类型基础设施
  • Qwen 3.5 MTP post-norm — 使用后归一化隐藏状态进行 MTP
  • StepFun 3.5 MTP — 单层 MTP 支持
  • n_outputs_max — context 参数限制最大输出数，节省 VRAM

KV Cache

  • TP 量化 KV cache — Tensor Parallel 现支持量化 KV cache
  • SWA checkpoint 优化 — 保存状态时仅写入未屏蔽的 cell，减少 I/O
  • hparams.n_layer_all — 重构层计数，区分总层数与 KV 层数

Server/API

  • /v1/chat/completions/input_tokens — 新 API：仅计数 token 不执行完整推理
  • 实时推理中断 — POST /v1/chat/completions/control 可中断正在进行的推理
  • SSE ping interval — 防止长生成时连接断开
  • HTTP ETags — 支持 FNV-hash 缓存

后端

  • CUDA — PDL 修复（竞态条件、PTX 版本检查）、AMD MFMA MMQ 路由、量化 KV cache 预分配
  • Metal — 远程分配器心跳从 500ms 降至 5ms、GLU kernel 模板化支持 f16/f32
  • Vulkan — BF16 Flash Attention、FWHT Intel shmem、NVIDIA cooperative matrix decode
  • WebGPU — FlashAttention 重构 + MMVQ 路径
  • SYCL — 多列 MMVQ、Flash-attention Q4_1/Q5_0/Q5_1、虚拟内存池
  • OpenCL — Q5_0/Q5_1 支持、GATED_DELTA_NET、flat gemv 大 batch 优化
  • Hexagon — 通用算子融合框架（RMS_NORM+MUL）、Q4_1 MUL_MAT

量化与转换

  • FP8 → Q8 转换 — convert 工具新增 FP8 源到 Q8_0 的转换路径
  • Mistral3 NVFP4 — 模型加载时正确附加权重 scale

分词

  • WPM lowercase normalizer — WordPiece 分词器支持小写归一化
  • jina-embeddings-v2-base-zh — 新增 whitespace 预分词 tokenizer

废弃

  • llama_set_warmup — 标记为废弃（对 MoE 模型导致额外图重分配）

2025-05-25 ​

上游同步：124 commits, GGML 0.13.0 ​

将 vendor/llama.cpp 子模块从 1867a0c69 (gguf-v0.19.0-160) 更新至 328874d05 (b9310-20)。

关键变更：

  • 统一入口 — app/llama.cpp 提供 llama 可执行文件，通过子命令分发（serve/cli/bench/quantize/...）
  • GGML 0.13.0 — 版本从 0.12.0 升级
  • GGUF 新初始化 API — gguf_init_from_callback() 和 gguf_init_from_buffer() 支持网络流、加密存储、内存缓冲区
  • HybridDNA 分词器 — Carbon-3B 模型的混合 BPE + DNA k-mer 分词
  • NVFP4 量化 — NVIDIA 特定 4-bit 浮点量化格式
  • 后端采样 — Top-K 可在 GPU 上执行，优化 MTP 推测解码的 D2H 传输
  • CUDA fwht — 快速 Walsh-Hadamard 变换
  • 量化 LUT 并行化 — 启动时查找表初始化并行执行
  • FFN MUL_MAT 标记 — ffn_latent 张量正确标记为 MUL_MAT 操作

2025-05-18 ​

今日摘要 ​

初始化学习笔记站点，开始 llama.cpp 源码学习之旅。

计划 ​

  • 阅读 llama.cpp README 和 CMakeLists.txt
  • 理解项目整体架构
  • 从源码编译 CPU 版本

困惑与突破 ​

（记录学习过程中的困惑点和突破时刻）

笔记 ​

（记录关键发现和心得）