一个带Web UI管理的轻量级高性能OpenAI模型代理网关，支持Docker快速部署

AI摘要

【知识分享】model_auto_switch是一款轻量级、支持Docker部署的OpenAI兼容API代理网关。它支持多供应商接入、负载均衡、故障转移，并提供Web UI进行配置管理与监控。该工具通过优先级和权重调整、模型别名、失败重试等机制，旨在提升模型服务的可靠性。

一、简介

model_auto_switch是一个支持多供应商、负载均衡和故障转移的 OpenAI 兼容 API 代理网关
支持接入多个OpenAI API兼容的模型供应商，如openai、openrouter、newapi等等
支持供应商级别、模型级别的优先级和权重调整，支持模型别名、失败重试，可实现可靠的负载均衡和故障转移，可极大提高模型服务的可靠性
提供Web UI，可在线登录并管理供应商和模型配置，在线查看模型使用与健康情况、程序运行日志等
支持Docker部署，容器镜像和运行容器内存占都只有几MB，非常轻量
该工具的开源地址参考：github.com/luler/model_auto_switch

二、安装（Docker推荐）

提前准备好Docker、docker-compose软件环境

拉取代码，进入代码根目录

git clone https://github.com/luler/model_auto_switch.git
cd model_auto_switch

新建docker-compose.yml配置文件，配置内容如下：

services:
model_auto_switch:
  image: ghcr.io/luler/model_auto_switch:latest
  restart: always
  ports:
    - 20261:3000
  volumes:
    - ./runtime:/app/runtime #日志文件存储位置
    - ./app/appconfig/openai_proxy.yaml:/app/app/appconfig/openai_proxy.yaml #供应商模型配置保存文件
  environment:
    - TZ=${TZ:-Asia/Shanghai}                         #时区
    - PORT=${PORT:-3000}                              #服务端口

新配置接口和页面访问的API Key，编辑./app/appconfig/openai_proxy.yaml文件，只需要新增或配置api_keys，其他参数可以在管理页面编辑，参考如下

# OpenAI 代理配置
# 对外提供的 API Keys（客户端使用这些 key 访问本服务）
api_keys:
- "sk-your-custom-api-key"
# - "sk-another-key"
# 请求重试配置
max_retries: 3           # 单次请求最大尝试次数（默认1不重试，设置>1启用故障转移）
# 供应商管理器配置
max_failures: 3          # 全局连续失败多少次后标记模型为不健康（可被单个模型配置覆盖）
recovery_interval: 30    # 恢复检查间隔（秒）
health_check_period: 3600  # 健康检查周期（秒）
# 上游供应商配置列表
providers:
# 供应商1: OpenAI 官方
- name: "openai"
  base_url: "https://api.openai.com"
  api_key: "sk-xxxx"
  weight: 1            # 供应商权重（用于负载均衡）
  priority: 1          # 供应商优先级（数字越小优先级越高）
  timeout: 120         # 超时时间（秒）
  # 过滤上游不支持的参数
  exclude_params:
    - thinking
    - verbosity
  model_mappings:
    # 设置 alias，对外暴露 alias 名称
    - upstream: "gpt-5"
      alias: "gpt-5"
      priority: 0   # 模型优先级（数字越小优先级越高 0-N）
      weight: 1
      # max_failures: 5  # 可选：该模型的连续失败阈值，不填则使用全局配置
    - upstream: "gpt-4o"
      alias: "gpt-5"
      priority: 0
      weight: 1