跳轉到主要內容
別讓上游當機變成你的當機。
AIHubMix 提供兩個Key 層級的能力，在主控台設定一次即可生效，用戶端程式碼無需改動：
  • 模型名映射（Model Mapping）是指在閘道層把用戶端請求裡的模型別名改寫為真實上游模型的能力。
  • 錯誤時回退模型（Fallback）是指當主模型呼叫失敗時，閘道按預先設定的優先順序自動嘗試備用模型，對用戶端無感。
這兩個能力適用於所有透過 AIHubMix 接入的用戶端與平台。無論是上游通道臨時故障、需要在多個模型之間做容災，還是用戶端只認特定格式的模型名，過去都要改程式碼或自建閘道才能解決；現在在 AIHubMix 的 Key 設定裡就能完成，不必改用戶端程式碼、也不必自建閘道。
AIHubMix 支援在 Key 層級設定模型名映射與錯誤回退，並按最終回應模型計費。兩者都在 AIHubMix Key 管理頁 為單個 API Key 設定。
在建立 / 編輯 Key 時，可在面板的 Model name mapping 與 Fallback models on error 兩個區塊分別設定：
在 AIHubMix 建立 Key 面板中設定模型名映射與錯誤回退

​
1. 模型名映射（Model Mapping）

模型名映射用於處理「用戶端看到的模型名」和「AIHubMix 實際呼叫的模型」不一致的問題。它是Key 層級（per-key）的別名改寫：把請求裡的別名改寫成你在 Key 裡設定的目標模型。
目標模型在選定通道後，平台內部還會做一層通道級映射到真實上游模型；該層對使用者透明、無需設定。你只需要關心「別名 → 目標模型」這一層。
範例：
用戶端請求模型名（別名）AIHubMix 目標模型
my-gptgpt-5.5-pro
my-fastgemini-3.1-pro-preview
my-coderdeepseek-v4
my-glmcoding-glm-4.6-free
上表模型名均可在 AIHubMix 模型頁 查詢。
常見用途：
  • 用戶端限制模型名格式，例如 Claude Desktop 要求模型名符合 Claude 風格（見 第 5 節）。
  • 給複雜模型 ID 設定更短、更穩定的別名。
  • 用戶端設定保持不變，AIHubMix 後台切換真實模型。
  • 多個平台共用一套接入命名，但根據 Key 路由到不同模型。
逐字元一致：用戶端傳送的模型名必須和映射左側逐字元一致。例如 my-gpt-5.5 和 my-gpt-5-5 是兩個不同的字串，不一致就不會命中映射。

​
2. 錯誤時回退模型（Fallback）

錯誤時回退模型用於在主模型失敗時按順序嘗試備用模型。它不是用戶端側重試，而是 AIHubMix 閘道側在同一個 Key 設定下完成的模型切換；接入方不需要在每次請求裡傳額外路由參數。 可以把 Fallback 理解成「映射到一個有序列表」：主模型失敗後，閘道自動沿列表往下一個備用模型走。 範例（在同一個 Key 裡設定）：
順序備用模型
1gpt-5.4
2gemini-3.1-pro-preview

​
2.1 觸發條件（必須全部滿足才回退）

只有以下條件全部成立時才會發生回退：
  1. Key 設定了非空的備用模型列表。
  2. 主模型的所有通道都被試過、且都以「可重試錯誤」失敗（通道耗盡）。
  3. 回應尚未開始返回（首位元組 / header 還沒發給用戶端）。
  4. 錯誤不是 Key / 使用者級錯誤（見下方 2.2 對照表）。
切到下一個備用模型後，閘道會用新模型重新選通道再試。

​
2.2 哪些會回退、哪些不會

