Skip to content

proxy-guide.md

Latest commit

 

History

History
122 lines (80 loc) · 7.7 KB

proxy-guide.md

File metadata and controls

122 lines (80 loc) · 7.7 KB
Raw

代理接入指南

本地代理提供 OpenAI 和 Anthropic 兼容 HTTP 端点, 并使用当前调度组为每个请求选择上游.

启动前准备

  1. 在 上游 页面添加至少一个可用上游.
  2. 在 调度组 页面确认当前入口组能够访问该上游.
  3. 在 仪表盘 点击 启动.
  4. 复制界面显示的 Base URL 和本地访问 key.

默认值:

Base URL: http://127.0.0.1:15721/v1
Authorization: Bearer cs-<uuid>

支持的端点

请求 说明
GET /health 服务健康检查, 不需要认证
GET /v1/models 汇总当前路由可达上游的模型
GET /models 不带 /v1 的模型列表别名
GET /v1/models/<id> 模型详情
POST /v1/responses Responses API
POST /v1/responses/<subpath> Responses 子路径, 包括 compact 和 input_tokens
POST /v1/chat/completions Chat Completions API
POST /v1/messages Anthropic Messages API
POST /v1/messages/count_tokens Anthropic 原生 token 计数
POST /v1/images/<subpath> Images 子路径, 例如 generations 和 edits

/responses, /chat/completions, /messages, /messages/count_tokens 和 /models/<id> 也提供不带 /v1 的别名. /vN/... 会当作 /v1/... 的别名, 例如 POST /v4/chat/completions. /chat/completion 会当作 /chat/completions 的别名. /backend-api/codex/responses 及其子路径可用于 Codex 风格请求.

当前没有 POST /v1/images 根路径, 客户端必须使用具体子路径. Responses 的 GET 和 WebSocket 模式尚未实现, 当前会返回 501.

认证

所有已实现的代理接口都需要精确的本地访问 key. /health 和尚未实现的 Responses GET 占位路由除外. OpenAI 客户端通常使用 Bearer, Anthropic 客户端可以使用 x-api-key:

Authorization: Bearer <仪表盘本地访问 key>
x-api-key: <仪表盘本地访问 key>

缺失或错误的 key 返回 401 和 authentication_error. 这个 key 只负责保护本地代理, 不会转发给上游. Relay 上游使用各自保存的 API Key, OAuth 上游使用自动维护的 access token.

临时 Key

顶部的 临时 Key 页面可以创建格式为 cs-tmp-<uuid> 的临时本地访问 key. 主 key 不受影响且仍然无限. 每个临时 key 可以勾选以下限制:

  • 成功请求次数上限: 只统计成功返回 2xx 的请求, 失败和重试不消耗次数.
  • 总 token 用量上限: 按 input, output, cache_read 和 cache_creation token 总和计算.
  • 固定时长过期: 创建时输入数字并选择分钟, 小时或天, 从创建时刻开始倒计时.
  • 模型范围限制: 输入一个或多个模型 glob 模式, 例如 gpt-* 或 qwen3-coder, 临时 key 只能请求匹配的模型, /v1/models 也只返回匹配项.

无效, 禁用或过期的临时 key 返回 401 和 authentication_error. 达到次数或 token 上限的 key 返回 429 和 rate_limit_error. 在页面中重置用量后, 该 key 立即可以再次使用, 限额, key 值和过期时间保持不变. 临时 key 与主 key 一样可以通过 Bearer 或 x-api-key 发送, 且不会被转发给上游.

由于 token 上限在请求完成后累计, 单个请求可能超过剩余额度, 但该 key 会在后续请求中被拒绝. 并发请求也可能让最后一小批成功请求略超次数上限.

模型列表

GET /v1/models 会遍历当前调度路径可达的上游:

  • Relay 上游实际请求其 /models 接口.
  • Codex OAuth 上游返回一个以上游名称构造的占位模型.
  • 重复模型 ID 会去重.
  • 模型映射规则会尽量反向还原客户端可见的模型 ID.
  • 单个上游查询失败时仍返回其他结果, 所有来源失败时返回代理错误.
  • 响应形状按 Base URL 识别结果解析, 支持 data 与 models 数组, 顶层数组, 以及 id, name, slug 三种 ID 字段, 详见上游管理指南的 Base URL 识别章节.

