> ## 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-cn/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-cn/guides/permissions.md)。
4. 解析模型名。路由名展开为路由成员，`供应商/模型` 形式的名称指向单个供应商。候选目标先按第 3 步允许的供应商和凭证筛选，再按层级、健康状况和权重排序。详见[模型与路由](https://gproxy.leenhawk.com/zh-cn/guides/models.md)。
5. 选择供应商和凭证。在动用任何凭证之前先检查一次费用预算，然后从排在最前的候选中选出凭证发起尝试。如果失败原因允许重试，就换下一份可用凭证或下一个路由成员。
6. 转换并发送。客户端协议与上游协议不同时，请求直接转换为上游格式；重写规则作用于转换后的请求，再由渠道附上凭证的认证信息发出。响应按相反顺序处理：先执行重写规则，再转换回客户端使用的协议。
7. 结算用量与费用。每次实际的上游调用产生一条用量记录，包含 token 数等计量。费用按配置的价格规则计算，在调用结束后计入适用的预算。详见[用量、日志与审计](https://gproxy.leenhawk.com/zh-cn/guides/observability.md)。

协议转换只改变请求格式，不改变上游的能力。上游不支持的操作，无论客户端从哪个端点调用都会失败。

## 术语

### 渠道（Channel）

渠道是某一类上游服务的适配器，规定登录认证方式、上游接受的请求格式和支持的操作，例如 `openai`、`codex`、`custom`。`custom` 用于需要自行填写服务地址和协议列表的 OpenAI 兼容服务。全部渠道见[渠道目录](https://gproxy.leenhawk.com/zh-cn/reference/channel-catalog.md)。

### 供应商

供应商是保存下来的一条上游连接，包括名称、渠道、服务地址、渠道配置和一组凭证。多个供应商可以使用同一种渠道，例如两个地址不同的 OpenAI 兼容服务。供应商名称还会出现在请求地址和模型名中，见下文。

### 凭证（Credential）

凭证是供应商登录上游所用的 API Key、OAuth 令牌或 Cookie。一个供应商可以保存多份凭证，GPROXY 在每次请求时从中选择，遇到限流或故障的凭证会换用其他凭证。凭证可以归属于用户、组织或团队，以此限定谁能使用。

配置主密钥后，凭证等机密信息加密存储。CLI 未配置主密钥时以明文存储，并打印提示。详见[配置](https://gproxy.leenhawk.com/zh-cn/reference/configuration.md)。

### 模型路由（Route）

模型路由是客户端使用的模型名，对应一个或多个成员。每个成员由一个供应商和一个上游模型 ID 组成，并带有权重和回退层级。修改、增加或调整成员顺序时，客户端继续使用原来的模型名即可。

### 网关 API Key

网关 API Key 由 GPROXY 签发给用户，客户端用它调用模型。请求会受到所属用户和密钥自身的权限、限流与预算约束。网关 API Key 与保存在供应商中的上游 API Key 是两回事，后者不会交给客户端。详见[用户与 API Key](https://gproxy.leenhawk.com/zh-cn/guides/users-and-keys.md)。

### 重写规则

重写规则在请求或响应经过供应商时对其进行修改：追加系统提示词、插入缓存断点、设置或删除 JSON 字段、替换文本、设置请求头。规则按规则集组织，规则集绑定到供应商。详见[重写规则](https://gproxy.leenhawk.com/zh-cn/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-cn/guides/models.md)。

## 运行形式

同一个网关有三种发布形式：

* Application：桌面或手机应用，带应用内设置向导和控制台。
* CLI 与容器：服务器进程，提供 HTTP API 和浏览器控制台。
* Cloudflare Workers：边缘部署，使用远程存储，支持 WebSocket / Realtime。

安装包和平台限制见[下载与安装](https://gproxy.leenhawk.com/zh-cn/download.md)。从 v3 升级时，请先阅读[迁移说明](https://gproxy.leenhawk.com/zh-cn/deployment/v3-to-v4.md)。开始配置请跟随[快速开始](https://gproxy.leenhawk.com/zh-cn/getting-started/quick-start.md)。


## Related topics

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


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