llama.cpp 1.0.0 升级指南:破坏性变更、FP8 KV 缓存与服务器安全

安全升级到 llama.cpp 和 ggml 1.0.0,避免本地编码 Agent、C 语言绑定和启动脚本失效。了解 35 个废弃函数及 --defrag-thold 的移除方式,对比 FP16 与 FP8 KV 缓存的显存和性能,配置需要 GPU 的 MoE 专家缓存,并检查 llama-server 的未认证工具访问和私网媒体 URL 安全设置。本文还介绍语义化版本规则、版本固定、接口验证,以及 Ollama 和 LM Studio 用户何时需要跟进。

本文内容
llama.cpp 1.0.0 升级指南:破坏性变更、FP8 KV 缓存与服务器安全

升级到 llama.cpp 1.0.0 前,先检查 C 语言绑定、启动参数和 llama-server 的安全配置。2026 年 11 月 13 日发布的版本移除了废弃 API,新增 FP8 KV 缓存和 MoE 专家缓存控制参数,并调整了服务器工具和私网媒体 URL 的安全权限。如果你通过 llama-server 为本地编码 Agent 提供模型服务,建议先升级测试环境,确认普通聊天补全和工具调用都正常,再切换生产环境。

截至 2026 年 11 月 14 日,llama.cpp 1.0.0 已可获取。此次发布还为 libllama 和 libggml 引入了更明确的版本兼容性承诺:今后公开 C API 出现破坏性变更时,必须提升主版本号。

这让依赖升级更容易评估,但不代表模型输出、推理性能、GPU 后端行为或所有 HTTP 接口都保证不变。

llama.cpp 1.0.0 有哪些重要变化?

这次升级主要影响三类开发者:直接集成 llama.cpp 库的开发者、运行 llama-server 的服务维护者,以及需要优化本地模型显存占用的用户。

领域1.0.0 的变化需要采取的操作
版本管理公开 C API 和 ABI 的不兼容变更通过主版本号体现生产环境固定版本或提交
C API移除 35 个废弃函数及 llama_set_warmup修改绑定代码并重新编译
上下文配置移除 defrag_thold 和 --defrag-thold删除过时配置
推测解码NextN API 移入 llama.h,一个状态函数更名更新头文件引用和函数调用
KV 缓存K、V 缓存支持 f8_e4m3对比显存、质量及后端兼容性
MoE 推理GPU 专家缓存支持让 CPU 处理部分缓存未命中检查 GPU 并调整缓存大小和 CPU 分担比例
服务器安全工具认证和私网媒体 URL 受到新的权限控制检查网络暴露范围和认证
模型支持新增 Kimi-K3.1-Pro、Ripple、xing4_0 及多模态支持确认模型转换与加载条件
语音 API新增兼容 OpenAI 的 /v1/audio/speech 接口使用受支持的语音模型测试

具体变化可查阅 v1.0.0 官方 Release Notes 和项目发布的语义化版本说明。

项目表示,目前支持超过 150 种模型架构变体。这说明架构覆盖范围扩大,并不意味着每个模型权重文件、功能或 GPU 后端都能正常配合使用。

1.0.0 的语义化版本规则意味着什么?

从 1.0.0 开始,llama.cpp 和 ggml 对公开 C 接口的兼容性作出了明确承诺。适用范围是 ./include 下的公开头文件,包括 libllama 和 libggml 暴露的接口。

维护者定义了三种版本变更规则:

版本组成触发条件示例
MAJOR公开 C API 出现破坏性变更1.x.x 升至 2.0.0
MINOR增加向后兼容的功能、后端、模型或 API1.0.0 升至 1.1.0
PATCH修复 Bug,公开 API 不变1.0.0 升至 1.0.1

表中的版本号仅用于解释规则,不代表官方已经宣布这些后续版本。

如果应用直接链接 libllama,这项规则可以降低同一主版本内公开函数签名意外变化的风险。

但兼容性承诺不自动覆盖内部头文件、未公开的符号、CLI 参数、HTTP 响应细节或模型生成行为。因此,即使只是更新次版本,也应该测试实际工作负载。

如何固定 llama.cpp 版本?

将 llama.cpp 编译进自己的应用时,使用明确的 Release Tag 或不可变的 Git Commit。

