從模型適配層開始:用統一介面馴服多家 LLM API 差異的實戰指南

如果你的 AI 應用只接一家模型,這篇可以先略過;但只要你開始做備援、比價,或按任務挑模型(也就是上一篇談的模型路由與降級),很快就會撞上一堵牆:同一段業務程式,換個 model 就報錯;串流格式各家長得不一樣;工具呼叫的欄位名稱不同;錯誤碼一家是 429、另一家是 rate_limit_error。這篇要做的,就是在你的應用與各家 API 之間墊一層「轉接頭」——模型適配層(LLM Adapter / Provider Adapter),把差異關在一個地方,讓上層永遠只講一種語言。

一、為什麼需要適配層:三個真實痛點

別急著寫抽象,先看清楚差異到底長在哪裡:

  • 請求格式差異:messages 的結構、system 訊息要不要獨立放、參數名(有的叫 max_tokens、有的叫 max_completion_tokens)、temperature 的支援範圍,甚至圖片要塞 image_url 還是 content block。
  • 回應與串流差異:有的放在 choices[0].message.content,有的放在 content 陣列裡;SSE 事件名稱不同、有沒有 [DONE] 結尾、usage 藏在最後一個 chunk 還是獨立欄位。
  • 能力與錯誤差異:JSON 模式 / strict 的支援程度、Function Calling 的說明格式、429 與 5xx 的重試語意,全部不一樣。

重點:適配層的目的不是把各家「削成最低公分母」,而是把差異收斂在單一檔案——業務碼不必知道今天背後是誰在回答。這跟前面聊過的 MCP(把「工具」標準化)不同:MCP 統一是「AI ↔ 外部工具」的協定,適配層統一的是「應用 ↔ 模型供應商」的介面。

二、先定義自己的語言:最小共用介面

關鍵心法:不要照抄任何一家的格式當共用介面,否則換家時你會被當初抄的那家綁架。定義一個只服務你應用的精簡型別:

// 應用內部統一的請求 / 回應(與任何一家廠商無關)
type ChatRequest = {
  model: string;            // 邏輯名,如 "fast" / "strong",不是廠商型號
  system?: string;
  messages: { role: "user" | "assistant" | "tool"; content: string }[];
  tools?: ToolDef[];
  jsonMode?: boolean;
  stream?: boolean;
};

type ChatResponse = {
  text: string;
  toolCalls?: { id: string; name: string; args: unknown }[];
  usage: { input: number; output: number };
  finishReason: "stop" | "length" | "tool" | "error";
};

重點:用邏輯模型名而非廠商型號,路由與降級(555)才能在不動業務碼的前提下換模型;usage 一併正規化,成本看板與快取命中率(553)才算得準。

三、實戰四步驟

步驟 1:定義 Provider 介面,一家一個檔案

interface LlmProvider {
  chat(req: ChatRequest, apiKey: string): Promise<ChatResponse>;
  stream(req: ChatRequest, apiKey: string): AsyncIterable<string>;
}

每個供應商一個 providers/xxx.ts,只做「翻譯」,不做任何業務判斷。金鑰一律由後端代理傳入(沿用 511 的習慣),絕不進前端。

步驟 2:寫第一個轉接器(請求翻譯 + 回應正規化)

// providers/providerA.ts —— 這家的怪脾氣全部關在這個檔案
export const providerA: LlmProvider = {
  async chat(req, apiKey) {
    const body = {
      model: MODEL_MAP[req.model] ?? MODEL_MAP.fast,
      messages: [
        ...(req.system ? [{ role: "system", content: req.system }] : []),
        ...req.messages.map(toVendorMessage),        // role / content 對齊
      ],
      max_tokens: 1024,
      ...(req.jsonMode ? { response_format: { type: "json_object" } } : {}),
      ...(req.tools ? { tools: req.tools.map(toVendorTool) } : {}),
      stream: false,
    };
    const r = await fetch(ENDPOINT, {
      method: "POST",
      headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
      body: JSON.stringify(body),
    });
    if (!r.ok) throw normalizeError(r.status, await r.text());  // 統一錯誤型別
    const j = await r.json();
    return normalizeResponse(j);                      // 各家欄位 → ChatResponse
  },
  async *stream(req, apiKey) { /* 見步驟 3,統一吐純文字片段 */ },
};

