luler 一、简介 model_auto_switch是一个支持多供应商、负载均衡和故障转移的 OpenAI 兼容 API 代理网关 支持接入多个OpenAI API兼容的模型供应商，如openai、openrouter、newapi等等 支持供应商级别、模型级别的优先级和权重调整，支持模型别名、失败重试，可实现可靠的负载均衡和故障转移，可极大提高模型服务的可靠性 提供Web UI，可在线登录并管理供应商和模型配置，在线查看模型使用与健康情况、程序运行日志等 支持Docker部署，容器镜像和运行容器内存占都只有几MB，非常轻量 该工具的开源地址参考：https://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 配置完成，执行如下命令启动服务 docker-compose up -d 启动成功后，可以访问页面：http://127.0.0.1:20261/ 三、使用 登录管理页面，访问：http://127.0.0.1:20261/，输入openai_proxy.yaml中配置的api_keys 可以在线配置模型供应商，接入各种openai接口兼容的模型供应商，配置模型、权重、优先级、重试、健康检查等 可实时查看模型的健康状况、负载状况等信息 可在线查看程序运行日志，有助于分析问题原因 可以接入openai兼容的客户端，提供模型网关代理服务 四、总结 该模型代理网关与newapi等网关有类似的功能，但它更强调模型的可靠性，针对性优化了优先级别机制、负载均衡和故障转移 它的优先级机制是高优先级模型不可用后才会轮到低优先级模型，在一些特殊场景非常有用，如gpt-5不可用后自动降级为gpt-4o 故障转移也不错，可以实现在指定重试次数内根据负载权重配置尝试所有可用模型，保证了客户端模型使用的稳定性 总之，该工具可以作为其他网关或者模型供应商的轻量化下游，提供差异化的模型映射配置和稳定的模型负载服务
