llama.cpp 1.0.0 升级清单:删掉的 35 个 API、改名的 NextN 与服务端收紧的默认值
llama.cpp 和它底层的 ggml 在同一次发布里一起跨过 1.0.0。这次变更不只是加个标签:公共 C API 删了一批符号、NextN 相关接口从 llama-ext.h 挪进 llama.h、server 的几个安全开关从默认放开改成显式 opt-in。已经部署出去的服务,升级前需要逐项过一遍。
- 仓库:https://github.com/ggml-org/llama.cpp 、https://github.com/ggml-org/ggml
- Release:https://github.com/ggml-org/llama.cpp/releases/tag/v1.0.0
- 公告:https://huggingface.co/blog/ggml-org/llama-cpp-v1
- 安装与快速开始:https://llama.app
版本号从此带语义
llama.cpp(libllama,C/C++ 大模型推理库)与 ggml(libggml,底层机器学习张量库)今后都用主版本号标记 API 或 ABI 不兼容的变化:
- MAJOR(如 1.x.x → 2.0.0):
./include中公共 C API 出现破坏性变更,API/ABI 不兼容通过主版本升级体现。 - MINOR(如 1.0.x → 1.1.0):向后兼容的功能、后端更新、模型支持或 API 新增。
- PATCH(如 1.0.0 → 1.0.1):不改变 API 的 bug 修复。
此前发布以滚动构建号 b1xxxx(nightly)形式出现,现在带 v 前缀的标签走语义化版本。对接 libllama 的项目,看第一位数字就能判断能否直接换版本。
配套的工程改动:CI 用 Hugging Face 的 HF Buckets / HF Jobs 扩容;在 NVIDIA、AMD、Qualcomm、Arm、IBM、Intel 硬件支持下增加自托管测试运行器;开发流程审慎使用 LLM,代码质量与架构控制优先。ggml 的每个后端都可编译为动态库、运行时按需加载;llama.cpp 已支持超过 150 种模型架构变体和主流推测解码方法。
被删掉的公开 API
llama.h 里移除:
llama_set_warmup- 35 个废弃函数
defrag_thold参数,以及对应的--defrag-thold命令行选项
(#30565)
NextN 进 llama.h,一个函数改名
NextN / 推测解码的 API 从 llama-ext.h 提升到 llama.h,扩展头不再是唯一入口。同时 llama_set_embd_state_src 改名为 llama_set_ctx_state_src(#30565)。改名在编译期就能暴露,但把旧调用藏在宏或动态查找里的代码不会报错,需要主动搜一遍。
llama_context_params 新增两个字段
llama_context_params 增加 moe_cache_size 与 moe_cache_cpu_share(#30966)。对应的 MoE cache 实现:miss 时使用 CPU 份额,LRFU/ClassLRU 替换策略,命中的专家不再等 CPU。
FP8 KV cache 与外部 PLE
- FP8 KV cache:
-ctk/-ctv f8_e4m3,支持可选的静态 per-tensor scales(#28392)。 - 外部 PLE/engram 从独立的 GGUF 分片加载:
--shard/--ple(#31185)。 - Windows 无缓冲模型加载,对齐 Linux 的 DirectIO 路径。
- 复用 backend scheduler 与 graph 结果,跳过未使用的 graph metadata 页。
- 移除 non-fused GDN 路径和依赖 ubatch 的 graph node 预算。
- jinja:支持链式比较与参数解包。
- chat:qwen3-coder/deepseek/ministral3、Muse Spark、gemma4 解析器遵循
response_format。 - json-schema:修复普通类型的
allOf;转义控制字符,清洗工具参数里的非法 UTF-8。
llama-server:几个安全开关变成显式 opt-in
--allow-unauthenticated-tools、--media-allow-private-urls改为显式 opt-in(#32113、#32115)。依赖默认行为跑通「MCP 工具 + 外部媒体 URL」的部署,升级后会直接失败,必须在启动参数里手动打开。- 修复
--cors-origins、DNS rebinding、CORS 代理 SSRF 以及子实例访问(#32098、#32115、#32120)。反过来,来源校验变严格,靠通配或宽松配置的前端可能被拦。 HF_TOKEN只对huggingface.co主机生效(#31730)。把 token 带给镜像站或自建模型仓库的用法会失效。- MCP 工具调用在客户端断开或超时后取消,并通知 MCP server。
--sleep-idle-seconds在请求仍持有状态期间保持 server 唤醒。- 上下文检查点改用引用计数,不再深拷贝;共享前缀请求先访问父 slot 再访问子 slot。
- realtime API:出错时发送 error 事件而不是崩溃,拒绝非对象的 session 更新,修复输出语言。
- 接受顶层
response_format.schema形式,并转换 Responses 的text.formatJSON schema。
新增 /v1/audio/speech
server 增加 OpenAI 兼容的 /v1/audio/speech 端点,/tts 增加 temperature 选项。多模态侧同步补上 drama-3 TTS(fishaudio)、MTMD_GEN_AUDIO_TYPE_DRAMA3、mtmd_helper_gen_audio_inp 的 temp 参数,以及按模型采样率流式输出裸 PCM 的 mtmd_helper_resampler。
其余多模态改动:删除 clip.h,模型/子上下文基础设施并入 mtmd;子上下文共享 compute buffer,为 vision+audio+gen 模型省内存;log-mel 移进 graph 计算,不再每请求起线程;支持 Gemma 4 流式音频输入、MageVL-Cowork 与 Kimi-K3.1 视觉。
新增的三个文本架构:Kimi-K3.1-Pro(K3 中 full-attention 的 MLA 层换成 DSA)、Ripple-65B-Preview(新的 dense 65B 架构,无新算子)、xing4_0(mHC、MLA、MoE、MTP)。
ggml 1.0.0
ggml 1.0.0 同样裁掉废弃的公共 API 与遗留 DIAG_MASK 算子,新增可配置的 YaRN 截断和 FP8 支持。性能工作铺开在各后端:CUDA/Metal 上的 few-row 量化 matmul 与 MoE fusion、Vulkan 的 prefill FlashAttention 路径、SYCL 的 device 侧 MoE scheduler、OpenCL 中拆解的 Adreno FlashAttention、新的 WebGPU kernel、扩展的 Hexagon 算子覆盖,以及避免上传未使用输入的 scheduler 改进。
升级检查步骤
- 搜被删符号:
grep -rn "llama_set_warmup\|defrag_thold" .,源码、启动脚本、systemd unit、docker-compose 都要搜;--defrag-thold往往只在部署文件里出现。 - 全库改名:
grep -rn "llama_set_embd_state_src",替换为llama_set_ctx_state_src;直接改用llama-ext.h拿 NextN 的调用,可以改指llama.h。 - 重编验证:按原后端重新构建(
cmake .. -DGGML_CUDA=ON后cmake --build . --config Release -j 8),链接 libllama 的外部项目一并编译。MAJOR 变更意味着不重编就可能对不上。 - server 回归:起服务后逐项验证 MCP 工具、外部媒体 URL、跨域前端、HF 下载,以及新增的
/v1/audio/speech。前三项任一没配 opt-in 或来源没写对,表现都是「以前能用、现在不行」。 - KV 量化对照:用了 KV cache 量化的,把
-ctk/-ctv换成f8_e4m3跑一轮,对照显存占用和输出一致性;用了外部 PLE 分片的,确认--shard/--ple的路径。 - MoE 调参:设置
moe_cache_size与moe_cache_cpu_share,观察命中率与延迟变化。
最快验证方式:curl -LsSf https://llama.app/install.sh | sh,然后 llama cli -hf ggml-org/Qwen3.5-0.8B-GGUF 或 llama serve -hf ggml-org/Qwen3.5-0.8B-GGUF。
支持的后端:BLAS、BLIS、CANN、CUDA、HIP、Hexagon、IBM zDNN、MUSA、Metal、OpenCL、OpenVINO(in progress)、RPC、SYCL、VirtGPU、Vulkan、WebGPU、ZenDNN。量化覆盖 1.5-bit 到 8-bit 整数,支持 CPU+GPU 混合推理。