> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/build/ai-gateway.md).

# AI Gateway

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

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

{% hint style="info" %}
AI Gateway 需為組織開通後才能使用（企業版功能，目前為 Beta）。尚未開通時，左側選單不會出現 AI Gateway，<mark style="color:blue;">組織概覽</mark> 的「進階功能」區塊會以灰色顯示；如需開通請聯繫您的業務窗口（見 [進階功能](/org/overview/organization-overview.md#advanced-features)）。
{% endhint %}

## 誰可以使用 <a href="#permissions" id="permissions"></a>

| 操作                                               | 需要的權限                                                                                                                                                    |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 看到左側選單的 AI Gateway，查看各分頁內容                       | 角色權限 <mark style="color:blue;">AI Gateway 權限</mark>（組織擁有者預設具備；其他角色的開啟方式見 [讓指定角色使用 AI Gateway](/org/roles/role-permission.md#enable-ai-gateway-for-role)） |
| 新增、編輯、測試、刪除供應商憑證、自建模型與備援模型群組                     | 組織擁有者                                                                                                                                                    |
| 切換託管模型的 <mark style="color:blue;">組織可用</mark> 開關 | 組織擁有者（與 [模型調用權限](/org/model-access.md) 頁相同）                                                                                                              |
| 建立呼叫 Gateway 用的 API Key                          | <mark style="color:blue;">API Key 管理權限</mark>                                                                                                            |

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

## 進入方式 <a href="#how-to-enter" id="how-to-enter"></a>

從左側選單點選 <mark style="color:blue;">AI Gateway</mark>，預設進入 <mark style="color:blue;">總覽</mark>。底下共有五個分頁：

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

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

## 總覽 <a href="#overview" id="overview"></a>

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

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

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

## 新增供應商 <a href="#add-provider" id="add-provider"></a>

在 <mark style="color:blue;">模型供應商</mark> 點選 <mark style="color:blue;">新增 Provider</mark>，跟著四步精靈操作。同一種供應商可以新增多筆（例如不同區域的 Bedrock）。

{% stepper %}
{% step %}

### 選供應商 <a href="#pick-provider" id="pick-provider"></a>

選擇供應商類型。卡片上標 <mark style="color:blue;">支援自動偵測</mark> 的供應商，建立後可自動列出可用模型；標 <mark style="color:blue;">需手動新增模型</mark> 的，之後要到模型目錄逐一新增。
{% endstep %}

{% step %}

### 連線憑證 <a href="#provider-credentials" id="provider-credentials"></a>

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

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

{% step %}

### 偵測模型 <a href="#discover-models" id="discover-models"></a>

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

{% step %}

### 完成 <a href="#provider-done" id="provider-done"></a>

畫面顯示 <mark style="color:blue;">供應商已接入</mark> 與匯入結果。匯入的模型上下文與能力是預設值，可到 <mark style="color:blue;">模型目錄</mark> 逐一調整。
{% endstep %}
{% endstepper %}

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

## 管理模型 <a href="#manage-models" id="manage-models"></a>

<mark style="color:blue;">模型</mark> 分頁把兩種模型列在同一份目錄：

* **託管模型**：MaiAgent 提供的模型，來源標示為「MaiAgent 託管」。
* **自建模型**：用組織自己的供應商憑證建立的模型，來源標示為 <mark style="color:blue;">自建</mark>，<mark style="color:blue;">定價</mark> 欄顯示「總 token 數 × N%」的流量費率。

目錄欄位包含 <mark style="color:blue;">名稱</mark>、<mark style="color:blue;">組織可用</mark>、<mark style="color:blue;">被備援引用</mark>、<mark style="color:blue;">來源</mark>、<mark style="color:blue;">提供者</mark>、<mark style="color:blue;">Model ID</mark>、<mark style="color:blue;">定價</mark>、<mark style="color:blue;">上下文</mark>；上方可依能力（<mark style="color:blue;">對話</mark>、<mark style="color:blue;">視覺</mark>、<mark style="color:blue;">工具呼叫</mark>、<mark style="color:blue;">推理</mark>）、供應商或關鍵字篩選。點選任一列會開啟 <mark style="color:blue;">模型詳情</mark>，可複製 Gateway 模型 ID，並查看所屬供應商與 <mark style="color:blue;">出現在哪些備援鏈</mark>。

### 組織可用開關 <a href="#org-access-switch" id="org-access-switch"></a>

託管模型的 <mark style="color:blue;">組織可用</mark> 開關，與 [模型調用權限](/org/model-access.md) 頁是同一份設定：在這裡關閉，AI 助理的模型選單也會同步移除該模型。關閉前會跳出「停用此模型？」確認，並列出會影響幾個助理、幾條備援鏈。顯示鎖頭的模型代表尚未由 MaiAgent 為組織開通，或平台已停用此模型的 Gateway 存取，組織無法自行開啟。自建模型一律顯示 <mark style="color:blue;">自建・自動可用</mark>，不受這個開關控制。

### 新增自建模型 <a href="#add-custom-model" id="add-custom-model"></a>

1. 點選 <mark style="color:blue;">新增模型</mark>，在 <mark style="color:blue;">選 Provider</mark> 步驟選一個供應商憑證（還沒有供應商時，可直接按 <mark style="color:blue;">新增供應商</mark>）。
2. 在 <mark style="color:blue;">模型設定</mark> 填寫：
   * <mark style="color:blue;">名稱</mark>：顯示在目錄與模型選單的名稱。
   * <mark style="color:blue;">系列</mark>：Anthropic、GPT、Gemini、Grok、Qwen、DeepSeek、Mistral 或 Other。
   * <mark style="color:blue;">模型 ID</mark>：供應商端預期的模型 ID（例如 `gpt-4.1`）。同一個供應商憑證下不能重複。
   * <mark style="color:blue;">上下文</mark>、<mark style="color:blue;">最大輸出 token</mark>：預設 128,000 與 8,000，請依模型規格調整。
   * <mark style="color:blue;">能力</mark>：<mark style="color:blue;">視覺</mark>、<mark style="color:blue;">工具呼叫</mark>、<mark style="color:blue;">串流</mark>、<mark style="color:blue;">推理</mark>。
3. 按 <mark style="color:blue;">建立</mark>。完成頁會顯示系統自動產生的 Gateway 模型 ID，可按 <mark style="color:blue;">測試連線</mark> 確認可以呼叫。

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

## 備援模型群組 <a href="#fallback-groups" id="fallback-groups"></a>

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

1. 在 <mark style="color:blue;">備援模型群組</mark> 點選 <mark style="color:blue;">新增備援模型群組</mark>。
2. 輸入 <mark style="color:blue;">群組名稱</mark>（例如「Claude 高可用」）。
3. 在 <mark style="color:blue;">備援鏈</mark> 第一列選擇主模型，按 <mark style="color:blue;">新增下一順位</mark> 加入備援模型；託管模型與自建模型都可以選，至少要選一個。可拖曳或用 <mark style="color:blue;">上移</mark>、<mark style="color:blue;">下移</mark> 調整順序。
4. 按 <mark style="color:blue;">儲存</mark>。系統會自動產生群組 Slug，程式呼叫時把 Slug 填在 model 欄位即可使用整條備援鏈。

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

## 串接範例 <a href="#integration-examples" id="integration-examples"></a>

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

呼叫用的 API Key 由具 <mark style="color:blue;">API Key 管理權限</mark> 的管理員在 <mark style="color:blue;">組織設定</mark> → <mark style="color:blue;">API Key 管理</mark> 建立；每把金鑰綁定一位成員，可在組織可用的模型範圍內再縮小 <mark style="color:blue;">開通模型</mark>，並設定 <mark style="color:blue;">每分鐘請求數（RPM）</mark> 與 <mark style="color:blue;">每分鐘 Token 數（TPM）</mark>。驗證方式、錯誤碼等細節請看 [AI Gateway：OpenAI 相容 API 串接](https://docs.maiagent.ai/tech/ai-gateway/ai-gateway-openai-compatible) 與 [AI Gateway 安全性](https://docs.maiagent.ai/tech/ai-gateway/ai-gateway-security)。

## 讓 AI 助理與 MaiGPT 使用 <a href="#use-in-agents-and-maigpt" id="use-in-agents-and-maigpt"></a>

* **AI 助理**：自建模型建立後，會自動出現在 [AI 助理設定](/build/agent-builder/agent/setup.md) 的 <mark style="color:blue;">LLM 模型</mark> 選單，並標示 <mark style="color:blue;">自建</mark>。具 <mark style="color:blue;">AI Gateway 權限</mark> 的成員編輯 AI 助理時，選單另有 <mark style="color:blue;">備援模型群組</mark> 一組，可直接選用組織的備援群組；選用備援群組時不會顯示思考設定。
* **MaiGPT**：MaiGPT 只列出具 <mark style="color:blue;">工具呼叫</mark> 能力的模型，因此自建模型要勾選 <mark style="color:blue;">工具呼叫</mark> 才會出現。若成員的角色限制了 MaiGPT 可用模型，還需在 [MaiGPT 角色使用權限](/org/roles/maigpt-role-permissions.md) 勾選該模型。

{% hint style="warning" %}
刪除自建模型或備援模型群組前，請先到使用它們的 AI 助理改選其他模型，再刪除，避免線上服務中斷。
{% endhint %}

## 計費 <a href="#billing" id="billing"></a>

使用自建模型（自帶憑證或自架端點）時，MaiAgent 不再按平台的模型費率收費，而是依總 token 數收取流量費；託管模型仍依原本的費率計費。費率與消耗紀錄的查看方式請見 [AI Gateway 自建模型的流量費](/others/credits.md#ai-gateway-traffic-fee)。

## 常見問題 <a href="#faq" id="faq"></a>

#### Q：左側選單沒有 AI Gateway？ <a href="#faq-menu-missing" id="faq-menu-missing"></a>

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

#### Q：OpenAI Compatible 供應商按「測試」，提示沒有預設測試模型？ <a href="#faq-compatible-test" id="faq-compatible-test"></a>

供應商列的 <mark style="color:blue;">測試</mark> 會用該供應商的預設測試模型送出一則測試請求，OpenAI 相容端點沒有預設模型可用。請先在模型目錄建立自建模型，再用該模型列的 <mark style="color:blue;">測試</mark> 確認連線。

#### Q：刪除供應商失敗？ <a href="#faq-delete-provider" id="faq-delete-provider"></a>

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

#### Q：AI 助理的模型選單沒有備援模型群組？ <a href="#faq-fallback-not-in-agent" id="faq-fallback-not-in-agent"></a>

編輯 AI 助理的成員需具備 <mark style="color:blue;">AI Gateway 權限</mark>，選單才會列出組織的備援模型群組；平台層的唯讀群組不會出現在 AI 助理選單中。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/build/ai-gateway.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.