官方编译指南提供了 Git 和 CMake 的基本操作。下面在此基础上固定到 v1.0.0。

在 Bash 中执行:

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
git fetch --tags
git checkout v1.0.0

cmake -B build
cmake --build build --config Release

以上 CMake 命令采用项目文档中的基础 CPU 编译流程。不同平台可能默认启用其他后端,不能仅凭这两条命令就认定模型一定在某个设备上运行。

官方服务器文档说明,标准编译生成的可执行文件位于 ./build/bin/llama-server。某些平台或 CMake Generator 可能采用不同的输出目录。

需要 GPU 加速时,应根据目标后端添加官方文档中的 CMake 参数。

生产环境建议记录:

  • Release Tag 和对应的 Git Commit。
  • CMake 编译选项。
  • 实际使用的 CPU 或 GPU 后端。
  • 依赖该版本的应用和绑定库版本。

每次更新依赖后,先完成测试,再替换正在使用的二进制文件。

如果应用或 Python Wrapper 自带一份 llama.cpp 源码,还要固定上层应用的版本。Wrapper 版本号不一定对应上游 llama.cpp 的版本号。

哪些 API 和命令行参数被移除了?

升级时最容易导致编译失败或启动脚本失效的,是废弃 C API 和旧的内存碎片整理阈值参数。

根据 PR #30565 的 API 清理,此次移除了 35 个废弃函数、llama_set_warmup 以及旧的碎片整理阈值配置。

迁移时重点检查:

  • 删除 llama_set_warmup 调用。
  • 从上下文配置中删除 defrag_thold。
  • 从启动脚本中删除 --defrag-thold。
  • 在适用位置,将 llama_set_embd_state_src 替换为 llama_set_ctx_state_src。
  • 更新 NextN 和推测解码相关的头文件引用及声明。这些接口现已移入 llama.h。

35 个废弃函数的移除不代表存在 35 个一一对应的替代函数。应对照 v1.0.0 对应的头文件变更,逐个确认自己的绑定实际使用了哪些符号。

如何修复仍使用 —defrag-thold 的启动脚本?

旧版本的启动命令可能如下:

./build/bin/llama-server \
  -m /path/to/model.gguf \
  -c 32768 \
  --defrag-thold 0.1

在 1.0.0 中,直接删除已经失效的参数:

./build/bin/llama-server \
  -m /path/to/model.gguf \
  -c 32768

这里要做的是移除参数,而不是更换另一个阈值。不要自行猜测 --defrag-thold 的替代选项。

可以用以下命令搜索 Shell 脚本、Docker 配置、服务配置和源码中的旧引用:

grep -RInE \
  'defrag[_-]thold|llama_set_warmup|llama_set_embd_state_src' \
  ./scripts ./config ./src

请根据实际项目调整搜索目录。如果某个目录不存在,就从命令中删除该路径。

另外检查环境变量和 Wrapper 配置。有些应用会在启动时自动拼接命令行参数,即使你已经修改主脚本,旧参数仍可能从其他配置来源出现。

如何更新 C 和 Python 绑定?

如果应用直接包含 llama.h,先将代码中的接口使用方式与 v1.0.0 的公开头文件进行比较,再重新编译。

对于使用 CMake 的项目,需要使用新库重新构建依赖它的应用,并检查编译器和链接器输出。

对于 Python Wrapper,首先确认当前 Wrapper 版本是否明确支持 llama.cpp 1.0.0。

仅安装新版 llama.cpp 可执行文件,并不会自动更新 Python 扩展中已经编译好的函数定义。

如果 Wrapper 自带 llama.cpp 源码,应按照该项目的依赖更新流程操作,不要未经兼容性确认就手动替换共享库。

Python import 成功只是第一步。还应加载模型、生成 Token,并测试应用实际使用的上下文状态管理或推测解码功能。

如何在 llama.cpp 1.0.0 中启用 FP8 KV 缓存?

设置 -ctk f8_e4m3 -ctv f8_e4m3,即可请求使用 FP8 格式存储 Attention 的 Key 和 Value 缓存。

KV 缓存保存此前 Token 的注意力状态,使模型在继续生成时不必重新计算整个历史上下文。上下文越长,KV 缓存通常占用越多内存。

