OLLAMA 本地模型不支持 tool_call 的根因与等效替代方案

本报告回答的 3 个问题 + L1/L2/L3 心智模型

这个决策不是"模型弱所以放弃 tool_call"那么简单——它经过三层叠加 + 任务形态两层分析才得出的工程结论。记住这个三层叠加：协议层（L1）支持 ≠ 兼容层（L2）能用 ≠ 模型层（L3）会发。任何"为什么 XX 不能用标准协议"的问题，都可以套这个分层去拆。

1. 为什么 ollama 三个 runner 不走标准 tool_call 协议？（§1-3 回答：三层叠加 + 任务形态）
2. 三个 runner 如何等效实现 tool_call 该承担的能力？（§4 回答：范式转移 + 能力对照表）
3. 在哪些场景下应改回标准 tool_call？（§5 回答：决策树 + 4 场景行动项）

"三层叠加"是这个报告的核心方法论。先对齐一个基础词：本页反复出现的 API（Application Programming Interface，应用程序接口）指"调用大模型服务的 HTTP 接口"。在看图之前，先把每一层是什么 / 提供什么 / 在 ollama 场景的具体表现 / 可能怎么崩讲清楚——后面所有论证都站在这层之上。

• 是什么：由 OpenAI 等规范方定义的协议标准——tools / tool_choice / message.tool_calls / role:"tool" + tool_call_id 四个字段在文档里写得清清楚楚
• 提供什么：一份"客户端与推理服务之间应该传什么 JSON（JavaScript Object Notation，人类可读的文本数据格式）"的合同——所有兼容端点都声明支持
• 在 ollama 场景：Ollama 0.5+ 文档 https://github.com/ollama/ollama/blob/main/docs/openai.md 明确写了支持 /v1/chat/completions 兼容端点，包括 tools
• 怎么崩：基本不会崩——L1 是"标准在不在"的问题。OpenAI 2023-06 起就把这套 API 钉死了

• 是什么：各个推理服务（Ollama / vLLM / DeepSeek / DashScope / Together / Groq 等）自己实现的 OpenAI 兼容端点——它们读规范、写代码、暴露 HTTP 端口
• 提供什么：一个"长得像 OpenAI API"的端点——但只是"长得像"，行为未必一致
• 在 ollama 场景：Ollama 0.5.x 之前对未知 / 不完整字段的策略是静默忽略而非报错（tool_choice:"required" 部分版本失效、strict:true 静默忽略等）
• 怎么崩："兼容端点不等于行为一致"——L1 通过不代表 L2 通过。这是 OpenAI cookbook 反复警告过的"方言陷阱"（详见姊妹讲义 llm-chat-protocol-guide.html §8）

• 是什么：模型本身在训练数据里学到的能力——能不能稳定输出 tool_call JSON、能不能写出符合 JSON Schema 的参数、能不能在正确位置填 id
• 提供什么：模型推理的"格式技能"——这是模型权重决定的，不是 L1/L2 能改的
• 在 ollama 场景：本机实测的 qwen3.8:27b-mlx / qwen3.6:35b-coding-mxfp8 是 coding 任务微调，没做 tool_call SFT——发不出 tool_call JSON
• 怎么崩：训练数据决定能力边界——换 prompt 没用、换 API 没用、换兼容层没用，必须换模型（或换带 function-calling 微调的版本，如 qwen2.5:7b-instruct、nous-hermes:function-calling）

• 代码审计者：评估"为什么 ollama runner 源码里没传 tools"——看完能讲清"这不是偷懒，是工程权衡"
• 架构决策者：决定"该上 ollama 还是云端 API"——看完能用决策树选型
• 新 agent 开发者：准备接入新 agent 类型——看完知道"何时该传 tools，何时不该传"

OpenAI Chat Completions 的 tool_call：4 字段 + 完整往返

tool_call 是 OpenAI 协议中"让模型发起工具调用"的标准机制。涉及 4 个标准字段：请求体 tools / tool_choice，响应体 message.tool_calls，消息回填 role:"tool" + tool_call_id。"正常 Agent"全部走这条路——但这条路对 LLM（Large Language Model，大语言模型）输出的"格式技能"要求很高。

① Agent 组装 messages + tools  ──→  POST /v1/chat/completions
② 解析响应，读 finish_reason
       │
       ├── "stop"            → 收尾退出
       │
       └── "tool_calls"      → 逐个执行：
                                  - json.loads(arguments)  ← 防御 try/except
                                  - 本地执行 shell/函数/HTTP
                                  - 取 stdout
                                  - append {"role":"tool", tool_call_id, content}
                              → 回到 ①（携带工具结果再请求）

{
  id: string,                  // "call_..." 配对键
  type: "function",
  function: {
    name: string,
    arguments: string          // ⚠️ JSON 字符串，不是对象！需 json.loads + 防御
  }
}

三层叠加：协议层标准 ≠ 兼容层能用 ≠ 模型层会发

本节是报告的核心论证章。"不传 tools"不是单一原因——是协议层（L1）支持 + 兼容层（L2）方言陷阱 + 模型层（L3）训练数据限制三层叠加的工程结论。三层都"通过"才真能用；任一层薄弱，端到端仍崩。

