Harness Adapter 拆解:同一个模型为什么要为不同 Agent 框架分别训练?
先说结论
Hugging Face 在 2026 年 11 月 20 日发布的 Harness Adapters 实验,给 Agent 工程提出了一个很实际的问题:模型能力不是脱离运行环境存在的,同一个模型放进不同 Agent 框架,工具协议、提示模板、重试方式和轨迹长度都会改变最终表现。因此,针对具体 harness 和任务分布训练一个 LoRA 适配器,可能比继续把通用模型做得更大更有效。
官方最醒目的结果是:Qwen3.8-27B 在 pi 框架上跑 Terminal-Bench 2.1 时,基础模型 pass@1 为 39%,平均每题消耗约 2.9K token;加入针对 pi 训练的强化学习 LoRA 后,成绩升到 55%,平均 token 降到 1.5K。换句话说,适配器同时改善了“做不做对”和“要走多少步”。
我的判断是:Harness Adapter 值得作为中型 Agent 团队的专项优化路线,但不应该被理解成“给每个框架训练一个模型”这么简单。真正重要的是让训练时的 Agent 执行循环和上线时保持一致,并且用可靠的验证器定义什么叫完成;否则强化学习只会把错误的工具习惯学得更牢。
发生了什么
主来源是 Hugging Face 官方博客《Introducing harness adapters: adapt your favorite model to your harness to improve performance and cost》,发布日期为 2026 年 11 月 20 日:
- 原始文章:https://huggingface.co/blog/harness-adapters-at-scale
- 官方代码与文章版本:https://github.com/huggingface/blog/blob/main/harness-adapters-at-scale.md
- 适配器与相关产物集合:https://huggingface.co/collections/harness-hub/qwen38-27b-harness-adapters
官方事实是:研究团队冻结 Qwen3.8-27B 的基础权重,分别在 Pi、OpenCode 和 Hermes Agent 三个真实 harness 内训练 LoRA;训练使用 TRL 的 AsyncGRPOTrainer、OpenEnv 和 Harbor,任务、训练与 Agent rollout 都可以在 Hub Jobs 中运行。每个 harness 都有自己的适配器,另外还把三份 LoRA 合并成一个可以跨三种 harness 使用的 super-adapter。
我的判断是:这篇文章的真正贡献不是某个单一分数,而是把“模型—Agent 框架—任务分布”看成一个联合优化对象。过去大家习惯问“哪个模型最强”,现在更应该问“哪个模型在我的执行循环里最省步骤、最少工具调用,并且能稳定通过我的验证器”。
技术细节
1. 训练的不是抽象模型,而是完整执行循环
很多强化学习 Agent 工作把 Agent loop 重新实现一遍:框架自己定义消息格式、工具接口和 rollout 逻辑,模型在这个简化环境里学习。但 Harness Adapters 的做法不同:让目标 harness 按它原本的方式运行,训练器只通过代理记录它产生的 token 和工具轨迹。
这点很关键。Pi、OpenCode 与 Hermes Agent 的差异不只在名字:它们可能使用不同的系统提示、工具描述、上下文拼接顺序、命令执行方式和失败重试策略。训练阶段如果把这些细节抹平,最终得到的优化很可能只对“训练用的仿真 loop”有效;上线后换回真实 harness,模型的工具节奏就可能失效。
官方最终镜像使用的版本是 Pi 1.5.2、OpenCode 2.2.7 和 Hermes Agent v0.22.6。这里的版本信息不是装饰,而是复现条件的一部分:升级 harness 后,提示模板或工具返回格式变化,旧适配器的收益就需要重新验证。
2. 任务集必须同时满足“能评分”和“值得训练”
强化学习最容易被低估的不是优化器,而是任务与验证器。官方给出的原则很直接:任务必须可以执行,验证器必须能判断结果,而且要有证据证明验证器本身没有把错误答案判成正确答案;如果基础模型已经轻松完成任务,这道题也没有训练价值。
团队把任务来源合并成一条流水线:SWE-smith 通过真实 Python 与 Go 仓库注入缺陷,SWE-Gym 把真实问题和已合并修复转成任务,Tasksmith 则从已合并的变更生成任务。所有任务先经过资格筛选、Harbor 打包与 openenv validate,再用 Qwen3.8-27B 基础模型做难度检查。
这个流程的工程含义是:训练数据不是“越多越好”,而是要同时有真实缺陷、可运行环境、可信测试和适中的难度。没有验证的自动生成任务会把奖励模型带偏;大量基础模型本来就能做的题,则会消耗训练预算而不带来能力变化。
3. AsyncGRPO 如何控制训练成本
最终适配器基于 Qwen/Qwen3.8-27B,使用 TRL 的 AsyncGRPOTrainer,LoRA 采用 all-linear 方式挂载。训练 rollout 阶段关闭 thinking,奖励由验证器正确性和一个小的工具效率奖励组成,工具效率奖励权重为 0.1。
官方还记录了一个很有价值的训练经验:学习率为 5e-5 的较长训练出现 rollout 长度塌缩和熵上升,最终采用 2e-5。这说明“工具调用变少”与“模型不再认真做事”之间只有一线之隔,效率奖励不能脱离正确性奖励单独最大化。
基础设施上,每个适配器使用两张 B200:一张运行 vLLM,另一张负责训练。最终数据混合包括 750 个 harness-adapters 强化学习环境任务和 300 个 termgrade 环境任务。训练累计 598 steps、78,114 个样本、约 167M 训练 token。
4. 专用适配器与 super-adapter 的取舍
三份专用适配器分别针对 Pi、Hermes Agent 和 OpenCode。为了做跨框架版本,团队把三份 LoRA 沿 rank 维拼接,得到 rank 96 的 super-adapter,并比较三种合并权重:三分之一、二分之一和直接相加。
在 Terminal-Bench 2.1 的 89 道任务上,基础模型在三个 harness 的平均 pass@1 为 43.3%,工具调用平均 49.2 次;权重为二分之一的 super-adapter 平均 pass@1 为 52.5%,工具调用降到 25.9 次。直接相加虽然让 Hermes Agent 达到 62.8%,但 Pi 又跌回接近基础模型,平均工具调用进一步降到 13.4 次——这不是纯粹的胜利,更像是模型过度激进地提前结束。
最终的二分之一权重是一个折中:它没有完全保留每个专用适配器的峰值,但跨三种 harness 更稳定。官方也明确建议,如果只使用一个 harness 且关闭 thinking,优先使用对应的专用适配器;super-adapter 更适合需要一份模型覆盖多个运行环境的场景。
5. 结果到底提升了多少
在 SWE-bench Pro 的 51 道困难任务上,Pi 适配器从 39.2% 提升到 64.7%,Hermes Agent 从 29.4% 到 43.1%,OpenCode 从 35.3% 到 51.0%。在 Terminal-Bench 2.1 全量任务上,Pi 提升 16.3 个百分点,Hermes Agent 提升 14.1 个百分点。
效率方面,专用适配器在双方都解决的任务上,SWE-bench Pro 的工具调用减少 56%–72%,Terminal-Bench 2.1 减少 53%–70%。super-adapter 在不同设置下也能减少大量工具调用:部分任务减少 53%–73%,输出 token 也有明显下降。
但官方同时给了一个必须保留的限制:在训练分布外的任务上,Pi 和 OpenCode 只是略高于基础模型,合并适配器基本持平,Hermes Agent 反而低于基础模型。也就是说,适配器对目标 harness 和目标任务确实有效,但它不是普遍智能的免费增益。
对 Agent / 工程的影响
第一,模型评测要绑定执行框架
以后报告 Agent 模型成绩时,只写模型名称和 benchmark 已经不够。至少还应记录 harness 版本、工具集合、最大步骤数、thinking 开关、并发设置和验证器版本。同一个基础模型从 Pi 换到 Hermes Agent,结果差异可能来自执行循环,而不是权重本身。
这也改变了 A/B 测试的做法:如果只替换模型,不固定 harness 与工具 schema,实验结果无法归因。正确的最小实验应固定一套任务和执行框架,只比较基础模型、专用适配器和跨框架适配器三组结果。
第二,工具调用次数是很有用的二级指标
过去大家主要看 pass@1,但 Agent 的真实成本还包括工具调用次数、生成 token、失败重试次数和总延迟。Harness Adapter 的收益很像“让模型更早做出正确动作”:少绕路、少重复查看文件、少调用无关工具。
不过工具调用减少必须与正确性一起看。13 次调用如果意味着提前放弃,就不是效率优化;正确的目标是“在保持任务成功率的前提下减少调用”。工程指标应至少包括:成功率、平均与 P95 工具调用数、输出 token、总时延和验证器拒绝率。
第三,强化学习的核心资产是验证器
如果团队想复用这条路线,第一步不是租 GPU,而是整理自己的任务和验收标准。对代码 Agent 来说,单元测试、静态检查、构建结果和行为测试可以组成验证器;对文档或数据任务,则需要结构化 Schema、事实检查和人工抽样。
验证器还要做“反例测试”:故意给一个表面完成、实际错误的结果,确认验证器会拒绝。否则模型会找到奖励漏洞,学会提交最容易骗过检查的答案,而不是完成真实任务。
第四,专用化要设置维护边界
只要 harness 的系统提示、工具描述或错误格式变化,适配器就可能需要回归。团队不应把它当成永久模型版本,而应该像维护一个带依赖约束的构建产物:记录基础模型、harness 版本、任务集版本、训练超参和评测结果。
如果业务同时运行多种 Agent 框架,super-adapter 可以降低发布和存储复杂度;如果业务只依赖一个框架,专用适配器通常更值得优先测试。不要为了“一个模型到处跑”牺牲掉专用适配器已经验证过的收益。
我的判断
第一,Harness Adapter 是 Agent 优化从提示词工程走向系统工程的信号。决定结果的不只是模型参数,还有它如何看工具、如何处理失败以及何时结束。
第二,真正值得复制的是“真实 harness + 可信任务 + 可审计验证器”的训练闭环,不是某个 55% 的分数。没有闭环,换一个任务分布就会失效。
第三,中型团队不必马上训练大规模适配器。先用固定任务集统计工具调用和失败类型,再判断问题来自模型能力、工具设计还是执行循环;只有确认瓶颈稳定存在,LoRA 强化学习才值得投入。
Q&A
Q1:来源和发布日期是什么?
A:主源是 Hugging Face 官方博客《Introducing harness adapters: adapt your favorite model to your harness to improve performance and cost》,发布日期为 2026-11-20,原始 URL 是 https://huggingface.co/blog/harness-adapters-at-scale。官方文章版本见 https://github.com/huggingface/blog/blob/main/harness-adapters-at-scale.md,模型和适配器集合见 https://huggingface.co/collections/harness-hub/qwen38-27b-harness-adapters。
Q2:Harness Adapter 和普通 LoRA 有什么不同?
A:参数形式仍然是 LoRA,但训练目标不同。普通 LoRA 常围绕静态数据或通用任务训练;Harness Adapter 把完整 Agent 框架放进 rollout,让模型在真实工具协议、提示模板和验证器下学习。因此它优化的是“模型与执行环境的组合”,不是只优化文本输出。
Q3:能不能复现?
A:可以按官方公开配方做最小复现:固定一个基础模型和一个 harness,准备带可信测试的任务,使用 OpenEnv 与 Harbor 打包,在训练前运行 openenv validate,再用 TRL 的 AsyncGRPOTrainer 训练 LoRA。评测时必须固定 harness 版本、工具集合、thinking 设置和任务划分,不能只比较一张最终分数表。
Q4:为什么不同 Agent 框架要分别训练?
A:因为框架改变了模型看到的上下文和行动反馈。工具描述顺序、错误信息、重试策略、终止条件和默认提示都可能影响模型的行为轨迹。专用适配器可以学习这些稳定模式;但如果框架差异很小,先改进工具 schema 和提示模板,可能比训练适配器更划算。
Q5:super-adapter 是否比专用适配器更好?
A:不是绝对更好。super-adapter 的优势是一个产物覆盖多个 harness,跨环境更方便;专用适配器通常在自己的 harness 上峰值更高。官方结果显示合并权重需要折中,直接相加会让部分框架过度提前结束。选择时要看部署规模、维护成本和单框架的性能要求。
Q6:最容易踩的坑是什么?
A:一是验证器接受了错误结果,模型学会钻奖励漏洞;二是只看 pass@1,不看工具调用和 token 成本;三是升级 harness 后仍沿用旧适配器;四是把训练分布内提升误认为通用能力。上线前至少做一次跨任务、跨版本和失败样本回归。
字数自检:正文超过 1500 个中文字符。
隐私自检:未包含内部网络地址、真实机器标识、认证凭据或用户相关信息。
来源自检:已列出官方来源、发布日期和原始 URL。
封面 seed:包含日期与主题 slug,未与历史文章复用。
categories:ai_tech。