FP8 每个数值使用 8 bits,而 FP16 使用 16 bits。对于维度相同的张量,FP8 理论上可以将 K/V 原始数据的存储空间减少约一半。

这个估算不包含元数据、缩放系数、内存对齐、模型权重和计算缓冲区。因此,不能将其理解为整体显存占用必然下降 50%。

先使用 FP16 建立性能基线

比较 FP16 和 FP8 时,必须保持模型和上下文长度一致。

先使用 FP16 启动本地服务器:

./build/bin/llama-server \
  -m /path/to/model.gguf \
  -c 32768 \
  --host 127.0.0.1 \
  --port 8080 \
  -ctk f16 \
  -ctv f16

记录启动日志中显示的 KV Buffer 分配量、设备剩余内存、Prompt 处理速度和生成速度。

然后停止服务器,改用 FP8:

./build/bin/llama-server \
  -m /path/to/model.gguf \
  -c 32768 \
  --host 127.0.0.1 \
  --port 8080 \
  -ctk f8_e4m3 \
  -ctv f8_e4m3

1.0.0 新增的 FP8 KV 缓存还支持可选的静态 Per-Tensor Scale。

启动后检查日志,确认实际选择的缓存数据类型和分配大小。

命令行参数被识别,并不代表 GPU 后端的所有优化执行路径都支持该格式。应结合设备、模型和真实任务结果判断是否适合启用。

使用 FP8 就能把上下文长度翻倍吗?

不一定。

FP8 能减少 KV 张量存储需求,但上下文长度仍受到模型支持范围和可用内存的限制。

假设某个工作负载的 FP16 KV 缓存原始数据占用 8 GiB。在张量维度相同的条件下,FP8 原始数据可能降至约 4 GiB。

这是理论计算,并非 llama.cpp 的实测结果。

释放出的显存可能用于更长的上下文,也可能用于处理更多并发请求。但它不会让模型突破本身支持的有效上下文范围。

FP8 的数值精度也低于 FP16。官方发布资料没有给出适用于所有模型和 GPU 的编码质量或工具调用准确率结论。

如果你运行的是编码 Agent,建议用同一套仓库任务比较两种缓存格式:

  1. 从较长的源码文件中找到指定符号。
  2. 完成涉及多个文件的修改。
  3. 生成结构化工具调用。
  4. 经过多轮长对话后继续完成任务。

除了 Tokens Per Second,还要检查代码是否正确、工具调用参数能否解析,以及长会话中的任务完成情况。

新增的 MoE 专家缓存如何工作?

当 Mixture-of-Experts(MoE,混合专家)模型的专家权重存放在系统 RAM 中,而不是全部放在 GPU 显存中时,新缓存可能改善推理性能。

MoE 模型会为每个 Token 选择部分专家参与计算。解码过程中,如果频繁将专家权重从 RAM 传输到 GPU,数据传输就可能成为性能瓶颈。

MoE 专家缓存会将经常使用、原本位于 CPU 内存中的专家保留在 GPU 显存中。另一个参数允许 CPU 处理部分缓存未命中。

这与 FP8 KV 缓存是两种独立机制:

  • MoE 缓存管理模型的专家权重。
  • KV 缓存保存 Attention 状态。

官方 MoE 缓存指南说明了相关参数的作用。

参数作用默认值
-cmoe将全部 MoE 专家权重保留在 CPU 内存中不主动指定时关闭
--moe-cache-mib N为 CPU 内存中的专家分配 N MiB GPU 缓存0,禁用
--moe-cache-cpu-share F缓存填满后,由 CPU 处理比例为 F 的缓存未命中0

官方文档规定,CPU 分担比例的范围为 0 到 1。

具体运行规则如下:

  • 缓存命中的专家在 GPU 上执行。
  • 缓存填满之前,未命中的专家会上传到 GPU。
  • 缓存填满之后,CPU 根据配置的比例处理一部分未命中。
  • 剩余未命中仍会上传到 GPU 执行。
  • 大批量处理仍可能需要上传所使用的专家权重。

如果 CPU 从 RAM 读取专家权重的速度快于 GPU 接收这些权重的传输速度,让 CPU 分担计算可能有帮助。

