11 KiB

Raw Blame History

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。

变更动机

问题

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

解决方案

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

技术实现

1. 修复 OpenAI Provider

修复继承关系

# ❌ 错误：继承不存在的 AIProvider
class OpenAIProvider(AIProvider):
    pass

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

修复构造函数

# ❌ 错误：需要传入 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

实现缺失的方法

async def generate_sound(self, description: str, duration: int = 5, **kwargs):
    """OpenAI 不支持音效生成"""
    raise NotImplementedError("OpenAI 不支持音效生成，请使用其他 AI Provider")

统一返回格式

所有方法返回的字典必须包含 url 字段（如果有文件）：

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

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

添加日志

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

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` 文件

# 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

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

配置环境变量：

# 编辑 server/.env
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

重启服务：

docker restart jointo-server-app
docker restart jointo-server-celery-ai

验证配置：

# 查看日志
docker logs jointo-server-celery-ai | grep -i openai

# 预期输出
INFO - 初始化 OpenAI Provider: model=dall-e-3
INFO - 创建 OpenAI Provider: model=dall-e-3

测试图片生成

# 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

验证文件存储

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

支持的功能

✅ 已支持

功能	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

OPENAI_API_KEY=

方式 2：在代码中强制使用 Mock

config = {'use_mock': True}
provider = AIProviderFactory.create_provider('dall-e-3', config)

Q2: 如何使用国内代理？

编辑 .env 文件：

OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://api.openai-proxy.com/v1

常见代理服务：

Q3: API Key 无效怎么办？

检查 API Key 格式（sk-proj- 或 sk- 开头）
确认 API Key 未过期
在 OpenAI Platform 重新生成

Q4: 余额不足怎么办？

访问 Billing 页面
检查账户余额
充值或等待免费额度重置

性能影响

优点

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

缺点

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

优化建议

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

后续优化

短期（1-2 周）

添加 Stability AI Provider（Stable Diffusion）
添加 Runway Provider（视频生成）
添加 API 使用量监控

中期（1-2 月）

实现 Provider 负载均衡
添加 API 调用重试机制
实现 API 费用统计

长期（3-6 月）

支持自定义 AI Provider
实现 AI 模型热切换
添加 AI 生成质量评分

总结

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

关键特性：

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

下一步：

配置 OpenAI API Key
重启服务
测试图片生成 API
验证文件上传到 MinIO
监控 API 使用量和费用

11 KiB Raw Blame History