如何固定 llama.cpp 服务器版本标签

llama.cpp 版本标记发生了哪些变化

固定 llama.cpp 的版本发布意味着构建一个指定名称的标签，并将该名称记录在模型文件旁边。标签不会自行移动，因此服务器今天生成的结果与明天相同。多年来，只有一种标签可供选择：类似 b10502 的构建编号，由 master 自动生成。从 2026 年起，新增了第二种标签，即类似 v0.1.2 的版本标签；两条发布轨道会在同一时间基于相同的历史记录生成。

这些版本标签目前还不具备版本号通常代表的含义。v0.1.2 中的发布说明用一行文字明确说明了这一点：

语义化版本控制仍在完善中。更多信息请参阅 https://github.com/ggml-org/ggml/discussions/1579

请按字面理解这句话。该链接背后的 ggml 讨论 仍在制定这套方案，包括发布频率以及哪些变更算作补丁版本。v0. 标签表示项目选择在历史记录中标记一个节点。它并不保证下一个标签只因末位数字增加 1，就能安全地直接替换。

构建标签中的数字同样不代表版本含义。该数字来自提交次数，因此无论是否有与你的环境相关的变化，都会自行递增。截至 19 August 2026，发布列表首页共有 9 个构建标签，范围从 b10455 到 b10502，其中包括 v0.1.2。

不要在承载任何服务的服务器上直接从 master 构建

git pull 后再重新构建，会得到过去几小时内合入的最新内容。这在笔记本上没有问题。但在服务器上，这会让您无法回答行为发生变化时最重要的问题：当前运行的是什么，上周运行的又是什么。模型生成的文本及其生成速度都会随构建版本变化。如果有人反馈上周二的回答质量变差，而您从未记录上周二对应的提交，就无法查明原因。

请改为固定使用某个 tag。项目会为您创建这些 tag，每个预构建的发布归档也都以对应的 tag 命名。

应将 llama.cpp 版本固定到哪个标签？

如果需要固定到一个明确且已知的状态，请固定构建标签。这条轨迹历史更长，发布归档也使用该轨迹命名，大多数错误报告也会引用它，因此构建编号最容易与其他人的版本进行比较。

如果更倾向于跟踪较短的明确节点列表，请固定版本标签。升级前先阅读其说明，并牢记上文的注意事项，因为当前的编号还不能作为兼容性保证。

无论选择哪种方式，运维规则都相同。标签字符串保存在文件中。只有该字符串发生变化时，才重新构建服务器。每次修改都应是经过明确决策的操作。

构建固定标签

sudo apt update
sudo apt install -y build-essential cmake git
git clone --depth 1 --branch b10502 https://github.com/ggml-org/llama.cpp.git ~/src/llama.cpp-b10502
cd ~/src/llama.cpp-b10502
git describe --tags

git describe --tags 应输出 b10502。在标签处执行浅克隆只包含该提交，不包含之后的提交，因此不会有人因疏忽执行 git pull 将其移动。若 configure 步骤因缺少依赖项而停止，请安装它提示的依赖项，然后重新运行。

根据硬件需求使用相应选项进行构建。仅使用 CPU：

cmake -B build
cmake --build build --config Release -j $(nproc)

使用 NVIDIA GPU，需先安装 CUDA toolkit：

cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j $(nproc)

仅使用 CPU 的主机上使用 OpenBLAS：

cmake -B build -DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS
cmake --build build --config Release -j $(nproc)

二进制文件会生成在 build/bin 中，与其加载的共享库放在一起（libllama.so 和 libggml 文件）。安装前确认构建结果可以运行：

./build/bin/llama-server --version

将整个目录安装到以标签命名的路径下，然后让一个符号链接指向该目录：

sudo install -d /opt/llama.cpp/b10502
sudo cp -a build/bin /opt/llama.cpp/b10502/bin
sudo ln -sfn /opt/llama.cpp/b10502 /opt/llama.cpp/current

复制整个目录，不要只复制单个文件。单独的 llama-server 首次运行时会因 error while loading shared libraries: libllama.so: cannot open shared object file 失败，因为它需要的库就在该目录中，与它位于同一层级。

让服务指向该符号链接，不要指向标签目录：

[Service]
ExecStart=/opt/llama.cpp/current/bin/llama-server -m /srv/models/model-q4_k_m.gguf -c 8192 -ngl 99 --host 127.0.0.1 --port 8080

systemd 启动进程时会解析符号链接，因此切换构建版本只需更改符号链接目标并执行 sudo systemctl restart llama-server。其余 unit 文件配置以及前置反向代理的配置，请参阅VPS 上部署 llama.cpp 服务器的完整指南。