Pinned Host Memory(固定页主机内存)会影响这一取舍。如果 GPU 已经能充分利用传输带宽,高效上传专家权重,那么增加 CPU 分担比例可能几乎没有收益。

示例:缓存存放在 RAM 中的 MoE 专家

这个配置要求模型和 GPU 后端支持相关功能,并且 GPU 有足够的空闲显存。

只有 CPU 的编译版本无法提供这里介绍的 GPU 专家缓存。

如果使用 NVIDIA GPU,并且已经安装所需的 CUDA 开发环境,可以按照官方 CUDA 编译说明运行:

cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

对于其他受支持的 GPU 平台,应使用对应后端的官方编译参数。

在支持 MoE 缓存的 GPU 编译版本中,可以通过以下命令启动兼容的 MoE 模型:

./build/bin/llama-server \
  -m /path/to/moe-model.gguf \
  -cmoe \
  -c 32768 \
  --host 127.0.0.1 \
  --port 8080 \
  --moe-cache-mib 2048 \
  --moe-cache-cpu-share 0.5

这里的 -cmoe 表示将全部 MoE 专家权重放在 CPU 内存中。

--moe-cache-mib 2048 请求分配 2,048 MiB GPU 缓存,用于保存选中的专家。

--moe-cache-cpu-share 0.5 表示缓存填满之后,由 CPU 处理 50% 的缓存未命中。

注意,这个比例只在缓存填满后发挥作用。缓存未填满之前,未命中的专家仍会上传到 GPU;缓存命中始终由 GPU 执行。

以上参数只是配置示例,并不是所有硬件的推荐值。

GPU 还需要为模型层、KV 缓存和计算 Buffer 保留空间。专家缓存越大,可供其他部分使用的显存就越少。

如果分配失败或显存不够,可以缩小缓存,或者重新安排模型权重的位置。MoE 缓存不会自动让超出硬件容量的模型成功运行。

使用官方调优脚本选择缓存配置

llama.cpp 提供了专门的脚本,用于测试不同的专家缓存参数。

在 llama.cpp 仓库目录中运行:

python3 scripts/moe-cache-tune.py -- \
  ./build/bin/llama-server \
  -m /path/to/moe-model.gguf \
  -cmoe \
  -t 8 \
  -c 32768

官方调优脚本会以不同的缓存大小和 CPU 分担比例启动服务器。

根据官方说明,脚本进行六组测量:两种缓存大小,分别搭配 0、0.5 和 0.95 三个 CPU 分担比例。

随后,脚本利用测量值估算其他配置,并输出实测速度、预测吞吐量和推荐参数。

运行时应保留自己的真实模型、CPU 线程数、上下文长度和专家放置设置。这些参数直接影响可用显存与推理速度。

该缓存主要针对小批量解码,包括普通生成和推测解码。大批量处理仍可能需要上传专家权重。

如果使用的是 Dense 模型,或者全部专家权重本来就能放进 GPU,主机内存专家缓存通常没有明显用处。此时先保留默认的禁用状态。

llama-server 1.0.0 的安全设置有哪些变化?

1.0.0 为两类敏感操作增加了明确的安全许可开关:未认证的服务器工具访问,以及对私有网络媒体 URL 的访问。

当 llama-server 不仅供本机使用,还允许其他设备连接时,这些设置尤其需要检查。

—allow-unauthenticated-tools

--allow-unauthenticated-tools 允许在服务器监听非回环地址、且未配置 API Key 的情况下,公开服务器工具、MCP 服务器或 MCP 代理。

根据官方服务器参数说明,这项权限默认关闭,仅适用于受信任的网络。

这里需要区分服务器的监听地址:

  • 使用 127.0.0.1 监听时,服务限制在本机访问。
  • 使用 0.0.0.0 监听时,服务可能通过其他网络接口被访问。

因此,如果服务器同时满足非回环地址监听、启用服务器工具或 MCP、未配置 API Key 这几个条件,就需要明确检查其安全风险。

对应开关为:

--allow-unauthenticated-tools

不要将它当作升级后的常规修复参数直接加上。它会明确允许未认证用户访问具有安全风险的服务器功能。

还要区分两种行为:服务器端工具或 MCP 的执行权限,与模型在响应中生成结构化 tool_calls,并不是同一回事。

如果你只在本机开发,优先使用回环地址:

