Initial commit: clean project structure
- Backend: FastAPI + SQLAlchemy + Celery (Python 3.11+) - Frontend: Vue 3 + TypeScript + Pinia + Tailwind - Admin Frontend: separate Vue 3 app for management - Docker Compose: 9 services orchestration - Specs: design prototypes, memory system PRD, product roadmap Cleanup performed: - Removed temporary debug scripts from backend root - Removed deprecated admin_app.py (embedded UI) - Removed duplicate docs from admin-frontend - Updated .gitignore for Vite cache and egg-info
This commit is contained in:
zhangtuo
246
backend/docs/provider_system.md
Normal file
246
backend/docs/provider_system.md
Normal file
@@ -0,0 +1,246 @@
|
||||
# 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 认证
|
||||
|
||||
### 配置说明
|
||||
|
||||
```bash
|
||||
# 启动主应用
|
||||
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)
|
||||
**目标**: 主渠道压力大时自动分流到后备渠道
|
||||
|
||||
**实现方案**:
|
||||
- 监控指标: 并发数、响应延迟、错误率
|
||||
- 分流阈值配置:
|
||||
```python
|
||||
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 格式
|
||||
- 输出结构:
|
||||
```python
|
||||
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. 成本追踪系统
|
||||
**目标**: 记录实际消费，支持预算控制
|
||||
|
||||
**实现方案**:
|
||||
- 成本记录表:
|
||||
```python
|
||||
class CostRecord:
|
||||
user_id: str
|
||||
provider_id: str
|
||||
capability: str # text/image/tts
|
||||
estimated_cost: Decimal
|
||||
actual_cost: Decimal | None
|
||||
timestamp: datetime
|
||||
```
|
||||
- 预算配置:
|
||||
```python
|
||||
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
|
||||
|
||||
**实现方案**:
|
||||
- 租户配置表:
|
||||
```python
|
||||
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. 创建适配器文件:
|
||||
```python
|
||||
# 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` 中导入:
|
||||
```python
|
||||
# app/services/adapters/__init__.py
|
||||
from app.services.adapters.image import new_provider as _new_provider # noqa: F401
|
||||
```
|
||||
|
||||
3. 添加配置:
|
||||
```python
|
||||
# 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=
|
||||
```
|
||||
Reference in New Issue
Block a user