Goose 的 Toolshim 微调方案:让没有原生工具调用能力的开源模型也能可靠执行 Agent 任务
Goose 的 Toolshim 微调方案:让没有原生工具调用能力的开源模型也能可靠执行 Agent 任务
导读
本文围绕 goose 团队提出的「Toolshim(工具垫片)」微调路线展开:当 Gemma3、DeepSeek-R1、Llama4 这类开源模型在工具调用上表现不稳甚至完全不支持工具时,如何用一个轻量级(≤12B)的专用小模型,将大模型的纯文本输出翻译成结构化、可执行的工具调用。文章会说明为什么工具调用对通用 Agent 不可或缺、当前模型在工具调用上的典型问题、微调数据如何从真实 goose 会话中构造,以及微调目标模型与评测方式,同时结合仓库中 ToolShim 运行时实现 与 goose-local-inference 的文本式工具模拟解析,帮助你理解这一思路如何在当前代码库中落地。
阅读本文后,你将掌握:goose 对「非原生工具调用模型」的两条兜底路径(运行时解析垫片与微调专用垫片)的核心设计、微调工具垫片的数据构造与模型选择策略,以及如何在当前版本 goose 中通过环境变量启用 ToolShim 做本地实验。
为什么工具调用对 Agent 至关重要
goose 是「不限于代码建议」的通用 Agent:它可以安装依赖、执行命令、编辑与测试代码,与外部系统真实交互。而这一切的基础,是模型具备**工具调用(tool calling)**能力——即模型不仅能生成文本/图像,还能发出结构化的"调用某个工具"指令,例如执行 Shell、查询数据库、检索网页或操作 Figma 这类外部设计工具。
原文把纯生成(文本、图像、语音、视频)视为通往 Agent 能力的第一步:只生成还不够,模型需要"腿"去跑起来。对于窄而确定性的 LLM 应用,工具调用或许多余;但对 goose 这类通用 Agent,没有可靠的工具调用,能帮用户完成的自动化与繁琐工作将大打折扣。
goose 团队此前发布的基准测试表明:在工具调用未被原生支持或支持不佳的模型上(如 Gemma3、DeepSeek-R1、phi4),模型常在不合适的时机发起工具调用,或产出畸形、格式不一致的调用。而即便是 Llama4、DeepSeek v3(0324) 这类旗舰开源权重模型,近期的工具调用表现也仍然不稳定。这正是 Toolshim 想要解决的问题。
背景:把本地模型当作 "toolshim"
Toolshim(工具垫片) 是夹在"承担 Agent 工作的主模型"与"真正执行动作的工具层"之间的薄层,其目标是让主模型从"聊天机器人"变成"会行动的 Agent"。
- goose 希望能与尽可能多样化的模型协作;
- 一些前沿模型(开源与闭源)在各类基准上表现优秀,但在 Agent 场景下需要工具调用时却明显不足;
- 部分推理模型在设计上根本不支持工具调用。
若 Toolshim 可行,就能解锁这两类模型的 Agent 潜力。此前的基准实验已经验证了方向的可行性:使用一个通用本地模型(mistral-nemo)作为垫片时,phi4(14b) 和 gemma3(27b) 的工具调用成绩已接近 llama3.3(70b)。这意味着:只要把注意力集中在提升垫片模型本身上,主模型的 Agent 表现还有很大提升空间。
goose 的 Toolshim 在架构上是独立于主模型的"解释器"层。仓库中 crates/goose/src/providers/toolshim.rs 的模块注释给出了完整的运行时实现思路:
- 接收任意 LLM 输出的纯文本;
- 把文本发送给一个独立的 interpreter(解释器)模型(可与主模型相同或不同);
- 由解释器模型把"工具调用意图"提取为合适的格式;
- 将解释器模型的输出转换为 goose 的标准工具调用结构;
- 把解析出的工具调用**回填(augment)**到原始消息上,再交给工具层执行。
当前工具调用生成的核心挑战
原文归纳了三类现实问题,它们是微调 Toolshim 的直接动机。
1. 模型训练模板不一致,影响远超预期
不同模型家族的训练数据格式差异极大:例如 Qwen 系列采用 Hermes 风格的函数调用格式;而 Openhands 即使在显式要求输出 JSON 工具调用的情况下仍输出 Markdown——这说明训练数据的形态对可靠工具调用生成的影响常被低估。
2. 现有 workaround(如 guided decoding)并不足够
部分模型服务商采用引导解码(guided decoding)来保证函数调用可解析,但如果模型训练时并未见过与用户上下文匹配的 schema,这类强制手段仍可能产出低质量的调用。Llama4 在工具使用上的普遍问题,也可能反映出服务商在有效承载新模型能力时面临的普遍挑战。
3. 托管服务商对工具调用的支持参差不齐
托管商通常会提供 chat template 等手段,引导较大的模型输出格式正确的工具调用并支持 OpenAI 风格的 tools API,但实践中往往一次对话后就失效,且服务商之间差异很大。若再经过 OpenRouter、HuggingFace hosted inference 这类模型路由,问题会被进一步放大。
各模型的具体怪癖(来自原文实验)
仓库中原文保留了这些真实示例截图,可直观感受"同一任务、千奇百怪的输出格式":
- Openhands:明确要求输出 JSON 格式工具调用,仍输出 Markdown(疑与训练数据形态有关)。
- Llama4 Maverick:默认产出畸形工具调用;被明确提示"以 JSON 输出工具调用"后表现有改善。下方两图分别展示了 OpenRouter 上使用 tool calls 接口、以及改用 JSON 提示词后的输出差异。
- Gemma3:DeepMind 工程师建议在上下文中以 Python 格式提供函数调用模板;实测其 12B 模型也能较好地直接输出合法 JSON 工具调用。
- Functionary 系列模型:因其训练提示词模板使用 TypeScript schema,与 Ollama 支持的 JSON schema 不兼容,导致 Ollama 无法支持其工具调用。
这些例子共同指向一个结论:单靠提示词或服务端模板,难以对不同训练范式的模型做统一兜底,需要一个专门做"翻译/标准化"的垫片层。
提案:微调一个轻量级 Toolshim 模型(≤12B)
goose 的提案是:开发一个专用 Toolshim 模型,把开源模型输出翻译为结构良好的工具调用,充当可靠的后处理器(post-processor),横跨各家训练模板不一致、工具调用生成不可靠的模型家族。
两个关键设计原则:
- 即使模型原生支持工具调用 API 也不使用,统一走"模型输出 → 垫片翻译"路径,保证跨模型一致性;
- 工具上下文通过 system prompt 提供给垫片,而不是依赖各家 API 的 tool schema 机制。
配套的模型选择为轻量级选手:mistral-nemo(14b)、gemma 4-12b、qwen2.5-coder 7-14b。
仓库中的同源实践:面向本地推理的 ToolShim 运行时
在仓库当前代码中,"小模型当垫片"的运行时版本已经落地为两条路径,理解它们能帮你更准确地把握博客提案的上下文。
路径一:基于 llama.cpp/Ollama 的 ToolInterpreter
crates/goose/src/providers/toolshim.rs 定义了 ToolInterpreter trait:
pub trait ToolInterpreter {
/// 从文本中解读潜在工具调用,转换为标准工具调用 JSON 格式
async fn interpret_to_tool_calls(
&self,
content: &str,
tools: &[Tool],
) -> Result<Vec<CallToolRequestParams>, ProviderError>;
}
并提供两个实现:
OllamaInterpreter:通过 Ollama 的/api/chat结构化输出接口,要求解释器输出固定 JSON Schema({"tool_calls": [{"name": ..., "arguments": {...}}]}),其中name、arguments均为必填字段;LocalInterpreter:本地 llama.cpp 后端实现,通过创建localprovider 做流式推理完成解释。
代码中还有大量"容错解析"逻辑,印证了原文观察到的模型输出混乱问题:工具名可能带 functions. 前缀、索引前缀或点号(工具名会被归一化为 goose 的 __ 约定),例如 resolve_tool_name 会对候选名逐一比对;还会用 tree-sitter 解析 TypeScript,把模型输出的 Developer.shell({...}) 形式代码块转成 shell 工具调用(maybe_convert_execute_to_shell_tool_call)。此外,解释器输出可能残留 <|tool_call_begin|> 这类标记或 "name"/"arguments" JSON 指令文本,代码通过 sanitize_residual_markers 在消息离开 pipeline 前统一清洗。
路径二:goose-local-inference 的文本式工具模拟
当本地小模型本身没有原生工具调用能力时,crates/goose-local-inference/src/tool_emulation.rs 采用纯文本约定:模型被提示以 $ 命令 行首前缀输出 shell 命令、以 ```execute_typescript 围栏块输出代码执行调用,随后由 StreamingEmulatorParser 在流式输出中把这些模式解析为 goose 工具调用消息。
配套的系统提示模板 tiny_model_system.md 给出了这种"文本工具协议"的具体写法:
To run a shell command, start a new line with ls` 运行完命令后你会看到输出,用它来回答用户或决定下一步,不要重复已运行的命令;如果你已经知道答案,就不要使用 shell 命令。
native_tool_parsing.rs 则补充了 JSON 方向的解析:message_from_native_tool_text 会尝试解析 OpenAI 消息 JSON({"tool_calls": [...]})、顶层 tool_calls 数组,乃至 <function=name><parameter=k>v</parameter></function> 形式的 XML 调用。这些运行时解析能力,正是博客中"模型输出格式千奇百怪,需要一个统一翻译层"论断在代码层的直接体现。
实验方法:数据收集、建模与评测
数据收集:从真实 goose 会话构造训练语料
要微调垫片模型,需要"主模型文本输出 → 标准工具调用"的配对样本。goose 的优势在于拥有海量真实 Agent 会话历史。具体做法:
- 抽取历史 goose 会话中的用户消息,并筛选出那些被 Anthropic/OpenAI 模型用工具调用跟进的消息(截至当时所有工具调用);
- 用工具调用能力强的开源模型重生成工具调用(如 QwQ、Qwen、deepseek chat v3);
- 让工具调用能力较弱/不支持的模型(如 DeepSeek-R1、Llama4、Gemma3)按正确 schema(JSON/Markdown)输出工具调用文本,再把输出解析成工具调用,得到"难模型的文本输出"样本;
- 丢弃畸形、无法正确执行或满足其他拒绝条件的工具调用;
- 用上述流程生成几千条示例。
这样得到的训练集天然对齐"垫片的使用场景":输入是五花八门的模型文本,标签是干净可执行的工具调用。
建模:小模型是性价比核心
微调目标集中在 ≤14B 的轻量级模型:mistral-nemo(14b)、gemma 4-12b、qwen2.5-coder 7-14b。选择小模型的原因可从原文推导:垫片位于主模型与工具之间,需要低延迟、可本地部署,同时 12B 量级(如 gemma3 12B 能直接输出合法 JSON)已展现出足够的格式模仿能力,微调空间大。
评测:与 Goosebench 直接对照
评测复用基准博客中的 Goosebench evals:直接对比"同一主模型在有无微调后 Toolshim 支撑下"的表现差异。这种 A/B 评测方式能清晰量化垫片的价值——即主模型不动,只更换垫片,观察端到端 Agent 成绩变化。
说明:原文所指的 benchmark 细节收录于仓库 documentation/blog/2025-03-31-goose-benchmark/index.md。
未来方向:从"模型垫片"走向结构化文本解析
除了本地模型垫片,原文还提出了后续的非模型路线:基于数千条工具结果示例构造解析器(parser)、解析器组合子(parser combinator)、上下文无关文法(context-free grammar,甚至非常大的文法)。这类解析器即使规模很大,也能以极低延迟运行,从强大通用模型的富文本回复中提取工具调用参数。此外还有更多结构化文本提取技术值得探索,用于辅助"从模型回复中发现并抽取工具调用"。
这一方向与仓库代码中的思路一致:当前的 native_tool_parsing.rs(JSON 候选提取、XML 函数块解析)与 tool_emulation.rs(Markdown 围栏流式解析,含 256KB 上下文与 1MB 解析预算的上限保护)本身就是"确定性结构化提取"的早期形态,未来可在此基础上进一步扩大解析器的覆盖与规模。
在本仓库中亲手尝试 ToolShim
若想复现"模型垫片"的运行时体验(而非微调),当前仓库已经支持通过环境变量开启 ToolShim:
| 环境变量 | 作用 | 取值 | 默认 |
|---|---|---|---|
GOOSE_TOOLSHIM |
为以文本方式输出工具调用的模型启用 ToolShim | "1" / "true"(不区分大小写) |
false(关闭) |
GOOSE_TOOLSHIM_BACKEND |
垫片解释器后端 | "ollama"(默认)、"local"、"llama.cpp" |
"ollama" |
GOOSE_TOOLSHIM_OLLAMA_MODEL |
作为解释器的 Ollama 模型 | 模型名,如 llama3.2、mistral-nemo |
"mistral-nemo" |
GOOSE_TOOLSHIM_MODEL |
local/llama.cpp 后端所用模型 | 模型名 | 使用 LOCAL_LLM_MODEL 配置 |
环境变量说明整理自 environment-variables.md,Ollama 上的实验性用法见 ollama.md。一个最小启用示例:
export GOOSE_TOOLSHIM=true
export GOOSE_TOOLSHIM_OLLAMA_MODEL=llama3.2
goose session
在本地推理侧(crates/goose-local-inference),prompt_template.rs 中的 render_template 会用 minijinja 渲染内置提示模板,并优先读取用户配置目录下 prompts/<name> 的自定义模板——这意味着 tiny_model_system.md 这类"教小模型输出 $ 命令"的提示词是可以覆盖定制的,为实验"如何引导弱模型输出可解析工具调用"提供了抓手。
注意:ToolShim 属于实验性特性,行为与配置在未来版本中可能调整,运行前请以当前仓库与文档为准。
小结
goose 的 Toolshim 微调方案回答了一个实用问题:当开源模型的工具调用能力不可靠甚至缺失时,如何低成本地让它们加入 Agent 工作流。答案是训练一个 ≤12B 的轻量翻译层——它不参与决策,只负责把主模型的自由文本"翻译"成结构化工具调用,从而统一 Qwen/Hermes、Openhands-Markdown、Llama4-JSON、Functionary-TypeScript 等各种训练范式之间的差异。
数据来自真实的 goose 会话(数千条配对样本),目标模型集中在 mistral-nemo、gemma 4-12b、qwen2.5-coder 等轻量级模型,评测直接复用 Goosebench 做有/无垫片的 A/B 对照;而仓库中 toolshim.rs 的 ToolInterpreter 解释器架构与 goose-local-inference 的文本/JSON 工具解析能力,已经从运行时侧验证了这条路线。未来,垫片还可能与确定性文法解析器结合,在更低延迟下完成工具调用的发现与提取。




