模型路由：自訂對應、通配符優先級與預設策略

你在客戶端裡寫的 model，不一定等於 Antigravity Tools 最終請求上游時用的「物理模型」。模型路由做的事很簡單：把「對外穩定的模型名」對應成「對內真正要用的模型」，並把結果放進回應標頭 X-Mapped-Model 裡，方便你確認是否走到了預期路徑。

學完你能做什麼

在 UI 裡設定 proxy.custom_mapping（精確對應 + 通配符對應）
說清楚一條規則到底是怎么被命中的（精確 > 通配符 > 預設對應）
一鍵套用預設規則，快速相容 OpenAI/Claude 客戶端
用 curl -i 驗證 X-Mapped-Model，定位「為什麼沒按我想的路由」

你現在的困境

你希望客戶端一直寫 gpt-4o，但上游想穩定落到某個 Gemini 模型
你有一堆版本化模型名（例如 gpt-4-xxxx），不想每次都手動加對應
你看到請求成功了，但不確定到底跑的是哪個物理模型

什麼時候用這一招

你要給團隊提供一個「固定對外模型集合」，遮蔽上游模型變動
你想把多種 OpenAI/Claude 模型名統一路由到少數幾個高性價比模型
你在排障 401/429/0 token 時，需要確認對應後的實際模型

🎒 開始前的準備

你已經能啟動本地反代，並能從外部請求跑通（建議先完成啟動本地反代並接入第一個客戶端（/healthz + SDK 設定））
你知道怎麼用 curl -i 看回應標頭（上一課裡用過 X-Mapped-Model）

這課裡兩個關鍵詞

custom_mapping：你的「自訂規則表」，鍵是客戶端傳入的模型名（或通配符 pattern），值是最終要用的模型名（來源：src/types/config.ts）。
通配符 *：用於批次匹配模型名（例如 gpt-4*），匹配實作是區分大小寫的（來源：src-tauri/src/proxy/common/model_mapping.rs）。

核心思路

後端在處理請求時，會先算出一個 mapped_model：

先看 custom_mapping 有沒有精確命中（key 完全等於 model）
再嘗試通配符命中：選「非 * 字元更多」的規則（更具體的規則優先）
都沒命中，再走系統預設對應（例如一些 OpenAI/Claude 模型別名到內部模型的對應）

這個 mapped_model 會被寫入回應標頭 X-Mapped-Model（至少 OpenAI handler 會這樣做），你用它就能確認「我寫的 model 最後變成了什麼」。

熱更新語意（不用重啟）

當反代服務正在執行時，前端呼叫 update_model_mapping 會讓後端立刻把 custom_mapping 寫入記憶體的 RwLock，同時也會儲存到持久化設定裡（來源：src-tauri/src/commands/proxy.rs；src-tauri/src/proxy/server.rs）。

跟我做

第 1 步：在 API Proxy 頁找到「模型路由」卡片

為什麼 模型路由的設定入口就在 UI 裡；你不需要手動編輯設定檔。

打開 Antigravity Tools -> API Proxy 頁面，往下滾動。

你應該看到：一個標題類似「模型路由中心」的卡片，右上角有兩個按鈕：「套用預設對應」和「重置對應」（來源：src/pages/ApiProxy.tsx）。

第 2 步：加一條「精確對應」（最可控）

為什麼 精確對應優先級最高，適合「我就要這一個模型名落到這一個物理模型」。

在「新增對應」區域：

Original 填你要對外暴露的模型名，比如 gpt-4o
Target 從下拉裡選一個目標模型，比如 gemini-3-flash

點擊 Add。

你應該看到：對應列表裡出現 gpt-4o -> gemini-3-flash，並彈出儲存成功提示。

第 3 步：加一條「通配符對應」（批次覆蓋）

為什麼 當你有一堆版本化模型名時（例如 gpt-4-turbo、gpt-4-1106-preview），用通配符能省掉很多重複設定。

再新增一條對應：