./build/bin/llama-server \
  -m /path/to/model.gguf \
  --host 127.0.0.1 \
  --port 8080 \
  --jinja

需要让远程客户端连接时,应使用文档支持的 --api-key 认证方式,并配合网络访问限制。

在 Bash 中,可以不回显输入内容地读取 API Key:

read -rs LLAMA_SERVER_API_KEY && export LLAMA_SERVER_API_KEY

执行后,终端会等待输入密钥。输入内容不会显示在屏幕上,也不会作为命令参数写入 Shell 历史。

随后通过环境变量启动服务器:

./build/bin/llama-server \
  -m /path/to/model.gguf \
  --host 0.0.0.0 \
  --port 8080 \
  --jinja \
  --api-key "$LLAMA_SERVER_API_KEY"

应同时配置防火墙或其他适当的网络访问控制。仅有 API Key 并不意味着可以安全地把任意服务器直接暴露到公网。

—media-allow-private-urls

第二项变化涉及服务器收到的 HTTP(S) 媒体 URL,包括图像引用。

在默认安全设置下,服务器不允许通过媒体 URL 请求本机地址或私有网络地址。

需要显式允许时,使用:

--media-allow-private-urls

启用后,服务器可以访问指向本机或私有地址的 HTTP(S) 媒体资源。

如果可信应用把图片保存在内部服务中,这个功能可能有用。

但如果不可信用户能够控制媒体 URL,就会增加 SSRF(服务器端请求伪造)风险。攻击者可能尝试诱导服务器访问原本不应该暴露的内部资源。

更安全的做法是优先使用 API 支持的直接图像数据提交方式,或者采用受控的媒体托管服务。

如果业务必须访问私网媒体 URL,应限制可以发起请求的用户,以及服务器能够访问的目标地址。不要仅为了让一个未知来源的 URL 加载成功就打开该开关。

其他服务器安全修复

1.0.0 还包括以下安全改动:

  • 修复 --cors-origins 的验证和 Origin 匹配。
  • 增强 DNS Rebinding 防护。
  • 修复通过 CORS 代理发起 SSRF 的问题。
  • 修复浏览器直接访问子服务器实例的相关问题。
  • 限制 HF_TOKEN 的传输目标。
  • 客户端断开连接或请求超时后,取消相关 MCP 工具调用。

其中,HF_TOKEN 现在限制为仅向 huggingface.co 主机发送。

对于连接 MCP 的编码 Agent,取消机制有助于避免客户端已经断开后,相关工具调用继续无意义地运行。

不过,取消通知并不保证外部工具能够撤销已经执行完成的操作。

可以查阅 PR #32113、PR #32115 和 v1.0.0 Release Notes,了解这些安全变更。

升级后如何验证本地编码 Agent 后端?

先确认 llama-server 能正常生成内容,再连接 Claude Code、OpenCode 或其他编码客户端。

第一步是在本机启动服务器,并使用适合指令遵循任务的编码模型。

./build/bin/llama-server \
  -m /path/to/coding-model.gguf \
  --alias local-coder \
  -c 32768 \
  --host 127.0.0.1 \
  --port 8080 \
  --jinja

这里的模型需要具备客户端要求的工具调用能力。

--jinja 用于启用聊天模板处理,但它不会让原本不支持工具调用的模型自动获得这项能力。

使用 curl 检查模型列表接口:

curl --fail-with-body \
  http://127.0.0.1:8080/v1/models

正常情况下,返回的模型列表应包含配置的 local-coder 别名。

然后发送一个简单的聊天补全请求:

curl --fail-with-body \
  http://127.0.0.1:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "local-coder",
    "messages": [
      {
        "role": "user",
        "content": "Explain what a Git diff shows in one sentence."
      }
    ],
    "max_tokens": 100
  }'

请求成功后,应在响应的 choices 字段中看到模型生成的内容。

接下来,按照编码客户端的官方文档配置自定义 Provider。

本地 OpenAI 兼容接口的 Base URL 为:

http://127.0.0.1:8080/v1

注意,支持 OpenAI Chat Completions 不代表同时完整支持 Anthropic Messages API 或 OpenAI Responses API。

如果要接入 Claude Code,可能需要协议适配器或其他受支持的接入方式。

