> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 模型映射與回退
> 在 AIHubMix 主控台為每個 API Key 設定模型名映射與錯誤時回退：把用戶端的模型別名改寫為真實上游模型，主模型失敗時自動切換到備用模型，按最終回應模型計費，用戶端程式碼零改動。
> 別讓上游當機變成你的當機。
AIHubMix 提供兩個**Key 層級**的能力，在主控台設定一次即可生效，用戶端程式碼無需改動：
* **模型名映射**（Model Mapping）是指在閘道層把用戶端請求裡的模型別名改寫為真實上游模型的能力。
* **錯誤時回退模型**（Fallback）是指當主模型呼叫失敗時，閘道按預先設定的優先順序自動嘗試備用模型，對用戶端無感。
這兩個能力適用於所有透過 AIHubMix 接入的用戶端與平台。無論是上游通道臨時故障、需要在多個模型之間做容災，還是用戶端只認特定格式的模型名，過去都要改程式碼或自建閘道才能解決；現在在 AIHubMix 的 Key 設定裡就能完成，不必改用戶端程式碼、也不必自建閘道。
AIHubMix 支援在 Key 層級設定模型名映射與錯誤回退，並按最終回應模型計費。兩者都在 [AIHubMix Key 管理頁](https://console.aihubmix.com/token) 為單個 API Key 設定。
在建立 / 編輯 Key 時，可在面板的 `Model name mapping` 與 `Fallback models on error` 兩個區塊分別設定：
***
## 1. 模型名映射（Model Mapping）
模型名映射用於處理「用戶端看到的模型名」和「AIHubMix 實際呼叫的模型」不一致的問題。它是**Key 層級**（per-key）的別名改寫：把請求裡的別名改寫成你在 Key 裡設定的目標模型。
> 目標模型在選定通道後，平台內部還會做一層通道級映射到真實上游模型；該層對使用者透明、無需設定。你只需要關心「別名 → 目標模型」這一層。
範例：
| 用戶端請求模型名（別名） | AIHubMix 目標模型 |
| ------------ | ------------------------ |
| `my-gpt` | `gpt-5.5` |
| `my-fast` | `gemini-3.1-pro-preview` |
| `my-coder` | `deepseek-v4-flash` |
| `my-glm` | `coding-glm-5.2-free` |
> 上表模型名均可在 [AIHubMix 模型頁](https://aihubmix.com/models) 查詢。
常見用途：
* 用戶端限制模型名格式，例如 Claude Desktop 要求模型名符合 Claude 風格（見 [第 5 節](#5-場景一：claude-desktop)）。
* 給複雜模型 ID 設定更短、更穩定的別名。
* 用戶端設定保持不變，AIHubMix 後台切換真實模型。
* 多個平台共用一套接入命名，但根據 Key 路由到不同模型。
> **逐字元一致**：用戶端傳送的模型名必須和映射左側**逐字元一致**。例如 `my-gpt-5.5` 和 `my-gpt-5-5` 是兩個不同的字串，不一致就不會命中映射。
***
## 2. 錯誤時回退模型（Fallback）
錯誤時回退模型用於在主模型失敗時按順序嘗試備用模型。它不是用戶端側重試，而是 AIHubMix 閘道側在同一個 Key 設定下完成的模型切換；接入方不需要在每次請求裡傳額外路由參數。
可以把 Fallback 理解成「映射到一個**有序列表**」：主模型失敗後，閘道自動沿列表往下一個備用模型走。
範例（在同一個 Key 裡設定）：
| 順序 | 備用模型 |
| -- | ------------------------ |
| 1 | `gpt-5.4` |
| 2 | `gemini-3.1-pro-preview` |
### 2.1 觸發條件（必須全部滿足才回退）
只有**以下條件全部成立**時才會發生回退：
1. Key 設定了非空的備用模型列表。
2. 主模型的**所有通道都被試過、且都以「可重試錯誤」失敗**（通道耗盡）。
3. **回應尚未開始返回**（首位元組 / header 還沒發給用戶端）。
4. 錯誤不是 Key / 使用者級錯誤（見下方 [2.2 對照表](#2-2-哪些會回退、哪些不會)）。
切到下一個備用模型後，閘道會用新模型重新選通道再試。
### 2.2 哪些會回退、哪些不會
| 情況 | 是否回退 |
| ------------------------------------------------ | :-----------: |
| 主模型全通道「可重試失敗」、回應未開始 | ✅ 回退 |
| 指定了具體通道（Key 後綴 `sk-xxx-{id}`、`/v1/proxy/{id}/*`） | ❌ |
| 回應已開始返回（串流已出首位元組） | ❌ |
| 用戶端中斷 / 請求逾時 | ❌ |
| 你的 AIHubMix Key 額度不足 / 失效 / 過期 / 停用 | ❌ |
| 帳號封禁 / 命中風控關鍵字 | ❌ |
| 免費主模型觸發額度 / 頻率限流 | ✅ 回退到備用付費模型 |
| 備用列表裡的**免費模型** | ⏭️ 跳過該項，繼續下一個 |
| 備用列表裡超出 Key 可用範圍的模型 | ⏭️ 跳過 |
> 說明：這裡「Key 失效」指的是**你自己的 AIHubMix Key**失效，不會回退。若是某個**上游通道**的 key 壞了，閘道會換通道，通道耗盡後**仍可**回退——兩者不要混淆。
### 2.3 計費口徑
**按最終回應模型計費。** 如果最終由回退模型回應，計費、能力和上下文限制都以最終回應的那個模型為準。這個模型也會體現在回應標頭裡（見 [第 4 節](#4-設定與驗證)）。
### 2.4 免費模型規則（重要）
**免費模型不能作為 fallback 選項**——免費模型只能作主模型，放進備用列表會被**靜默跳過**，繼續往下一個。所以不要把免費模型寫進 fallback 列表。
> **典型用法**：把免費模型設為主模型、付費模型放進備用列表。免費主模型觸發額度 / 頻率限流時，會自動回退到備用的付費模型——平時省成本用免費額度，限流後無縫切到付費模型保證可用。這是 fallback 最常見的用法之一。
***
## 3. 和 OpenRouter / LiteLLM 的區別
模型映射和回退並不是新概念，OpenRouter、LiteLLM 等都提供類似能力。AIHubMix 的差異在於**設定成本最低**：
| 能力 | OpenRouter | LiteLLM | AIHubMix |
| --------------------------- | :---------------: | :--------------------: | :----------: |
| 設定方式 | 程式碼裡傳 `models` 陣列 | 自建 `config.yaml` proxy | 主控台按 API Key |
| 用戶端程式碼零改動 | ❌ | ❌ | ✅ |
| 無需自部署 / 自建閘道 | ✅ | ❌ | ✅ |
| 保留原生協定（Claude / Gemini SDK） | ❌ | ❌ | ✅ |
| 按最終回應模型計費 | ✅ | — | ✅ |
| 按 API Key 粒度設定 | ❌ | ❌ | ✅ |
一句話：**不用自建閘道、不用改一行用戶端程式碼，在 Key 上設定一次就生效。**
***
## 4. 設定與驗證
### 4.1 設定
1. 在**Key**裡設定別名映射：左側別名要和用戶端實際傳送的模型名**逐字元一致**。
2. 在**同一 Key**裡設定備用模型列表（有序優先順序列表）。
3. 備用列表**只放付費 / 可用模型，不放免費模型**（會被跳過）。
4. 備用列表裡的模型必須在該 Key 的可用模型範圍內（越權模型會被跳過）。
### 4.2 驗證（優先看回應標頭，而不是翻日誌）
排查時**不要只看用戶端選了哪個模型**，最權威、可自動化的方式是讀回應標頭：
* `X-Aihubmix-Fallback: true`：本次請求發生了回退（最終模型 ≠ 主模型時附加）。
* `X-Aihubmix-Model`：本次實際回應、且據此計費的模型。
curl 驗證範例：
```bash theme={null}
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](https://docs.aihubmix.com/cn/api/claude-desktop)，本節只講映射與回退的增量設定。
### 5.1 為什麼需要映射
Claude Desktop 以 `Gateway`（Anthropic-compatible）方式接入，用戶端會按 Claude 風格約束模型名，因此模型名必須使用 `claude-` 前綴。
於是產生一個矛盾：用戶端那側只能寫 `claude-` 風格的名字，但你真正想呼叫的是 `gpt-5.5`、`gemini-3.1-pro-preview` 這些。**模型名映射正是為此而生**——用戶端寫別名 `claude-g-p-t-5.5`，AIHubMix 側映射到真實的 `gpt-5.5`。
> Claude Desktop 走的是 Claude 原生 `/v1/messages` 介面，所以本文範例裡**映射和 Fallback 都生效**。
### 5.2 AIHubMix 映射與回退設定
範例設定：
```text theme={null}
claude-g-p-t-5.5 -> gpt-5.5
claude-gemi-3.1 -> gemini-3.1-pro-preview
claude-depsek-v4 -> deepseek-v4-flash
fallback:
1. gpt-5.4
2. gemini-3.1-pro-preview
```
### 5.3 Claude Desktop 模型列表
在 Claude Desktop 的 `Model list` 裡設定的是**映射前的別名**——也就是 Claude Desktop 發給 AIHubMix 的模型名，不是真實上游模型名。
設定完成後，Claude Desktop 的模型下拉框會出現對應模型：
命名建議：
* `Model ID` 使用 `claude-` 前綴。
* 不要直接寫 `gpt`、`gemini`、`deepseek` 等真實模型系列名，可使用 `g-p-t`、`gemi`、`depsek` 等別名。
* `Model ID` 必須和 AIHubMix 映射左側**逐字元一致**，否則請求不會命中預期映射，可能繼續走錯誤回退模型。
***
## 6. 場景二：多模態能力兜底
多模態能力兜底用於處理「主模型能回答文字，但不支援當前輸入類型」的場景。比如用戶端傳送了圖片或影片，主模型只有文字輸入能力，AIHubMix 可以繼續嘗試回退列表裡支援對應模態的模型。
下面是一條實際測試鏈路。這條 Key 的映射與 fallback 設定如下（見下方截圖），重點是 fallback 列表裡既有文字模型也有支援圖片理解的模型：
```text theme={null}
claude-g-l-m-4.6 -> coding-glm-5.2-free
claude-g-p-t-5.5 -> gpt-5.5
claude-gemi-3.1 -> gemini-3.1-pro-preview
fallback:
1. gpt-5.4
2. gemini-3.1-flash-image
3. veo-3.1-lite-generate-preview
```
在 Claude Desktop 裡，選中的模型顯示為 `claude-g-l-m-4.6`——一個只支援文字輸入的模型。使用者上傳了一張 AIHubMix 模型列表頁面截圖，並詢問「這個網站是做什麼的」。因為請求裡包含圖片，文字模型無法直接處理該輸入，於是觸發了 fallback。
AIHubMix 日誌顯示，這次最終實際呼叫的是 `Google AI Studio/gemini-3.1-flash-image`，也就是 fallback 列表裡的第 2 個。第 1 個 `gpt-5.4` 同樣不支援該圖片輸入、對這次請求繼續返回可重試錯誤，於是閘道接著往下，落到了支援圖片理解的 `gemini-3.1-flash-image`。
> **觸發原因要講清**：這裡兜底是因為**上游對該圖片輸入返回了可重試錯誤、且主模型通道耗盡**——和「主模型限流後回退」是同一套回退機制，只是觸發的錯誤類型不同（前者是輸入不被支援，後者是額度 / 頻率限流）。
>
> **注意區分理解與生成**：這裡說的是**圖片 / 影片理解**兜底，不是**圖片生成或影片生成**。聊天請求不會自動變成生成介面；要測試畫圖或影片生成，應走對應的生成介面和模型。模型能力以 AIHubMix 模型頁當前標註的 `Input Modalities` 為準。
***
## 7. 場景三：免費模型兜底（省成本 + 保可用）
這是 fallback 最常見的用法之一：把**免費模型設為主模型**、**付費模型放進備用列表**。平時請求都走免費模型、省成本；一旦免費主模型觸發額度 / 頻率限流，閘道自動回退到備用的付費模型，保證服務不中斷。
範例 Key 設定：
```text theme={null}
主模型（免費）: coding-glm-5.2-free
fallback:
1. gpt-5.4
2. gemini-3.1-pro-preview
```
行為：
* 免費額度還夠用時，請求由主模型 `coding-glm-5.2-free` 回應，按免費計費。
* 免費主模型觸發限流後，自動回退到 `gpt-5.4`；若 `gpt-5.4` 也不可用，再嘗試 `gemini-3.1-pro-preview`。
* 最終由哪個模型回應，就**按那個模型計費**（見 [2.3](#2-3-計費口徑)）。
> **注意**：免費模型只能作主模型，**不能放進 fallback 列表**（放進去會被跳過，見 [2.4](#2-4-免費模型規則（重要）)）。所以「免費兜底」的正確姿勢是：免費在主、付費在備，而不是反過來。
驗證方式同樣是看回應標頭：發生回退時返回 `X-Aihubmix-Fallback: true`，`X-Aihubmix-Model` 顯示最終回應模型（見 [第 4 節](#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 節](#4-設定與驗證)。
**Q：哪些錯誤會觸發回退，哪些不會？**
A：見 [2.2 的對照表](#2-2-哪些會回退、哪些不會)。簡單說：上游可重試失敗、通道耗盡、回應未開始才會回退；指定通道、回應已開始、用戶端中斷 / 逾時、Key / 使用者級錯誤都不回退。
**Q：免費模型能放進 fallback 列表嗎？**
A：不能，會被跳過。免費模型只能作主模型。
**Q：和 OpenRouter / LiteLLM 的 model alias / fallback 有什麼區別？**
A：AIHubMix 是**Key 級、平台託管**，在主控台設定一次就生效，不用改用戶端程式碼、也不用自建閘道。詳見 [第 3 節](#3-和-openrouter-/-litellm-的區別)。
***
## 相關資源
* [在 Claude Desktop 中接入 AIHubMix](https://docs.aihubmix.com/cn/api/claude-desktop)：開發者模式、Gateway 設定、auth scheme 等完整步驟。
* [AIHubMix 模型頁](https://aihubmix.com/models)：查詢模型名稱、價格與 `Input Modalities`。
* [在 LiteLLM 中接入 AIHubMix](https://docs.aihubmix.com/cn/clients/LiteLLM)：需要自建閘道 + 模型映射 / 回退時的參考。