企业官网建设流程全解析

K2-Horizon-MoVA-36B-A4B-oQ4e 是一款面向本地 Agent 场景深度优化的 MoE 推理模型（MLX 量化版），核心能力是极其稳定的 Tool Call（工具调用）与 XML/JSON 结构化输出。但在真实接入中，大多数人因为格式参数名写错、schema 传成字符串、历史消息缺少思考字段而踩坑。本文带你 5 分钟搞懂它的三种 Tool Call 格式和正确用法。

一、为什么它是本地 Agent 的 Tool Call 优选？

先看图说话。在独立基准对比中，K2-Horizon 在 Agent 相关维度几乎是碾压级的：

📌 结论很简单：如果你的本地 Agent 流水线对工具调用的可靠性和结构化输出有要求，K2-Horizon 是最强选择之一。详细数据见 README.md 的 Benchmark 章节。

模型本体是一个稀疏 MoE 架构：总参数 36B、激活仅 4B，原生 512K 上下文（见 config.json 中max_position_embeddings: 524288），MLX 适配代码在 k2_horizon_mova_mlx.py。

二、Tool Call 三种格式详解：XML（默认）、JSON、xml_typed

K2-Horizon 使用 IFM 自定义 chat template（完整定义在 chat_template.jinja），它把"工具格式"拆成了两个独立维度——这是最容易混淆的地方：

也就是说：默认情况下，工具定义以 Markdown 呈现给模型，而模型的调用输出走 XML。两者可以独立组合。

1）XML 格式（默认）：键值对 + 纯文本

字符串和标量参数写纯文本，数组和对象参数必须写成 JSON 字面量——这是模板的硬性要求：

<ifm|tool_calls> <ifm|tool_call>get_weather <ifm|arg_key>city</ifm|arg_key> <ifm|arg_value>Beijing</ifm|arg_value> <ifm|arg_key>days</ifm|arg_key> <ifm|arg_value>[1, 2, 3]</ifm|arg_value> </ifm|tool_call> </ifm|tool_calls>

2）JSON 格式：一行一个调用

所有调用包在同一个<ifm|tool_calls>块内，每次调用是一个单行 JSON 对象：

<ifm|tool_calls> <ifm|tool_call>{"name": "get_weather", "arguments": {"city": "Beijing", "days": [1, 2, 3]}}</ifm|tool_call> </ifm|tool_calls>

✅ 想要最容易被下游程序解析？把tool_call_format设为json即可。

3）xml_typed：给每个参数带上类型标签

在 XML 基础上为每个参数多一个<ifm|arg_type>标签，类型取自工具定义；若参数类型是oneOf/anyOf，则使用实际值的类型。适合复杂 schema 下进一步降低参数错配的概率。

🔧 小贴士：当工具 schema 含有模板"漂亮渲染器"无法表达的构造时，整个工具清单会自动回退为 JSON 原文展示（render_tool_presentation逻辑），无需你手动处理。

三、90% 的人都会踩的 5 个坑

以下每一个坑，模板里都有对应的raise_exception硬性校验，触发就会直接报错：

坑 1：用错了参数名，直接被拒绝

模板明确禁用了三个旧参数名，传了就会报错：

报错信息会直接告诉你该用哪个，别无视它 😄

坑 2：把parameters/arguments传成 JSON 字符串

两处硬性要求是dict（对象）而非字符串：

• 定义工具时：tool.function.parameters must be a dict, not a JSON string
• 回放历史 tool_calls 时：tool_call.arguments must be a dict, not a JSON string

另外每个工具必须有parameters字段（含type、properties、required），写错成arguments也会报错。

坑 3：assistant 历史消息缺少"思考"字段

K2-Horizon 是推理模型，模板要求每条 assistant 历史消息必须携带以下字段之一：

think/think_fast/think_faster/reasoning_content/reasoning

多轮对话里只存content不存思考内容，模板会直接抛Assistant message is missing a thinking field。用 OpenAI 兼容接口时，记得把reasoning_content完整写回历史。

坑 4：oMLX 版本过旧

K2-Horizon 需要oMLX v0.6.4+（含 K2-Horizon 支持补丁），该补丁新增了：k2_horizon模型类型、<ifm|think>思考内容处理、Tool Call 解析（纯文本与 XML 格式）、多轮对话支持。版本不达标会报ValueError: Model type k2_horizon not supported。所有<ifm|...>标签会被 oMLX 在返回前自动剥离，用户看到的只是干净正文。

坑 5：忘了调reasoning_effort

模板通过reasoning_effort决定思考档位，默认high（对应<ifm|think>）：

做 Agent 长链路时，简单步骤用low能显著提速，复杂决策再切回high。

四、快速上手：3 条命令跑通本地 Tool Call

以 OpenAI 兼容接口为例，指定格式只需在chat_template_kwargs里声明：

extra_body={"chat_template_kwargs": { "tool_call_format": "json", # 或 "xml"（默认）、"xml_typed" "tool_presentation_format": "xml", # 或 "markdown"（默认）、"json" "reasoning_effort": "high", }}

本地跑起来的完整流程（安装mlx-lm、生成命令、推理接口示例）都在 README.md 的 Quickstart 与 Reasoning 章节，照抄即可。工具结果用role: "tool"的消息回传即可进入下一轮。

五、关键文件导读

想深入定制，重点看这几个文件：

• chat_template.jinja —— Tool Call 格式的全部定义：参数校验、XML/JSON/Markdown 渲染、<ifm|tool_call>结构
• config.json —— 模型结构：100 个专家每 token 激活 8 个、512K 上下文、oQ4e 混合精度量化细节
• k2_horizon_mova_mlx.py —— MLX 推理适配器（MoE 路由 + MoVA 注意力实现）
• README_oQ4e.md —— 本仓库 4-bit 量化版的说明卡
• oq_imatrix_report.json —— imatrix 量化校准报告

总结

K2-Horizon-MoVA-36B-A4B-oQ4e 的 Agent 超能力不神秘，记住三句话就能用对：

1. 格式双参数：tool_call_format（默认xml）管模型怎么"说"，tool_presentation_format（默认markdown）管工具怎么"呈现"；
2. 一切传对象：parameters和arguments必须是 dict，绝不是 JSON 字符串；
3. 历史带思考：assistant 消息永远回写reasoning_content，并配合reasoning_effort控档。

避开这 5 个坑，你就能把它的 Tool Call 93 分实力真正榨出来 🚀