AI Gateway

在 AI Gateway 接入組織自己的模型供應商、管理模型目錄與備援模型群組，並查看 Gateway 流量與異常。

AI Gateway 是組織統一管理模型接入的地方：把組織自己的供應商憑證（例如 OpenAI、Amazon Bedrock）或自架的 OpenAI 相容端點接進來，建成「自建模型」，再用「備援模型群組」設定主模型失敗時依序改用的模型。接好的模型可以給 Agent、MaiGPT，或以 OpenAI 相容 API 串接的程式使用。本頁給負責模型治理的組織管理員與 IT 人員，說明後台怎麼設定；程式串接細節請看技術手冊的 AI Gateway：OpenAI 相容 API 串接。

AI Gateway 需為組織開通後才能使用（企業版功能，目前為 Beta）。尚未開通時，左側選單不會出現 AI Gateway，組織概覽 的「進階功能」區塊會以灰色顯示；如需開通請聯繫您的業務窗口（見 進階功能）。

誰可以使用

操作	需要的權限
看到左側選單的 AI Gateway，查看各分頁內容	角色權限 AI Gateway 權限（組織擁有者預設具備；其他角色的開啟方式見 讓指定角色使用 AI Gateway）
新增、編輯、測試、刪除供應商憑證、自建模型與備援模型群組	組織擁有者
切換託管模型的 組織可用 開關	組織擁有者（與 模型調用權限 頁相同）
建立呼叫 Gateway 用的 API Key	API Key 管理權限

不是組織擁有者的成員可以檢視各分頁，但新增、修改、刪除與測試都會被系統拒絕。新增 Provider、新增模型、新增備援模型群組 等按鈕會呈現停用，滑鼠移上去會顯示「僅組織擁有者可管理供應商憑證」「僅組織擁有者可管理自建模型」或「僅組織擁有者可管理備援規則」。

進入方式

從左側選單點選 AI Gateway，預設進入 總覽。底下共有五個分頁：

分頁	用途
總覽	Gateway 流量、花費、延遲與需要處理的異常
模型供應商	管理組織自己的供應商憑證
模型	模型目錄：託管模型與自建模型
備援模型群組	主模型失敗時依序改用的備援鏈
串接範例	以 OpenAI 相容 API 呼叫的程式碼範例

組織還沒有任何供應商時，總覽 會顯示「歡迎使用 AI Gateway」三步驟：新增供應商 → 到 模型目錄 啟用要用的模型 → 新增 API Key。完成第一步後，總覽就會變成即時的健康儀表板。

總覽

總覽統計的是組織 Gateway 流量，包含 OpenAI 相容 API 的呼叫，以及使用自建模型的 Agent 對話。右上角可選 近 1 小時、近 24 小時、近 7 天、近 30 天，或用日期選擇器指定開始與結束時間（自訂區間最長 92 天）。

區塊	內容
判決列	顯示「一切正常・無待處理項目」或「N 件需注意／需處理」；右側有 存取診斷，有待辦時可一鍵捲到「需要注意」卡
指標卡	請求、花費（credits）、Token、錯誤率、最慢延遲、備援觸發，並與前一段等長區間比較
供應商	每個供應商一顆狀態標籤：正常、限流偏高（近 24 小時上游錯誤率超過 5%）或 待設定（憑證停用）。點選後可看到近 24 小時上游錯誤率與處理建議，並 測試連線 或 管理憑證；限流偏高 時另有 建立備援規則
用量趨勢、延遲	請求數或成本的趨勢圖；首字延遲（TTFT）、總延遲、上游延遲 各列 一般（p50）與 最慢（p95）
用量拆解	依 供應商 或 模型 列出請求數、備援次數與花費（供應商另列錯誤率）；展開模型可看到呼叫它的 API Key
需要注意	供應商近 24 小時上游錯誤率超過 5%；API Key 綁定成員的額度使用率達 90%，或金鑰已停用但近 24 小時仍有請求；備援規則本月觸發次數達上月同期 2 倍以上

存取診斷 用來排查「有人打不到模型」：選一把 API 金鑰（可再選一個模型）後按 診斷，系統會逐一檢查金鑰未撤銷、已啟用、未過期，成員與使用者啟用中，組織已啟用 Gateway、組織可用此模型、金鑰已開通此模型，並標出第一個未通過的關卡。

新增供應商

在 模型供應商 點選 新增 Provider，跟著四步精靈操作。同一種供應商可以新增多筆（例如不同區域的 Bedrock）。

1

選供應商

