# OpenAI Provider 集成

**日期**: 2026-01-30  
**类型**: Feature Enhancement  
**影响范围**: AI Service, AI Providers  
**关联文档**: `docs/server/guides/openai-api-configuration.md`

## 变更概述

集成真实的 OpenAI API Provider，支持使用 DALL-E、GPT、TTS、Whisper 等模型进行 AI 内容生成。系统会根据是否配置 API Key 自动选择使用真实 Provider 或 Mock Provider。

## 变更动机

### 问题
1. **仅支持 Mock Provider**：所有 AI 任务都返回测试数据，无法生成真实内容
2. **无法使用真实 AI 模型**：用户无法体验真实的 AI 生成效果
3. **缺少配置指南**：开发者不知道如何配置 OpenAI API

### 解决方案
- 实现完整的 OpenAI Provider，支持图片、文本、配音、字幕生成
- 自动检测 API Key，未配置时使用 Mock Provider
- 提供详细的配置指南和测试方法

## 技术实现

### 1. 修复 OpenAI Provider

#### 修复继承关系
```python
# ❌ 错误：继承不存在的 AIProvider
class OpenAIProvider(AIProvider):
    pass

# ✅ 正确：继承 BaseAIProvider
class OpenAIProvider(BaseAIProvider):
    pass
```

#### 修复构造函数
```python
# ❌ 错误：需要传入 api_key 参数
def __init__(self, api_key: str, **kwargs):
    pass

# ✅ 正确：从 settings 读取配置
def __init__(self, model_name: str, config: Optional[Dict[str, Any]] = None):
    super().__init__(model_name, config)
    self.api_key = settings.OPENAI_API_KEY
    self.base_url = settings.OPENAI_BASE_URL
```

#### 实现缺失的方法
```python
async def generate_sound(self, description: str, duration: int = 5, **kwargs):
    """OpenAI 不支持音效生成"""
    raise NotImplementedError("OpenAI 不支持音效生成，请使用其他 AI Provider")
```

#### 统一返回格式
所有方法返回的字典必须包含 `url` 字段（如果有文件）：

```python
# 图片生成
return {
    'url': data['data'][0]['url'],  # ✅ 使用 'url'
    'metadata': {...}
}

# 文本处理
return {
    'result': content,
    'url': None,  # ✅ GPT 返回文本，不是文件
    'metadata': {...}
}
```

#### 添加日志
```python
logger.info("调用 OpenAI DALL-E: prompt=%s, size=%s", prompt[:50], size)
logger.info("OpenAI DALL-E 生成成功: url=%s", data['data'][0]['url'])
```

### 2. 更新 Provider Factory

#### 自动选择 Provider
```python
class AIProviderFactory:
    # OpenAI 模型列表
    OPENAI_MODELS = [
        'dall-e-3', 'dall-e-2',
        'gpt-4', 'gpt-4-turbo', 'gpt-3.5-turbo',
        'tts-1', 'tts-1-hd',
        'whisper-1'
    ]
    
    @staticmethod
    def create_provider(model_name: str, config: Optional[Dict[str, Any]] = None):
        # 检查是否强制使用 Mock
        use_mock = config.get('use_mock', False) if config else False
        
        # 如果没有配置 API Key，自动使用 Mock
        if not use_mock and not settings.OPENAI_API_KEY:
            logger.warning("OPENAI_API_KEY 未配置，使用 Mock Provider")
            use_mock = True
        
        if use_mock:
            return MockAIProvider(model_name, config)
        
        # 根据模型名称选择 Provider
        if model_name in AIProviderFactory.OPENAI_MODELS:
            return OpenAIProvider(model_name, config)
        
        # 未知模型，使用 Mock
        return MockAIProvider(model_name, config)
```

#### 支持的模型

| 模型类型 | 模型名称 | 功能 |
|---------|---------|------|
| 图片生成 | `dall-e-3`, `dall-e-2` | 文本转图片 |
| 文本处理 | `gpt-4`, `gpt-4-turbo`, `gpt-3.5-turbo` | 剧本解析、内容分析 |
| 配音生成 | `tts-1`, `tts-1-hd` | 文本转语音 |
| 字幕生成 | `whisper-1` | 语音转文本 |

### 3. 更新环境变量

#### `.env` 文件
```env
# AI 服务配置
# OpenAI API Key（必需，用于 DALL-E、GPT、TTS、Whisper）
# 获取方式：https://platform.openai.com/api-keys
# 留空则自动使用 Mock Provider（返回测试数据）
OPENAI_API_KEY=
OPENAI_BASE_URL=https://api.openai.com/v1
```

