One Switch

One Switch

本地 AI API 网关，在多个模型供应商或上游模型之间自动故障转移。

只需把 AI 客户端连接到一个本地地址，One Switch 就会按队列优先级选择上游。当当前渠道遇到网络故障、超时、限流、鉴权异常或服务端错误时，请求会自动尝试下一个可用渠道。所有配置、密钥和请求记录均保留在本机。

为什么使用 One Switch

• 一个入口连接多个上游：客户端只需配置一次本地 API 地址，不必反复修改不同供应商的 Base URL。
• 自动故障转移：网络错误、超时、401、403、408、429 和 5xx 响应会触发队列中的下一次尝试。
• 协议感知路由：同一个上游模型可以配置多个协议端点，请求只会进入与其协议匹配的端点。
• 统一模型名称：客户端请求中的 model 会被替换为当前队列项配置的真实上游模型 ID。
• 手动切换与拖拽排序：可以随时指定首选模型或调整优先级，不会中断已经开始的请求。
• 流式响应透传：支持 SSE 流式输出；只要上游持续返回数据，长时间生成不会被总时长限制。
• 健康检查与冷却：连续失败的供应商会暂时进入冷却期，恢复后重新参与路由。
• 请求修改规则：在不写代码的前提下，按匹配条件对请求/响应 Header 与 JSON Body 做增删改写，弥补不同供应商之间的轻量兼容差异。
• 本地可观测性：提供请求尝试记录、成功率、延迟、TTFT、Token 用量、缓存命中和失败原因统计，以及实时运行日志视图。
• 渠道诊断：不转发请求即可直接测试队列中每个模型各协议端点是否能正常连接。
• 本地优先：API Key 使用 Electron safeStorage 加密保存，配置导出默认不包含密钥。

界面预览

截图素材统一存放在 [`snapshot/`](./snapshot/) 目录中。




支持的协议

协议	本地路径	常见上游
OpenAI Chat Completions	/v1/chat/completions	OpenAI、DeepSeek、OpenRouter、Ollama 及其他 OpenAI 兼容服务
OpenAI Responses	/v1/responses	OpenAI Responses API 兼容服务
Anthropic Messages	/v1/messages	Anthropic Claude 及兼容服务

上述路径也兼容省略 `/v1` 的形式。`GET /v1/models` 由 One Switch 本地提供，返回统一的 `default` 模型。

One Switch 默认优先使用与客户端协议一致的端点；对明确开启端点级协议转换的绑定，也支持部分 OpenAI 与 Anthropic 协议之间的请求、响应和流式 SSE 转换。转换属于尽力而为的兼容层，部分参数可能丢失。一次故障转移只会尝试原生匹配或已明确开启转换的队列项。Gemini 和自定义协议目前尚未在当前版本中开放。

工作方式

AI 客户端
    │
    │  http://127.0.0.1:9300/v1/...
    ▼
One Switch
    │
    ├─ 1. 识别请求协议
    ├─ 2. 筛选支持该协议且处于健康状态的模型
    ├─ 3. 按队列顺序改写真实模型 ID 并发起请求
    └─ 4. 失败时尝试下一个候选
            ├─ Provider A / Model A
            ├─ Provider B / Model B
            └─ Provider C / Model C

对于流式请求，One Switch 只会在响应尚未发送给客户端时切换上游。一旦响应头或内容已经开始透传，中途断开会被记录为失败，但不会拼接另一个模型的输出，以免产生混杂响应。

安装

前往 [GitHub Releases](https://github.com/yinxulai/one-switch/releas