Misc. bug: [llama-server] /v1/models metadata serializes “vocab_type” as boolean true instead of integer enum

问题场景

用户在 macOS（Apple Silicon）上通过 Homebrew 安装 llama.cpp 0.4.1，使用 llama-server 加载 GGUF 模型（示例为 sakura-14b-qwen2.5-v1.0-iq4xs），并通过 --host 127.0.0.1 启动本地服务。随后调用 OpenAI 兼容接口 GET /v1/models，检查返回 JSON 中 data[0].meta.vocab_type 字段时触发该问题，期望值为整数枚举（如 BPE 对应 2），实际得到布尔值 true。

报错原文

Misc. bug: [llama-server] /v1/models metadata serializes "vocab_type" as boolean true instead of integer enum

% curl -s http://127.0.0.1:8080/v1/models | jq '.data[0].meta.vocab_type'
true

Expected result should be "2".

原因分析

根据 Issue 中的成因分析，在 tools/server/server.cpp 构造 /v1/models 端点元数据 JSON 对象时，vocab_type 被隐式当作布尔检查处理，即 (bool) llama_vocab_type(...)，而没有按整数枚举值序列化。按文档和内部枚举，其取值应为：LLAMA_VOCAB_TYPE_NONE = 0、LLAMA_VOCAB_TYPE_SPM = 1、LLAMA_VOCAB_TYPE_BPE = 2、LLAMA_VOCAB_TYPE_WPM = 3。该回归被定位为在 0.3.0 与 0.4.0 之间引入。

环境排查

• 确认 llama.cpp 版本：llama-server --version，Issue 中受影响版本为 0.4.1 (build 10964, commit b29c606e2)。
• 确认安装方式：Issue 中使用 Homebrew；不同安装渠道可能包含不同提交，需核对实际 commit。
• 确认操作系统与硬件：Issue 为 macOS / Apple Silicon（Darwin arm64），构建工具 AppleClang 21.0.0.21000334。
• 确认受影响模块：llama-server，接口为 GET /v1/models。
• 确认模型加载正常，问题与具体 GGUF 模型无关，任何标准模型均可能复现。

解决步骤

1. 先用 curl 或浏览器访问 http://127.0.0.1:8080/v1/models，定位 data[0].meta.vocab_type 字段，确认其是否为布尔值 true。
2. 对照 llama.cpp 版本与 commit，确认是否处于 0.3.0 至 0.4.0 之间引入该回归的构建范围。
3. 若确认命中，升级到包含 PR #28518 修复的 llama.cpp 版本；由于 Issue 未给出手工热修步骤，不建议直接改本地源码。
4. 如果暂时无法升级，可在 API 客户端侧对 vocab_type 做容错，避免把它当整数枚举强制校验；这只是规避手段，不是修复。
5. 升级后重启 llama-server，重新请求接口确认字段类型已恢复为整数。

验证方法

服务重启后执行如下请求，确认 vocab_type 返回整数（BPE 模型应为 2），而不是布尔值：

% curl -s http://127.0.0.1:8080/v1/models | jq '.data[0].meta.vocab_type'
2

同时确认 llama-server --version 已切换到包含修复的构建，且 API 客户端不再因字段类型不匹配而校验失败。

参考来源

ggml-org/llama.cpp #29091

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。