llama.cpp 发了 1.0:删掉 37 项 API,和一句被传错的"3.5 年"

举报
Daniel777 发表于 2026/11/15 11:48:11 2026/11/15
【摘要】 打开 v1.0.0 的发布说明,第一段不是新功能,是删除清单。删掉 35 个废弃的公开函数,删掉 llama_set_warmup,删掉 defrag_thold 这个参数和它对应的命令行开关;同时把一个在实验头文件里放了一阵子的 API 转正进 llama.h。这些动作合起来,占掉了 1.0 这一版 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.h is 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. The llama-ext.h is not public so we can change it without announcing this with a version bumps.

翻过来就是三点:

  1. 它不在公开 API 里,可以随时改、随时删,不发版、不通知;
  2. 在这里试验成熟的接口,会被"毕业"进 llama.h——那时才计入版本号;
  3. 下游如果直接依赖了 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 ggml copy is identical to the released ggml copy. This guarantees that a downstream building from the release tags and linking to a system-wide ggml will 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 对终端用户几乎无感,对写代码调用它的人是一次必修的迁移。

这也解释了为什么这条消息在中文技术圈传播时会被写成"稳定版发布,本地部署终于稳了"——那个说法对用户是安慰,对开发者却是误导:真正的变化在头文件里,不在推理速度上。


十、关键要点

  1. "3.5 年首个稳定版"是两件事被压成了一句。 项目 2023 年 3 月创建,确实三年零八个月;但语义化版本 2026 年 8 月才引入,0.2 到 1.0 只用了 84 天。
  2. 84 天里发了 6 个版本、1793 个 nightly 构建,平均每天 21.3 个。 版本号是锚点,nightly 才是真实节奏。
  3. 1.0 的主要内容是删除:35 个废弃函数 + llama_set_warmup + defrag_thold 参数,共 37 项破坏性变更,只对应 2 项新增。
  4. "改名"和"删除"是两种破坏。 删除让人找不到符号;改名把新名字留在错误信息里,反而缩短了升级路径。同一次发布两种都用上了。
  5. llama-ext.h 是版本号之外的缓冲区。 官方明说它不 public、可随时改、不触发版本变更;从这里毕业进 llama.h 才计入 semver。依赖过它的代码,任何一次 nightly 都可能被破坏。
  6. ggml v1.0.0 比 llama.cpp v1.0.0 早 1 小时 46 分,因为 release tag 的前提是"内嵌 ggml 副本与官方版完全一致"。这是"下游能链接系统级 ggml"倒逼出来的硬约束。
  7. 1.0 主要服务打包者,不是用户。 Debian 维护者的原话是"终于可以维护 SOVER,把 llama.cpp 作为库放进公共搜索路径"。
  8. 5 类下游分成两种装法:Homebrew/Debian 链接系统级 ggml;Winget/llama.app 打包内部副本。前者要 ABI 稳定,后者只要能跑。
  9. "稳定"承诺的是接口形状,不是实现静止。 新增模型、性能改进都算 minor,会持续发生。
  10. server 新增功能也算 major,因为它改变了 REST API 面——接口变宽也是接口变了。
  11. 新增一个 enum 值也算 ABI 破坏,这条对写 C 扩展的人尤其要紧。
  12. 1.0 之后 nightly 没停,11-15 已到 b12388。1.0 是可引用的坐标,不是冻结的分支。
  13. 构建要带 -DLLAMA_BUILD_IS_DEV=OFF,这是正式版与 nightly 在配置层的唯一区别。
  14. 功能侧三件值得看:OCP FP8 KV cache、MoE 专家缓存可走 host 内存并调 CPU 分担比例、server 补了 SSRF/CORS/DNS rebinding 且默认收紧。
  15. 对用户几乎无感,对写 C 调用的人是必修迁移。 真正的变化在头文件里,不在推理速度上。
【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。