#### 配置说明
- ✅ 留空 `OPENAI_API_KEY`：自动使用 Mock Provider
- ✅ 配置 `OPENAI_API_KEY`：使用真实 OpenAI API
- ✅ 支持自定义 `OPENAI_BASE_URL`（代理服务）

### 4. 工作流程

#### 图片生成流程
```
1. 用户调用 /api/v1/ai/generate-image
2. AI Service 创建任务，预扣积分
3. Celery Worker 调用 AIProviderFactory.create_provider('dall-e-3')
4. Factory 检查 OPENAI_API_KEY：
   - 已配置 → 返回 OpenAIProvider
   - 未配置 → 返回 MockAIProvider
5. Provider 生成图片（真实 API 或 Mock 数据）
6. 下载图片并上传到 MinIO
7. 更新任务状态，确认积分消耗
```

#### 自动降级机制
```
OPENAI_API_KEY 未配置
    ↓
自动使用 Mock Provider
    ↓
返回测试数据
    ↓
不消耗真实 API 额度
```

## 文件修改清单

### 修改文件
- `server/app/services/ai_providers/openai_provider.py`
  - 修复继承关系（`BaseAIProvider`）
  - 修复构造函数（从 `settings` 读取配置）
  - 实现 `generate_sound()` 方法
  - 统一返回格式（使用 `url` 字段）
  - 添加详细日志
  - 修复所有方法的参数和返回值

- `server/app/services/ai_providers/factory.py`
  - 添加 `OPENAI_MODELS` 列表
  - 实现自动选择 Provider 逻辑
  - 添加 API Key 检测
  - 添加详细日志

- `server/.env`
  - 添加 `OPENAI_API_KEY` 配置说明
  - 添加获取方式链接

### 新增文件
- `docs/server/guides/openai-api-configuration.md`
  - 完整的配置指南
  - 获取 API Key 步骤
  - 支持的模型列表
  - 测试验证方法
  - 常见问题解答

- `docs/server/changelogs/2026-01-30-openai-provider-integration.md`
  - 本文档

## 使用指南

### 配置 OpenAI API Key

1. **获取 API Key**：
   - 访问 https://platform.openai.com/api-keys
   - 创建新的 API Key
   - 复制 Key（格式：`sk-proj-...`）

2. **配置环境变量**：
   ```bash
   # 编辑 server/.env
   OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   ```

3. **重启服务**：
   ```bash
   docker restart jointo-server-app
   docker restart jointo-server-celery-ai
   ```

4. **验证配置**：
   ```bash
   # 查看日志
   docker logs jointo-server-celery-ai | grep -i openai
   
   # 预期输出
   INFO - 初始化 OpenAI Provider: model=dall-e-3
   INFO - 创建 OpenAI Provider: model=dall-e-3
   ```

### 测试图片生成

```bash
# 1. 登录获取 token
TOKEN=$(curl -X POST http://localhost:6170/api/v1/auth/login/phone \
  -H "Content-Type: application/json" \
  -d '{"phone": "+8613800138000", "country_code": "+86", "code": "6666"}' \
  | jq -r '.data.access_token')

# 2. 调用图片生成 API
curl -X POST http://localhost:6170/api/v1/ai/generate-image \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一只可爱的小猫在花园里玩耍",
    "model": "dall-e-3",
    "width": 1024,
    "height": 1024
  }' | jq

# 3. 查询任务状态
JOB_ID="<从上一步获取的 job_id>"
curl http://localhost:6170/api/v1/ai/jobs/$JOB_ID \
  -H "Authorization: Bearer $TOKEN" | jq
```

### 验证文件存储

1. 访问 MinIO Console：http://localhost:6185
2. 登录（用户名/密码见 `.env` 文件）
3. 进入 `jointo` bucket
4. 查看 `ai-generated/images/` 目录
5. 确认文件已上传

## 支持的功能

### ✅ 已支持

| 功能 | OpenAI 模型 | 状态 |
|------|------------|------|
| 图片生成 | DALL-E 3, DALL-E 2 | ✅ 完全支持 |
| 文本处理 | GPT-4, GPT-3.5 Turbo | ✅ 完全支持 |
| 配音生成 | TTS-1, TTS-1-HD | ✅ 完全支持 |
| 字幕生成 | Whisper-1 | ✅ 完全支持 |

### ❌ 不支持