Original：gpt-4*
Target：gemini-3-pro-high

你應該看到：列表裡出現 gpt-4* -> gemini-3-pro-high。

規則優先級的「坑位」

當 gpt-4o 同時滿足精確規則 gpt-4o 和通配符規則 gpt-4* 時，後端會先走精確命中（來源：src-tauri/src/proxy/common/model_mapping.rs）。

第 4 步：一鍵套用預設規則（快速相容）

為什麼 如果你主要目的是「快速相容常見 OpenAI/Claude 模型名」，預設能幫你直接填好一批通配符規則。

點擊「套用預設對應」。

你應該看到：列表裡新增多條規則，包含類似下面這些（來源：src/pages/ApiProxy.tsx）：

json

{
  "gpt-4*": "gemini-3-pro-high",
  "gpt-4o*": "gemini-3-flash",
  "gpt-3.5*": "gemini-2.5-flash",
  "o1-*": "gemini-3-pro-high",
  "o3-*": "gemini-3-pro-high",
  "claude-3-5-sonnet-*": "claude-sonnet-4-5",
  "claude-3-opus-*": "claude-opus-4-5-thinking",
  "claude-opus-4-*": "claude-opus-4-5-thinking",
  "claude-haiku-*": "gemini-2.5-flash",
  "claude-3-haiku-*": "gemini-2.5-flash"
}

第 5 步：用 `X-Mapped-Model` 驗證路由是否生效

為什麼 你想確認「設定寫進去了」，更想確認「請求真的按這條規則走了」。最省事的辦法就是看 X-Mapped-Model。

macOS/LinuxWindows

bash

curl -i http://127.0.0.1:8045/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "hi"}]
  }'

powershell

$resp = Invoke-WebRequest "http://127.0.0.1:8045/v1/chat/completions" -Method Post -ContentType "application/json" -Body '{
  "model": "gpt-4o",
  "messages": [{"role": "user", "content": "hi"}]
}'
$resp.Headers["X-Mapped-Model"]

你應該看到：回應標頭裡有 X-Mapped-Model: ...。如果你在第 2 步把 gpt-4o 精確對應到了 gemini-3-flash，這裡就應該能看到對應值（回應標頭寫入見 src-tauri/src/proxy/handlers/openai.rs）。

第 6 步：需要回到「純預設對應」時，重置 custom_mapping

為什麼 你在排障時，往往希望先排除「自訂規則的影響」。把 custom_mapping 清空，是最直接的回退手段。

點擊「重置對應」。

你應該看到：對應列表清空；之後再請求時，如果沒有命中自訂規則，就會走系統預設對應（來源：src/pages/ApiProxy.tsx；src-tauri/src/proxy/common/model_mapping.rs）。

檢查點 ✅

[ ] 你能在 UI 裡新增/刪除 custom_mapping 規則
[ ] 你能解釋清楚：精確規則為什麼會壓過通配符規則
[ ] 你能用 curl -i 或 PowerShell 讀到 X-Mapped-Model

踩坑提醒

場景	你可能會怎么做（❌）	推薦做法（✓）
通配符沒生效	寫了 `GPT-4*` 期待匹配 `gpt-4-turbo`	用小寫 `gpt-4*`；後端通配符匹配是區分大小寫的
兩條通配符都能命中	同時寫 `gpt-` 和 `gpt-4`，不確定會走哪條	讓更具體的規則更「長」，確保它的非 `*` 字元更多
規則看起來對，但還是沒變	只看回應 body，不看回應標頭	用 `curl -i` 確認 `X-Mapped-Model`（這是後端顯式回傳的結果）
兩條規則「同樣具體」	寫了兩條通配符，非 `*` 字元數量一樣	避免這種設定；原始碼註解說明這種情況下結果依賴 `HashMap` 遍歷順序，可能不穩定（來源：`src-tauri/src/proxy/common/model_mapping.rs`）

本課小結

