llama.cpp 发了 1.0:删掉 37 项 API,和一句被传错的"3.5 年"
打开 v1.0.0 的发布说明,第一段不是新功能,是删除清单。
删掉 35 个废弃的公开函数,删掉 llama_set_warmup,删掉 defrag_thold 这个参数和它对应的命令行开关;同时把一个在实验头文件里放了一阵子的 API 转正进 llama.h。这些动作合起来,占掉了 1.0 这一版 API 变更的绝大部分。
而流传最广的那句"3.5 年来首个完全稳定的大版本",把两件事混成了一件:项目确实有三年半以上的历史,但语义化版本体系只用了 84 天,就从 0.2 走到了 1.0。
这篇按一手发布记录和官方的版本策略文档,把"1.0"当成一份规格书来读:它写清了什么、没写什么、以及谁会真的受影响。
一、先纠正那个"3.5 年"
仓库创建于 2023 年 3 月 10 日,到 1.0 发布是三年零八个月。这段时间里,它一直用 bXXXXX 这种提交序号当版本号,从 b1 一路数到 b12388。
语义化版本是 2026 年 8 月才引入的。 有正式 release 记录的六个版本,时间和对应的 nightly 构建号如下:
| 版本 | 发布日期 | 对应 nightly | 距上一版 |
|---|---|---|---|
| v0.2.0 | 2026-08-21 | b10566 | — |
| v0.4.0 | 2026-09-04 | b10809 | 14 天 |
| v0.6.0 | 2026-10-05 | b11429 | 31 天 |
| v0.8.0 | 2026-10-28 | b11960 | 23 天 |
| v0.9.0 | 2026-11-04 | b12110 | 7 天 |
| v1.0.0 | 2026-11-13 | b12359 | 9 天 |
【官方】上表日期与 nightly 编号均取自各版本 release 页面,每个语义化版本的发布说明里都注明了它对应的构建号。
v0.2.0 到 v1.0.0,84 天,1793 个 nightly 构建,平均每天 21.3 个。
这张图的读法:折线之上是六次发布,折线之下是每天二十多次构建。 版本号不是节奏,它是一个个被钉在时间轴上的锚点。
所以那句"3.5 年"该怎么改写:项目跑了三年半,但从"开始用语义化版本"到"敢说 1.0",只用了一个季度。这两件事的差别,决定了 1.0 该被读成"终于成熟"还是"刚把账清完"。
从节奏看,更接近后者——最后一版 0.9 到 1.0 只隔 9 天,中间还塞了 249 个构建。这不是一个"慢慢打磨到位"的曲线,更像"体系跑通了,顺手把欠的账一次结掉"。
二、1.0 到底改了什么
发布说明里 API changes 一段,逐条列出来是这样的:
| 变更 | 数量 | 性质 |
|---|---|---|
| 删除废弃的公开函数 | 35 | 破坏性:调用会直接编译失败 |
删除 defrag_thold 及 --defrag-thold |
2 | 破坏性:配置项消失 |
llama_set_embd_state_src → llama_set_ctx_state_src |
1 | 需改调用:函数改名 |
NextN/speculative API 从 llama-ext.h 移入 llama.h |
1 | 转正:从实验变成正式 |
llama_context_params 新增 moe_cache_size、moe_cache_cpu_share |
2 | 新增:有默认值 |
【官方】以上条目取自 v1.0.0 release notes 的 API changes 段,其中删除项对应上游 PR「llama : prune」。
删 37 项、加 2 项、转正 1 项、改名 1 项。 这张构成表本身就是一句话:这次发布的主体不是"多了什么",是"少了什么"。
为什么删是必须的。三年半里,llama.h 累积了大量被新接口取代的旧函数——它们被标记废弃,但为了兼容一直留着。留着的好处是老代码能编过;代价是每个下游都得记住"哪些能用、哪些别用",而这些函数的实现还要跟着内部重构一起维护。
1.0 做的事情,是把这份历史包袱一次性剪掉。
这里有一个细节值得单独说:"改名"和"删除"是两种不同性质的破坏。
- 删掉一个函数,调用方会在编译时或链接时直接失败,错误信息指向"找不到符号",但不会告诉你该换成什么;
- 改一个名字,同样是失败,但名字本身是线索——
embd_state变成ctx_state,改动的人能立刻猜到"大概是同一个东西换了叫法"。
同一次发布里两种手段都用上了:能直接删的就删(35 个),不好删或还有价值的就改名(1 个)。这是一个挺务实的取舍——破坏性变更的目的不是让人难受,是让升级路径尽量短。
三、llama-ext.h:版本号之外的那个缓冲区
被转正的那个 API(NextN/speculative),之前一直住在 llama-ext.h 里。这个头文件的作用,官方在版本策略讨论里说得非常清楚:
The purpose of the
llama-ext.his to be able to experiment with some API changes without affecting the official API of the library and therefore without affecting the minor and major versions. Thellama-ext.his not public so we can change it without announcing this with a version bumps.
翻过来就是三点:
- 它不在公开 API 里,可以随时改、随时删,不发版、不通知;
- 在这里试验成熟的接口,会被"毕业"进
llama.h——那时才计入版本号; - 下游如果直接依赖了
llama-ext.h,等于自愿把自己的代码绑在一个不承诺稳定的接口上。
【官方】以上引文与三点归纳来自 ggml-org 的版本策略讨论(discussion #1579)。
这个设计解决了一个真实矛盾:库要演进,但又不能每改一个实验性接口就 bump 主版本号。 把"试验"和"承诺"分成两个头文件,等于给版本号加了一个缓冲层。
对使用者的直接含义很具体:如果你 fork 或封装过 llama.cpp,先去查自己的代码里有没有 include 过这个头文件。 有的话,1.0 之后要重新对一遍——不是因为 1.0 删了它,而是因为它本来就不保证稳定,任何一次 nightly 都可能让它变形。
# 自查:项目里有没有直接依赖实验头文件或被删符号
git grep -n "llama-ext.h" -- '*.c' '*.cc' '*.cpp' '*.h' '*.hpp'
git grep -nE "llama_set_warmup|defrag_thold" -- '*.c' '*.cc' '*.cpp' '*.h' '*.hpp'
第一条命中,说明你依赖了不承诺稳定的接口;第二条命中,说明 1.0 会让你的代码编不过。两类问题性质不同,处理方式也不同。
四、为什么 ggml 比 llama.cpp 早发 1 小时 46 分
这两个时间点值得放在一起看:
| 项目 | 版本 | 发布时间 |
|---|---|---|
| ggml | v1.0.0 | 2026-11-13 08:34 |
| llama.cpp | v1.0.0 | 2026-11-13 10:20 |
差 1 小时 46 分钟。这不是巧合,是规则决定的。
官方版本策略里写着:llama.cpp 仓库内嵌一份 ggml 副本,nightly 构建用的就是这份副本,它可以和官方发布的 ggml 版本不一致;而正式 release tag 的创建条件是——
The release tags are created on the condition that the internal
ggmlcopy is identical to the releasedggmlcopy. This guarantees that a downstream building from the release tags and linking to a system-wideggmlwill be compatible.
【官方】引文来自 ggml-org 版本策略讨论。
也就是说:必须先有 ggml 的正式版,llama.cpp 才能打 release tag。 这个顺序是被"下游要能链接系统级 ggml"这个需求倒逼出来的,不是流程习惯。
这条约束对打包者的意义,比对新功能的意义大得多。它意味着一个发行版可以这样装:系统里装一份 libggml,再让 llama.cpp 链接过去,而不是让每个包都塞一份自己的副本。
两种装法的差别会一路传导下去——副本打进去,安全更新要等上游发版;链接系统库,换一次 ggml 就能让所有依赖它的包同时受益。 这也是为什么 Debian 的维护者在这份讨论下说了一句很实在的话:
Super-happy to see semantic versioning for llama.cpp coming. That will also enable maintaining a SOVER. And that will allow us in Debian to ship it as a library in public search paths, because we can now guarantee backwards-compatibility.
【交叉】引文来自该讨论的公开评论。
五、1.0 是发给打包者的,不是发给用户的
顺着上一节往下推,可以把下游分成两类,它们的诉求几乎相反。
| 下游 | 怎么处理 ggml | 关心什么 |
|---|---|---|
| Homebrew、Debian | 依赖并链接系统级 ggml | ABI 稳定、SOVER 可维护、升级不会连带炸掉别的包 |
| Winget、llama.app 打包仓 | 打包内部副本 | 单文件可执行、开箱即用、不关心库版本 |
【官方】分类来自版本策略讨论里的 Downstreams 一节。
第一类要的是"别乱变,变了要能预知";第二类要的是"能跑就行"。
1.0 主要服务第一类。因为只有在有明确主版本号的前提下,打包者才能:给小版本升级放心打补丁、在主版本变化时改 SONAME 并让依赖它的包重新构建。
换个说法:1.0 的价值不在"更稳",在"可被计算"。 之前三年半的问题是版本号不含信息——b12388 和 b12359 谁更新、谁有破坏性变更,只能靠翻 commit。
这也解释了为什么发布说明末尾专门列了 Nightly build 的链接,还留了一个 v1.0.0-b12359-b1b770d 这样的 tag:1.0 是 b12359 那一次的语义化别名。 内容一样,只是多了一层"官方承诺过"的含义。
六、"稳定"这个词的边界
版本策略讨论里,维护者把什么算 major、什么只算 minor/patch,列得相当细。这份清单比任何"稳定版发布"的标题都有用:
| 变更类型 | 版本位 |
|---|---|
| 小 bug 修复、vendor 依赖更新 | patch |
| 新增模型支持、性能改进 | minor |
| 公开 API 大改(新增一套接口、废弃旧的) | major |
| server 新增功能(会改变 REST API) | major |
| 仅 inference 端点(completions、embeddings)的破坏性变更 | major |
| router API、tools、CORS proxy 的破坏性变更 | patch |
| llama-cli/llama-ui/llama-quantize 的变更 | 通常 minor |
| 新增一个 enum 值 | 算 ABI 破坏 |
【官方】整理自版本策略讨论中的规则草案与后续确认。
两条最容易被忽略:
其一,新增功能也算 major。 一般库的惯例是"加东西不算破坏",但这里明确写了 server 新增功能要 bump major——因为它改了对外暴露的 REST API 面。接口变宽也是接口变了。
其二,加一个 enum 值也算 ABI 破坏。 这条对写 C 扩展的人尤其要紧:枚举的取值集合变了,用旧头文件编译的代码在运行时的行为就可能不再对齐。
反过来看,"稳定"这个词在这里的实际含义是:主版本号不变,就不做让下游编不过的改动;但 minor 版本会持续加模型、加性能优化、改内部结构。 它承诺的是接口的形状,不是实现的静止。
七、nightly 没有停
1.0 发布之后,b 系列继续在发:11-15 的最新构建是 b12388,仍然标记为预发布。
| nightly(bXXXX) | 正式版(vX.Y.Z) | |
|---|---|---|
| 来源 | master 分支每次合入 | 特定一次构建的快照 |
| 版本标记 | 提交序号 | 语义化版本 |
| CMake 开关 | -DLLAMA_BUILD_IS_DEV=ON |
-DLLAMA_BUILD_IS_DEV=OFF |
| 内嵌 ggml | 可能与官方版不一致 | 必须与官方版一致 |
| 发布频率 | 每天二十多次 | 不定期,最近三次间隔 7/9 天 |
【官方】表格依据版本策略讨论与 release 记录整理。
所以"1.0"不等于"从此不滚动了"。它给的是一个可引用的坐标,而不是一条冻结的分支。
# 从正式版构建(对应官方 release 构建使用的开关)
git clone --branch v1.0.0 --depth 1 <仓库地址>
cmake -B build -DLLAMA_BUILD_IS_DEV=OFF -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release -j
需要 -DLLAMA_BUILD_IS_DEV=OFF 这一点,正是它和 nightly 构建在配置层的唯一区别。忘了这个开关,编出来的东西版本号会显示成构建序号,语义化那层含义就丢了。
同一套规则下,为什么只有它需要双轨
ggml-org 名下有几个项目都用语义化版本,但构建轨道的安排不一样:
| 项目 | nightly 构建 | 正式发布 | tag 形式 |
|---|---|---|---|
| llama.cpp | 有(bXXXX,每天二十多次) | 有(vX.Y.Z) | b[NUM] 与 vX.Y.Z 并存 |
| whisper.cpp | 没有 | 有(vX.Y.Z) | 只有 vX.Y.Z |
| ggml | — | 有(vX.Y.Z) | vX.Y.Z |
| llama.cpp/gguf-py | — | 有 | gguf-vX.Y.Z(独立编号) |
| llama.vim | — | 有 | vX.Y.Z |
【官方】上表整理自版本策略讨论的 Projects 一节。
差别的原因不复杂:whisper.cpp 的合入节奏慢,一个 release 就能覆盖大部分用户;llama.cpp 每天二十多次构建,如果只靠正式版,下游会长期落在一个月前的代码上。
所以双轨是被迭代速度逼出来的:nightly 保证"最新能用",release 保证"有据可依"。两条轨道服务两种需求,谁也替代不了谁。
这也解释了 1.0 的"稳定"为什么比一般项目弱一层——它的主分支一天动二十多次,语义化版本只是给这条快速流动的河钉了几个桩。 桩是真的,河也一直在流。
八、1.0 里还有什么(功能部分)
清账之外,这一版确实也带了新东西。按官方 overview 的原文顺序:
| 类别 | 内容 |
|---|---|
| 量化与缓存 | OCP FP8 KV cache(-ctk/-ctv f8_e4m3,支持逐 tensor 静态 scale) |
| MoE | host 内存的专家缓存,可配置 CPU 分担比例;LRFU/ClassLRU 替换策略,命中时不阻塞在 CPU 上 |
| 模型加载 | 外部 PLE/engram 分片(--shard/--ple);Windows 无缓冲加载对齐 Linux DirectIO |
| 新架构 | Kimi-K3.1-Pro、Ripple-65B-Preview(dense 65B)、xing4_0(mHC + MLA + MoE + MTP) |
| 多模态 | drama-3 TTS、MageVL-Cowork、Kimi-K3.1 视觉;clip.h 移除,统一进 mtmd |
| 服务端 | 新增 OpenAI 兼容的 /v1/audio/speech;安全加固:SSRF、CORS、DNS rebinding、MCP 工具调用取消 |
| 界面 | 全新 Web UI:会话分组、侧栏折叠、markdown 实时预览编辑器、移动端原生布局 |
【官方】整理自 v1.0.0 release notes 的 Overview 与分类小节。
两处值得单独提:
MoE 专家缓存走 CPU 这一项,对显存吃紧的机器意义直接——把不常命中的专家放到 host 内存,等于用内存换显存。参数里给了 moe_cache_cpu_share 来控制 CPU 分担比例,这是个可以被调的量,不是全有或全无的开关。
服务端那批安全修复值得单独看:SSRF、CORS、DNS rebinding 三项都是把 llama-server 暴露到内网或公网时才会踩的坑。以前的默认行为偏宽松,这次加了 --allow-unauthenticated-tools 和 --media-allow-private-urls 两个显式开关,把"要不要放开"变成需要主动勾选的事。默认收紧、放开要显式声明,是这一版在安全上的主要变化。
九、自己要不要跟
| 你的情况 | 判断 |
|---|---|
只用 llama-server/llama-cli 跑模型,没写过 C 代码 |
不用急,继续跟 nightly 就行;1.0 的内容 nightly 里早都有了 |
自己写了 C/C++ 调用 llama.h |
必须跟,35 个函数没了,不跟会卡在旧版本越走越远 |
| 打过补丁、fork 过源码 | 先查 llama-ext.h,依赖过的话要重新对一遍接口 |
| 做发行版打包 | 必须跟,1.0 是 SOVER 的起点,从这里开始才能算兼容性 |
| 想把 llama.cpp 当库嵌进产品 | 跟,这是 1.0 主要服务的场景 |
关心 llama-server 暴露在网络上 |
跟,这一版补了 SSRF/CORS/DNS rebinding |
一句话概括:1.0 对终端用户几乎无感,对写代码调用它的人是一次必修的迁移。
这也解释了为什么这条消息在中文技术圈传播时会被写成"稳定版发布,本地部署终于稳了"——那个说法对用户是安慰,对开发者却是误导:真正的变化在头文件里,不在推理速度上。
十、关键要点
- "3.5 年首个稳定版"是两件事被压成了一句。 项目 2023 年 3 月创建,确实三年零八个月;但语义化版本 2026 年 8 月才引入,0.2 到 1.0 只用了 84 天。
- 84 天里发了 6 个版本、1793 个 nightly 构建,平均每天 21.3 个。 版本号是锚点,nightly 才是真实节奏。
- 1.0 的主要内容是删除:35 个废弃函数 +
llama_set_warmup+defrag_thold参数,共 37 项破坏性变更,只对应 2 项新增。 - "改名"和"删除"是两种破坏。 删除让人找不到符号;改名把新名字留在错误信息里,反而缩短了升级路径。同一次发布两种都用上了。
llama-ext.h是版本号之外的缓冲区。 官方明说它不 public、可随时改、不触发版本变更;从这里毕业进llama.h才计入 semver。依赖过它的代码,任何一次 nightly 都可能被破坏。- ggml v1.0.0 比 llama.cpp v1.0.0 早 1 小时 46 分,因为 release tag 的前提是"内嵌 ggml 副本与官方版完全一致"。这是"下游能链接系统级 ggml"倒逼出来的硬约束。
- 1.0 主要服务打包者,不是用户。 Debian 维护者的原话是"终于可以维护 SOVER,把 llama.cpp 作为库放进公共搜索路径"。
- 5 类下游分成两种装法:Homebrew/Debian 链接系统级 ggml;Winget/llama.app 打包内部副本。前者要 ABI 稳定,后者只要能跑。
- "稳定"承诺的是接口形状,不是实现静止。 新增模型、性能改进都算 minor,会持续发生。
- server 新增功能也算 major,因为它改变了 REST API 面——接口变宽也是接口变了。
- 新增一个 enum 值也算 ABI 破坏,这条对写 C 扩展的人尤其要紧。
- 1.0 之后 nightly 没停,11-15 已到 b12388。1.0 是可引用的坐标,不是冻结的分支。
- 构建要带
-DLLAMA_BUILD_IS_DEV=OFF,这是正式版与 nightly 在配置层的唯一区别。 - 功能侧三件值得看:OCP FP8 KV cache、MoE 专家缓存可走 host 内存并调 CPU 分担比例、server 补了 SSRF/CORS/DNS rebinding 且默认收紧。
- 对用户几乎无感,对写 C 调用的人是必修迁移。 真正的变化在头文件里,不在推理速度上。
- 点赞
- 收藏
- 关注作者
评论(0)