注意 normalizeError:把 429、5xx、timeout 收成同一種錯誤物件,fallback 鏈(555)才不用為每家寫一次判斷。結構化輸出(551)的 strict 也放在這裡決定要不要下發,而不是散在 Prompt 裡。

步驟 3:串流正規化——最容易被忽略的一層

async function* normalizeSSE(res: Response): AsyncIterable<string> {
  const reader = res.body!.getReader();
  const decoder = new TextDecoder();
  let buf = "";
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    buf += decoder.decode(value, { stream: true });   // 半包別急著 parse
    const lines = buf.split("\n");
    buf = lines.pop() ?? "";                          // 留最後一行給下一輪
    for (const line of lines) {
      if (!line.startsWith("data:")) continue;
      const payload = line.slice(5).trim();
      if (payload === "" || payload === "[DONE]") continue;
      const chunk = JSON.parse(payload);
      const piece = chunk.choices?.[0]?.delta?.content
                 ?? chunk.delta?.text ?? "";          // 各家欄位不同
      if (piece) yield piece;                        // 上層只看到純文字
    }
  }
}

特別注意:SSE 是位元組流,不是「一行一個完整 JSON」,一個 chunk 可能切在半個字或半個物件中間,所以一定要緩衝最後一行。這正是最早接模型(511)時最容易漏、上線後又最難除錯的細節。

步驟 4:註冊表 + 能力宣告,讓路由有依據

export const REGISTRY = {
  providerA: { adapter: providerA, caps: { json: true,  tools: true,  vision: true  } },
  providerB: { adapter: providerB, caps: { json: true,  tools: false, vision: false } },
};

export function chat(req: ChatRequest) {
  const { adapter, caps } = REGISTRY[route(req)];        // 555 的 route 選型
  if (req.jsonMode && !caps.json) throw new Error("此模型不支援 JSON 模式");
  if (req.tools?.length && !caps.tools) throw new Error("此模型不支援工具呼叫");
  return adapter.chat(req, getKey());
}

重點:能力表(caps)要跟著適配層走。降級時你才知道「換過去會少什麼」——是少了 JSON 約束(551)、還是少了工具(520),而不是等線上炸了才發現。這就是 555 提過「各家 payload 需 adapter」的真正落地。

四、三條紀律與三個坑

  • 差異只進一個檔案:千萬別在業務碼裡寫 if (model === "xxx"),否則接第三家就是災難。
  • 別削到最低公分母:用 caps 宣告 + 明確降級,比「全部只支援純文字」務實得多。
  • 錯誤與 usage 也要正規化:觀測(505)、評估(528)、成本(553)才對得上同一把尺。

三個最常踩的坑:① 參數名看似相同、語意不同(同一個 max_tokens 在兩家可能一個是輸出上限、一個含輸入);② 工具呼叫 id 回填格式不同,多工具並行(533)時最容易串錯腿;③ 串流下的 usage 常只出現在最後一個 chunk,漏接就讓成本看板長期失準。

五、什麼時候不必用

只接一家、且短期內不會換,直接呼叫就好,別為了「架構好看」多墊一層抽象。等到你真的要接第二家、要做故障轉移、或想把模型當成可替換零件時再抽出來,重構成本最低、邊界也最清楚。架構是為了解決已經發生的痛,不是為了預支還沒來的痛。

本文為技術實作分享,程式碼為示意精簡版,上線前請依各供應商官方文件調整欄位與錯誤處理。

互動話題:你的應用現在接了幾家模型?最讓你頭痛的是「參數名不同」、「串流格式不同」,還是「工具呼叫對不起來」?歡迎留言分享,下次我們可以來聊適配層的自動化回歸測試——用同一份測試集(呼應 528)一次驗證每家轉接器有沒有翻譯正確。