| 功能 | 原因 | 替代方案 |
|------|------|---------|
| 视频生成 | OpenAI 不提供视频生成 API | 使用 Runway 或 Pika |
| 音效生成 | OpenAI 不提供音效生成 API | 使用其他 AI Provider |

## 费用说明

### OpenAI API 定价（2026 年 1 月）

| 服务 | 费用 | 说明 |
|------|------|------|
| DALL-E 3 (1024x1024) | $0.040/张 | 标准质量 |
| DALL-E 3 (1024x1024, HD) | $0.080/张 | 高清质量 |
| GPT-4 Turbo | $0.01/$0.03 per 1K tokens | 输入/输出 |
| GPT-3.5 Turbo | $0.0005/$0.0015 per 1K tokens | 输入/输出 |
| TTS-1 | $0.015/1K 字符 | 标准质量 |
| TTS-1-HD | $0.030/1K 字符 | 高清质量 |
| Whisper-1 | $0.006/分钟 | 语音转文本 |

### 费用估算

**示例 1：生成 10 张图片**
- 模型：DALL-E 3 (1024x1024, standard)
- 费用：10 × $0.040 = $0.40

**示例 2：解析 1000 字剧本**
- 模型：GPT-4 Turbo
- 输入：~1K tokens，输出：~2K tokens
- 费用：$0.01 + $0.06 = $0.07

**示例 3：生成 100 字配音**
- 模型：TTS-1
- 费用：0.1K × $0.015 = $0.0015

## 常见问题

### Q1: 如何切换回 Mock Provider？

**方式 1**：清空 API Key
```env
OPENAI_API_KEY=
```

**方式 2**：在代码中强制使用 Mock
```python
config = {'use_mock': True}
provider = AIProviderFactory.create_provider('dall-e-3', config)
```

### Q2: 如何使用国内代理？

编辑 `.env` 文件：
```env
OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://api.openai-proxy.com/v1
```

常见代理服务：
- [OpenAI-SB](https://openai-sb.com/)
- [API2D](https://api2d.com/)
- [CloseAI](https://close.ai/)

### Q3: API Key 无效怎么办？

1. 检查 API Key 格式（`sk-proj-` 或 `sk-` 开头）
2. 确认 API Key 未过期
3. 在 [OpenAI Platform](https://platform.openai.com/api-keys) 重新生成

### Q4: 余额不足怎么办？

1. 访问 [Billing 页面](https://platform.openai.com/account/billing/overview)
2. 检查账户余额
3. 充值或等待免费额度重置

## 性能影响

### 优点
- ✅ 真实的 AI 生成效果
- ✅ 高质量的内容输出
- ✅ 支持多种模型和参数

### 缺点
- ⚠️ 需要消耗 API 额度
- ⚠️ 网络延迟（国内访问较慢）
- ⚠️ 依赖第三方服务稳定性

### 优化建议
- 使用国内代理服务减少延迟
- 合理设置超时时间（300 秒）
- 监控 API 使用量，避免超额

## 后续优化

### 短期（1-2 周）
1. 添加 Stability AI Provider（Stable Diffusion）
2. 添加 Runway Provider（视频生成）
3. 添加 API 使用量监控

### 中期（1-2 月）
1. 实现 Provider 负载均衡
2. 添加 API 调用重试机制
3. 实现 API 费用统计

### 长期（3-6 月）
1. 支持自定义 AI Provider
2. 实现 AI 模型热切换
3. 添加 AI 生成质量评分

## 相关文档

- [OpenAI API 配置指南](../guides/openai-api-configuration.md)
- [AI Service 设计文档](../../requirements/backend/04-services/ai/ai-service.md)
- [AI API 测试指南](../guides/ai-api-testing.md)
- [OpenAI API 官方文档](https://platform.openai.com/docs/api-reference)

## 总结

成功集成 OpenAI Provider，支持使用真实的 AI 模型进行内容生成。系统会根据是否配置 API Key 自动选择使用真实 Provider 或 Mock Provider，确保开发和生产环境的灵活性。

**关键特性**：
- ✅ 自动检测 API Key，智能选择 Provider
- ✅ 支持 DALL-E、GPT、TTS、Whisper 等模型
- ✅ 完整的错误处理和日志记录
- ✅ 详细的配置指南和测试方法
- ✅ 与 FileStorageService 无缝集成

**下一步**：
1. 配置 OpenAI API Key
2. 重启服务
3. 测试图片生成 API
4. 验证文件上传到 MinIO
5. 监控 API 使用量和费用