项目_CLIProxyAPI自动发现模型与模型同步面板改造

最近我基于 CLIProxyAPI 做了一轮比较完整的改造，目标很明确：让 OpenAI-compatible 上游的模型不再需要手工维护，而是能够自动同步、在管理面板里看到状态，并且真正参与调用链路。

这篇文章把这次改造的整条逻辑链梳理一下，也算给后面继续维护留一份清晰记录。

1. 问题背景

CLIProxyAPI 原本已经支持通过配置接入 OpenAI-compatible 提供商，但是实际使用时有一个很烦的点：

openai-compatibility:
  - name: xxx
    base-url: https://example.com/v1
    api-key-entries:
      - api-key: sk-xxx
    models:
      - name: gpt-4o
      - name: claude-sonnet-4

也就是说，你必须自己手工维护 models 列表。

这在实际使用里会有几个问题：

上游模型经常变化，人工维护很麻烦；
不同 key 看到的模型可能不一样；
管理面板里没有“同步状态”概念；
即使自动发现了模型，如果没真正接进调用链，也只是“看起来有”，实际上不能调。

所以这次改造的核心目标是：

让 OpenAI-compatible 提供商支持自动发现模型，并且把自动发现结果真正接入调用链，而不只是做成一个好看的状态页。

2. 后端改了什么

这次后端的改动主要集中在两个方向：

模型发现与同步
调用链路接入

2.1 自动发现 OpenAI-compatible 上游模型

我在 CLIProxyAPI 里增加了一套 upstream model sync 逻辑，专门针对 openai-compatibility 提供商：

启动时自动请求上游 /v1/models
默认每 30 分钟 自动同步一次
也支持通过管理接口手动触发同步

新增的配置项是：

openai-compatibility:
  - name: local-relay
    base-url: http://127.0.0.1:8317/v1
    auto-discover-models: true
    api-key-entries:
      - api-key: your-key-1
      - api-key: your-key-2
    models: []

这里最关键的是：

auto-discover-models: true
models: [] 可以为空

2.2 多 API Key 聚合与去重

只用第一个 API key 去拉模型列表是不够的，因为不同 key 对应的权限、套餐、可见模型都可能不同。

所以后端改成了：

遍历所有 api-key-entries
每个 key 请求一次 /v1/models
合并结果
按模型 ID 去重
某几个 key 失败也不影响整体，只要有一个 key 成功就算同步成功

这样一来，同一个提供商最终拿到的是一个更接近“真实可用全集”的模型列表。

2.3 新增模型同步管理接口

为了让同步过程可观察、可手动触发，新增了两个管理接口：

GET  /v0/management/model-sync/status
POST /v0/management/model-sync/run

它们分别负责：

查看每个 provider 的上次同步时间、成功状态、模型数量、错误信息
手动触发一次立即同步

这一步其实很重要。因为“自动同步”这种东西，如果没有状态页和手动触发按钮，最后都会变成黑盒，出了问题只能靠猜。

3. 前端改了什么

后端有了能力之后，还得把面板跟上，不然用户只能改 YAML。

这次前端主要做了三件事：

3.1 新增“模型同步”页面

在管理面板里增加了一个独立的中文页面：

模型同步

这个页面可以看到：

每个 source 的模型数量
最近尝试时间
最近成功时间
错误信息
手动触发同步按钮

这样至少先把“自动同步”从后台逻辑，变成了一个可视化的管理能力。

3.2 在 OpenAI-compatible 提供商编辑页加开关

只靠配配置文件不够顺手，所以又在 OpenAI-compatible 提供商编辑页加了一个：

自动发现模型 开关

打开开关、保存配置后，就可以让这个 provider 进入自动同步链路。

3.3 把新增功能统一改成中文

既然这次是自己维护的 fork，而且主要自己用，所以新增的页面和文案都直接改成了中文，比如：

模型同步
立即同步
自动发现模型
最近尝试
最近成功

这样后面自己维护时也更顺手。

4. 真正的难点：不是“同步到”，而是“能调用”

