# RFC 134: AI 服务完整实现

**状态**: 已实施  
**创建时间**: 2026-01-23  
**作者**: AI Assistant  
**类型**: 新功能

---

## 概述

完整实现 AI 生成服务，支持图片、视频、音效、配音、字幕和文本处理等多种 AI 功能，集成多个 AI 提供商（OpenAI、Stability AI、Runway），使用 Celery 处理异步任务。

## 动机

为导演组平台提供强大的 AI 辅助功能，帮助用户快速生成各类媒体资源，提升创作效率。

## 设计方案

### 1. 架构设计

```
┌─────────────┐
│  API Layer  │ ← FastAPI REST 接口
└──────┬──────┘
       │
┌──────▼──────┐
│   Service   │ ← 业务逻辑层
└──────┬──────┘
       │
┌──────▼──────┐
│ Repository  │ ← 数据访问层
└──────┬──────┘
       │
┌──────▼──────┐
│  Database   │ ← PostgreSQL 17
└─────────────┘

┌─────────────┐
│   Celery    │ ← 异步任务处理
└──────┬──────┘
       │
┌──────▼──────┐
│ AI Provider │ ← AI 提供商抽象层
└──────┬──────┘
       │
┌──────▼──────┐
│  OpenAI     │
│ Stability   │ ← 具体提供商实现
│  Runway     │
└─────────────┘
```

### 2. 数据库设计

#### 核心表

1. **ai_models** - AI 模型配置
   - 存储可用的 AI 模型及其定价
   - 支持动态配置，无需修改代码

2. **ai_jobs** - AI 任务记录
   - 记录所有 AI 生成任务
   - 支持状态跟踪和进度更新

3. **ai_usage_logs** - 使用日志
   - 详细记录每次 AI 调用
   - 支持成本分析和账单生成

4. **ai_quotas** - 配额管理
   - 支持每日/每月配额限制
   - 自动重置过期配额

### 3. AI 提供商抽象

使用抽象基类 `AIProvider` 定义统一接口：

```python
class AIProvider(ABC):
    @abstractmethod
    async def generate_image(...)
    
    @abstractmethod
    async def generate_video(...)
    
    async def generate_voice(...)
    async def generate_subtitle(...)
    async def process_text(...)
```

具体实现：
- `OpenAIProvider` - DALL-E, TTS, Whisper, GPT
- `StabilityProvider` - Stable Diffusion, Stable Video
- `RunwayProvider` - Gen-2 视频生成

### 4. 异步任务处理

使用 Celery 处理耗时的 AI 生成任务：

```python
@celery_app.task(base=AITask, bind=True, max_retries=3)
def generate_image_task(self, job_id, user_id, prompt, ...):
    return asyncio.run(_generate_image_async(...))
```

特性：
- 自动重试（最多 3 次）
- 任务状态跟踪
- 失败自动回调
- 超时控制

### 5. API 接口

提供 10 个 REST 端点：

1. `POST /api/v1/ai/generate-image` - 生成图片
2. `POST /api/v1/ai/generate-video` - 生成视频
3. `POST /api/v1/ai/generate-sound` - 生成音效
4. `POST /api/v1/ai/generate-voice` - 生成配音
5. `POST /api/v1/ai/generate-subtitle` - 生成字幕
6. `POST /api/v1/ai/process-text` - 处理文本
7. `GET /api/v1/ai/jobs/{job_id}` - 查询任务状态
8. `POST /api/v1/ai/jobs/{job_id}/cancel` - 取消任务
9. `GET /api/v1/ai/usage/stats` - 获取使用统计
10. `GET /api/v1/ai/models` - 获取可用模型

## 实施细节

### 文件结构

```
server/app/
├── models/
│   ├── ai_model.py          # AI 模型枚举和 SQLModel
│   ├── ai_job.py            # AI 任务枚举和 SQLModel
│   ├── ai_quota.py          # 配额枚举和 SQLModel
│   └── ai_usage_log.py      # 使用日志 SQLModel
├── repositories/
│   ├── ai_model_repository.py
│   ├── ai_job_repository.py
│   ├── ai_quota_repository.py
│   └── ai_usage_log_repository.py
├── services/
│   ├── ai_service.py        # AI 核心服务
│   └── ai_providers/
│       ├── base.py          # 抽象基类
│       ├── openai_provider.py
│       ├── stability_provider.py
│       ├── runway_provider.py
│       └── factory.py       # 提供商工厂
├── tasks/
│   ├── celery_app.py        # Celery 配置
│   └── ai_tasks.py          # AI 异步任务
├── api/v1/
│   └── ai.py                # API 路由
├── schemas/
│   └── ai.py                # Pydantic schemas
└── migrations/
    └── 007_ai_service_tables.py
```

