如果你的 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)一次驗證每家轉接器有沒有翻譯正確。