eval_752
  • 简体中文

      • LiteLLM Python SDK 集成蓝图

      状态：draft · Owner: Codex

      本蓝图描述 LiteLLM Python SDK 如何融入 FastAPI + Celery 架构。 目标是让 provider 配置、run 执行、评分和 LightEval 互操作围绕同一条集成面保持一致。

      目标

      • 集中化 LiteLLM client 初始化，让 FastAPI、Celery workers 和 LightEval 复用相同默认值
      • 通过本地 OpenAI-compatible gateways 保持可复现、可确定的测试覆盖
      • 在不把 secrets 泄露到错误层级的前提下暴露运行时控制项
      • 让适配层足够薄，从而为未来替换 SDK 预留空间

      当前基线

      • eval_752.services.litellm_client.LiteLLMClient 封装了 litellm.completion
      • Celery tasks 通过 worker 侧辅助代码获取 client，并在其中解密 provider keys
      • provider 创建流程把加密后的 API key 和可选 rate_limit JSON 存入 providers 表
      • 单元测试使用 mocks 或 fakes；集成测试使用本地 OpenAI-compatible gateway

      设计概览

      FastAPI endpoints ─┐
                   ├──▶ ProviderService ───▶ LiteLLMClientFactory
Celery workers  ───┘                              │
                                                  ├──▶ direct run execution
                                                  └──▶ LightEval config + execution path

      组件规划

      Factory 与缓存

      在 eval_752.services 下引入 LiteLLMClientFactory：

      • 接收 LiteLLMSettings
      • 按 provider/key 组合缓存同步 clients
      • 为未来扩展 async clients 预留空间，便于 streaming 需求增大时接入
      • 为测试暴露 reset() hook

      Settings 拆分

      • 仅启动阶段生效的 engine 选择仍保留在 backend/src/eval_752/app/config.py
      • 运行时请求超时与重试策略通过 workspace settings 持久化
      • 环境变量 / UI 的职责边界必须在 配置说明 中同步记录

      重试与限流策略

      • provider 元数据可以描述并发度及其他限流相关字段
      • 重试逻辑应在 LiteLLM client 调用外层包裹显式 backoff 与结构化日志
      • 日志建议记录 provider_id、model、retry_count、latency_ms 以及可用时的 token usage

      测试挂钩

      • 生产环境只保留一条标准 LiteLLM 路径
      • 单元测试仍可使用 stub / fake clients
      • 集成测试应继续使用本地 OpenAI-compatible gateway 和确定性 model names

      FastAPI 用法

      /providers/{id}/smoke-test 端点应通过共享 factory 获取 client，这样 smoke tests 与真实 runs 才会使用相同默认值。

      Celery 用法

      • worker 执行应通过同一个 factory
      • 优先保留 streaming-first 行为；只有在 provider 拒绝 streaming 时才回退到 buffered
      • 结构化调用日志应接入 run log stream

      与 LightEval 对齐

      • 生成 LightEval config 时，应复用相同的 provider base URL 与 key 选择逻辑
      • 当启用 use_lighteval_executor 时，LightEval 路径应与直接 LiteLLM 路径保持配置兼容

      可观测性

      建议指标：

      • litellm_requests_total
      • litellm_request_latency_seconds
      • litellm_tokens_total

      建议 labels：

      • provider_id
      • model
      • status

      待决问题

      • Phase 3 之前是否需要按天维度的 token budget
      • 如果未来需要更强的 proxy 兼容性，provider-specific headers 应如何存储
      • streaming adapters 在不复制逻辑的情况下应如何演进

      下一步动作

      • 持续保持运行时控制项与 secret templates 对齐
      • 继续加固 factory 与集成覆盖
      • 保持本蓝图与实现及验收文档同步