llama.cpp 跑通 Qwen2.5 工具调用的 4 类坑位排查法-平芜编程栈

llama.cpp 跑通 Qwen2.5 工具调用的 4 类坑位排查法

【免费下载链接】llama.cppLLM inference in C/C++项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp

llama.cpp 的 llama-server 已原生支持 Qwen2.5 工具调用（Hermes 2 Pro 格式），多数失败案例源于--jinja未开启或量化过低，表现为响应里没有 tool_calls。

环境核对：启动前 5 项检查

核对项	预期值	错误时的可见表现
llama-server 版本	支持 Qwen2.5 原生模板的近期 release（以当前 release 为准）	`/props`无`chat_template_tool_use`字段
`--jinja`标志	显式开启	模型只回自然语言，`finish_reason`为`stop`
模型 tool_use 模板	`/props`中`chat_template_tool_use`非空	日志出现`Chat format: Generic`，调用成功率下降
量化等级	权重 Q6_K 及以上，KV 不启用 q4_0	tool_calls 参数缺失或 JSON 截断
`tools`字段格式	数组，元素为含`function`子对象的对象	400：`'tools' must be an array of objects`

按故障现象分诊：4 类可观察异常

现象：响应里只有 content，没有 tool_calls

现象

{"choices":[{"finish_reason":"stop","message":{"content":"北京今天晴，26 度。"}}]}

根因

未开启--jinja时，服务端只在内置通用模板集合中选择模板，Qwen2.5 的 tool_use 模板不会被注入，模型按普通对话回答。标志定义见 common/arg.cpp 第 3632 行附近。

修复

./build/bin/llama-server --jinja -fa -m <MODEL_PATH> --port <PORT>

验证

curl -s http://localhost:<PORT>/props | grep chat_template_tool_use

预期输出非空模板字段，其中包含 tool_use 渲染逻辑。

现象：400 报错 tool_choice 需要 jinja 标志

现象

{"error":{"message":"tool_choice param requires --jinja flag"}}

根因

服务端仅在 jinja 模式下解析tool_choice，否则直接抛出该异常，见 tools/server/server-common.cpp 第 1145 行。

修复

"tool_choice": "auto"

或将重启服务时补上--jinja。

验证

curl -s http://localhost:<PORT>/v1/chat/completions -d '{"model":"<MODEL>","messages":[{"role":"user","content":"北京天气如何？"}],"tools":[<工具定义>]}' | grep -o '"finish_reason":"[^"]*"'

预期输出"finish_reason":"tool"。

现象：400 报错自定义 grammar 与 tools 冲突

现象

{"error":{"message":"Cannot use custom grammar constraints with tools."}}

根因

请求同时携带grammar/json_schema自定义约束与tools时两者互斥，校验点在同一文件第 1290 行。

修复

curl http://localhost:<PORT>/v1/chat/completions -d '{"model":"<MODEL>","messages":[{"role":"user","content":"北京天气如何？"}],"tools":[<工具定义>]}'

即删除请求中的grammar与json_schema字段后重发。

验证

curl -s http://localhost:<PORT>/v1/chat/completions -d '{"model":"<MODEL>","messages":[{"role":"user","content":"北京天气如何？"}],"tools":[<工具定义>]}' | grep -o '"finish_reason":"[^"]*"'

预期输出"finish_reason":"tool"。

现象：tool_calls 参数缺失或 JSON 截断

现象

{"tool_calls":[{"name":"get_current_weather","arguments":"{\"location\": "}]}

根因

工具调用对精度敏感，低量化权重或激进 KV 量化会破坏格式遵循。docs/function-calling.md 第 332 行明确警告-ctk q4_0级别的 KV 量化会显著劣化表现。

修复

./build/bin/llama-quantize <MODEL_PATH> <MODEL_PATH>.q6k Q6_K

验证

curl -s http://localhost:<PORT>/v1/chat/completions -d '{"model":"<MODEL>","messages":[{"role":"user","content":"北京天气如何？"}],"tools":[<工具定义>]}' | grep -o '"finish_reason":"[^"]*"'

预期输出"finish_reason":"tool"，重复多轮确认参数完整。

参数与采样配置对照

参数名	默认值	推荐值	影响范围
`--jinja`	关闭	开启	决定 tool_use 模板是否生效
`--chat-template-file`	GGUF 元数据内模板	模型官方 tool_use 模板文件	元数据模板缺失或错误时的覆盖手段
`tool_choice`（请求字段）	`auto`	`auto`，需强制调用时用`required`	仅 jinja 模式可解析
`parallel_tool_calls`（请求字段）	由模板能力决定	多工具并行时传`true`	单轮能否输出多个 tool_calls
`-ctk`（KV 量化）	`f16`	保持`f16`，最多`q8_0`	激进值直接拉低调用成功率

Qwen2.5 系列有原生 Hermes 2 Pro 格式，优先信任 GGUF 内置模板，仅在/props检查发现模板缺失时用文件覆盖。完全无官方 tool 模板时可退回--chat-template chatml，属通用格式，token 消耗更高。

端到端最小可复现链路

以下链路复现一次完整的 Qwen2.5 工具调用请求。

定义工具元数据

[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string"}},"required":["location"]}}}]

启动服务

./build/bin/llama-server --jinja -fa -m <MODEL_PATH> --port <PORT>

发送请求

curl http://localhost:<PORT>/v1/chat/completions -d '{"model":"<MODEL>","messages":[{"role":"user","content":"北京天气如何？"}],"tools":[<工具定义，取自第 1 步>]}'

校验响应

curl -s http://localhost:<PORT>/v1/chat/completions -d '{"model":"<MODEL>","messages":[{"role":"user","content":"北京天气如何？"}],"tools":[<工具定义，取自第 1 步>]}' | grep -o '"finish_reason":"[^"]*"'

预期输出"finish_reason":"tool"，且message.tool_calls[0].name与工具名一致。