AI 供应商管理

配图占位：本节用于在后续视觉评审中插入「供应商管理」列表页截图（11 列：名称+类型 / 状态 / API Key / 连通性 / 模型数 / 最近测试 / 优先级 / 权重 / 响应耗时 / 额度进度 / 操作）。

用途

/admin/ai-providers 用于登记并维护上游 AI 供应商的接入通道：连通性、协议、凭据、计费倍率、路由调度元数据（优先级 / 权重 / 响应耗时 / 额度）与「拉取模型」能力。一个供应商对应一条上游通道；模型目录默认挂在供应商之下，按供应商分别授权和计量。

主要场景：

首次接入新供应商：填写 Base URL / API Key / 协议模式，保存后立即可被模型目录引用。
巡检已接入供应商：通过「连通性 / 最近测试 / 响应耗时 / 额度进度」四列观察健康状态与额度使用情况，按需重置密钥或重新拉取模型。
删除供应商：先迁移或下线其下挂载的模型，避免出现孤儿模型引用。

使用前准备

仅管理员账号可见；登录态与 supabase 会话由 AdminGuard 守护。
若需首次接入 OpenAI 兼容服务，请提前准备上游 https://... 的 Base URL、可用的 API Key、自定义 Headers（JSON 格式，可使用 ${ENV_VAR} 占位符）。
模型目录（/admin/ai-models）依赖本页面登记的供应商作为外键；新增模型前必须先在此完成供应商登记。
价格中心（/admin/ai-pricing）的计费倍率与本页面共享 billingMultiplier；修改后会影响该供应商下所有模型的价格策略。

操作步骤

打开 /admin/ai-providers。表格由 AdminProvidersTab 承载，列依次为：名称+类型 / 状态（Switch）/ API Key / 连通性 / 模型数 / 最近测试 / 优先级 / 权重 / 响应耗时 / 额度进度 / 操作。
点击「新建供应商」，在抽屉（AdminProviderEditorDrawer）内填写字段：
- 供应商名称：必填，全局唯一，作为内部键名引用。
- Base URL：OpenAI 兼容协议的目标地址（必填，含 https:// 校验）。
- API Key：必填，写入时加密存储，仅在「测试连通性」或代理调用时解密使用。
- 路径前缀：可选，覆盖默认 /v1，例如 Azure 的 /openai/deployments/<name> 或自建网关前缀。
- 自定义 Headers：JSON 格式，可使用 ${ENV_VAR} 占位符在请求注入时展开。
- 模型别名映射：上游模型名 → 平台内显示名，用于保持上游迁移时下游引用稳定。
- 流式开关：是否启用 SSE 流式响应；关闭时所有调用强制走非流式。
- Function Call 开关：是否支持工具调用；关闭后模型目录里支持工具的模型会被屏蔽。
- 计费倍率：供应商成本到积分的换算系数，默认 1.0，可按运营成本调整。
- API 模式：openai_compat / anthropic / gemini / azure，决定调用客户端与转换层。
- 代理：可选 HTTP 代理地址，仅在该供应商需要时填写。
- 优先级（P0 路由调度元数据）：数值越大越优先；同优先级按权重比例分流。默认 0。
- 权重（P0 路由调度元数据）：同优先级内的权重比例，必须 > 0（≤ 0 自动兜底为 1，避免调度层除零）。默认 1。
- 额度（P0 路由调度元数据）：供应商额度上限（最小货币单位）。留空 / 填 0 视为「不限」。
- 已用（P0 路由调度元数据）：由路由层在请求成功后累加，管理员不可手动修改。
点击「测试连通性」验证 API Key 有效（走 POST /api/admin/ai-providers/{providerId}/test），同时把响应毫秒数持久化到 lastResponseMs，UI 用颜色编码展示健康度（< 500 ms 绿 / 500-2000 ms 黄 / > 2000 ms 红）。
点击「拉取模型」自动填充模型列表（走 POST /api/admin/ai-providers/{providerId}/fetch-models）。拉到 N 个模型后会引导到 /admin/ai-models 一键建模型（行为：结果缓存到 ai_providers.upstreamModels；不自动创建 GlobalModel 条目；N 个模型列表仅作预览参考）。
保存（POST /api/admin/ai-providers 或 PATCH /api/admin/ai-providers/{providerId}）。
若需轮换密钥，编辑抽屉内覆写 API Key 字段后保存即可；清空字段提交时保留原密钥（审计层不允许意外清空）。

结果与状态

新增供应商：行内 Switch 由 disabled → enabled；API Key 列显示「已配置」绿色 tag；连通性初始为「未测试」。
测试连通性：返回值 ok 时连通性列变为绿色「通过」pill；若上游返回 429 则显示「限流」warning 色；响应耗时按实测毫秒数着色并显示具体值（如 245 ms）。
拉取模型：上游返回的模型列表作为初始化建议写入模型目录，但不会自动创建条目；需要管理员手动到 /admin/ai-models 二次确认。
编辑保存：变更立即同步到 /api/admin/ai-providers GET 响应，刷新列表无需等待缓存。
删除供应商：软删（保留记录），关联模型引用会失效，需先迁移或下线模型再删除。

权限和边界

仅管理员账号可见；登录态与会话由 AdminGuard 守护。
API Key 加密后不可读回，仅支持「整体替换」。PATCH 编辑时若 base.apiKey 为空字符串，保留原密钥而非清空——这是审计层 A-2 的产物，避免意外清空导致供应商离线。
Function Call 关闭时不可选用支持工具的模型；模型目录会强制剔除该供应商下的「工具型」行。
删除供应商前必须先迁移或下线其下挂载的模型，避免出现孤儿模型引用。
「拉取模型」失败不会阻塞保存，但需要手动添加模型条目以保证目录完整。
路由调度层按 priority desc, weight desc 选择供应商；具体调度实现位于 src/lib/model-gateway/（本页面只承担元数据维护职责）。

常见问题

Q：编辑时不小心把 API Key 清空了，会丢失原密钥吗？ A：不会。后端 A-2 审计项保证 input.base.apiKey === '' 时跳过 encryptedApiKey 更新，原密钥保留。如需主动清空，使用「清密钥」按钮（POST /api/admin/ai-providers/{providerId}/secret，传 {confirm:true}）。
Q：连通性一直是「未测试」，点击「测试连通性」无反应？ A：检查浏览器网络面板确认 POST /api/admin/ai-providers/{providerId}/test 实际发出；常见原因：上游 Base URL 不通、防火墙拦截、API Key 失效。再次点击时观察 Switch 的 loading 状态。
Q：拉取模型返回空数组？ A：上游 /v1/models 端点路径可能不是默认 /v1，需要在「路径前缀」字段覆盖；部分代理服务不暴露此接口，需手动在 /admin/ai-models 新建条目。
Q：删除供应商时报「存在关联模型」？ A：先到 /admin/ai-models 列表按该供应商筛选，迁移或下线所有挂载模型后再次尝试删除。
Q：响应耗时一直是 —，点击「测试连通性」也没变化？ A：<500 ms 显示绿色 tag，<2000 ms 黄色 tag，≥ 2000 ms 红色 tag。超过 2 s 通常意味着上游限流或网络抖动，可结合连通性列 pill 一同判断。如果点击后 UI 没更新，刷新页面看 lastResponseMs 是否入库。
Q：额度列显示「不限」，但实际想设置上限？ A：编辑抽屉内「额度」字段填写整数（最小货币单位），保存后该字段才会进入数据库；null / 0 / 空字符串统一视为「不限」。

AI 供应商管理

用途

使用前准备

操作步骤

结果与状态

权限和边界

常见问题

相关文档