> ## Documentation Index
> Fetch the complete documentation index at: https://gproxy.leenhawk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 基本概念

> 請求在 GPROXY 中經過的各個環節、需要設定的項目，以及模型名稱和請求位址如何決定上游。

本章說明一個請求在 GPROXY 中會經過哪些環節，並介紹設定時會遇到的各種物件。後續的管理指南會直接使用這些術語，建議先讀完本章。

## 請求的處理過程

用戶端只需要知道閘道位址、閘道 API Key 和模型名稱。GPROXY 本身不執行模型，推論由上游服務完成；GPROXY 負責決定請求要送往哪個上游、使用哪一份帳戶憑證，以及用什麼格式傳送。

1. 用戶端發出請求。可以使用 OpenAI Chat Completions、OpenAI Responses、Claude Messages 或 Gemini GenerateContent 協定，串流和非串流皆可。嵌入、重排序、圖像、音訊、影片、檔案和 Realtime 另有對應的端點，清單見[路由與端點](https://gproxy.leenhawk.com/zh-tw/reference/routing-table.md)。
2. GPROXY 驗證金鑰。金鑰從 `Authorization: Bearer`、`x-api-key` 或 `x-goog-api-key` 請求標頭讀取，可以是閘道 API Key，也可以是 GPROXY 簽發的 OAuth 存取權杖。驗證通過後，就能確定呼叫方是哪位使用者，以及金鑰綁定的組織或團隊。
3. 准入檢查。權限規則決定呼叫方在目前的模型和操作上可以使用哪些供應商；憑證歸屬和金鑰綁定決定可以使用哪些憑證；接著確定適用的費用預算。限流放在最後計數，因為其他檢查沒有通過的請求，不應該占用任何人的額度。各項檢查的細節見[權限、限流與費用預算](https://gproxy.leenhawk.com/zh-tw/guides/permissions.md)。
4. 解析模型名稱。路由名稱會展開為路由成員，`供應商/模型` 形式的名稱則指向單一供應商。候選目標先依第 3 步允許的供應商和憑證篩選，再依層級、健康狀態和權重排序。詳見[模型與路由](https://gproxy.leenhawk.com/zh-tw/guides/models.md)。
5. 選擇供應商和憑證。在動用任何憑證之前，會先檢查一次費用預算，然後從排在最前面的候選中選出憑證發出嘗試。如果失敗原因允許重試，就改用下一份可用憑證或下一個路由成員。
6. 轉換並傳送。用戶端協定與上游協定不同時，請求會直接轉換為上游格式；重寫規則作用於轉換後的請求，再由渠道附上憑證的認證資訊送出。回應則以相反順序處理：先套用重寫規則，再轉換回用戶端使用的協定。
7. 結算用量與費用。每次實際的上游呼叫都會產生一筆用量記錄，包含 token 數等計量資料。費用依設定的價格規則計算，在呼叫結束後計入適用的預算。詳見[用量、日誌與稽核](https://gproxy.leenhawk.com/zh-tw/guides/observability.md)。

協定轉換只改變請求格式，不會改變上游的能力。上游不支援的操作，不論用戶端從哪個端點呼叫都會失敗。

## 術語

### 渠道（Channel）

渠道是某一類上游服務的轉接層，規定登入認證方式、上游接受的請求格式和支援的操作，例如 `openai`、`codex`、`custom`。`custom` 用於需要自行填寫服務位址和協定清單的 OpenAI 相容服務。所有渠道見[渠道目錄](https://gproxy.leenhawk.com/zh-tw/reference/channel-catalog.md)。

### 供應商

供應商是一條已儲存的上游連線，包括名稱、渠道、服務位址、渠道設定和一組憑證。多個供應商可以使用同一種渠道，例如兩個位址不同的 OpenAI 相容服務。供應商名稱也會出現在請求位址和模型名稱中，見下文。

### 憑證（Credential）

憑證是供應商登入上游所用的 API Key、OAuth 權杖或 Cookie。一個供應商可以儲存多份憑證，GPROXY 每次請求時從中挑選，遇到被限流或故障的憑證時會改用其他憑證。憑證可以歸屬於使用者、組織或團隊，藉此限定誰能使用。

設定主金鑰後，憑證等機密資訊會加密儲存。CLI 未設定主金鑰時會以明文儲存，並印出提示。詳見[設定](https://gproxy.leenhawk.com/zh-tw/reference/configuration.md)。

### 模型路由（Route）

模型路由是用戶端使用的模型名稱，對應一個或多個成員。每個成員由一個供應商和一個上游模型 ID 組成，並帶有權重和備援層級。修改、新增成員或調整成員順序時，用戶端繼續使用原本的模型名稱即可。

### 閘道 API Key

閘道 API Key 由 GPROXY 簽發給使用者，用戶端用它來呼叫模型。請求會受到所屬使用者和金鑰本身的權限、限流與預算限制。閘道 API Key 和儲存在供應商中的上游 API Key 是兩回事，後者不會交給用戶端。詳見[使用者與 API Key](https://gproxy.leenhawk.com/zh-tw/guides/users-and-keys.md)。

### 重寫規則

重寫規則會在請求或回應經過供應商時加以修改：附加系統提示詞、插入快取斷點、設定或刪除 JSON 欄位、取代文字、設定請求標頭。規則以規則集組織，規則集綁定到供應商。詳見[重寫規則](https://gproxy.leenhawk.com/zh-tw/guides/rules.md)。

### 使用者、組織與團隊

使用者是帶有 `admin` 或 `user` 角色的帳戶。設定了密碼的使用者可以登入控制台；所有使用者都可以持有 API Key。角色為 `admin` 的執行個體管理員負責管理整個執行個體。

組織和團隊用來為使用者分組，團隊隸屬於某個組織。使用者透過成員關係在群組內取得角色，組織或團隊管理員可以管理所屬群組的資源，但不是執行個體管理員。API Key 可以綁定組織或團隊，綁定決定金鑰能使用哪些共用憑證，以及要計入哪些群組的預算。

## 模型名稱與請求位址

請求本文中的模型名稱決定目標。假設已建立名為 `fast` 的路由，向 `/v1/chat/completions` 傳送 `model: "fast"` 即可。

不經過路由、直接呼叫某個供應商時，把供應商名稱放進位址，並填寫上游模型 ID：`/openai-main/v1/chat/completions`。也可以繼續使用 `/v1/chat/completions`，把模型名稱寫成 `openai-main/<上游模型 ID>`。

路由名稱可以帶命名空間。名為 `acme/fast` 的路由，既可以在 `/v1/chat/completions` 上以 `model: "acme/fast"` 呼叫，也可以透過 `/acme/v1/chat/completions` 搭配 `model: "fast"` 呼叫。

完整的解析順序，以及避免路由名稱與供應商名稱衝突的命名限制，見[模型與路由](https://gproxy.leenhawk.com/zh-tw/guides/models.md)。

## 執行形式

同一個閘道有三種發行形式：

* Application：桌面或手機應用程式，內建設定精靈和控制台。
* CLI 與容器：伺服器處理程序，提供 HTTP API 和瀏覽器控制台。
* Cloudflare Workers：邊緣部署，使用遠端儲存，支援 WebSocket / Realtime。

安裝套件和平台限制見[下載與安裝](https://gproxy.leenhawk.com/zh-tw/download.md)。從 v3 升級時，請先閱讀[遷移說明](https://gproxy.leenhawk.com/zh-tw/deployment/v3-to-v4.md)。開始設定請依照[快速開始](https://gproxy.leenhawk.com/zh-tw/getting-started/quick-start.md)。


## Related topics

- [GPROXY](https://gproxy.leenhawk.com/zh-tw/index.md)
- [控制台](https://gproxy.leenhawk.com/zh-tw/guides/console.md)
- [架構](https://gproxy.leenhawk.com/zh-tw/development/architecture.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.