作为一个经常在大模型应用层折腾的开发者，我遇到最常见也最头疼的问题，就是明明在GPT上写得飞起的Skill，换个模型，比如切到Claude，或者本地部署的Qwen，立刻就"智障"了。输出的JSON格式乱了、工具调用直接报错、甚至干脆不按提示词走。很多人把这归咎于"模型不行"，但这往往不是模型的问题，而是你的Skill根本没有做模型适配。今天，我把自己的踩坑和解决方案整理出来，希望能帮你解决掉这个跨模型开发的噩梦。
1. 别急着写代码，先给Skill做一次"体检"
在动手写适配代码之前，我们先要搞清楚一个问题：为什么同一个Skill在不同大模型上表现差异巨大？这就像把同一个员工（Skill）派到不同公司（大模型）工作，每家公司的工作流程、沟通风格、管理工具都不一样，员工当然会水土不服。我不建议上来就埋头改Prompt，那样只会陷入改完A坏B的死循环。
1.1 看清三个"水土不服"的来源
第一个是指令遵循能力的差异。GPT-4o以前时代的模型，你告诉它"只输出JSON格式关联JSON对象"，它可能老老实实照做；但换成某些优化过对话流畅度的模型，它可能会在JSON外加一堆解释性文字，比如"好的！这是您需要的JSON："这种废话。这种差异就和员工对"尽快完成"这个指令的理解一样，有的人认为10分钟，有的人认为一天。
第二个是工具调用的协议不统一。现在的Agent开发重度依赖Function Calling（工具调用）。OpenAI有自己的工具调用格式，Anthropic（Claude）也有自己的一套tool use格式，而Ollama本地模型则可能使用类似OpenAI但又不完全相同的接口。如果你的Skill硬编码了OpenAI的执行逻辑，到了别的模型上，整个工具调用链可能就断了。你需要搞清楚底层调用的是Chat Completions API还是Responses API，这直接决定了消息历史的结构。
第三个是上下文处理机制的差异。有的模型对System Prompt极其敏感（比如老版的Llama），你放一段很长的System Prompt，它会严格按照标准执行；而有的模型（比如某些微调的Qwen版本）对于长Context的召回能力会下降，导致技能中的使用说明被模型"遗忘"。这也是为什么网上很多基于RAG的"skill项目"火的原因。
1.2 给Skill建模：不能只追求"能用"
很多个人开发者写Skill，通常是这样干的：写一个巨长的Prompt模板字符串，里面塞满各种指令和示例，然后通过LangChain框架丢给大模型。这种"铁板一块"的写法，在当前多种模型并存环境下是最失败的。因为这种结构里，业务逻辑、输出格式定义、Few-shot示例全都耦合在一起，乱成一锅粥。我推荐的做法，是需要把Skill看成一个由多个独立组件组合成的"乐高积木块"。
你要记录下这个Skill的核心职责、指定的输出JSON Schema、一张包含多个调用场景的Few-shot示例表，只需给大模型提供精神类输入等。这里重点是掌握一个关键原则：将"思考过程"与"输出格式"剥离。就算底层模型不同，它也绝不能影响这个Skill的业务逻辑，否则换模型就等于重写一个Skill。
2. 拆解Skill的组成：把"提示词"变成"数据"
要想让同一个Skill在不同大模型上运行时表现一致，我们就要把Skill彻底"数据化"。这就像美式餐厅的M记隔音门——把本来就是门套件的东西，做成标准化的半成品，门店只需要按手册组装即可。
2.1 核心抓手：独立的JsonSchema定义
首先，为一个Skill定义输出的JSON Schema。这个是整个适配计划的基础。不管大模型是哪家的，最终我们输出的JSON都要符合这个Schema。例如，一个"客户意图识别"技能的Schema应该是这样的：
{ "name": "customer_intent_skill", "schema": { "type": "object", "properties": { "intent": { "type": "string", "enum": ["咨询", "投诉", "下单", "售后"] }, "keyword": { "type": "string", "description": "作为判断依据的关键词" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": ["intent", "keyword", "confidence"] } }这一个步骤非常关键，千万不要做简单了。很多模型（特别是LLaMA和Gemma系列）非常吃这种严格结构化定义约束。你确定好这个Schema之后，在适配阶段就可以检测对应的行为。这里定义清楚了，后续的提示词动态编译、输出校验和修正就都能自动化掉了。
2.2 提示词模板即"数据包"
我们需要摒弃把一大段System Prompt写在代码里的习惯，改成把提示词拆分成几个互相独立的"数据包"：
- 角色定义包：负责开门见山定义该技能解决的痛点（比如"你是一个专业的客服质检员"）。
- 任务指令包：负责说明步骤（例如"提取对话中的情绪词并给出评分"）。
- 能力指引包：负责告诉模型遇到某种情况时如何解决（例如"如果无法判断用户意图，请标记为需人工确认"）。
- 输出约束包：负责明确输出JSON的格式要求，通常只写两句最严谨的话就够，多余的全是干扰。
每个模型对于这些模块有不同偏好。经验来看，GPT-4级别的模型，你就放一个精简的角色定义和结构化输出要求，它会很快领悟；但和小语种模型（比如BLOOM、Yuan），你就必须提供很详细的步骤和大篇幅的条件判断，否则它会把你的约束当"简历"忽略掉。这里怎么设计呢？我们将这些"数据包"落库管理，每次拼接的时候根据目标Model的名称，通过一个工厂函数去组装。
看一段非常直观的代码：
export function buildSystemPrompt( targetModel: string, skillConfig: SkillConfig ): string { const promptPack = skillConfig.packFor(targetModel); return [ promptPack.coreRole ?? skillConfig.role, promptPack.executionPlan ?? skillConfig.steps.join('\n'), '严格参考以下JSON Schema输出：' + JSON.stringify(skillConfig.jsonSchema), targetModel.includes('llama') ? promptPack.harshRules : '' ].filter(Boolean).join('\n'); }2.3 Few-shot示例：不同模型吃不同量的"厨余垃圾"
这里又要区分了。GPT-4o、Claude 3.5 Sonnet这类一流模型，你给它1-2个高质量示例足以，甚至可以不给。但你若是在本地部署7B/13B级别的Qwen或者Llama，你就必须在Prompt里给足5-8个覆盖各种可能情况的密集示例。模型感觉像在"对照填空"，输出的质量会明显提升。这里我特别建议，千万不要把所有样例一股脑全部堆在messages数组的同一个位置，不同的模型对该位置的信息重视程度不同。比如有的模型对System Message不敏感，你需要把示例放到最后一个User Message之后作为补充引导，这些细节调试很熬人。
3. 模型适配层实战：一套代码，让Llama和GPT跑同一个Skill
理清了结构，终于可以上真实的调试代码逻辑了。这部分是实战环节。我们以最常用的Python来走一遍跨模型适配流程，请直接使用抽象后的逻辑代码（这里不依赖某个具体LangChain，用原生OpenAI兼容库也可以）。
3.1 设计一个"适配器栈"来处理底层死板的东西
我需要创建一个适配层，它统一接收以下输入：消息列表（含System和User）、工具函数定义列表（JSON Schema）、模型名称。适配层内部会根据模型名称做两件事：重写工具调用协议，格式化输出结果。
核心的适配器结构如下：
class SkillExecutor: def __init__(self, model_name: str, skill_config: dict): self.model_name = model_name self.config = skill_config try: self.client = create_client(model_name) # 根据模型初始化OpenAI/Claude/Ollama client def execute(self, user_input: str): # Step 1: 通过config动态编译提示词模板 system_prompt = self.compile_system_prompt() # Step 2: 将JSON Schema统一转换为对应供应商的工具定义格式 tool_schema = self.format_tool_schema(self.config['json_schema']) # Step 3: 发起请求，使用统一的Messages格式 response = self.client.chat.completions.create( model=self.model_name, messages=messages, tools=[tool_schema] if self.supports_tools() else None, temperature=0.1, max_tokens=1000 ) # Step 4: 调用适配层的后处理器处理各类模型的"怪异输出" return self.parse_response(response)3.2 典型调试实况：Llama-3模型使用的"降级"策略
当你接入Ollama等本地跑的Llama-3模型时，适配层就要完成一个不可避免的降级操作。因为本地部署的模型很可能会返回tool_calls为空，甚至会因为调整了temperature导致输出的是混杂Markdown的JSON。这时我们不能干等着，通过几分钟的观察，我摸索出几个较稳定的兼容方案：
- 强制字符串处理：当代码检测到
tool_calls字段为空后，进入逐个分支判断逻辑，直接走字符串解析流。 - 清洗文本：解析前过滤掉前后包裹的```json标记，去除可能存在的注释用双斜杠。
- 人工中场引导：如果还是解析错误，上面说到的适配器栈就自动插入一条OpenAI兼容的对话历史记录："你刚才输出的JSON格式不符合要求，请仅生成有效JSON数组对象，不做任何解释"，然后依此拼接重新请求一次。
# 适配器中的解析降级核心逻辑 def parse_response(self, response): # 直连模式解析结构 if self.supports_tools(): args = response.choices[0].message.tool_calls[0].function.arguments return json.loads(args) # 降级模式：文本模式 content = response.choices[0].message.content # 用正则清洗可能在JSON外层包住的Markdown cleaned = re.sub(r'^```json\s*|\s*```$', '', content.strip()) try: return json.loads(cleaned) except: # 这里触发第二轮人工中场引导重试（代码省略）单独拿出这段代码你就能看到，所谓适配不同大模型，核心其实是对"行为差异"的容忍处理和重试策略。这里我再强调一个容易被忽视的重点：在低于10B参数的模型环境下，少用"Smart Code"的调用方式，多将工具定义转换成自定义RegExp逻辑，从而提高吞吐稳定性。这个思路虽然高级一步，但能躲避模型能力不足导致的安全问题。
3.3 数据返回格式差异：针对供应商做字段映射
即使接的是定义兼容的GPT接口，也可能出现字段不同的情况。比如Claude官方SDK返回里结构是content[].text，OpenAI则是choices[].message.content。如果你在Skill内部写死了response['choices']，那么跑Claude时就得报错。这就是必须实现的适配器层的职责：规范内部统一返回结构（比如kitchen模型返回的标准结构{'output': final_data, 'raw': raw_object}）。
这部分还会牵扯到超时重试和模型限流计数，我就暂不展开，但思路是一致的：底层越乱，上层保障越需要尽可能简单直观。
4. 踩坑记录：解决"不听话"的模型输出问题
你在实际做Skill适配的过程中，绕过某些"大模型不听话"的问题确实能放慢节奏。下面这些都是我经历过且真实有效的方法，整理出来供你少走弯路。
4.1 模型老喜欢在JSON外包裹废话
当你让模型输出"情绪评分并给出标签"时，它偏偏返回："好的，根据您提供的对话内容，我给出了情绪评分：\n{'score': 0.8}"。这个问题很普遍。应对策略有一定层次感。第一次解析，若JSON失败，就用正则提出来\{[\s\S]*?\}丢回去再解析，如果还失败，那就直接执行一次"对话退格重试"。
def extract_json_objects(text): # 利用堆栈追踪结构，适配残缺的JSON文本 stack = [] start = None for i, char in enumerate(text): if char == '{': if not stack: start = i stack.append(char) elif char == '}': if stack: stack.pop() if not stack and start is not None: yield text[start:i+1] start = None4.2 部分模型对参数极其敏感
有些模型对于收到错误参数会validation_error，比如Claude的max_tokens如果设置的低于输出长度，就会导致返回内容被截断且不报错，最后落到JSON解析失败上面。一开始我在Claude Sonnet上调试时发现返回未闭合的中括号，后来逐渐比对，终于发现是max_tokens设置不对。解决方案：适配层自动限定max_tokens至少为输出Schema预估长度的2倍，或者在请求超时前补发一条"继续输出剩余内容"的请求来拼块。这里如果你想灵活一些，可以直接利用上下文缓存（Context Caching）的方式，省你多次会话导致的重试开销。
4.3 弱模型的"建议框"推理
在处理小参数模型时，模型似乎总是在推理时夹藏私货（比如，它反复说"我认为这个意图是投诉"）。要解决逻辑固化问题，你可以添加一个反策略：限制Prompt中禁止使用"感觉"、"判断"、"应该"等弱语义词汇，指令必须用带有明确对象的动词替代，比如"提取"、"标注"、"筛选"。同时，需要采用某种方式约束推理原则（例如："提取意图时，优先匹配FAQ中的精确词组，禁止基于猜测生成原因"）。在经过几次有效适配之后你会进一步发现，不同大模型对这些操作提示词的响应差异会影响到最终JSON的准确度，早做准备也能多留一些余量。
4.4 结合RAG或向量库来强化不太聪明的模型
对于本地部署的7B/8B等小模型，纯靠提示词硬掰肯定不够。最好事先把技能需要的行业术语库、可能用到的枚举值列表（比如所有产品名称）全部注入到一个本地向量数据库。Skill执行输出之前，接入一个memoized_retriever来动态获取最相似内容并塞进上下文。这样模型的确更容易理解新词汇，从而更准确地输出你要的标准值。
5. 最后，聊聊怎么批量测试你的适配体系
适配代码写完了，绝不能上线跑一下就完事，你为了让这个Skill健壮，必须有一套持续的回归测试工程体系。
我们可以整理三类测试数据，跑完一个模型跑另一个。对于每一个受支持的目标模型，都会用同一张标准数据集（包含意图模糊、恶意骚扰、多轮对话等场景）来验收。个人习惯是把每条测试记录都压成JSON存储，然后通过多进程自动并发请求多个模型，快速验证，当出现输出不合法（即不通过前面校验器时）的样本，就立刻存储上下文快照。这个测试集在处理本地模型与云端大模型时有着较好的召回率。
再给你一个较通用的技巧：在跑新模型之前，先跑通一个lint_prompt流程，它可以排查输出模板中隐藏的一处不平衡括号或者错误值枚举，避免模型因为上下文冲突导致输出偏轨。你可以在这一步把大模型名称注入到提示词中，让模型看到基座信息并按指定风格答题——有些模型看到你自己的"身份"信息时会更加游刃有余。
说实话，要让同一个Skill适配所有大模型，就像手握一台多功能路由器，你必须清楚每个底层模型能提供什么服务，接着修改Skill的路由方式、重试机制和解析校验规则。没有那个传说中的"拔插即用"的兴头，但通过真正梳理代码结构并做好适配分层，是足以保证你的Skill在GitHub上获得大量Star并稳定运行的。希望我写的这些经验，对正在为大模型兼容性发愁的你有些许启发。
