dreamweaver/backend/docs/provider_system.md

Provider 系统开发文档

当前版本功能 (v0.2.0)

已完成功能

1. CQTAI nano 图像适配器 (app/services/adapters/image/cqtai.py)

   • 异步生成 + 轮询获取结果
   • 支持 nano-banana / nano-banana-pro 模型
   • 支持多种分辨率和画面比例
   • 支持图生图 (filesUrl)

2. 密钥加密存储 (app/services/secret_service.py)

   • Fernet 对称加密，密钥从 SECRET_KEY 派生
   • Provider API Key 自动加密存储
   • 密钥管理 API (CRUD)

3. 指标收集系统 (app/services/provider_metrics.py)

   • 调用成功率、延迟、成本统计
   • 时间窗口聚合查询
   • 已集成到 provider_router

4. 熔断器功能 (app/services/provider_metrics.py)

   • 连续失败 3 次触发熔断
   • 60 秒后自动恢复尝试
   • 健康状态持久化到数据库

5. 管理后台前端 (app/admin_app.py)

   • 独立端口部署 (8001)
   • Vue 3 + Tailwind CSS 单页应用
   • Provider CRUD 管理
   • 密钥管理界面
   • Basic Auth 认证

配置说明

# 启动主应用
uvicorn app.main:app --port 8000

# 启动管理后台 (独立端口)
uvicorn app.admin_app:app --port 8001

环境变量:

CQTAI_API_KEY=your-cqtai-api-key
ENABLE_ADMIN_CONSOLE=true
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your-secure-password

---

下一版本优化计划 (v0.3.0)

高优先级

1. 智能负载分流 (方案 B)

目标: 主渠道压力大时自动分流到后备渠道

实现方案:

• 监控指标: 并发数、响应延迟、错误率
• 分流阈值配置:

  class LoadBalanceConfig:
      max_concurrent: int = 10  # 并发超过此值时分流
      max_latency_ms: int = 5000  # 延迟超过此值时分流
      max_error_rate: float = 0.1  # 错误率超过 10% 时分流
  

• 分流策略: 加权轮询，根据健康度动态调整权重

涉及文件:

• app/services/provider_router.py - 添加负载均衡逻辑
• app/services/provider_metrics.py - 添加并发计数器
• app/db/admin_models.py - 添加 LoadBalanceConfig 模型

2. Storybook 适配器

目标: 生成可翻页的分页故事书

实现方案:

• 参考 Gemini AI Story Generator 格式
• 输出结构:

  class StorybookPage:
      page_number: int
      text: str
      image_prompt: str
      image_url: str | None
  
  class Storybook:
      title: str
      pages: list[StorybookPage]
      cover_url: str | None
  

• 集成文本 + 图像生成流水线

涉及文件:

• app/services/adapters/storybook/ - 新建目录
• app/api/stories.py - 添加 storybook 生成端点

中优先级

3. 成本追踪系统

目标: 记录实际消费，支持预算控制

实现方案:

• 成本记录表:

  class CostRecord:
      user_id: str
      provider_id: str
      capability: str  # text/image/tts
      estimated_cost: Decimal
      actual_cost: Decimal | None
      timestamp: datetime
  

• 预算配置:

  class BudgetConfig:
      user_id: str
      daily_limit: Decimal
      monthly_limit: Decimal
      alert_threshold: float = 0.8  # 80% 时告警
  

• 超预算处理: 拒绝请求 / 降级到低成本 provider

涉及文件:

• app/db/admin_models.py - 添加 CostRecord, BudgetConfig
• app/services/cost_tracker.py - 新建
• app/api/admin_providers.py - 添加成本查询 API

4. 指标可视化

目标: 管理后台展示供应商指标图表

实现方案:

• 添加指标查询 API:
  • GET /admin/metrics/summary - 汇总统计
  • GET /admin/metrics/timeline - 时间线数据
  • GET /admin/metrics/providers/{id} - 单个供应商详情
• 前端使用 Chart.js 或 ECharts 展示

低优先级

5. 多租户 Provider 配置

目标: 每个租户可配置独立 provider 列表和 API Key

实现方案:

• 租户配置表:

  class TenantProviderConfig:
      tenant_id: str
      provider_type: str
      provider_ids: list[str]  # 按优先级排序
      api_key_override: str | None  # 加密存储
  

• 路由时优先使用租户配置，回退到全局配置

6. Provider 健康检查调度器

目标: 定期主动检查 provider 健康状态

实现方案:

• Celery Beat 定时任务
• 每 5 分钟检查一次所有启用的 provider
• 更新 ProviderHealth 表

7. 适配器热加载

目标: 支持运行时动态加载新适配器

实现方案:

• 适配器插件目录: app/services/adapters/plugins/
• 启动时扫描并注册
• 提供 API 触发重新扫描

---

API 变更记录

v0.2.0 新增

Method	Route	Description
GET	/admin/secrets	列出所有密钥名称
POST	/admin/secrets	创建/更新密钥
DELETE	/admin/secrets/{name}	删除密钥
GET	/admin/secrets/{name}/verify	验证密钥有效性

计划中 (v0.3.0)

Method	Route	Description
GET	/admin/metrics/summary	指标汇总
GET	/admin/metrics/timeline	时间线数据
POST	/api/storybook/generate	生成分页故事书
GET	/admin/costs	成本统计
POST	/admin/budgets	设置预算

---

适配器开发指南

添加新适配器

1. 创建适配器文件:

# app/services/adapters/image/new_provider.py
from app.services.adapters.base import AdapterConfig, BaseAdapter
from app.services.adapters.registry import AdapterRegistry

@AdapterRegistry.register("image", "new_provider")
class NewProviderAdapter(BaseAdapter[str]):
    adapter_type = "image"
    adapter_name = "new_provider"

    async def execute(self, prompt: str, **kwargs) -> str:
        # 实现生成逻辑
        pass

    async def health_check(self) -> bool:
        # 实现健康检查
        pass

    @property
    def estimated_cost(self) -> float:
        return 0.01  # USD

2. 在 __init__.py 中导入:

# app/services/adapters/__init__.py
from app.services.adapters.image import new_provider as _new_provider  # noqa: F401

3. 添加配置:

# app/core/config.py
new_provider_api_key: str = ""

# app/services/provider_router.py
API_KEY_MAP["new_provider"] = "new_provider_api_key"

4. 更新 .env.example:

NEW_PROVIDER_API_KEY=