记录 GGUF 文件旁的标签和量化级别

构建版本决定输出结果的一半。模型文件决定另一半。GGUF（GGML 通用文件格式）是权重发布时使用的容器。同一模型通常会以多个量化级别发布，因此，即使两台服务器使用相同的标签，结果仍可能不同：一台使用 Q4_K_M 文件，另一台使用 Q8_0 文件。在模型旁保留一个小文件，记录完整的重建信息，以便精确还原环境：

tag: b10502
commit: 7c1f2a9
model_file: model-q4_k_m.gguf
model_sha256: <output of sha256sum>
quant: Q4_K_M
cmake_args: -DGGML_CUDA=ON
cuda: <output of nvcc --version>
bench_cmd: llama-bench -p 512 -n 128 -r 5
bench_result: <fill in from the run on this box>

在固定的 checkout 中使用 git rev-parse --short HEAD 获取提交。使用 sha256sum model-q4_k_m.gguf 获取校验和，并在下载时将其与发布者提供的值进行比较，因为将下载文件与发布的校验和进行比对可以在截断文件引发难以定位的问题前发现它。量化级别本身对回答的影响程度是另一个问题，不同量化级别的代价对此有详细说明。

如何升级而不影响服务器？

将升级作为一次演练。将新标签构建在旧版本旁边，测量两个版本，并保留旧版本，直到新版本验证成功。

1. 将新标签克隆到单独的目录中。不要复用旧的 checkout。
2. 使用 manifest 中记录的相同 cmake 参数进行构建。
3. 使用相同的模型文件、相同的 prompt 长度和相同的重复次数，在两个构建版本上运行 llama-bench。
4. 向两个服务器发送一个你熟悉答案的 prompt，然后读取两条回复。
5. 移动符号链接，重启服务，并将旧目录保留在磁盘上。

/opt/llama.cpp/b10502/bin/llama-bench -m /srv/models/model-q4_k_m.gguf -p 512 -n 128 -r 5
/opt/llama.cpp/<new tag>/bin/llama-bench -m /srv/models/model-q4_k_m.gguf -p 512 -n 128 -r 5

llama-bench 会为每项测试输出一行，其中包含 backend 列、ngl 列，以及带有标准差的每秒 tokens 列。比较两个构建版本中的同一行，不要将一个构建版本的 prompt 行与另一个构建版本的 generation 行比较。在不同 prompt 长度下取得的数值属于不同的测量结果，因此每次都以相同方式测量每秒 tokens比数值本身更重要。

回滚只需执行两条命令，而且只有在旧目录仍然存在时才有效：

sudo ln -sfn /opt/llama.cpp/b10502 /opt/llama.cpp/current
sudo systemctl restart llama-server

至少保留上一个构建版本。它占用的磁盘空间只相当于旁边模型文件所用空间的一小部分。

llama.cpp 升级后哪些内容会失效

模型文件停止加载。 这通常正是人们升级的原因：新发布的模型使用了固定版本构建不支持的架构，因此无法加载。llama-server 会在启动期间退出，日志中会出现 failed to load model from /srv/models/model-q4_k_m.gguf 行。查看该行之前输出的内容，确认加载器执行到了哪一步。GGUF 头部也包含格式版本（规范当前值为 3，版本 2 将长度字段从 32 位扩展为 64 位），但在实际情况下，未知的架构名称通常会早于格式版本检查导致加载停止。解决方法是选择较新的 tag，并记录所用版本。

服务器标志已重命名或弃用。 无法识别的标志会导致 llama-server 在启动时停止，而不是被忽略。在 systemd 下，这表现为服务不断启动后退出。journalctl -u llama-server -n 50 会显示实际错误信息。截至 19 August 2026，服务器文档已将 --mlock 和 --mmap 标记为弃用，建议改用 -lm, --load-mode；该选项接受 auto、mmap、mlock 和 dio 等值。GPU offload 标志记录为 -ngl, --gpu-layers，而较旧的指南写作 --n-gpu-layers。移动符号链接前，运行 /opt/llama.cpp/<new tag>/bin/llama-server --help，并将 unit 文件中的每个标志与其进行核对。

构建选项已重命名。 CMake 选项的前缀已从 LLAMA_ 改为 GGML_，根目录中的 CMakeLists.txt 仍保留映射关系。LLAMA_CUBLAS 现在会以致命错误形式指出 GGML_CUDA 是替代选项；LLAMA_CUDA 和 LLAMA_METAL 则会发出警告，并自动为您转换。构建脚本在 configure 步骤停止，反而说明问题已被正确发现。更隐蔽的失败更严重：如果意外省略 -DGGML_CUDA=ON，构建会成功，服务器也会启动，但所有任务都在 CPU 上运行。llama-bench 可立即显示这一点，因为 backend 列的值为 CPU。

