这阵子帮几个朋友调模型应用，发现一个特别有意思的现象：大家本地都部署了同一个开源模型，但有人觉得"这模型真聪明"，有人骂"这模型就是个傻子"。同样的模型，差距咋就这么大呢？排查到最后，问题几乎都出在 Harness 上——也就是把模型包起来的那层工程壳子。这次干货周记的番外篇，我就把 Harness 和模型之间的那些隐形关系掰开揉碎聊一聊，先说清楚差异从哪来，再给出一套可以照着做的对比诊断方法。
1. Harness 到底是什么？模型之间的"隐形变量"
1.1 先给 Harness 画个像：模型跑起来之前的那层壳
很多人把"部署一个大模型"理解成"把权重文件下载下来，跑个推理服务就完事"。放在两年前，这个理解没毛病，那时候主流玩法是直接调 OpenAI 接口，模型逻辑和应用逻辑之间只有薄薄一层 API 调用。但现在情况完全不同了，尤其是开源模型和 Agent 应用普及之后，模型权重只是整个系统的一个零件，真正决定用户体验的，是围绕模型搭建的那一整圈工程代码，这圈代码就是 Harness。
我习惯把 Harness 分成两类来看。一类是 Model Harness，主要负责模型推理本身：加载权重、拼 prompt、控制采样参数、解析输出，你可以理解成模型的"驾驶舱仪表盘"。另一类是 Agent Harness，除了管推理，还管工具调用、多轮记忆、任务规划、执行循环，相当于给模型配了一个完整的工作台和秘书团队。热词里同时出现"harness和agent区别"和"agent harness"，说明大家也在纠结这个概念，其实不用太纠结，你只需要记住：不管哪一类，Harness 都在模型之外，但直接决定了模型的本事能不能发挥出来。
我举个不太严谨但特别贴切的类比：模型是发动机，Harness 是整车。同一个发动机，装到家用车上和装到赛车上，零百加速能差好几倍。你能说发动机变了吗？没有。但进气调校、喷油策略、变速箱逻辑、轮胎抓地力全变了，结果自然天差地别。大模型也是一样，模型内部的参数一动没动，但外部给它喂什么、怎么喂、允许它怎么输出、输出后怎么处理，这些全由 Harness 说了算。
1.2 为什么 Harness 能改变模型表现：三层差异理论
要理解 Harness 对模型表现的影响到底有多大，我建议大家把差异拆成三个层次来看。这是我调了几个月各种框架之后总结出来的思路，排查问题时按层次找，特别高效。
第一层是信息注入层，也就是模型在推理前看到了什么。系统提示词的内容、用户输入的组装方式、历史消息的截断策略、外部知识库的注入位置，全在这一层。模型是个纯粹的"基于上文预测下文"的机器，你给它看的东西不同，它的行为就不同。这一层也是最容易拉大差距的地方，因为很多 Harness 在 prompt 组装上的粗糙程度超出你的想象。
第二层是推理控制层，也就是模型在生成时受到哪些约束。采样参数（temperature、top_p）、最大生成长度、停止词、惩罚系数、结构化输出约束，这些参数不同 Harness 的默认值完全不一样。有的 Harness 为了省显存把 max_tokens 设成 512，结果模型话还没说完就被硬生生截断，看起来就像"变笨了"。有的 Harness 把 temperature 设成 0.7，做分类任务时结果忽东忽西，看起来就像"不稳定"。
第三层是结果回收层，也就是模型输出之后，Harness 怎么处理这段文本。是原样返回给用户，还是要求模型输出 JSON 然后解析，还是通过函数调用来强制结构化，还是加了一层后处理正则把有效内容提取出来。这一层的坑也很多，尤其是现在大家都喜欢让模型输出结构化数据，Harness 的解析逻辑稍微笨一点，模型输出再规范也能给你整出 bug 来。
这三层差异单独看都不复杂，但它们叠加在一起的效果惊人。同一个模型，一个精心设计的 Harness 和一个随手写的 Harness，最终表现可能像两个不同水平的模型在对话。这句话不是夸张，我后面会放实测数据。
2. 五个最容易让模型"判若两人"的 Harness 细节
2.1 系统提示词的"前调"效应：第一句话就定调子
先看信息注入层里最基础也最重要的一个环节：系统提示词（system prompt）。模型对一段文本的注意力不是均匀分布的，开头部分对后续生成的影响格外大，这有点像人听汇报时的"第一印象"，所以我把这叫作"前调"效应。
这个细节我在对比 Harness 时发现差距极大。有些 Harness 示例里给的 system prompt 就一句话："You are a helpful assistant." 模型收到这种指令也能干活，但等于把模型扔进一个没有规则的考场。而好的 Harness 会在 system prompt 里写清楚角色定位、回答风格、输出格式、禁忌事项，甚至给一两个 few-shot 示例。同样是让模型从一段合同里抽取关键条款，前者可能给出大段废话还漏项，后者能直接输出规范的 JSON 数组。
这里我要特别提醒一个容易踩的坑：系统提示词不是越复杂越好。我见过有人把 system prompt 写成 3000 字的"企业规章制度"，结果模型变得极度保守，问什么都说"根据规定无法回答"。Harness 设计系统提示词的难点在于平衡，既要给足约束，又不能把模型的发挥空间全堵死。我自己常用的判断标准是：把 Prompt 里的每个句子都过一遍，问自己"这句话对模型完成目标是有帮助，还是只是在表达焦虑"，那些只是表达焦虑的句子，删掉。
2.2 采样参数默认值：temperature 在悄悄变，你可能没发现
再来说推理控制层里最容易忽略的变量：采样参数。很多 Harness 框架都有默认参数，但默认值究竟是什么，不同框架天差地别。这直接解释了一个常见现象——你在 A 框架里测得效果很好的 Prompt，原封不动搬到 B 框架里，输出风格突然就变了，不是模型换了，是采样参数换了。
我实际遇到的典型情况是这样的：框架 A 默认 temperature=0.1，适合稳定输出，你写的 Prompt 也是奔着稳定去的；框架 B 默认 temperature=0.7，明显更发散，同一个 Prompt 跑出来就带上了"创作味儿"。反过来也有，框架 A 默认 0.7，框架 B 默认 0.1，你从 B 搬到 A，会突然觉得模型"放飞自我"了。
所以我的第一个建议是：任何 Harness 接进来，第一件事就是把它的采样参数默认值全部打出来看一眼，尤其是 temperature、top_p、max_tokens、presence_penalty 和 frequency_penalty 这五个。第二个建议是：做 Prompt 评测时，一定要在采样参数完全一致的前提下测，不然你评估的根本不是 Prompt 好坏，而是参数差异导致的噪声。第三个建议是，别盲目相信"temperature 越低越稳定"，确实低温度能减少随机性，但也会让模型更容易陷入重复和机械式回答，如果你的任务需要一定灵活性，反而应该稍微调高。
2.3 上下文窗口的裁剪与注入策略：模型只看得见它"眼前"的东西
上下文窗口的管理是 Harness 技术含量最高的部分之一，也是模型表现差异最大的来源之一，但很多人根本没意识到这里还有讲究。每个模型都有上下文长度上限，当你的对话历史、知识库内容、工具返回结果加起来超过上限时，Harness 必须选择"扔掉"哪些内容。
最简单的 Harness 采取的策略是"掐头留尾"：从最早的消息开始删，删到剩余内容塞得进窗口为止。这个策略在小上下文场景下凑合能用，但对话一长就会出问题，更可怕的是它会把中间部分的指令和历史信息丢掉。学术上有个著名的"lost in the middle"现象：大模型对长上下文开头和结尾的内容记忆最清楚，对中间部分最健忘。一个只做简单截断的 Harness，等于主动把重要信息推到了模型的盲区。
好的 Harness 会做更聪明的处理，比如把历史对话做摘要压缩，保留核心信息而不是逐字保留；把 RAG 检索到的文档按照相关度重新排序，把最重要的内容放在开头和结尾；或者对系统指令做"锚定"，保证无论上下文多长，关键指令永远占据窗口里的固定位置。这个环节的差异在复杂任务里体现得淋漓尽致：同一个模型，用带摘要压缩的 Harness 能稳定完成 20 轮以上的多轮任务，用简单截断的 Harness 到第 8 轮就开始"失忆"回答问题驴唇不对马嘴。
2.4 输出解析：模型其实答对了，是 Harness 把结果整坏了
测试模型应用时，我经常遇到一种让人哭笑不得的情况：调用日志里模型返回的内容明明是对的，但应用最终显示的结果是错的。这类问题十有八九出在输出解析环节。模型吐出来的是文本，Harness 要把它变成程序能用的数据，这中间的"翻译"做得不好，锅就甩到了模型头上。
常见的坑有三种。第一种是要求模型输出 JSON，但 Harness 没有做格式约束，模型输出了 JSON 外面包着 ```json 代码块标记，json.loads 直接报错。第二种是 Harness 用正则表达式从模型输出里硬抠内容，匹配规则写得太贪婪或者太保守，把有效内容截掉了一块。第三种是模型输出了 JSON，但 JSON 里面有换行符、Unicode 转义，Harness 的解析器处理不了。
为什么说这能造成"模型差距大"的错觉？因为普通用户只看最终结果，不会去翻日志。A Harness 老老实实把模型输出的 JSON 解析成功，显示正常；B Harness 解析失败后返回一句"系统错误"，用户就觉得 B 用的模型不行。解决方案其实不复杂，一个是尽量用模型自带的 function calling 或结构化输出能力，让模型直接在受限格式里生成；另一个是给 Harness 加上"输出修补"逻辑，解析失败后把代码块包装去除、补全残缺括号后重试。但这些都是 Harness 层面的功夫，和模型本身一点关系都没有。
2.5 工具调用与 Prompt 模板差异：同一个模型，Agent 能力忽强忽弱
Agent Harness 兴起之后，工具调用变成了新的差异放大器。模型本身有没有工具调用能力是一回事，Harness 怎么把工具定义、调用指令、工具结果回填给模型是另一回事。我把这两者分别叫作"模型的天赋"和"Harness 的翻译质量"，Agent 场景下，翻译质量对最终表现的影响甚至超过天赋。
不同 Harness 对工具的描述格式完全不统一。有的用 OpenAI 风格的 tools 列表，每个工具包含 name、description、parameters 的 JSON Schema；有的用自定义的 XML 格式，把工具写在 标签里。同一个模型对这两种格式的敏感度差异很大，有些模型在 OpenAI 风格格式下工具选择准确率高达九成，换成 XML 格式直接掉到六成以下。
另外还有工具结果的回填细节。有的 Harness 把工具返回结果原封不动塞进上下文，结果可能长达几千 token，把上下文窗口挤爆了；有的 Harness 会做结果摘要，只保留关键字段。我在实际使用中发现，工具结果回填后模型的下一步决策质量，高度依赖这个细节。如果你发现同一个模型在 A 框架里很会"用工具"，在 B 框架里像个"工具白痴"，先去查工具 schema 和结果回填逻辑，别急着换模型。
3. 实测对比：同一个模型在两个 Harness 里的表现差在哪
3.1 准备一套可复现的对比实验方案
前面讲的都是原理，下面给一套可以实际操作的对比方案。我自己做模型应用评估时，一直用"同一模型、同一任务、不同 Harness"的控制变量法，先把模型固定死，再测 Harness 的差异。这套方案不需要复杂的评测集，只需要准备一组有明确标准的测试用例就行。
测试任务我建议选三类：第一类是常规问答，用来感受输出风格的差异；第二类是结构化抽取，让模型从给定文本中提取指定信息并以 JSON 输出，用来测输出解析链路；第三类是工具调用，给模型一个可用工具，看它能不能正确选择并格式化参数。我这次测试用的是本地部署的一个 DeepSeek 系列开源对话模型，跑在两个 Harness 上——一个是我自己写的最小化推理封装，直接调用模型推理接口，自定义 prompt 模板和参数；另一个是带 Agent 编排能力的现成框架，支持工具调用和多轮管理。两个 Harness 部署在同一台机器上，用的是同一个模型权重文件。
这里要特别强调：测试时一定要把变量锁死。如果你要测 Harness 本身，就不要同时换模型版本，也不要在两个 Harness 里设置不同的 temperature。我在自研封装里把 temperature 设为 0.3，再把 Agent 框架的 temperature 也改成 0.3，这样测出来才是纯粹的 Harness 差异。不然你根本说不清结果是框架造成的还是参数造成的。
3.2 第一组对比：常规问答场景下的直接观感
第一个测试很简单，我问两个 Harness 同一个问题："用三句话向一个完全不懂技术的人解释什么是 API。"两个 Harness 都用的同一个模型，但回答风格差异非常明显。
自研封装的表现中规中矩，回答大概是"API 是一种让不同软件之间互相沟通的约定，就像餐厅里的服务员，帮你把需求传给后厨，再把做好的菜端回来。程序员按照这个约定写代码，就能让两个原本不认识的应用顺利协作。"这个回答结构清楚，比喻也贴切，属于正常水平。
Agent 框架的回答就更有"框架感"：它没有直接回答，而是先把我的话复述了一遍，然后说"这是一个非常好的问题，让我先想一下怎么回答最合适"，接着引用了自己在系统提示词里被设定的角色，最后才给出类似内容但明显更长、更正式的解释。论信息量，两者差不多；论用户体验，前者反而更清爽。这就是 Harness 在 system prompt 里加了太多"角色扮演"和"思考过程"指令导致的输出冗余。如果你的应用追求效率，这种"仪式感"就是负优化。
3.3 第二组对比：结构化输出场景下的格式血泪史
第二个测试是结构化抽取，我给了两段客户反馈文本，要求模型输出一个 JSON 数组，每个元素包含 sentiment（情感倾向）、category（问题分类）、suggestion（建议），并且要求只输出 JSON，不要解释。这个任务最能体现 Harness 在输出约束和解析层面的差距。
自研封装这边，我在系统提示词里明确写了 JSON 结构定义和示例，同时把 temperature 调到 0.2，模型输出了一个干净合法的 JSON 数组，解析一次成功，整个链路非常顺滑。
Agent 框架那边就翻车了。它的系统提示词里有一堆关于"你必须以助手身份友好地回复"之类的指令，和 JSON 输出要求互相打架。模型输出的内容里先是来了一句"好的，我已经分析了您的反馈，以下是结构化结果："，然后才输出 JSON，而且 JSON 外层还带了 markdown 代码块标记。框架自带的结果解析器碰到这种输出，直接报 JSONDecodeError。如果你只看最终效果，会以为这个模型在 A 框架里"很听话"，在 B 框架里"乱输出"。实际上模型的底层能力没变，变的是 Harness 给它的指令结构和解析容错。
这个问题在真实项目里太常见了。我见过一个团队因为类似问题，花了整整两周去微调模型，想让模型"输出更规范的 JSON"，结果发现罪魁祸首是框架的输出解析链路不够健壮。建议大家遇到结构化输出不稳定时，先打开原始推理日志，看看模型真正输出了什么，再判断是模型的错还是解析器的错。
3.4 输出差异归因：一份四步走的诊断清单
为了让大家排查时有个抓手，我把这次踩坑经验整理成了一份四步归因清单。以后遇到"同一模型换框架就变笨"的问题，按这个顺序查，至少能覆盖八成以上的原因。
第一步查系统提示词：对比两个 Harness 实际拼装出来的完整 prompt，而不是只看你在配置界面写的那部分。很多框架会在你写的内容之外偷偷加东西，比如固定的角色前缀、安全提示、输出格式要求。这些附加内容很可能在跟你的业务指令抢注意力。
第二步查采样参数：确认两个 Harness 的 temperature、top_p、max_tokens、惩罚系数是否一致。特别注意 max_tokens，这个参数最容易在长任务里制造"模型话说到一半就没了"的假象。
第三步查上下文截断策略：如果对话或者输入文本较长，去看看 Harness 是否截断、截断的是哪部分。凡是简单掐头留尾的，出了问题是大概率事件。
第四步查工具调用模板：两个框架对工具的定义格式是否一致，工具描述够不够清晰，工具返回结果回填时有没有被过度截断。如果 Agent 框架的工具选择准确率忽高忽低，问题基本就出在这一步。
这张清单我贴在工位旁边很久了，每次排查问题都从它开始。绝大多数所谓"这个模型不适合这个框架"的结论，查完这四步之后都会变成"这个框架的默认配置不太合适"。
4. 常见问题与排查技巧实录
4.1 现象：同样的提示词，在两个框架里结果完全不一样
这是被问到最多的问题。很多人觉得"提示词一样，模型一样，结果就该一样"，实际上框架在背后做了太多你不知道的事。排查方法很简单，就是上面清单的第一步：把两个框架实际发给模型的完整消息体打印出来，一行一行对比。我敢说大多数情况下你会发现，两个框架最后拼出来的 prompt 根本不一样。
有个印象很深的案例：一个朋友在 A 框架里写了 system prompt，要模型"始终用中文回答"，测试正常；搬到 B 框架后，模型时不时蹦英文。他一度怀疑是模型量化版本的问题，后来把 B 框架的实际请求体拉出来一看，发现这个框架在系统提示词里追加了一句"You are a helpful assistant designed to respond in English." 好家伙，框架自己的默认 prompt 直接覆盖了用户设定。这种问题不看实际请求体，查一辈子都查不出来。
所以我的建议是：凡是框架，第一件事先搞清楚它的 prompt 组装逻辑，特别是它会不会在用户 prompt 之前或之后注入隐藏内容。翻文档也好，看源码也好，总比自己瞎猜强。用完框架后如果觉得模型"不听话"，先怀疑框架有没有"抢台词"。
4.2 现象：模型输出被截断，或者内容出现重复
这类问题我遇到多次，原因集中在两个地方：一个是 max_tokens 设置太小，模型还没把话说完就被硬截断。另一个是停止词配置不当，模型输出了不该触发停止的符号，提前终止了生成。尤其是让模型输出代码或 JSON 的时候，如果 Harness 把换行符或者某个标点设成了停止词，那输出内容就会诡异地缺胳膊少腿。
排查思路很简单：看原始输出和 token 用量。如果每次输出都刚好卡在接近 max_tokens 的位置，那就是长度限制的问题，调大就行。如果输出戛然而止但 token 用量远没到上限，检查停止词和采样参数，有时候 temperature 太高也会导致模型输出出现异常重复，这是模型绕进了重复循环，不是 Harness 的错，但一个带重复惩罚的 Harness 能很好地抑制这种问题。我自己的习惯是把 frequency_penalty 设到 0.3 左右，既能防重复，又不会太影响表达的自然度。
4.3 现象：同一个 Harness，换模型版本就"变笨"
这个现象看起来是模型的问题，其实也跟 Harness 有关。不同版本的模型，对 prompt 格式的敏感度可能不同，对工具调用的格式要求也可能不同。Harness 里写死的那些"针对旧版本优化的 prompt 模板"，放在新版本上未必适用。
举个例子，某个模型的旧版本对 tools 定义里的 description 字段不太敏感，工具名取得好就行；新版本微调后更依赖 description 的语义清晰度，如果你的 Harness 还是沿用旧版那套"工具名简短、描述敷衍"的模板，工具调用准确率就会明显下降。这不叫模型变笨了，这叫你的 Harness 在模型升级后没有同步升级。
遇到这种情况，我建议把 Harness 和模型的版本组合当成一个整体来管理。每次升级模型，都跑一遍回归测试，特别是在结构化输出和工具调用这两个最敏感的环节。同时把 prompt 模板也纳入版本管理，不要觉得 prompt 是"写一次就完事"的东西，模型在变，prompt 就必须跟着变。
4.4 避坑经验总结：让 Harness 为你所用，而不是被它牵着走
最后分享几点这几年被反复验证的避坑经验。第一条，阅读日志永远比阅读框架文档重要。框架文档告诉你"设计上应该怎样"，日志告诉你"实际上到底怎样"。遇到问题先看真实请求和真实输出，不要急着改代码。
第二条，给 Harness 的每个关键配置做版本记录。包括 system prompt、采样参数、上下文截断策略、工具 schema，这些全要留痕。记录这些不费多少功夫，但能在对比测试时帮你精确复现任何一次历史表现。我见过太多人凭记忆调参，调来调去最后连自己也说不清哪组配置好。
第三条，也是我最想强调的：评价一个模型好不好用之前，先问一句"我这个 Harness 有没有拖它的后腿"