情況是否回退
主模型全通道「可重試失敗」、回應未開始✅ 回退
指定了具體通道（Key 後綴 sk-xxx-{id}、/v1/proxy/{id}/*）❌
回應已開始返回（串流已出首位元組）❌
用戶端中斷 / 請求逾時❌
你的 AIHubMix Key 額度不足 / 失效 / 過期 / 停用❌
帳號封禁 / 命中風控關鍵字❌
免費主模型觸發額度 / 頻率限流✅ 回退到備用付費模型
備用列表裡的免費模型⏭️ 跳過該項，繼續下一個
備用列表裡超出 Key 可用範圍的模型⏭️ 跳過
說明：這裡「Key 失效」指的是你自己的 AIHubMix Key失效，不會回退。若是某個上游通道的 key 壞了，閘道會換通道，通道耗盡後仍可回退——兩者不要混淆。

​
2.3 計費口徑

按最終回應模型計費。 如果最終由回退模型回應，計費、能力和上下文限制都以最終回應的那個模型為準。這個模型也會體現在回應標頭裡（見 第 4 節）。

​
2.4 免費模型規則（重要）

免費模型不能作為 fallback 選項——免費模型只能作主模型，放進備用列表會被靜默跳過，繼續往下一個。所以不要把免費模型寫進 fallback 列表。
典型用法：把免費模型設為主模型、付費模型放進備用列表。免費主模型觸發額度 / 頻率限流時，會自動回退到備用的付費模型——平時省成本用免費額度，限流後無縫切到付費模型保證可用。這是 fallback 最常見的用法之一。

​
3. 和 OpenRouter / LiteLLM 的區別

模型映射和回退並不是新概念，OpenRouter、LiteLLM 等都提供類似能力。AIHubMix 的差異在於設定成本最低：
能力OpenRouterLiteLLMAIHubMix
設定位置程式碼裡，每次請求帶 models 陣列config.yaml，需自建 / 自部署 proxy主控台，按 API Key
啟用要改用戶端程式碼嗎每個請求都要加陣列改設定 + 跑 proxy不用
需要自部署嗎不需要需要不需要
原生協定保留（Claude / Gemini SDK）歸一成一套 schema翻譯轉換保留
按最終回應模型計費是（用你自己的 key）是
一句話：不用自建閘道、不用改一行用戶端程式碼，在 Key 上設定一次就生效。

​
4. 設定與驗證

​
4.1 設定

  1. 在Key裡設定別名映射：左側別名要和用戶端實際傳送的模型名逐字元一致。
  2. 在同一 Key裡設定備用模型列表（有序優先順序列表）。
  3. 備用列表只放付費 / 可用模型，不放免費模型（會被跳過）。
  4. 備用列表裡的模型必須在該 Key 的可用模型範圍內（越權模型會被跳過）。

​
4.2 驗證（優先看回應標頭，而不是翻日誌）

排查時不要只看用戶端選了哪個模型，最權威、可自動化的方式是讀回應標頭：
  • X-Aihubmix-Fallback: true：本次請求發生了回退（最終模型 ≠ 主模型時附加）。
  • X-Aihubmix-Model：本次實際回應、且據此計費的模型。
curl 驗證範例： 
curl -i https://aihubmix.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的 Key" \
  -H "Content-Type: application/json" \
  -d '{"model":"my-gpt","messages":[{"role":"user","content":"hi"}]}' \
  | grep -i -E 'x-aihubmix-(model|fallback)'
主控台日誌可以交叉核對請求模型、映射後主模型和最終回應模型。

​
5. 場景一：Claude Desktop

Claude Desktop 透過 Gateway 接入 AIHubMix，是模型名映射的典型場景。
本節假設你已經完成 Claude Desktop 的基礎接入。完整接入步驟（下載安裝、開發者模式、Gateway 設定、auth scheme 等）見 在 Claude Desktop 中接入 AIHubMix，本節只講映射與回退的增量設定。

​
5.1 為什麼需要映射

Claude Desktop 以 Gateway（Anthropic-compatible）方式接入，用戶端會按 Claude 風格約束模型名，因此模型名必須使用 claude- 前綴。 於是產生一個矛盾：用戶端那側只能寫 claude- 風格的名字，但你真正想呼叫的是 gpt-5.5-pro、gemini-3.1-pro-preview 這些。模型名映射正是為此而生——用戶端寫別名 claude-g-p-t-5.5，AIHubMix 側映射到真實的 gpt-5.5-pro。
Claude Desktop 走的是 Claude 原生 /v1/messages 介面，所以本文範例裡映射和 Fallback 都生效。

​
5.2 AIHubMix 映射與回退設定

範例設定： 
claude-g-p-t-5.5 -> gpt-5.5-pro
claude-gemi-3.1 -> gemini-3.1-pro-preview
claude-depsek-v4 -> deepseek-v4

fallback:
1. gpt-5.4
2. gemini-3.1-pro-preview
AIHubMix 後台設定模型名映射與 Fallback 回退列表

​
5.3 Claude Desktop 模型列表

在 Claude Desktop 的 Model list 裡設定的是映射前的別名——也就是 Claude Desktop 發給 AIHubMix 的模型名，不是真實上游模型名。
Claude Desktop Model list 設定映射前的模型別名
設定完成後，Claude Desktop 的模型下拉框會出現對應模型：
Claude Desktop 模型下拉框出現設定的別名模型
命名建議：
  • Model ID 使用 claude- 前綴。
  • 不要直接寫 gpt、gemini、deepseek 等真實模型系列名，可使用 g-p-t、gemi、depsek 等別名。
  • Model ID 必須和 AIHubMix 映射左側逐字元一致，否則請求不會命中預期映射，可能繼續走錯誤回退模型。

​
6. 場景二：多模態能力兜底

多模態能力兜底用於處理「主模型能回答文字，但不支援當前輸入類型」的場景。比如用戶端傳送了圖片或影片，主模型只有文字輸入能力，AIHubMix 可以繼續嘗試回退列表裡支援對應模態的模型。 下面是一條實際測試鏈路。這條 Key 的映射與 fallback 設定如下（見下方截圖），重點是 fallback 列表裡既有文字模型也有支援圖片理解的模型： 
claude-g-l-m-4.6 -> coding-glm-4.6-free
claude-g-p-t-5.5 -> gpt-5.5-pro
claude-gemi-3.1 -> gemini-3.1-pro-preview

fallback:
1. gpt-5.4
2. gemini-3.1-flash-image
3. veo-3
在 Claude Desktop 裡，選中的模型顯示為 claude-g-l-m-4.6——一個只支援文字輸入的模型。使用者上傳了一張 AIHubMix 模型列表頁面截圖，並詢問「這個網站是做什麼的」。因為請求裡包含圖片，文字模型無法直接處理該輸入，於是觸發了 fallback。
Claude Desktop 中上傳圖片後由兜底模型返回結果
AIHubMix 日誌顯示，這次最終實際呼叫的是 Google AI Studio/gemini-3.1-flash-image，也就是 fallback 列表裡的第 2 個。第 1 個 gpt-5.4 同樣不支援該圖片輸入、對這次請求繼續返回可重試錯誤，於是閘道接著往下，落到了支援圖片理解的 gemini-3.1-flash-image。
AIHubMix 日誌顯示請求最終路由到支援圖片理解的回退模型 gemini-3.1-flash-image
觸發原因要講清：這裡兜底是因為上游對該圖片輸入返回了可重試錯誤、且主模型通道耗盡——和「主模型限流後回退」是同一套回退機制，只是觸發的錯誤類型不同（前者是輸入不被支援，後者是額度 / 頻率限流）。 注意區分理解與生成：這裡說的是圖片 / 影片理解兜底，不是圖片生成或影片生成。聊天請求不會自動變成生成介面；要測試畫圖或影片生成，應走對應的生成介面和模型。模型能力以 AIHubMix 模型頁當前標註的 Input Modalities 為準。

​
7. 場景三：免費模型兜底（省成本 + 保可用）

這是 fallback 最常見的用法之一：把免費模型設為主模型、付費模型放進備用列表。平時請求都走免費模型、省成本；一旦免費主模型觸發額度 / 頻率限流，閘道自動回退到備用的付費模型，保證服務不中斷。 範例 Key 設定： 
主模型（免費）: coding-glm-4.6-free

fallback:
1. gpt-5.4
2. gemini-3.1-pro-preview
行為：
  • 免費額度還夠用時，請求由主模型 coding-glm-4.6-free 回應，按免費計費。
  • 免費主模型觸發限流後，自動回退到 gpt-5.4；若 gpt-5.4 也不可用，再嘗試 gemini-3.1-pro-preview。
  • 最終由哪個模型回應，就按那個模型計費（見 2.3）。
注意：免費模型只能作主模型，不能放進 fallback 列表（放進去會被跳過，見 2.4）。所以「免費兜底」的正確姿勢是：免費在主、付費在備，而不是反過來。
驗證方式同樣是看回應標頭：發生回退時返回 X-Aihubmix-Fallback: true，X-Aihubmix-Model 顯示最終回應模型（見 第 4 節）。

​
8. 支援的端點

模型映射與錯誤回退目前支援以下介面類別：
介面類別Key 別名映射錯誤回退 Fallback
OpenAI 相容介面（/v1/chat/completions、/v1/completions、/v1/embeddings、/v1/images/*、/v1/audio/transcriptions·/translations、/v1/rerank、/v1/moderations、/v1/edits 等）✅✅
Claude 原生 /v1/messages✅✅
OpenAI Responses /v1/responses✅✅
其他原生透傳介面（Gemini 原生、Ideogram、/v1/videos、/v1/audio/speech（TTS）、Stability、OCR、/predictions 等）❌❌
指定通道透傳 /v1/proxy/{channelid}/*❌❌
按資源 ID 檢索 / 檔案類（GET /v1/responses/{id}、/v1/videos/{id}、files 等，請求體不含 model）❌❌
要點：
  • 模型映射與錯誤回退支援 OpenAI 相容介面、Claude 原生 /v1/messages、OpenAI Responses /v1/responses 三類介面。
  • 其他原生透傳介面（Gemini 原生、Ideogram、影片、TTS、Stability、OCR、predictions 等）、指定通道透傳、以及按資源 ID 檢索 / 檔案類介面暫不支援。
  • Claude Desktop 走的是 Claude 原生 /v1/messages，所以本文範例裡映射和 Fallback 都生效。

​
9. 常見問題 FAQ

Q：Claude Desktop 提示 model not found 怎麼辦？ A：檢查 Claude Desktop 裡的 Model ID 是否和 AIHubMix 映射左側逐字元一致；不一致就不會命中映射。 Q：回退會不會影響計費？ A：按最終回應模型計費。最終是哪個模型回應，就按那個模型的價格、能力和上下文限制計算。 Q：怎麼確認這次請求到底走沒走回退？ A：看回應標頭 X-Aihubmix-Fallback: true（發生了回退）和 X-Aihubmix-Model（最終回應模型），見 第 4 節。 Q：哪些錯誤會觸發回退，哪些不會？ A：見 2.2 的對照表。簡單說：上游可重試失敗、通道耗盡、回應未開始才會回退；指定通道、回應已開始、用戶端中斷 / 逾時、Key / 使用者級錯誤都不回退。 Q：免費模型能放進 fallback 列表嗎？ A：不能，會被跳過。免費模型只能作主模型。 Q：和 OpenRouter / LiteLLM 的 model alias / fallback 有什麼區別？ A：AIHubMix 是Key 級、平台託管，在主控台設定一次就生效，不用改用戶端程式碼、也不用自建閘道。詳見 第 3 節。

​
相關資源