模型列表会发起外部请求, 不等同于静态缓存.

请求包含 anthropic-version 时, /models 和 /models/<id> 返回 Anthropic 模型结构. 列表支持 before_id, after_id 和 limit, 并返回 has_more, first_id 与 last_id. 未携带该请求头时保持 OpenAI object=list 结构.

API 转换

API Key 上游可以声明 Responses, Chat Completions 或 Anthropic Messages Wire API. 三种文本入站协议都可以选择三种文本上游. Codex OAuth 作为 Responses 上游参与文本协议转换.

入站协议 Responses 上游 Chat 上游 Anthropic 上游
Responses 直通 转换 转换
Chat Completions 转换 直通 经 Responses 转换
Anthropic Messages 转换 经 Responses 转换 直通

转换覆盖文本, base64/URL 图片, system/developer 指令, function/custom/namespace tools, tool call/result, tool choice, web search, reasoning/thinking, 输出 token 上限, sampling 参数, usage 和 SSE 生命周期. 同协议请求保持直通, 因此 provider 私有字段, Anthropic cache_control, thinking signature 和 anthropic-beta 可以原样保留.

对仅支持 function 工具的 Chat Completions 上游, 可在上游编辑界面开启 过滤 server_tool. 开启后, 转 Chat Completions 时会丢弃 web_search/web_search_preview 等 server tool, 并移除引用已删除工具的 tool_choice.

跨协议时, document/PDF, audio 和未知 server tool 会返回客户端协议对应的 400 invalid_request_error. thinking signature 不会跨协议转发. anthropic-beta 只在 Anthropic 同协议直通时发送给上游.

Images 不会选择 Anthropic 上游. Responses compact 也不会选择 Anthropic 上游.

Token 计数

/messages/count_tokens 只选择支持原生计数的 Responses 或 Anthropic 候选. Responses 候选请求 /responses/input_tokens, Anthropic 候选请求 /messages/count_tokens. Chat 候选会跳过. 没有原生候选时返回 Anthropic 404 not_found_error, 不做本地 token 估算.

Compact 请求

路径中以 /responses/compact 开头的请求只会选择勾选 支持 compact 的上游. 如果路由直接指向不支持 compact 的上游, 请求会失败, 不会自动寻找备用目标.

Chat Completions 上游的 compact 依赖转换能力, 应在实际中转站上验证后再开启该标记.

错误和重试

无法选择上游或网络连接失败通常返回 502. 跨协议无法表达的请求返回 400. 错误 envelope 会匹配入站 OpenAI 或 Anthropic 协议. 同协议上游 HTTP 错误保持原始响应.

是否重试由最终解析到的目标组决定. 失败切换组可能在返回错误前尝试下一个候选. 随机, 轮询, 固定上游和模型映射直达上游只有一个候选. 模型映射或固定模式跳入失败切换组后, 仍会执行该组的重试策略. 具体行为见调度组配置指南.

调度层会将 HTTP 4xx 记为状态失败, 并在达到失败阈值后尝试备用上游. HTTP 529, 5xx, Anthropic overloaded_error, server_is_overloaded 和 slow_down 继续按服务端失败处理. 流式响应开始后无法透明切换上游.

单个上游可以配置 错误重试 策略. 它在调度器根据原始上游响应完成选路后, 才将特定错误改写为可由客户端重试的响应. 它不会触发当前请求的上游切换, 但客户端自行发起的新请求仍会重新进入调度.

已知限制

  • 客户端 query string 当前不会附加到上游 URL.
  • 只转发经过筛选的请求头, 任意自定义头不保证保留.
  • 本地客户端口没有 TLS, 速率限制或请求体大小限制.
  • 节点之间使用独立 TLS 口, 详见节点转发指南.
  • WebSocket Responses 尚未实现.
  • 非回环监听需要自行提供可信网络边界.