一开始我以为只要把模型同步到状态页里就够了，结果实测发现不是。

当 provider 的 models 为空时，虽然：

模型同步页里已经显示同步成功
/v1/models 里也能看到那些模型

但实际调用时还是会报：

auth_not_found: no auth available

这就说明一个关键问题：

“同步出来了”不等于“进入调用链了”。

4.1 第一刀：空 `models` 时回退使用动态发现结果

我先在调用链里补了一刀：

如果 openai-compatibility[].models 有手工配置，仍然优先用手工配置；
如果它为空，而且这个 provider 开了自动发现模型；
就从 upstream-sync:<provider> 这条动态同步结果里取模型，给对应 auth 做注册。

这样“自动发现的模型”第一次真正有机会进入 auth 注册链路。

4.2 第二刀：同步完成后自动刷新 auth 注册

但仅有第一刀还不够。

因为模型同步完成之后，auth 侧可能还保留的是旧快照。如果不同步完成后重新刷新 auth 注册，调用链依然拿不到新模型。

所以又补了第二刀：

监听 upstream-sync:<provider> 的模型注册变化
一旦这个动态 source 发生更新
自动对对应的 compat auth 执行一次 refresh

这一步补完之后，自动同步出来的模型才真正能参与路由。

5. 实测结果怎么判断是否真的打通

后面实际验证时，我发现一个很容易误判的点：

情况 A：报 `auth_not_found`

说明还是没接入调用链。

情况 B：报 429 / 403 / 502

这反而通常说明：

auth 已经选到了
请求已经打到上游了
只是上游额度、权限或服务本身有问题

比如我测试某个自动同步出来的模型时，返回的是：

429 month allocated quota exceeded

这说明问题已经不是“模型没挂上”，而是上游额度没了。

也就是说，调用链其实已经打通了。

6. 这次改造后的整体链路

整理一下，最后形成的逻辑链大概是这样：

1. 配置 OpenAI-compatible provider
2. 打开“自动发现模型”
3. 后端从 /v1/models 拉取模型列表
4. 多 API Key 结果聚合并去重
5. 同步状态写入 model-sync 管理页面
6. 动态发现的模型注册到 registry
7. 当 provider 手工 models 为空时，回退使用动态发现结果
8. 动态 source 变化后，自动刷新 compat auth 注册
9. 模型真正参与 auth 选择与调用路由

这才是一条完整可用的链路。

如果只做到第 3 步或第 5 步，本质上都还是半成品。

7. 配套工作

除了功能本身，我还顺手把这套 fork 的外围也整理了一下：

重写了前后端两个仓库的 README
改成中文主版本
添加了模型同步页面截图
打包了 Windows / Linux / macOS 的 release
release 附件里包含：
- 可执行程序
- management.html
- config.example.yaml

也就是说，这次不只是“本地改着玩”，而是已经整理成了一个可以拿出来持续维护的 fork 版本。

8. 我对这次改造的看法

这次改造最大的收获不是“多了一个状态页”，而是彻底理顺了一个问题：

自动发现模型这件事，只有真正接入 auth 与调用链，才算做完。

否则它只是一个看起来很美的功能。

另外还有一个很现实的经验：

前端问题，很多时候只是展示层；
真正麻烦的往往是“后端状态”和“调用链路”之间的同步；
只看面板，很容易误判问题到底出在配置、同步、还是上游本身。

9. 后面还可以继续做什么

虽然现在这条链已经能用了，但后面还有几个值得继续优化的方向：

在提供商卡片上直接显示“已发现模型数量”而不是只看手工 models；
给失败模型做状态标记，比如区分：
- 配额不足
- 权限不足
- 上游异常
增加同步间隔可配置；
增加更细粒度的 provider 级同步设置。

不过就当前阶段来说，这个版本已经足够实用了。

10. 相关仓库

后端 fork：

JBpeople/CLIProxyAPI

前端 fork：

JBpeople/Cli-Proxy-API-Management-Center

如果你也在用 OpenAI-compatible 上游，并且不想手工维护 models:，那么这套思路应该会比纯手工配置省事得多。