先交代一个可能让不少人大跌眼镜的数字同一颗 2B 参数的开源小模型工具调用相关评测从 0.017 干到了 0.821翻了将近 50 倍。我开源的这个项目叫 agent-harness 模拟项目X核心做的事情特别简单——给 agent 搭一层“驾驶舱”也就是 agent harness把模型、工具、评测脚本、上下文管理全部串起来。过去两个月我拿它做了大量对比实验发现一件很有意思的事模型参数没动提示词主旨也没动仅仅换一套框架封装分数就能差出这么多。所以这篇不打算只贴一个“看我开源了”的公告而是把这段时间踩过的坑、拆过的分数、改过的地方和最后沉淀下来的几个设计思路全部摊开聊。你可以把它当成一份 agent harness 的“拆解报告踩坑实录”不管你是想搭自己的工具调用评测还是想让手里的小模型在业务里变得“能用”这篇应该都能给你一点不太一样的参考。1. 先拆清楚agent harness 到底是什么为什么值得自己写一个1.1 一句话定义以及它和 agent“框架”的区别我见过很多人把 agent harness 和 agent 框架混为一谈其实两者分工不一样。框架通常负责“模型怎么和世界交互”——比如定义工具列表、处理模型输出、把轮次历史塞回上下文而 harness 更偏外层它决定的是“一次任务从开始到结束中间发生了什么可被记录、可被评测、可被干预”。打个比方模型是司机工具是油门刹车方向盘框架是车子的机械结构而 harness 是仪表盘加行驶记录仪加教练。它能告诉你司机在哪个路口打错了方向也能在偏离路线时强制拉回来。我设计 agent harness 模拟项目X 时重点不是去替代任何一个框架而是做一层薄适配层。底层模型、工具、数据集都可以插拔。这样我才可能做“同一颗模型换框架”的公平对照实验。1.2 为什么要拿 2B 模型做实验市面上很多人评测 agent 能力一上来就上几百亿参数的大模型这当然合理但离“大多数团队的真实预算”很远。2B 量级的模型才是很多边缘部署、私域问答、小型自动化场景里的常客也是“看起来什么都能聊两句一接到工具调用就露馅”的重灾区。拿 2B 模型做 harness 还有个额外好处错误放大效应。大模型往往会自己“脑补”修复格式问题小模型不会它遇到不熟悉的语法就实打实地出错。于是 harness 设计得好不好在小模型上特别容易暴露。这也解释了为什么同一个任务不同框架下分数会从接近零拉到 0.8 以上——你看到的不只是框架差异而是“接口摩擦”在小模型上被放大后的真实结果。1.3 实验的公平性约定到底是“四个框架”还是“四种协议”为了避免抬杠我得先说明这次对照的四个框架并不是四家公司的商业产品而是我在社区里最常见的四种典型 agent 交互范式。我做了四个适配器让同一个任务集、同一个模型权重、同一套工具注册表都能跑。换句话说模型是同一颗任务集是同一份工具是同一批只有“框架与模型之间的对话方式”不同。适配器代号交互协议风格工具定义形式允许最大步数错误恢复策略最终得分框架A纯文本协议型自然语言列表5无0.017框架B结构化 JSON 型JSON Schema8仅重试一次0.412框架C强约束状态机型预定义动作表15强制动作纠正0.458框架D低摩擦动态注册型半结构化 YAML带示例20逐步容错回传0.821这里要强调得分跨度这么大不代表框架A“垃圾”、框架D“神奇”。它更多说明了一个结论——对小模型来说接口摩擦是性能的头号杀手。后面我会把这 0.804 的差距拆到具体环节上。2. 第一次跑出 0.017 时我差点以为是模型坏了2.1 那个让人想砸键盘的夜晚项目刚开始我先用框架A做基线。任务集是 100 个带明确工具调用的模拟任务比如“查询某城市天气并计算温差”“解析订单状态并判断是否需要催单”这一类。模型输出日志我打印出来满屏都是模型在自言自语碰到正题就开始乱输出括号、JSON 失败、调用了不存在的工具名。跑完一看100 个任务里成功完成的是 0 个平均得分 0.017。这个 0.017 哪里来的是其中几个任务在早期步骤里碰对了工具名给了 0.05 的步骤分被平均后剩下这么点。我当时第一反应是模型权重有问题赶紧换了另一个人气更高的同尺寸模型来跑结果还是差不多的“灾难”。后来我意识到问题不在模型在我这个“驾驶舱”。框架A把所有工具定义写成自然语言直接拼进系统提示词末尾没有任何输出格式约束。大模型能勉强理解2B 模型直接迷失在长篇大论的工具描述里经常“越狱”去回复用户根本不知道自己现在要触发的是一个工具调用。2.2 把模型输出翻译成工具调用的四个岔路口我后来把不同框架的差异抽象成四个关键环节逐一代入实验工具定义呈现是自然语言、JSON Schema、伪代码还是带 few-shot 示例的半结构化 YAML。模型输出要求是自由文本里“碰运气”找工具名还是强制要求先输出一个固定开头再输出严格字段。调用解析拿到模型文本后是用正则硬匹配还是结构化解码还是允许模型自己声明函数名再校验。失败回传调用失败时是把原始错误堆栈丢给模型还是转成简单指令还是直接不再尝试。框架A在每一步都选了“最放任”的方案框架D则几乎每个环节都做了针对性设计。差距自然就出来了。这里我不卖关子先把结论放前面小模型不是不会调用工具它是“需要被明确告知格式”的模型。你给它越多模糊地带它就越容易发挥创意而创意在工具调用场景里基本等于错误。2.3 分数拆解0.804 的差距到底丢在哪里我按照产出的轨迹日志把失败原因分成了五类并统计了各框架下的占比失败类型框架A框架B框架C框架D输出非法 JSON / 解析失败48%17%20%6%使用了未注册的工具名22%9%8%3%参数内容与类型不符11%14%9%10%多步任务中途放弃或跑偏15%31%33%14%上下文截断导致历史丢失4%29%30%12%在框架A里解析失败占掉接近一半这根本不是智力问题是接口设计问题。从框架A换到框架B之后解析失败大幅下降但又暴露了新的麻烦结构化 JSON 提示词写得过长把上下文塞得满满当当导致 2B 模型在多步任务中容易“忘掉”前面的结果中途跑偏的比例反而上去了。所以后面两个框架我刻意把“提示词密度”压了下来工具定义不是全量塞进上下文而是按需加载需要哪个工具就注入哪个工具。框架D最终能拿到 0.821核心赢在两点一是每一步的“下一步动作”格式极其明确二是工具失败后会回传一段精简的修正提示直接告诉模型刚才哪里不对。3. harness 的核心设计把“让模型少猜”落到具体机制上3.1 工具注册表与动态加载而不是一股脑堆描述第一次把 20 个工具全部写进 Prompt2B 模型直接懵掉。后来我把工具注册表改成三层结构名称、参数 Schema、调用示例。模型在开始时只看到所有工具的一句话摘要真正执行到某一步时再把它需要的工具完整定义插入上下文。这个“按需加载”的效果非常直接。上下文里不再有几十行用不上的工具描述模型不需要在无关信息里做筛选生成质量立刻上了一个台阶。代价是 harness 要维护一个“当前会话已加载工具”的缓存并在上下文里显式记录哪些工具在加载列表中避免模型以为工具消失了。工具注册表的数据结构我用的 YAML 定义内部转换成 JSON Schema 再做校验长这样name: get_weather description: 查询指定城市的实时天气 parameters: city: type: string required: true description: 城市名称中文不带后缀 unit: type: string enum: [celsius, fahrenheit] default: celsius call_example: get_weather {city: 北京, unit: celsius}call_example 这个字段强烈建议加上。小模型对纯 Schema 的响应不好给一个具体例子之后生成格式的成功率提升非常明显。3.2 输出协议先声明意图再给出参数 JSON我在框架D里把模型输出规范成严格三段式。第一步只输出一个 token 级的动作词比如ACTION第二步输出要调用的工具名第三步输出一行参数 JSON。每一步都有正则和解析器盯着解析失败立即回传错误。拿多步任务中的一步举例模型理想输出是ACTION get_weather {city: 北京, unit: celsius}这不是什么高深设计但它解决了两个实际问题。一是把“自由对话”和“工具调用”在输出空间上劈成两半模型不会再把调用写在解释性文字里二是解析器可以非常鲁棒地处理动作词之外的一切噪声哪怕模型多说了几句废话只要包含这三行就能稳定触发调用。对比框架A里那种“在长文本里找工具名”的做法这种显式协议产生的结果就是目录树式的清晰、稳定几乎没有歧义。在 agent harness 里我认为这是最值得抄走的一块。3.3 错误回传的“话术”设计能扭转半个数量级这是我最意外的发现。框架C和框架D的差别完全不在加载方式而在“工具调用失败后把什么信息喂回给模型”。框架C会把原始异常堆栈直接拼进上下文模型看到一堆英文报错和 traceback直接停止输出或者复读上一轮的错误。框架D则会做一层“错误翻译”把异常转成一句非常具体的中文提示上一次工具调用失败。 原因参数 city 不符合要求。 要求city 必须是字符串类型不能为空。 请重新生成 ACTION。我把同样的错误场景换了三种回传话术测试原始堆栈重试成功率 21%一句话错误描述重试成功率 47%一句话描述 下一步指令关键字重试成功率 73%这背后其实是小模型对“长而复杂的反馈信息”处理能力太弱。原始堆栈对大模型也许不是大事但对 2B 参数来说信息噪音会压过信号。harness 里的错误回传不是简单的异常转发而是要承担“翻译官”的角色——把机器语言翻成人话把“错了”变成“接下来怎么办”。4. 四个框架的横向对比控制变量到底怎么拉平4.1 我把哪些参数焊死成了常量做这种对照实验最怕别人问一句“你确定是同一颗模型吗”我这边的参数清单是这样的同一份模型权重文件未做任何 adapter 微调。采样温度固定 0.2top_p 固定 0.9不开启频率惩罚。最大生成长度统一 512 token。同一个任务集同一个评测脚本同一条评价标准。所有框架共用同一套工具实现工具后端逻辑完全一致。每个任务固定跑 1 遍不做多次采样取最好防止“碰运气”拉高分数。其实“最大生成长度”差点成为变量。框架A因为需要在上下文里堆大量工具描述留给生成的空间变少很容易截断在 JSON 中间。后来我把所有上下文都做了统一精简并给每个任务预留足量输出 token才算把这条变量压住。4.2 从 0.017 到 0.821每一步分数是怎么涨上去的我用的是“增量改造”策略每改一个环节就重跑一次评测而不是一次性换了框架然后庆祝。这样我能说清楚每一分都来自哪个改动。改造顺序改动内容得分变化基线纯文本协议自然语言工具列表无失败回传0.017第一轮改为 JSON Schema 定义工具强制输出 JSON0.412第二轮工具按需加载压缩上下文长度0.577第三轮失败回传用一句话指令替代堆栈0.682第四轮增加“显式动作声明”输出协议0.803第五轮增加任务级重试和部分步骤分数累计0.821可以看到0.017 到 0.412 是最猛的一跳原因是“从自然语言碰运气”转向“强制结构化输出”。后面每一轮改动带来的收益在递减分数曲线也符合边际效应。但我认为从 0.577 到 0.682 这一段最有参考价值因为它纯粹是“话术”层面——不是结构不是协议只是把错误反馈说得更人话小模型就能多救回 10% 的任务。4.3 框架D赢在低摩擦不是赢在某种“魔法”很多朋友看完那个 0.821 第一时间问我“框架D是不是偷偷调了模型”我每次都要解释它赢在低摩擦赢在把每一步的“认知负担”都减到了最低。拆开看框架D并没有让模型做任何不可思议的事。它只是做到让模型永远只面对一种输出格式让模型每次只看到当前步骤需要的工具失败后收到明确、简短、能直接执行的指令多步任务里把历史结果压缩成结构化状态而不是让模型回顾越来越长的对话。对 2B 模型来说这四点每一个都是在帮它“省脑力”。模型不需要在长文本里搜索关键信息不需要自己推断输出格式不需要从报错堆栈里猜错误原因。省下来的注意力全部拿去完成任务推理分数自然上去。5. 开源后的反馈、边界和下一步想做的方向5.1 大家最常问的换成 30B 甚至更大模型差距还存在吗开源之后收到最多的问题就是这个。我的回答是存在但会被压缩。更大的模型更擅长从不规范的文本里恢复意图即使你在框架A那种“放任自流”的模式下它也能靠“脑补”把工具调用写对。差距可能从 50 倍缩小到 2 倍但绝不会消失。做了一个快速验证拿一个 7B 模型跑同样的四套框架得分分别是 0.213、0.664、0.688、0.874。趋势一致框架A还是最差框架D还是最好但差距明显收窄了。这印证了我的判断harness 的设计在小模型上是“救命”在大模型上是“优化”。大部分生产环境摸不到顶级大模型那这套东西的价值就更大。5.2 Harness 里最值得抄走的三个小设计如果你不打算用我这个项目只想自己动手我会强烈推荐先抄这三个设计第一工具 Schema 里必须有 call_example。别把描述写得天花乱坠给一个具体调用例子比什么都管用。第二失败回传必须带“下一步指令”。不要只告诉模型“错了”要告诉它“重新生成 ACTION”很多人忽略这个“下一步指令”恰恰是最省 token 又最有效的。第三轨迹日志必须结构化。每一步动作、工具名、参数、返回摘要、耗时、解析是否成功全部落成一行 JSON。没有这些日志你根本无从定位分数低在哪。日志格式我建议这样{step: 3, action: call_tool, tool: get_weather, args_ok: true, result_ok: true, latency_ms: 320, context_len: 1870}有了这个你可以对任何一次失败做复盘而不需要重新打印整段对话。5.3 边界在哪里以及下一步想继续做的事那些“只靠 prompt 就能解决的”边界正在被快速吃掉但更复杂的多智能体协作、长期任务记忆、并行工具调用还远没有到“换个外壳就能涨分”的阶段。下一步我准备在 harness 里加入两个方向一个是并行工具调用的评测支持让模型可以一次请求多个无依赖工具另一个是“过程质量”评估不只计算任务最终成功与否还看它走了多少冤枉路、有没有反复请求同一个工具。目前这个项目我只保证“在单一会话内完成工具调用型任务”这一条主线的稳定性。多智能体、多会话记忆、多人同时评测这些能力我在收集使用反馈有结论了会继续更新。最后分享一个我个人的体会项目做到一半时我特别想放弃因为 0.017 那个数字实在太打击人了。但坚持把分数拆到每个环节之后我发现大多数问题都不是模型参数不够而是我作为 harness 的设计者把本该自己承担的责任甩给了小模型。现在回头看开源这个项目最大的收获不是那个 0.821而是我终于搞清楚了一条原则——agent harness 的职责不是让模型更强而是让模型不需要那么强也能把任务做完。这条原则换到什么模型上都成立。