### 配置要求

在 `.env` 文件中添加：

```bash
# AI 服务配置
OPENAI_API_KEY=sk-...
STABILITY_API_KEY=sk-...
RUNWAY_API_KEY=...
```

### 依赖包

新增依赖：
- `celery==5.3.6` - 异步任务队列
- `celery[redis]==5.3.6` - Redis 支持
- `openai==1.12.0` - OpenAI SDK
- `anthropic==0.18.1` - Anthropic SDK

## 使用示例

### 1. 生成图片

```python
POST /api/v1/ai/generate-image
{
  "prompt": "一只可爱的猫咪在花园里玩耍",
  "model": "dall-e-3",
  "width": 1024,
  "height": 1024,
  "style": "vivid"
}

# 响应
{
  "job_id": "019d1234-5678-7abc-def0-111111111111",
  "task_id": "abc-123-def",
  "status": "pending",
  "estimated_cost": 0.04,
  "estimated_credits": 10
}
```

### 2. 查询任务状态

```python
GET /api/v1/ai/jobs/019d1234-5678-7abc-def0-111111111111

# 响应
{
  "job_id": "019d1234-5678-7abc-def0-111111111111",
  "status": 3,  # COMPLETED
  "progress": 100,
  "output_data": {
    "image_url": "https://storage.jointo.ai/ai/images/123.png"
  }
}
```

### 3. 处理文本（剧本拆解）

```python
POST /api/v1/ai/process-text
{
  "task_type": "screenplay_parse",
  "text": "场景1：咖啡厅 - 白天\n小明走进咖啡厅...",
  "model": "gpt-4",
  "output_format": "json"
}
```

## 性能考虑

1. **异步处理**: 所有 AI 生成任务使用 Celery 异步处理，避免阻塞 API
2. **配额限制**: 防止用户过度使用，保护系统资源
3. **任务重试**: 自动重试失败的任务，提高成功率
4. **超时控制**: 设置合理的超时时间，避免任务无限等待

## 安全考虑

1. **API 密钥管理**: 所有 AI 提供商的 API 密钥存储在环境变量中
2. **用户认证**: 所有 API 端点需要 JWT 认证
3. **配额限制**: 防止滥用和成本失控
4. **错误处理**: 不暴露敏感的错误信息

## 测试策略

1. **单元测试**: 测试 Repository 和 Service 层
2. **集成测试**: 测试 API 端点和数据库交互
3. **Mock 测试**: Mock AI 提供商，避免实际调用

## 部署步骤

1. 执行数据库迁移：
   ```bash
   python run_migration.py 007
   ```

2. 安装依赖：
   ```bash
   pip install -r requirements.txt
   ```

3. 配置环境变量（`.env`）

4. 启动 Celery Worker：
   ```bash
   celery -A app.tasks.celery_app worker --loglevel=info
   ```

5. 启动 Celery Beat（定时任务）：
   ```bash
   celery -A app.tasks.celery_app beat --loglevel=info
   ```

6. 重启 FastAPI 应用

## 后续优化

1. **Credit Service 集成**: 实现积分预扣和确认机制
2. **文件存储**: 集成 MinIO 存储生成的媒体文件
3. **进度回调**: 实现 WebSocket 推送任务进度
4. **批量处理**: 支持批量生成任务
5. **缓存优化**: 缓存常用的 AI 模型配置
6. **监控告警**: 添加任务失败率监控

## 相关文档

- [AI 服务设计文档](../../requirements/backend/04-services/ai/ai-service.md)
- [数据库设计](../../requirements/database-design.md)
- [异步任务处理](../../requirements/backend/07-async-tasks.md)

## 变更日志

- 2026-01-23: 初始实现，包含所有核心功能