llama.cpp 本周发了 v1.0.0:移除一批弃用 API、加 FP8 KV 缓存与语音端点、集中修服务端安全问题。这篇按官方 Release 与文档,把「从旧版本升上来」做成 9 步可照做的迁移与验收清单,附 9 个真实会卡住的坑。
llama.cpp v1.0.0 升级实操:迁移清单与服务加固
这篇教程解决什么
2026 年 11 月 13 日,llama.cpp 发布 v1.0.0。这不是又一个以 b 开头编号的自动构建:官方 Release 里写明,这个版本移除了弃用的公开 API、把 NextN(推测解码)相关接口提升到 llama.h、加入 OCP FP8 格式的 KV 缓存、给服务端补上安全开关与语音端点,并重做了内置网页界面。版本号跨到 1.0,意味着它带着破坏性变更,从旧版本直接覆盖可能编译不过。
这篇要做的事很具体:把「从旧版本升到 v1.0.0」拆成一条能照做的路径 —— 先查破坏性变更清单,再构建并跑通一个最小服务,然后验证两项新能力,最后在把服务暴露给局域网或公网之前装好护栏。读完你会得到一组命令与配置、每一步「看到什么算成功」的判据,以及一份上线前的验收清单。
先说清不覆盖什么:不跑通用基准、不比推理速度、不做模型质量评测、不给具体金额。FP8 KV 缓存能省多少显存、会不会影响输出这类问题,官方 Release 没有给可移植的通用结论,得用你自己的模型与查询集实测;本站不写无法复现的数字,价格与套餐额度一律以官网为准。也不替你决定「该不该把本地服务对外开放」,只把官方写明的安全默认值摆出来。
还有个容易先搞混的点:本地推理引擎解决的是「模型跑在哪、怎么被调」,与「给智能体用的浏览器」是两层东西,别把两边的配置混着抄。权限加固的思路倒是可复用,MCP 参考服务器的权限加固教程 讲的是同一类「先收边界再谈能力」的做法。事件本身见 llama.cpp 发布 v1.0.0 快讯。
开始前的准备
按官方文档与 Release 逐条对齐,缺一条后面某一步就会卡住:
- 固定到 v1.0.0 这个 tag,不要拿滚动更新的主分支当升级目标。主分支的命令名与文档可能已经比这个 tag 新,照着抄会对不上。
- 构建工具链:CMake 与可用的 C/C++ 编译器。官方服务端文档给的路径是先 cmake 生成构建目录,再构建 llama-server 这个目标,产物落在构建目录的 bin 下。需要 SSL 时用 OpenSSL 相关构建选项,随后以对应的证书与私钥参数启动。具体选项名以官方构建文档当期版本为准。
- 另一条更快的路:官方 README 的快速上手还提供了安装脚本、预编译二进制、容器镜像,以及按 Hugging Face 仓库名直接拉模型并运行的写法。命令名在不同版本会变,本文不把某一种写法当成通例 —— 以你切到的那个 tag 的官方 README 为准。
- 至少一份 GGUF 模型文件,以及与之匹配的内存或显存。模型的许可与来源自行核对;官方还提示,若机器经企业代理上网,先设好 HTTP 与 HTTPS 代理环境变量再执行会下载模型的命令,NO_PROXY 里的主机与回环地址会直连。
- 本地端口 9931 空闲。官方服务端文档写的默认监听地址是 127.0.0.1:9931,内置网页界面在同一地址,默认启用。
- 备份现有配置与启动脚本。若你的程序直接调用 libllama 的 C 接口,先把第 1 步的移除清单跑完再动手,否则升级会变成一次排查编译错误的长会。
- 成本与授权认知:本地运行不涉及按次调用计费,付出的是硬件、模型下载与维护;仓库内第三方组件各自保留原许可,二次分发前值得先看官方的第三方声明。具体套餐与额度以官网为准。
一句话概括前提:本地跑通只需要工具链与模型,把服务暴露出去才涉及认证与网络边界。先把工具链对齐,别一上来就研究对外开放。
步骤详解
第 1 步:先查破坏性变更清单
做什么:在自己的代码、构建脚本与启动参数里逐项搜官方 Release 列出的名字。v1.0.0 明写移除 llama_set_warmup、35 个弃用函数、defrag_thold 以及对应的命令行开关;把 NextN 接口从 llama-ext.h 提升到 llama.h,并把 llama_set_embd_state_src 改名为 llama_set_ctx_state_src;上下文参数里新增 moe_cache_size 与 moe_cache_cpu_share;多模态侧移除 clip.h、统一收敛到 mtmd,并在 mtmd.h 里新增戏剧化语音类型与温度参数。
看到什么算成功:搜不到被移除的名字,改名后的符号能编译通过,启动脚本里没有已删除的开关。这一步最容易被跳过,也最容易在后面变成「编译报一堆未声明符号」的假故障。
第 2 步:取回仓库并固定版本
做什么:克隆官方仓库、进入目录、切到 v1.0.0 这个 tag。
git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp
git checkout v1.0.0
看到什么算成功:版本查询指向 v1.0.0,而不是一串 b 加数字的自动构建标签。这里有个老坑值得记住:聚合订阅里的标题与更新时间常与真实 tag 对不上,标题写正式版、实际可能是候选版;判据要回官方 Release 页面核标签名与发布时间,别跟着订阅源的日期走。
第 3 步:构建
做什么:生成构建目录并编译服务端目标。
cmake -B build
cmake --build build --config Release -t llama-server
看到什么算成功:构建目录下出现可执行文件,运行帮助参数能正常打印。首次构建要编译的项目多、耗时长于后续增量构建,不要把它当成卡死而中断。若需要 SSL,按官方构建文档加上 OpenSSL 选项重新生成并编译。
第 4 步:跑起最小服务并确认健康
做什么:用一份本地模型启动服务端;官方服务端文档的示例写法是给定模型路径与上下文长度。
./build/bin/llama-server -m models/7B/ggml-model.gguf -c 2048
看到什么算成功:默认监听在 127.0.0.1:9931,内置网页界面在同一地址;健康检查返回状态 ok,模型仍在加载时返回 503 并给出加载中提示。官方写明健康检查是公开的、不做 API key 校验,等价的 v1 前缀路径也可用。容器方式启动时,官方示例为了容器外访问会显式改主机与端口,那属于部署场景,本地验证不必照做。
第 5 步:用 OpenAI 兼容端点发一次请求
做什么:向 v1 前缀的聊天补全端点发一个最小请求,带 JSON 内容类型头与鉴权头。官方示例里鉴权头用的是占位值,因为服务端默认没有配置 API key。
curl http://127.0.0.1:9931/v1/chat/completions -H "Content-Type: application/json" -H "Authorization: Bearer no-key" -d '{"model":"local","messages":[{"role":"user","content":"ping"}]}'
看到什么算成功:拿到带选项数组的 JSON 回复。这里要记牢一条路径差异:官方明确写了无前缀的 completion 端点不兼容 OpenAI 规范,兼容路径是带 v1 前缀的那个;嵌入与重排同理各有对应的兼容路径。把无前缀端点当兼容端点用,是联调时很常见的一类假故障。
第 6 步:启用 FP8 KV 缓存
做什么:官方 Release 给出的写法是为键与值分别指定 f8_e4m3 类型,并支持可选的静态逐张量缩放。在启动参数里加上这两个类型后重启服务。
./build/bin/llama-server -m models/7B/ggml-model.gguf -c 2048 -ctk f8_e4m3 -ctv f8_e4m3
看到什么算成功:服务正常起、健康通过、同一段输入能出结果。取舍要写清:这是拿精度换显存与带宽的开关,是否划算要用你自己的模型与查询集测;官方 Release 没有给通用的节省倍数,本站也不转述任何性能数字。上线前把「开与不开」两种配置各留一份输出对照,比看别人的结论可靠。
第 7 步:试一次语音输出
做什么:v1.0.0 为服务端新增了 OpenAI 兼容的语音合成端点,并给原有的文本转语音端点补充了温度选项。官方服务端文档当前完整写出的是无 v1 前缀的文本转语音端点,返回原始音频字节而非 JSON,官方给的 curl 示例是向该端点 POST 一段带 input 字段的 JSON 并把响应写成 wav 文件。
curl -X POST http://127.0.0.1:9931/tts -H "Content-Type: application/json" -d '{"input":"Hello, this is a test."}' -o output.wav
看到什么算成功:本地多出一个能播放的 wav 文件。两个端点路径在 Release 与服务端文档里的口径可能不同步,先用模型信息端点看输出模态里有没有 audio,再按官方当期文档选路径,别照抄第三方教程里的地址。官方还建议尽量提供参考音色,否则语音效果可能下降;音色列表、语言代码与响应格式等选项以官方服务端文档为准。
第 8 步:把护栏装好,再考虑对外开放
做什么:逐项核对官方写明的安全默认值,全部按最小权限收一遍。
(1)认证:API key 默认是 none,也就是默认没有认证。官方对公网部署的建议是设置 API key 并把服务放到反向代理后面;也支持从文件逐行读取多个 key。
(2)CORS:允许的来源默认很宽,且默认会把任意 Origin 回显并允许携带凭据;官方写明这只在只暴露无状态只读端点时才可接受。一旦启用内置工具或智能体相关开关,允许的来源会默认收敛到 localhost;自己显式传一个宽泛值,等于把这层默认保护撤掉。
(3)两个新增的显式开关:v1.0.0 增加了「允许未认证工具」与「允许私有地址媒体 URL」两个 opt-in,默认都是关闭。前者允许在非回环地址、无 API key 的情况下使用服务端工具与 MCP;后者允许媒体 URL 指向本地或私有地址。两者都别为了「先跑通」就打开。
(4)本地媒体:媒体目录默认禁用,本地文件要按官方文档加目录参数并用 file 前缀引用。
(5)其他端点:属性修改、指标、槽位监控等端点的默认值各不相同,按需关闭不需要的。
(6)本次修复项:官方 Release 还写明集中修了 CORS 来源、DNS rebinding、CORS 代理侧的 SSRF 与子实例访问,把 Hugging Face 令牌限制到对应主机,并在客户端断开或超时时取消 MCP 工具调用且通知 MCP 服务端。服务端文档可见部分没有逐条展开 DNS rebinding 与 SSRF 的配置,所以这里按 Release 措辞记为「本次修复项」,具体开关以官方当期文档为准。
看到什么算成功:不带 key 的请求被拒、指向私有地址的媒体被拒、工具相关开关保持关闭、服务仍只绑在回环地址。把这几条写成部署前的断言,比上线后靠记忆检查可靠。
第 9 步:把升级变成可重复的动作
做什么:把 tag、构建选项、启动参数、护栏开关与第 4 至第 8 步的验收判据写成一份脚本或清单。下次升级先跑第 1 步的移除清单,再跑第 8 步的断言。
看到什么算成功:换一台机器也能按同一份清单复现,且每次升级都能明确回答「这次有没有动过认证与网络边界」。版本升级不是一次性事件,把它日常化才不会在半年后无人记得哪些开关曾经被临时打开过。
常见坑与排错
编译报「未声明的符号」。 多半命中第 1 步的移除清单:弃用函数、热身函数、碎片整理阈值开关,或已被收敛掉的旧多模态头文件。先按名字搜一遍,别急着怀疑编译器或构建目录坏了。
tag 看着像正式版,其实是自动构建。 官方 Release 同时存在 v1.0.0 这样的语义化标签与 b 加数字这类滚动构建标签;订阅源里的标题与更新时间也可能与真实标签对不上。判据是回官方 Release 页面核标签名与发布时间,并用版本查询确认本地切到的确实是 v1.0.0。
把无前缀端点当 OpenAI 兼容端点。 官方明确写了无前缀的补全、嵌入、重排端点不兼容 OpenAI 规范,各自有带 v1 前缀的对应路径,且响应格式可能不同。客户端报字段缺失时先查路径,别先改解析代码。
以为默认就带认证。 API key 默认没有配置,健康检查更是公开且不校验。把监听地址从回环改成对外可访问之前,必须先设 key、收 CORS、并放到反向代理后面 —— 这个顺序反了,中间会有一段无保护的窗口。
开了工具就把 CORS 一起放开。 启用内置工具、智能体或 MCP 配置时,官方写明允许的来源会默认收敛到 localhost;若你为了「网页能连上」显式传了宽泛值,这层默认保护就没了。官方对工具、智能体与 MCP 配置都标了不要在不可信环境启用,内置工具更是直接标了实验性质。
私有地址的媒体加载失败。 允许私有地址媒体 URL 的开关默认关闭,本地文件应走媒体目录加 file 前缀的路径。为图省事打开私有地址放行,等于把服务端变成探测内网的工具,不值得。
语音端点返回 404。 Release 里的 OpenAI 兼容语音端点与服务端文档里完整写出的文本转语音端点,路径口径可能不同步。先用模型信息端点确认输出模态里有没有 audio,再按官方当期文档选路径;也确认模型本身是能生成语音的那类,而不是普通文本模型。
MCP 子进程权限超预期。 官方写明 MCP 只支持 stdio 传输,子进程与服务端同权限,所以只声明你信任的命令;每服务器可设单次工具调用超时,工具名按服务器名加工具名暴露,与内置工具彼此独立。别把「能挂 MCP」理解成「挂什么都被隔离」。
首次启动健康检查返回 503。 这是模型仍在加载的官方提示,不是服务失败。等状态转为 ok 再发业务请求,别在加载阶段就重启一遍。
进阶用法
把工具挪进隔离运行时。 官方提供工具运行时参数,可让内置工具在容器或经 SSH 的远端环境执行:容器方式会在启动时新建、复用并在服务退出时清理,也可用已有容器;远端方式要求密钥认证与可信主机密钥。文件读写类能力挪出宿主环境,出事时的爆炸半径小得多。
只挂 MCP,不启内置工具。 MCP 配置接受兼容 Cursor 的 JSON 文件,也可内联传入;每个条目可给命令、参数、环境变量、工作目录与单次超时。官方说明每个 MCP 服务端在启动时派生一次以列出工具、随后按需重新派生,工具与内置工具一样出现在网页界面与工具列表里,因此与内置工具开关相互独立 —— 可以只挂 MCP。配置格式与可用字段以官方当期文档为准。
MoE 与外部分片。 上下文参数新增的两个字段控制主机内存里的专家缓存大小与 CPU 占比,官方 Release 还写到可从独立 GGUF 分片加载外部 PLE 或 engram 数据,对应分片与 PLE 两个启动参数。这些面向大模型与特定硬件,含义与取值以官方当期文档为准,本文不替它写死。
SSL 与可观测。 需要加密传输时按官方构建文档启用 OpenSSL 选项,再用证书与私钥参数启动;指标端点默认关闭,打开后可接 Prometheus 兼容的采集。把会话、失败率与出站目标记进日志的做法,可对照 把智能体追踪接进 OTLP;来访身份分级可看 站点智能体访问分级教程。
参数优先级与布尔写法。 官方写明同一参数同时由命令行与环境变量给出时,命令行优先;布尔型参数接受 true / false、1 / 0、on / off、enabled / disabled 几组写法。用环境变量管理一整套部署参数时,这一条决定了「为什么我改了变量却没生效」。
常见问题
升级到 v1.0.0 一定要改代码吗?
看你怎么用。只跑现成可执行文件、通过 HTTP 端点调用的人,通常要做的只是核对启动脚本里有没有被删掉的开关;而直接链接 C 接口、自己写推理循环的程序,要先过第 1 步的移除与改名清单 —— 这个版本明确删了 35 个弃用函数与一个热身函数,还改了一个状态相关函数的名字,多模态侧也把旧头文件收敛了。稳妥顺序是先在自己的代码里搜名字、再切 tag、最后构建;反过来做会把「清单里早就写明的变更」变成一堆莫名其妙的编译错误。
FP8 KV 缓存能省多少显存、会不会掉质量?
官方 Release 只说明新增了这个能力和对应的类型写法,没有给可移植的通用数字,本站也不转述任何性能倍数或质量结论。这类开关的结果与模型、量化方式、上下文长度、硬件都相关,别人的数字搬到你这里通常不成立。做法是拿自己的模型与一份固定查询集,在开与不开两种配置下各跑一遍,对比输出与资源占用,再决定要不要进默认启动参数。把它当成需要验收的配置项,而不是「升级附赠的加速」。
可以把这个服务直接放到公网给团队用吗?
不建议按默认配置这么做。官方写明 API key 默认没有配置、健康检查公开不校验,允许的来源默认很宽且会回显任意 Origin 并允许携带凭据;官方自己给的公网部署建议是设置 key、把服务放到反向代理后面,CORS 来源按需收紧。两个新增的显式开关默认关闭,也别为了联调打开。顺序同样是先收边界再改监听地址,否则从改地址到配置生效之间会有一段无保护窗口。具体参数名与默认值以官方当期文档为准。
语音端点到底该用哪个路径?
按官方当期文档选,别照抄第三方教程。v1.0.0 的 Release 写明新增了 OpenAI 兼容的语音合成端点,并给原有文本转语音端点补了温度选项;而服务端文档当前完整写出的是无 v1 前缀的文本转语音端点,返回原始音频字节。两处口径可能不同步,稳妥做法是先用模型信息端点看输出模态里有没有 audio,确认手上的模型确实能生成语音,再按文档选路径、按文档写请求体。官方还建议提供参考音色,具体音色与语言参数看官方服务端文档。
为什么教程里不给具体的性能数字和价格?
因为这两类数字最容易过期、也最容易被误用。性能取决于模型、硬件与量化方式,官方 Release 没有给通用结论,本站不跑通用基准、也不编第一人称实测;价格、套餐与额度一律以官网为准。这篇能给的是可照做的步骤、每步的成功判据和已知的边界 —— 把这些做实,比抄一组会过期的数字更有用。真要评估收益,用你自己的模型与查询集固定配置跑对照即可。
相关工具与内容
本周事件见 llama.cpp 发布 v1.0.0 快讯。本地推理与部署相关的另几条路可看 Ollama 上的决策模型、Ollama 上架 Ripple Preview 与 搭本地跨模态检索;版本迁移这一类型的方法论可对照 Claude API 版本升级教程。
权限与观测方面,MCP 参考服务器的权限加固、站点智能体访问分级教程 与 把智能体追踪接进 OTLP 分别对应边界、身份与日志三件事。
同批的 AI 智能体碰钱怎么授权 讲的是消费侧的授权取舍,与本文的本地服务部署侧互补(该内链需两篇成对发布才生效)。按类目浏览可进 AI编程工具、AI智能体 与 AI音频;站内已核实的 Claude Code、Dify、n8n 分别对应编码、自建编排与自动化三种接法。
相关内容
Inkling 2 Mini 开放权重:循环混合专家模型主打本地运行,约 20GB 内存占用
Thinking Machines Lab 于 2026 年 11 月 20 日发布 Inkling 2 Mini,开放模型权重并提供可变循环研究版。官方说明它是 26.4B 总参数、3.4B 激活的循环混合专家模型,中间层对每个 token 运行三次,权重以内生的 NVFP4 与 MXFP8 精度部署,内存占用约 20GB,支持 Ollama、vLLM、SGLang 等多种推理路径。许可名称与上下文窗口官方页未写明,以官网为准。
编码助手换模型怎么验收:从基线到弃用期的八步
11 月 16 日 Copilot 三款模型下线,11 月 17 日 Copilot Evals 进入公开预览。这篇教程给一套可照做的验收流程:盘点写死模型名的地方、建样本集、写判据、跑基线、双跑对比、归因失败,最后挂成变更门禁。
自托管 Kitesurf:把智能体浏览器跑在本地的完整步骤
Cloudflare 本周把 Kitesurf 以 Apache 2.0 开源。这篇按官方仓库说明,在自己的机器上把它跑起来、用 Puppeteer 连上去截一张图,并给出部署前必须装好的认证护栏与六个真实会卡住的坑。
继续阅读:ChatGPT Wallet 发布:智能体可代付,但不接触真实卡号 · Google Wallet 接入 Gemini:个人财务问答走只读授权,资金仍碰不到