OpenCode 则可以使用兼容的自定义 Provider,前提是所选模型和接口协议与客户端配置相匹配。

正式连接真实代码仓库前,至少完成三个测试:

  1. 让 Agent 读取一个仓库文件。
  2. 让 Agent 提出一项文件修改。
  3. 让 Agent 执行一次工具调用。

如果只是普通文本生成成功,还不能证明结构化工具参数、文件编辑或长会话上下文都能正常工作。

如果还在选择编码模型,可以参考 Kimi K3.1 Pro 的 Claude Code 与 Codex 接入指南。Kimi K3.1 Pro 开放权重与许可证指南则介绍了本地模型权重、硬件要求与托管 API 之间的区别。

Ollama 和 LM Studio 用户需要立即升级吗?

如果你只是通过 Ollama 或 LM Studio 使用本地模型,没有直接编译或配置 llama.cpp,就不需要手动替换这些应用内部的推理库。

这类应用通常自行管理推理引擎版本、软件打包和兼容性测试。

llama.cpp 1.0.0 发布,并不代表所有依赖它的下游应用已经同步采用这个版本。

应通过各应用自己的更新方式和 Release Notes,确认实际使用的运行时版本。

以下情况值得重点关注:

  • 更新说明明确提到 llama.cpp 1.0.0 或相关上游变更。
  • 应用开始提供新的 KV 缓存格式或 MoE 缓存设置。
  • 服务器工具或 MCP 的认证要求发生变化。
  • 更新应用后,模型加载或工具调用行为与以前不同。

如果只是使用桌面聊天功能,而当前受支持的版本运行正常,也不需要某项新功能或修复,可以继续使用现有版本。

但如果 Ollama 或 LM Studio 是编码 Agent 的模型后端,每次更新应用后,都应该测试完整的客户端到服务器调用流程。

什么情况下应该考虑托管 API?

当本地硬件能够以所需速度运行目标模型,并支持足够的上下文长度时,本地推理仍然是合理的选择。

FP8 KV 缓存可能减少内存压力。MoE 缓存则可能改善部分专家权重放在 RAM 中的工作负载。但两者都不能解决所有硬件限制,也不保证编码任务一定更快。

如果模型权重、Attention 缓存或并发请求超过可用硬件资源,可以比较更小的本地模型和托管模型。

托管 API 可以免去自行管理模型 GPU 显存的工作,但需要考虑网络依赖、按量使用成本和服务提供方的限制。

BetterToken 是一种提供多模型、按量计费 API 接入的选择。它与本地 llama.cpp 执行相互独立,不提供 llama.cpp 运行时,也不提供其服务器安全功能。

选择托管模型前,可以在当前价格页面查看模型价格,并根据自己的工作负载估算使用成本。

如果准备让编码 Agent 在本地模型和托管模型之间切换,建议分别保留两套经过测试的 Provider 配置。

不要假设两种接入方式使用相同的模型 ID、工具调用格式或认证参数。

llama.cpp 1.0.0 安全升级检查清单

准备把生产环境中的本地编码 Agent 后端升级到 1.0.0 时,逐项确认:

  1. 固定 v1.0.0 源码版本或精确的编译产物。
  2. 删除 --defrag-thold 和已经移除的 C API 调用。
  3. 使用新的公开头文件重新编译原生绑定。
  4. 先沿用之前的 FP16 KV 缓存设置验证功能。
  5. 单独测试 FP8 KV,比较内存、速度和编码正确性。
  6. 仅在具备兼容 GPU 后端、专家权重位于 CPU 内存的条件下调整 MoE 缓存。
  7. 检查服务器工具认证和私网媒体 URL 访问限制。
  8. 验证 /v1/models、聊天补全、工具调用及编码客户端。
  9. 保留原来的二进制文件和配置,以便出现问题时回滚。

llama.cpp 1.0.0 为公开 C 库建立了更清晰的兼容性边界。但一次升级是否安全,仍取决于你的绑定代码、硬件、服务器网络暴露范围和实际 Agent 工作流程。

BetterToken · 企业采购
企业专属价
支持开发票对公转账 / 支付宝 / 微信支付全系列文本 / 编程、图像、视频模型
文本 / 编程
图像
视频
专属技术支持领取企业折扣价目表 →