選擇供應商類型。卡片上標 支援自動偵測 的供應商，建立後可自動列出可用模型；標 需手動新增模型 的，之後要到模型目錄逐一新增。

2

連線憑證

填入 顯示名稱（例如「Bedrock 美東」）與該供應商的憑證欄位，按 建立並偵測。憑證在這一步就已儲存，之後關掉精靈也不會遺失。

供應商	必填欄位	選填欄位	自動偵測模型
OpenAI	API Key	—	支援
Anthropic	API Key	API Base（選填，留空則使用官方端點）	支援
Amazon Bedrock	AWS Access Key ID、AWS Secret Access Key、AWS Region	—	需手動新增
Google Vertex AI	Service Account JSON（貼入整段服務帳戶 JSON）	—	需手動新增
vLLM	API Base（自架 vLLM 服務的網址，例如 https://vllm.example.com/v1）	API Key（選填）	支援
OpenAI Compatible	API Base（自架或第三方 OpenAI 相容端點的網址）	API Key（選填）	支援

3

偵測模型

系統向供應商查詢可用模型並預設全選，目錄已有的模型標示 已存在 且不可勾選。確認後按「匯入 N 個」，每個勾選的模型會建成一個自建模型；匯入中可按 停止。不需要時可按 跳過，改手動新增。

4

完成

畫面顯示 供應商已接入 與匯入結果。匯入的模型上下文與能力是預設值，可到 模型目錄 逐一調整。

供應商清單每列顯示狀態、遮罩後的憑證，以及「N 個模型」連結（點選會跳到模型目錄並篩出該供應商的模型），右側可 測試、編輯、刪除。編輯時不能更改供應商類型；密鑰欄位留空代表沿用原本的值。

管理模型

模型 分頁把兩種模型列在同一份目錄：

• 託管模型：MaiAgent 提供的模型，來源標示為「MaiAgent 託管」。

• 自建模型：用組織自己的供應商憑證建立的模型，來源標示為 自建，定價 欄顯示「總 token 數 × N%」的流量費率。

目錄欄位包含 名稱、組織可用、被備援引用、來源、提供者、Model ID、定價、上下文；上方可依能力（對話、視覺、工具呼叫、推理）、供應商或關鍵字篩選。點選任一列會開啟 模型詳情 抽屜，說明如下。

模型詳情抽屜

區塊	內容
標題列	模型名稱與 平台託管／自建 標籤；下方的 Gateway 模型 ID 旁有複製圖示。託管模型尚未在 Gateway 啟用時另有 未啟用 標籤，並提示「此模型目前未在 Gateway 啟用，打開「組織可用」後才會出現在託管清單」
上下文、最大輸出 token	模型規格
能力	視覺、工具呼叫、串流、推理等標籤
所屬供應商	託管模型顯示「平台託管 · 供應商名」。自建模型顯示憑證名稱、憑證狀態（啟用中／已停用）與 最近驗證 時間（未測試過顯示「尚未驗證」），右側 供應商 連結會跳到供應商頁並標示該筆憑證
出現在哪些備援鏈	列出引用這個模型的備援模型群組，標示是 主模型 或 第 N 順位；平台層 標籤代表由 MaiAgent 維護的群組。點任一條會跳到備援頁並直接開啟該群組編輯。未被引用時顯示「未被任何備援鏈引用」；非組織擁有者看到「需組織擁有者權限才能查看備援引用」
組織可用	與目錄同一個開關，可直接在抽屜內切換，規則見下一節

組織可用開關

託管模型的 組織可用 開關，與 模型調用權限 頁是同一份設定：在這裡關閉，Agent 的模型選單也會同步移除該模型。關閉前會跳出「停用此模型？」確認，並列出會影響幾個 Agent、幾條備援鏈。顯示鎖頭的模型代表尚未由 MaiAgent 為組織開通，或平台已停用此模型的 Gateway 存取，組織無法自行開啟。自建模型一律顯示 自建・自動可用，不受這個開關控制。

新增自建模型

1. 點選 新增模型，在 選 Provider 步驟選一個供應商憑證（還沒有供應商時，可直接按 新增供應商）。

2. 在 模型設定 填寫：

   • 名稱：顯示在目錄與模型選單的名稱。

   • 系列：Anthropic、GPT、Gemini、Grok、Qwen、DeepSeek、Mistral 或 Other。

   • 模型 ID：供應商端預期的模型 ID（例如 gpt-4.1）。同一個供應商憑證下不能重複。

   • 上下文、最大輸出 token：預設 128,000 與 8,000，請依模型規格調整。

   • 能力：視覺、工具呼叫、串流、推理。

