osw README

The project's README from github.com/yinxulai/osw. As one markdown file: README.md.

One Switch

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

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

为什么使用 One Switch

界面预览

截图素材统一存放在 snapshot/ 目录中。

One Switch 界面预览 01

One Switch 界面预览 02

One Switch 界面预览 03

支持的协议

协议 本地路径 常见上游
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 下载适合当前平台的安装包:

macOS 构建目前采用 ad-hoc 签名且未公证。由于尚未使用正式的 Developer ID 签名,当前自动更新会关闭 macOS 发行者代码签名校验,下载完整性依赖更新元数据中的 SHA-512;正式签名后将恢复签名校验。若系统阻止首次打开,请在“系统设置 → 隐私与安全性”中确认打开,或在 Finder 中右键应用并选择“打开”。

快速开始

1. 添加供应商

打开 模型管理,新增一个供应商并填写:

API Key 只保存在本机加密存储中,不会出现在导出的配置文件里。

2. 添加上游模型

在供应商下添加真实模型 ID,例如 gpt-4.1、deepseek-chat 或 claude-sonnet-4-20250514,然后为它启用一个或多个协议端点。

端点可以使用供应商的默认地址,也可以为单个模型填写完整接口地址。一个模型即使支持多个协议,在故障转移队列中也只占一行。

3. 设置故障转移顺序

进入 模型队列:

  1. 拖拽模型调整优先级。
  2. 启用或停用不希望参与路由的模型。
  3. 需要临时指定上游时,手动切换当前首选模型。
  4. 使用队列测试确认各协议端点可以正常连接。

手动切换只影响后续请求,正在进行的普通或流式请求不会被中断。首选模型失败后,自动故障转移仍然生效。

4. 连接 AI 客户端

代理默认监听:

http://127.0.0.1:9300

在客户端中根据其协议填写 Base URL:

客户端使用的协议 Base URL 或接口地址
OpenAI 兼容 http://127.0.0.1:9300/v1
OpenAI Responses http://127.0.0.1:9300/v1
Anthropic Messages http://127.0.0.1:9300

客户端要求填写 API Key 时,可以填写任意非空占位值;真实上游密钥由 One Switch 按供应商注入。模型名可填写 default,代理会自动替换为最终选中队列项的真实模型 ID。

也可以直接验证本地模型列表:

curl http://127.0.0.1:9300/v1/models

监听地址和端口可在 设置 中修改。修改后需要重启本地代理服务才能让监听配置生效。

控制台的 接入配置 页面会实时显示当前监听地址与各协议对应的 Base URL,并支持一键复制,方便接入客户端。

5. 添加请求重写规则(可选)

部分供应商或模型存在轻量的兼容差异(如需要补充 User-Agent、增删 Header 或改写 JSON 中的私有字段)。在 请求重写 页面可以创建一个或多个可配置、可排序、可复用的规则:

规则默认关闭,改动不会以脚本方式执行,仅做结构化的增删改写;流式响应阶段不做 Body 重写。

故障转移策略

情况 行为
网络错误、连接超时、流式空闲超时 尝试下一个候选
401、403 尝试下一个候选,并累计供应商失败状态
408、429 尝试下一个候选
5xx 尝试下一个候选
其他 4xx 直接返回客户端,不切换
已开始向客户端发送响应后断开 终止当前请求,不拼接其他上游输出

连续失败阈值、初始冷却时间、最大冷却时间和流式空闲超时均可在 设置 → 故障转移 中调整。

本地可观测性

运行方式

数据与隐私

默认应用数据目录:

平台 路径
macOS ~/Library/Application Support/One Switch/
Windows %APPDATA%\One Switch\
Linux ~/.config/One Switch/

本地开发

需要 Node.js 22 或更高版本,以及 pnpm 9.6:

pnpm install
pnpm run dev

常用命令:

pnpm run typecheck     # TypeScript 类型检查
pnpm run lint          # ESLint
pnpm run test:server   # 服务端测试
pnpm run build         # 构建当前平台安装包
pnpm run release:mac   # 构建 macOS arm64 与 x64 安装包
pnpm run release:win   # 构建 Windows arm64 与 x64 安装包
pnpm run release:linux # 构建 Linux arm64 与 x64 安装包

技术栈包括 Electron、React、TypeScript、Vite、Drizzle ORM 和 SQLite。更详细的设计与行为约定见 规格文档。

当前边界

参与开发

欢迎通过 Issues 报告问题或提出建议。提交问题时,建议附上 One Switch 版本、操作系统、请求协议以及脱敏后的运行日志;请勿粘贴 API Key、完整提示词或其他敏感信息。

osw (yinxulai/osw)

Searching Database…

196 ·GitHub
Что это?One Switch — локальный шлюз AI API: направьте своего ИИ-клиента на один локальный адрес, и он автоматически маршрутизирует и переключается между настроенными за ним провайдерами и моделями LLM.
Это облачный сервис или то, что я запускаю на своей машине?Это нативное десктопное приложение на Electron для macOS, Windows и Linux, которое запускает локальный прокси-сервер на 127.0.0.1; облачной составляющей нет.
Как его запустить?Скачайте установщик для своей ОС с GitHub Releases (.dmg для macOS Apple Silicon/Intel, .exe для Windows x64/ARM64, .AppImage для Linux), затем добавьте провайдера с его API-ключом в Model Management, добавьте восходящие модели под ним и задайте их порядок в Model Queue.
Нужны ли мои собственные API-ключи от каждого провайдера?Да, вы предоставляете свой API-ключ для каждого добавленного провайдера (OpenAI, DeepSeek, OpenRouter, Ollama, сервисы, совместимые с Anthropic, и т.д.). Сам ИИ-клиент не нуждается в настоящем ключе, поскольку One Switch подставляет реальный восходящий ключ.
Есть ли подводные камни установки на macOS?Сборка для macOS сейчас подписана только ad-hoc и не нотаризована, поэтому проверка подписи автообновления отключена, а первый запуск может быть заблокирован; нужно разрешить его через System Settings или правый клик > Open в Finder.
Что произойдёт, если соединение оборвётся посреди стрима?One Switch переключает восходящие потоки только до того, как какой-либо ответ отправлен клиенту. Если стриминговый ответ уже начался, а затем соединение прервалось, запрос завершается и логируется как сбой — он никогда не вклеит вывод другой модели в тот же ответ.
Поддерживает ли он Gemini?Пока нет. Сейчас он говорит только на OpenAI Chat Completions, OpenAI Responses и Anthropic Messages; Gemini и пользовательские протоколы числятся запланированными, но недоступны в текущей версии.
Можно исправить причуды провайдера без написания кода?Да — функция Request Rewrite позволяет добавлять, удалять или править заголовки и поля JSON-тела (с поддержкой regex) для каждого провайдера и модели через настраиваемые упорядочиваемые правила, без всякого скриптинга.
Можно вручную выбрать, какая модель обработает следующий запрос?Да, можно перетаскиванием менять порядок очереди или вручную задать предпочтительную модель в любой момент; переключение затрагивает только новые запросы и не прервёт уже идущие, а автоматический failover всё равно сработает, если ваш выбор не удастся.
Creator
yinxulai
Size
63.3 MB
Stars
196
Age
2mo
Commits · 90 Days