proxy.custom_mapping 是你控制「對外模型名 → 物理模型」的主入口
後端路由優先級是：精確命中 > 通配符命中（更具體優先）> 系統預設對應
X-Mapped-Model 是最可靠的驗證手段，排障時優先看它

下一課預告

下一課會繼續看 配額治理：Quota Protection + Smart Warmup 的組合打法（對應章節：advanced-quota）。

附錄：原始碼參考

點擊展開查看原始碼位置

更新時間：2026-01-23

功能	檔案路徑	行號
設定欄位：`proxy.custom_mapping`（前端類型）	`src/types/config.ts`	6-20
UI：寫入/重置/預設（呼叫 `update_model_mapping`）	`src/pages/ApiProxy.tsx`	371-475
UI：模型路由卡片（套用預設對應 / 重置對應 / 列表與新增表單）	`src/pages/ApiProxy.tsx`	1762-1931
後端命令：熱更新並持久化 `custom_mapping`	`src-tauri/src/commands/proxy.rs`	344-365
伺服器端狀態：`custom_mapping` 用 `RwLock<HashMap<..>>` 儲存	`src-tauri/src/proxy/server.rs`	16-53
路由演算法：精確 > 通配符（更具體優先）> 預設對應	`src-tauri/src/proxy/common/model_mapping.rs`	180-228
通配符匹配：支援多 `*`，且區分大小寫	`src-tauri/src/proxy/common/model_mapping.rs`	134-178
請求中計算 `mapped_model`（範例：OpenAI handler）	`src-tauri/src/proxy/handlers/openai.rs`	154-159
---	---	---

關鍵函式：

resolve_model_route(original_model, custom_mapping)：模型路由主入口（見 src-tauri/src/proxy/common/model_mapping.rs）

從零跑起來

遇到報錯怎麼辦

升級避坑指南

接入你的 AI 平台

將系統升級到生產級

技術字典

模型路由：自訂對應、通配符優先級與預設策略

學完你能做什麼

你現在的困境

什麼時候用這一招

🎒 開始前的準備

核心思路

跟我做

第 1 步：在 API Proxy 頁找到「模型路由」卡片

第 2 步：加一條「精確對應」（最可控）

第 3 步：加一條「通配符對應」（批次覆蓋）

第 4 步：一鍵套用預設規則（快速相容）

第 5 步：用 `X-Mapped-Model` 驗證路由是否生效

第 6 步：需要回到「純預設對應」時，重置 custom_mapping

檢查點 ✅

踩坑提醒

本課小結

下一課預告

附錄：原始碼參考

模型路由：自訂對應、通配符優先級與預設策略 ​

學完你能做什麼 ​

你現在的困境 ​

什麼時候用這一招 ​

🎒 開始前的準備 ​

核心思路 ​

跟我做 ​

第 1 步：在 API Proxy 頁找到「模型路由」卡片 ​

第 2 步：加一條「精確對應」（最可控） ​

第 3 步：加一條「通配符對應」（批次覆蓋） ​

第 4 步：一鍵套用預設規則（快速相容） ​

第 5 步：用 X-Mapped-Model 驗證路由是否生效 ​

第 6 步：需要回到「純預設對應」時，重置 custom_mapping ​

檢查點 ✅ ​

踩坑提醒 ​

本課小結 ​

下一課預告 ​

附錄：原始碼參考 ​

模型路由：自訂對應、通配符優先級與預設策略

學完你能做什麼

你現在的困境

什麼時候用這一招

🎒 開始前的準備

核心思路

跟我做

第 1 步：在 API Proxy 頁找到「模型路由」卡片

第 2 步：加一條「精確對應」（最可控）

第 3 步：加一條「通配符對應」（批次覆蓋）

第 4 步：一鍵套用預設規則（快速相容）

第 5 步：用 `X-Mapped-Model` 驗證路由是否生效

第 6 步：需要回到「純預設對應」時，重置 custom_mapping

檢查點 ✅

踩坑提醒

本課小結

下一課預告

附錄：原始碼參考