请求成功了。响应是有效的 JSON。SDK 没有报错。然而，应用程序却崩溃了。

这是一个关于当你把更换 LLM 提供商视为一次配置更改，而非一场结构性豪赌时，会发生什么的故事。你粘贴了一个新的 base URL，更换了 API key，并保持请求体完全一致，因为文档承诺这是一个与 OpenAI 兼容的端点。对于一个基础的 "hello world" 提示词，它能正常工作。你为此庆祝。随后，真实流量涌入，裂痕随之显现。

协议兼容性的幻象

HTTP 层的兼容性是浅层的。200 状态码和 JSON 响应体意味着服务器接受了你的消息。但这并不意味着服务器的思考方式与之前的提供商相同。OpenAI 兼容的端点共享请求格式，但不共享行为契约。两个提供商可能会接收完全相同的负载，却返回在细微且具有破坏性的维度上完全不同的答案。

你的代码在做假设。你假设 message.content 是一个字符串，因为以前一直如此。你假设工具调用（tool call）会带回干净、可解析的 JSON。你假设 finish_reason 传达的信号正如你所想的那样。这些假设在致命之前都是隐形的。

看看引发这一切的那个崩溃：

const text = response.choices[0].message.content.trim();

这行代码看起来很无害。它已经运行了好几周。然后，新的提供商返回了一个工具调用。在那一刻，message.content 不是一个空字符串，而是 null。实际的负载存在于 message.tool_calls 中，但解析器已经跳过了，对“无”执行了 .trim() 操作。API 没有抛出异常，网络层也没有抱怨。是你自己的解析器杀死了这个请求。

提供商在暗处的分歧

这些差异不会在更新日志中宣告。它们潜伏在响应对象的边缘，等待着边缘情况（edge cases）的出现。

工具调用格式（Tool-call formatting）。 一个提供商将工具参数作为预验证的 JSON 对象发送；另一个则将其作为字段内转义后的字符串发送；第三个可能将一个长工具调用拆分到多个流式增量（streaming deltas）中，迫使你在检查结构是否有效之前必须先对数据块进行缓冲。如果你的应用程序期望的是一个单一的可解析数据块，它就会卡死。

结束原因（Finish reasons）。 OpenAI 使用特定的字符串，如 "stop"、"length"、"tool_calls" 和 "content_filter"。一个兼容的提供商可能会返回 "end_turn"，或者在模型达到 token 上限时直接省略该字段。如果你的重试或回退逻辑在等待 "length" 来检测截断，那么在用户看到一个半成品答案时，你的逻辑会处于闲置状态。

使用情况字段（Usage fields）。 一些提供商会从流式响应中剥离 token 计数，以减少几毫秒的延迟。其他提供商则仅在最后一个数据块中附加使用情况，或者在非流式调用中完全省略它。如果你按 token 向客户收费，而你的计费代码期望每个响应对象中都存在 usage.total_tokens，那么你的计费流水将只会记录零。

流式行为（Streaming behavior）。 服务器发送事件（SSE）本应是标准化的，但不同提供商刷新缓冲区（flush buffers）的频率不同。事件边界各异。一个提供商通过 [DONE] 信号终止流；另一个则在没有任何哨兵信号的情况下直接断开连接。如果你的客户端在等待特定的结束标记，它就会挂起。

错误与超时（Errors and timeouts）。 速率限制（rate limit）在某个提供商那里可能表现为带有 retry-after 请求头的 429 错误，而在另一个提供商那里则是一个模糊的 502 错误。有些提供商接受了请求，然后在网络超时前静默两分钟。OpenAI SDK 不会自动将这些错误归一化为你日志所期望的异常类型。

针对不可预测结构的防御性解析

解决办法不是信任 Schema。解决办法是将每一个响应都视为“嫌疑对象”。

不要假设 content 是一个字符串。在操作它之前先进行检查。

const content = response.choices?.[0]?.message?.content;
const text = typeof content === "string" ? content.trim() : "";

不要假设工具参数是有效的 JSON。模型会提出一个动作，而你的代码必须决定该提议是否足够安全以供执行。为每一个工具参数的解析过程加上 try-catch。如果 JSON.parse 抛出异常，请将该工具调用视为格式错误的垃圾数据，并将其路由到错误处理器。一个幻觉产生的括号或缺失的引号，绝不应该作为未处理的异常向上抛出。

如果 tool_calls 存在但 content 缺失，你的应用程序应该识别出这是一种状态转换。用户并没有得到聊天回复，系统得到的是一个工作指令。这是两条不同的路径，你的路由逻辑在尝试进行字符串操作之前，应当能够识别这种区别。

部署前的行为测试

Pinging the endpoint with a "hi" message proves the network works. It proves nothing about your application.

Before you redirect production traffic, run a targeted behavioral test suite against the new provider:

  • Normal text response. Verify that content exists, is a string, and can be passed through your sanitization pipeline without casting errors.
  • Forced tool call. Set tool_choice to required. Confirm the provider honors it, and check whether content arrives as null, an empty string, or a missing key. Each of those states needs its own handler.
  • Malformed tool arguments. Inject scenarios where the model returns broken JSON inside tool arguments. Ensure your parser rejects them gracefully instead of crashing the worker.
  • Response near the token limit. Push the context window. Check the finish_reason. If the provider returns something unexpected when truncation happens, your summarization or retry logic must know how to react.

These are integration tests, not unit tests. They exercise the real relationship between your code and the provider's personality. Pass them before you call the migration done.

Build an Internal Contract

Provider differences should stop at your network boundary. Do not let them leak into business logic.

Create a normalization layer that consumes the raw SDK response and emits an object your application actually owns. Map provider-specific eccentricities into a stable internal format. If Provider A returns tool arguments as strings and Provider B returns objects, your mapper flattens both into your own ToolRequest structure. If usage is missing, your mapper either estimates it or flags the gap, but it never lets undefined seep into your cost-tracking modules.

If finish_reason is nonstandard, translate it into your own enum of terminal states: COMPLETE, TRUNCATED, TOOL_CALL, FILTERED. Your app should decide what to do based on these clean abstractions, not by sniffing raw strings from a third-party server.

This layer turns provider swaps from a game of whack-a-mole into a single-file change. You rewrite the mapper, run the behavioral tests, and move on. Your application remains untouched.

A Dependency Upgrade, Not a Config Tweak

Switching LLM providers is not like swapping CDN endpoints. It is closer to changing your database from PostgreSQL to MySQL. You would never assume the same connection string means identical query behavior. You would test locking semantics, migration paths, and indexing quirks. LLMs deserve the same respect. They are probabilistic systems masquerading as standard APIs, and their responses carry assumptions about formatting, truncation, and control flow that can shatter your application without raising a single network error.

The bug was never in the connection. It was in the assumption that compatibility means sameness. It does not. Validate the shape. Test the edges. Own the contract.

Source: The Bug Only Happened After I Switched LLM Providers

Community: GyaanSetu AI on Telegram