加速器构建不可移植。 截至 19 August 2026，构建 tag 附带的 Linux 资源包括 CPU、Vulkan、SYCL 和 OpenVINO 变体，支持 x64、arm64 和 s390x。该列表中没有 Linux 的 CUDA 压缩包，因此 NVIDIA 服务器需要从源代码构建，或运行容器镜像。Windows CUDA 压缩包按 toolkit 版本发布，这提供了一个有用提示：toolkit 版本是标识二进制文件的一部分，因此应将其与 cmake 参数一并记录。

改为固定容器镜像

规则相同，只是对象不同。已发布的镜像（ghcr.io/ggml-org/llama.cpp:server及其加速器变体）使用的是会变动的名称，因此下个月拉取 :server 时，获得的可能是同一标签下的不同程序。先拉取一次并读取摘要：

docker pull ghcr.io/ggml-org/llama.cpp:server

docker pull会输出一行 Digest: sha256:...。将该摘要写入 compose 文件，替换原来的标签。这样下次有人运行 docker compose pull 时，镜像不会在未察觉的情况下发生变化。在注释中保留上一个摘要，这样回滚时只需修改一处；这与Compose 堆栈的升级和回滚流程处理其他服务的方式相同。

固定版本的作用

固定版本可以明确记录当前运行的内容。当变更导致问题时，也可以在一分钟内恢复到之前的构建版本。llama.cpp 要求分别记录构建标签和模型文件，因为它会分别提供这两项内容。将二者打包在一起的运行时有所不同。Ollama 和 llama.cpp 作为服务器的对比介绍了其中的取舍：为整个组件记录一个版本号，需要记录和控制的内容更少。

FAQ

应该固定 bNNNN 构建标签，还是固定 v0.x 标签？

两者都可以，关键是固定某个标签。b10502 等构建标签属于长期跟踪线：每个预构建发行版归档都以它命名，大多数错误报告也会引用它，因此构建编号最便于与其他运维人员对照。v0.1.2 等版本标签数量更少，表示维护者有意标记的节点，适合每年只维护几次的服务器。相比选择哪种标签，更重要的是将标签字符串与模型文件记录在一起，并确保升级是明确的决策，而不是 git pull 的副作用。

llama.cpp 现在遵循语义化版本控制吗？

还没有，项目方明确这样说明。v0.1.2 的发行说明指出，语义化版本控制仍在完善中，并链接到一项 ggml 讨论，其中正在制定版本方案，包括发行节奏和补丁版本的定义。应将版本标签理解为维护者选择标记的节点。不要假设末位数字变化就一定保证可直接替换升级；切换前，应使用您自己的模型文件测试新标签。

如何确认服务器正在运行哪个 llama.cpp 构建？

llama-server --version 会输出版本和构建信息。启动日志也会以 build 行开头，其中包含构建编号、提交哈希和所用编译器，因此可通过 journalctl -u llama-server 在运行中的服务中查找该信息。在源码安装中，在固定版本的 checkout 目录内运行 git describe --tags 会输出标签，运行 readlink /opt/llama.cpp/current 则会显示服务实际指向的目录。

为什么升级 llama.cpp 后模型停止加载？

升级后立即出现加载失败，通常表示构建版本与 GGUF 文件不匹配。日志末尾会有 failed to load model from 行，其中包含路径；该行上方的内容则显示加载器已读取到哪一步。向前升级时，非常新的模型文件需要使用支持其架构的构建版本。向后回滚时，如果回滚到低于模型文件生成所需标签的版本，原本昨天还能使用的文件可能会加载失败。将符号链接指向之前的构建版本，重启服务，然后确认哪个构建版本与哪个文件能够正确配对，再决定要更换其中哪一个。

是否有可以固定版本的预构建 Linux 二进制文件，而不必自行构建？

有，但只适用于部分环境。每个构建标签都附带以该标签命名的发行版归档，例如 llama-b10502-bin-ubuntu-x64.tar.gz；截至 19 August 2026，还提供 arm64、s390x、Vulkan、SYCL 和 OpenVINO 变体。由于标签包含在文件名中，因此很容易固定版本。该列表中没有 Linux CUDA 归档，因此 NVIDIA 服务器仍需使用 -DGGML_CUDA=ON 从源码构建，或运行 CUDA 容器镜像之一。