所有宣称"OpenAI 兼容"的 chat completions 端点（Ollama / vLLM / DeepSeek / DashScope / Together / Groq 等）都声明支持 tools 字段。OpenAI Chat Completions v2023-06 起即稳定，tools / tool_choice / message.tool_calls / role:"tool" + tool_call_id 全部标准字段定义清晰。

Ollama 0.5.x 之前对未知 / 不完整字段的策略是静默忽略而非报错：

• tool_choice: "required" 或指定函数形式：部分版本失效
• 旧版本对 tools 数组里的 strict: true 字段：静默忽略
• 工具定义里 parameters.strict: true 强约束模式：取决于版本

加上本仓 one_shot_runner.py D4 决策记录的血泪事实：

根本原因：模型输出 tool_call JSON 的能力完全由训练数据决定。

tool_call JSON 是一种"格式技能"，必须在 SFT 阶段见过大量"问题 → tool_call JSON"样本对才能稳定输出。

这两个模型重在"读代码 + 写 patch"，没有专门做 tool_call SFT，所以发不出 tool_call JSON。

用 opencode 1.14.29 + qwen3.6:35b-coding / qwen3.8:27b-mlx 跑了 5 轮，4 类失败模式：

—— 即便 L1 + L2 都"通过"，L3 模型能力不足仍是稳定失败。

v1.1 新增：不是模型弱，是任务窄

第三讲解释了"为什么弱模型发不出 tool_call JSON"——但还有更上游的问题：SWE-bench（SWE = Software Engineering 软件工程 + bench = benchmark 基准测试，用真实 GitHub issue 评测代码 agent 的软件工程基准）这个任务本身就不需要 tool_call。"读代码 + 写 patch"这个任务完全可以被完全文本化，harness 把"该读什么"准备好，模型只管吐 diff。三个 ollama runner 不传 tools 字段，不是"因为模型弱"，是"因为这个任务根本不需要 tool_call"。弱模型用纯文本 bash 协议反而是顺水推舟。

SWE-bench 任务是后者——工具集是确定的，流程也是确定的。tool_call 提供的"通用对话能力"对它冗余。

—— 5 步里 0 步真的需要模型调工具。

输入：issue 文本（用户报的问题描述）
输出：unified diff（对哪些文件加什么行 / 删什么行）

—— 两端都是纯文本。

模型需要的"信息"（哪些文件、文件里有什么）在任务开始前就已经确定了：

• SWE-bench jsonl 里有 instance_id / repo / base_commit / problem_statement
• 仓库文件已经在 worktree 里（harness 备仓的）
• 关键文件可以用 BM25 / git log 反向定位（ollama-pipeline 路线）

所以"读代码"这件事harness 提前做了，把代码文本塞进 prompt；"写 patch"模型直接吐 unified diff。

prompt: "这是 issue...这是相关文件 a.py 内容...这是相关文件 b.py 内容..."
output: "diff --git a/a.py ... @@ -10,3 +10,4 @@ ... +fixed"

—— 这个纯文本 in / 纯文本 out的范式下，tool_call 真的没有位置。

—— 三种路线都没用 tool_call 字段，但都完成了"读代码 + 写 patch + 验证"的全部工作。

—— 通用 Agent 必须 tool_call，因为"做什么工具"在运行时才确定。

范式转移：从 API 层工具调用 → Harness 层工具调用

三个 runner 都把"工具调用"这件事从API 层降级到Harness 层：tool_call 从"模型对 API 的结构化输出"变成"模型对 harness 的纯文本输出"，harness 自己解析并执行。协议兼容性让位给模型可执行性——这个权衡是 ollama runner 设计的核心。

结论：能力等价，协议不同。tool_call 的所有语义都在 ollama-shell 中得到了纯文本版复刻。

你在一个代码仓库里修复 issue。每轮你必须且只能输出以下两种之一：

1. 一个 bash 命令块（我会执行并把输出回给你）：
```bash
<一条命令>
```
2. 单词 SUBMIT（确认修复完成，我会提取 git diff 作为答案）

红线：
- 所有操作限定在当前仓库目录内，禁止访问其它路径
- 禁止修改 tests/ 下任何文件
- 禁止运行 git log / git show / git blame（仓库历史与未来提交对你不可见）
- 用预装 venv 的 python 跑测试：<VENV_PYTHON>
- 最小改动修复；改动后必须重新运行相关测试验证

—— 明确让模型走"bash 块"路线（这模式模型在预训练时见过海量 bash 教程），避开"tool_call JSON"路线（需要专门 SFT）。

选型决策树：4 路径收敛到 4 种 runner

最后一张卡给可执行的决策：什么场景用什么 runner、什么场景必须切到云端。决策只看一个轴：模型本身能不能稳定输出 tool_call JSON——能就上标准协议，不能就走 ollama-shell 等效路线。

如果从 ollama 切到云端 API，只需替换 _client.py 的 base_url 和认证头，三个 ollama runner 的循环逻辑可以直接复用（或改用 kimi-fast / qwen-one-shot runner 走 one-shot 路径）。

但云端 API 的 tool_call 行为更稳定，有可能反而是 ollama-shell 的循环模式显得冗余（强模型不需要 5 道护栏）。届时可考虑直接用 qwen-one-shot（云端 one-shot + 强模型）或新增 openai-agent runner 走标准 tool_call 协议。