#Provider 管理流程 (Phase 2)

Last updated: 2025-11-09 · Owner: Codex

本文档说明在 v2 架构中如何通过平台管理模型提供商（Provider），涵盖录入密钥、配置模型、设置别名与审计流程。

#1. 目标

• 在应用内完成 Provider 生命周期管理，无需依赖环境变量或外部 Proxy。
• 将 API Key 以加密形式存储在数据库中，支持密钥轮换与禁用。
• 允许为同类模型设置别名（Alias），便于跨 Provider 对比。
• 提供基础的速率/预算配置，为后续 LiteLLM 限流与 LightEval 运行做准备。

#2. 新增 Provider

1. 打开 Settings → Providers 页面（/providers）。
2. 点击 New provider，填写：
   • Name：用于 UI 与图表展示。
   • Provider Type：openai / anthropic / gemini / custom。
   • Base URL：LiteLLM 将调用的 REST 入口。默认官方 API，可填写代理地址。
   • Capabilities：勾选该 Provider 支持的能力（system prompt、JSON mode、reasoning、image 等）。
   • Rate Limit：RPM / RPS / 并发等指标，Runner 会使用这些数值触发节流逻辑。
3. 在 API keys 区域录入密钥：
   • 每条记录包含 name + secret。提交后，secret 会使用 ENCRYPTION_KEY 进行 AES-GCM 加密，仅以密文存储。
   • 可添加多条密钥（例如生产/备用）。后续支持轮换：编辑时输入新密钥即可。
4. 保存后，后端会通过 LiteLLMClient 自动刷新可用模型列表（若 Provider 支持 list_models）。

#3. 管理模型与别名

• 进入 Provider 详情面板后，可为特定模型设置 Display label 与 Alias：
  • model_name：实际调用时使用的 ID，例如 gpt-4o。
  • alias：用于 Comparison 视图中跨 Provider 对齐的键，例如给 openai/gpt-4o 与 azure/gpt-4o 都设置为 gpt-4o。
• Comparison 页面会自动根据 Alias 分组，并允许保存预设（详见 Comparison 文档）。

#4. 密钥轮换与禁用

• 在 Provider 列表点击 Edit：
  1. 通过 Add key 添加新密钥。
  2. 提交后，可以在密钥列表中将旧密钥标记为 Disabled 或直接删除。
• 所有操作会写入 run_logs 与审计日志，方便后续追踪（未来版本将补充 UI 展示）。

#5. 速率限制与预算

• rate_limit 字段目前支持 rpm、rps、concurrency 等可选键。Celery Runner 会读取这些数值，在 LiteLLM 调用前执行令牌桶节流。
• 预算控制（token/day 等）将在 Phase 3 实现，此处字段先占位。

#6. LiteLLM 集成要点

• FastAPI 与 Celery 直接使用 LiteLLM Python SDK，LiteLLMClient 封装了解密、重试、日志等流程。
• 不再使用 LiteLLM Proxy 容器，减少运维成本。
• 如需走第三方代理，可在 Base URL 配置对应地址。

#7. 常见问题

• 为什么不支持环境变量配置密钥？
  • 避免在多个服务之间同步密钥，确保权限控制在应用层完成。
  • 结合 AES-GCM 加密，磁盘快照不会泄露明文密钥。
• 如何备份或迁移 Provider 数据？
  • 数据与密钥都存储在 PostgreSQL 中；ENCRYPTION_KEY 需要单独妥善保管。
  • 当前没有 legacy 数据可迁移；若未来需要，请参考 docs/migration/backup-strategy.md。

#8. 待办事项

• 紧密集成 LiteLLM 速率限制（P2-OPS-001），参见《docs/providers/litellm-sdk-blueprint.md》里的里程碑与设置清单。
• 提供 Provider 变更历史（审计日志 UI）。
• 支持团队协作下的权限/审批流程。