3. 按 建立。完成頁會顯示系統自動產生的 Gateway 模型 ID，可按 測試連線 確認可以呼叫。

Gateway 模型 ID 由供應商的 Slug 與模型名稱產生，建立後不會因改名而變動；程式呼叫時就填這個 ID。自建模型列右側可 測試、編輯、刪除。建立或更換模型 ID、供應商後，系統會在背景偵測模型是否拒絕 temperature、top_p、top_k 等參數，結果顯示在編輯視窗的 請求參數支援，也可按 重新偵測。並非所有供應商都能偵測，無法偵測時會提示「無法偵測此模型（需可用的憑證與支援的供應商）」。

備援模型群組

備援模型群組讓主模型失敗時，Gateway 依序改用備援鏈中的下一個模型，可以跨模型、跨供應商。

1. 在 備援模型群組 點選 新增備援模型群組。

2. 輸入 群組名稱（例如「Claude 高可用」）。

3. 在 備援鏈 第一列選擇主模型，按 新增下一順位 加入備援模型；託管模型與自建模型都可以選，至少要選一個。可拖曳或用 上移、下移 調整順序。

4. 按 儲存。系統會自動產生群組 Slug，程式呼叫時把 Slug 填在 model 欄位即可使用整條備援鏈。

觸發條件 為系統固定、不可自訂：逾時、連線錯誤、429 限流、5xx 錯誤。每張群組卡會顯示本月與上月同期的觸發次數；本月達上月同期 2 倍以上時會以紅字提醒。標示 平台層・唯讀 的群組是平台共用規則，組織端只能 檢視。

串接範例

串接範例 分頁說明以 OpenAI 相容介面呼叫 Gateway 的三個步驟（取得 Gateway 金鑰、指定模型名稱、自動轉送與備援），並提供 cURL、Python、Node.js 範例。從 選擇模型或備援群組 選取後，範例中的 model 會換成對應的 Gateway 模型 ID 或備援群組 Slug，可按 複製 直接使用。

呼叫用的 API Key 由具 API Key 管理權限 的管理員在 組織設定 → API Key 管理 建立；每把金鑰綁定一位成員，可在組織可用的模型範圍內再縮小 開通模型，並設定 每分鐘請求數（RPM） 與 每分鐘 Token 數（TPM）。驗證方式、錯誤碼等細節請看 AI Gateway：OpenAI 相容 API 串接 與 AI Gateway 安全性。

讓 Agent 與 MaiGPT 使用

• Agent：自建模型建立後，會自動出現在 Agent 設定 的 LLM 模型 選單，並標示 自建。具 AI Gateway 權限 的成員編輯 Agent 時，選單另有 備援模型群組 一組，可直接選用組織的備援群組；選用備援群組時不會顯示思考設定。

• MaiGPT：MaiGPT 只列出具 工具呼叫 能力的模型，因此自建模型要勾選 工具呼叫 才會出現。若成員的角色限制了 MaiGPT 可用模型，還需在 MaiGPT 角色使用權限 勾選該模型。

刪除自建模型或備援模型群組前，請先到使用它們的 Agent 改選其他模型，再刪除，避免線上服務中斷。

計費

使用自建模型（自帶憑證或自架端點）時，MaiAgent 不再按平台的模型費率收費，而是依總 token 數收取流量費；託管模型仍依原本的費率計費。費率與消耗紀錄的查看方式請見 AI Gateway 自建模型的流量費。

常見問題

Q：左側選單沒有 AI Gateway？

請確認兩件事：組織是否已開通 AI Gateway（可在 組織概覽 的「進階功能」查看），以及您所屬的角色是否勾選 AI Gateway 權限。

Q：OpenAI Compatible 供應商按「測試」，提示沒有預設測試模型？

供應商列的 測試 會用該供應商的預設測試模型送出一則測試請求，OpenAI 相容端點沒有預設模型可用。請先在模型目錄建立自建模型，再用該模型列的 測試 確認連線。

Q：刪除供應商失敗？

供應商憑證仍被自建模型使用時，系統會拒絕刪除。請先從供應商列的「N 個模型」連結找到這些自建模型並刪除，再刪除供應商。

Q：Agent 的模型選單沒有備援模型群組？

編輯 Agent 的成員需具備 AI Gateway 權限，選單才會列出組織的備援模型群組；平台層的唯讀群組不會出現在 Agent 選單中。