请求的处理过程
客户端只需要知道网关地址、网关 API Key 和模型名。GPROXY 本身不运行模型，推理由上游服务完成；GPROXY 负责决定请求发往哪个上游、使用哪份账户凭证、以什么格式发送。- 客户端发出请求。可以使用 OpenAI Chat Completions、OpenAI Responses、Claude Messages 或 Gemini GenerateContent 协议，流式和非流式均可。嵌入、重排、图像、音频、视频、文件和 Realtime 另有对应的端点，清单见路由与端点。
- GPROXY 验证密钥。密钥从
Authorization: Bearer、x-api-key或x-goog-api-key请求头读取，可以是网关 API Key，也可以是 GPROXY 签发的 OAuth 访问令牌。验证通过后即可确定调用方是哪个用户，以及密钥绑定的组织或团队。 - 准入检查。权限规则决定调用方对当前模型和操作可以使用哪些供应商；凭证归属和密钥绑定决定可以使用哪些凭证；随后确定适用的费用预算。限流放在最后计数，因为其他检查未通过的请求不应占用任何人的额度。各项检查的细节见权限、限流与费用预算。
- 解析模型名。路由名展开为路由成员，
供应商/模型形式的名称指向单个供应商。候选目标先按第 3 步允许的供应商和凭证筛选，再按层级、健康状况和权重排序。详见模型与路由。 - 选择供应商和凭证。在动用任何凭证之前先检查一次费用预算，然后从排在最前的候选中选出凭证发起尝试。如果失败原因允许重试，就换下一份可用凭证或下一个路由成员。
- 转换并发送。客户端协议与上游协议不同时，请求直接转换为上游格式；重写规则作用于转换后的请求，再由渠道附上凭证的认证信息发出。响应按相反顺序处理：先执行重写规则，再转换回客户端使用的协议。
- 结算用量与费用。每次实际的上游调用产生一条用量记录，包含 token 数等计量。费用按配置的价格规则计算，在调用结束后计入适用的预算。详见用量、日志与审计。
术语
渠道（Channel）
渠道是某一类上游服务的适配器，规定登录认证方式、上游接受的请求格式和支持的操作，例如openai、codex、custom。custom 用于需要自行填写服务地址和协议列表的 OpenAI 兼容服务。全部渠道见渠道目录。
供应商
供应商是保存下来的一条上游连接，包括名称、渠道、服务地址、渠道配置和一组凭证。多个供应商可以使用同一种渠道，例如两个地址不同的 OpenAI 兼容服务。供应商名称还会出现在请求地址和模型名中，见下文。凭证（Credential）
凭证是供应商登录上游所用的 API Key、OAuth 令牌或 Cookie。一个供应商可以保存多份凭证，GPROXY 在每次请求时从中选择，遇到限流或故障的凭证会换用其他凭证。凭证可以归属于用户、组织或团队，以此限定谁能使用。 配置主密钥后，凭证等机密信息加密存储。CLI 未配置主密钥时以明文存储，并打印提示。详见配置。模型路由（Route）
模型路由是客户端使用的模型名，对应一个或多个成员。每个成员由一个供应商和一个上游模型 ID 组成，并带有权重和回退层级。修改、增加或调整成员顺序时，客户端继续使用原来的模型名即可。网关 API Key
网关 API Key 由 GPROXY 签发给用户，客户端用它调用模型。请求会受到所属用户和密钥自身的权限、限流与预算约束。网关 API Key 与保存在供应商中的上游 API Key 是两回事，后者不会交给客户端。详见用户与 API Key。重写规则
重写规则在请求或响应经过供应商时对其进行修改：追加系统提示词、插入缓存断点、设置或删除 JSON 字段、替换文本、设置请求头。规则按规则集组织，规则集绑定到供应商。详见重写规则。用户、组织与团队
用户是带有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" 调用。
完整的解析顺序，以及防止路由名与供应商名冲突的命名限制，见模型与路由。
运行形式
同一个网关有三种发布形式：- Application：桌面或手机应用，带应用内设置向导和控制台。
- CLI 与容器：服务器进程，提供 HTTP API 和浏览器控制台。
- Cloudflare Workers：边缘部署，使用远程存储，支持 WebSocket / Realtime。