请求成功，响应是合法JSON，SDK没抛异常——但应用还是崩了。漏洞出现在我将一个LLM应用切换到另一个提供商的OpenAI兼容端点之后。集成看起来太简单：修改base URL，替换API key，保留请求体，直接上线。这个流程对最简单的提示有效，但并不意味着两个提供商会表现一致。故障不在HTTP协议层，而在于我的应用悄悄围绕某个提供商的特定行为建立起来的假设。
兼容的请求不等于兼容的行为
当一个API自称OpenAI兼容时，通常意味着服务器会接受相同的请求结构：{"model":"some-model","messages":[{"role":"user","content":"Summarize this support ticket."}]}
这允许复用客户端和认证模式，但生产环境依赖的不只是服务器是否接受请求，还包括：
- content是字符串、数组、空值还是null
- tool-call参数的序列化方式
- finish_reason可能的取值
- usage字段是否总是返回
- 流式完成的信号方式
- 结构化输出约束是否强制
- 错误、超时和不支持参数的报告方式
两个接受相同请求的提供商，返回的响应在语法上合法，但行为可能截然不同。
解析器中隐藏的假设
我最初的响应处理器隐含假设：const text = response.choices[0].message.content.trim();
这个逻辑一直工作，直到所选模型返回了一个工具调用。此时message.content为null，实际输出在message.tool_calls里。API没有失败，是解析器出了问题。
修复方法：先判断是否存在tool_calls数组且长度大于0，再判断content是否为字符串且非空，否则抛出异常。
工具调用是易碎的边界
工具调用至少引发三个兼容性问题：
1. 参数是否为合法JSON？外层响应是JSON，但嵌套的arguments字符串可能不是。不要直接传递给工具函数，必须先解析并捕获异常。
2. 参数是否满足业务约束？合法JSON不等于合法操作，需要校验字段类型、枚举值等。
3. 如何判断生成已完成？一些集成假设特定的finish_reason一定伴随工具调用，这个假设应该逐个提供商测试。
现在我把tool_calls的存在/有效性和finish_reason视为两个独立信号；如果它们不一致，记录响应并停止任何有副作用的执行。
测试提供商的真实行为，而不仅仅是可用性
普通的健康检查只问“端点能否返回响应”，这对切换提供商来说太弱了。兼容性检查应该问：“这个提供商是否保留了我的应用所依赖的行为？”
提供了一个Node.js测试脚本（需要Node 18+，无外部依赖）：
- 测试文本响应：发送固定回复指令，检查返回是否包含预期字符串。
- 测试工具调用：强制调用create_ticket工具，检查工具调用结构、参数JSON合法性及业务校验。
分别针对当前提供商和候选提供商运行脚本，比较观察结果，而不仅仅是PASS/FAIL。不同的contentType、缺少usage信息、意外的finish_reason或工具调用形状变化，可能无害，也可能暴露应用其他部分的假设。
切换前的测试清单
对于纯文本应用：正常文本响应、故意无效请求、超时/取消、接近输出token限制的响应。
对于智能体或工作流：强制工具调用、多工具可用、格式错误或不完整的工具参数、工具结果返回给模型、流式工具调用、不可重复执行的操作。
对于结构化数据：使用应用实际使用的schema测试，而非玩具对象。
在边界处归一化
一旦知道哪些差异是故意的，就在应用看到它们之前进行归一化：
- 检查choices[0].message是否存在
- 规范化为统一的内部契约：tool_calls数组、文本内容、invalid状态
- 应用其余部分消费这个内部契约，而不是直接依赖每个提供商的响应细节
提供商切换就是一次依赖升级
表面看只是配置变更：-LLM_BASE_URL=... +LLM_BASE_URL=...，但操作上应视为一次重大依赖升级。兼容的端点背后，边界行为（流式、工具调用、结构化输出、token限制、取消、错误语义、用量报告）可能不同。共享接口应该让切换可测试，而不是不可见。
现在，在生产环境修改base URL之前，我都会用相同的测试套件同时运行当前提供商和候选提供商。请求被接受只是第一个测试，不是兼容性的定义。
这段经历来自TokenBay的工程师，相关文章及测试脚本已发布在Dev.to上。
#开发者 #工具 #LLM #OpenAIAPI #兼容性 #Nodejs #TokenBay #AIGateway
@DevToolboxHub