8.1 KiB

Raw Blame History

AI 服务完整实现

日期: 2026-01-23
类型: 新功能
影响范围: 后端服务
相关 RFC: 134-ai-service-implementation.md

概述

完成 AI 服务的完整实现，包括数据库模型、仓储层、服务层、AI 提供商集成、异步任务处理和 API 端点。

变更内容

1. 数据库模型层 (4个文件)

文件: server/app/models/

ai_model.py - AI 模型配置（支持 OpenAI、Stability、Runway 等）
ai_job.py - AI 任务记录（9种任务类型）
ai_quota.py - AI 配额管理（日/月/总配额）
ai_usage_log.py - AI 使用日志（成本追踪）

关键设计:

使用 UUID v7 作为主键（TEXT 类型存储）
外键关联 users 和 projects 表
支持软删除和状态管理
完整的审计字段（created_at, updated_at）

2. 仓储层 (4个文件)

文件: server/app/repositories/

ai_model_repository.py - 模型 CRUD 操作
ai_job_repository.py - 任务管理（创建、查询、更新状态）
ai_quota_repository.py - 配额检查和扣减
ai_usage_log_repository.py - 使用记录和统计

特性:

全异步实现（async/await）
事务支持
复杂查询（按日期范围统计、配额检查）

3. AI 提供商层 (5个文件)

文件: server/app/services/ai_providers/

base.py - 抽象基类定义统一接口
openai_provider.py - OpenAI 集成（GPT、DALL-E、Whisper）
stability_provider.py - Stability AI 集成（图片生成）
runway_provider.py - Runway 集成（视频生成）
factory.py - 工厂模式动态创建提供商实例

支持的功能:

文本生成（GPT-4, Claude）
图片生成（DALL-E 3, Stable Diffusion）
视频生成（Runway Gen-2）
语音合成（TTS）
语音识别（Whisper）
字幕生成

4. 服务层 (1个文件)

文件: server/app/services/ai_service.py

核心方法:

generate_image() - 图片生成
generate_video() - 视频生成
generate_sound() - 音效生成
generate_voice() - 配音生成
generate_subtitle() - 字幕生成
process_text() - 文本处理（剧本拆解等）
get_job_status() - 查询任务状态
cancel_job() - 取消任务
get_user_usage_stats() - 获取使用统计
get_available_models() - 获取可用模型列表

业务逻辑:

配额检查和扣减
任务创建和状态管理
异步任务调度
成本计算和记录

5. Celery 异步任务 (2个文件)

文件: server/app/tasks/

celery_app.py - Celery 应用配置
ai_tasks.py - AI 任务处理器

任务类型:

process_ai_job - 通用 AI 任务处理
cleanup_expired_jobs - 清理过期任务（定时任务）

配置:

Redis 作为消息代理和结果后端
任务超时：1小时
结果保留：24小时
定时任务：每天凌晨2点清理

6. API 层 (2个文件)

文件:

server/app/schemas/ai.py - Pydantic 请求/响应模型
server/app/api/v1/ai.py - FastAPI 路由处理器

API 端点:

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

7. 数据库迁移 (1个文件)

文件: server/app/migrations/007_ai_service_tables.py

创建的表:

ai_models - AI 模型配置
ai_jobs - AI 任务记录
ai_usage_logs - AI 使用日志
ai_quotas - AI 配额管理

索引:

用户 ID 索引（所有表）
任务类型和状态索引
创建时间索引
复合索引（user_id + quota_type）

触发器:

update_updated_at_column - 自动更新 updated_at

函数:

reset_expired_quotas() - 重置过期配额

8. 配置更新 (3个文件)

文件:

server/app/core/config.py - 添加 AI 服务配置
server/requirements.txt - 添加依赖包
server/app/api/v1/router.py - 注册 AI 路由

新增配置:

# AI 服务配置
OPENAI_API_KEY: str
STABILITY_API_KEY: str
RUNWAY_API_KEY: str
CELERY_BROKER_URL: str
CELERY_RESULT_BACKEND: str

新增依赖:

celery[redis]==5.3.4 - 异步任务队列
openai==1.12.0 - OpenAI SDK
httpx==0.26.0 - HTTP 客户端

修复的问题

启动错误修复

导入错误: get_db 不存在
- 修复：将所有 get_db 改为 get_session
保留字段: metadata 是 SQLAlchemy 保留字
- 修复：重命名为 extra_data
外键错误: storyboards 表不存在
- 修复：暂时移除外键约束，改为普通字段
类型不匹配: user_id 类型不一致
- 修复：统一使用 UUID 类型（PG_UUID）
外键列名: projects.project_id 不存在
- 修复：使用实际列名 projects.id
路由未注册: AI 路由未在 router.py 中注册
- 修复：在 router.py 中添加 ai.router

数据库表结构

ai_models

- model_id (TEXT, PK)
- model_name (TEXT, UNIQUE)
- display_name (TEXT)
- provider (SMALLINT)
- model_type (SMALLINT)
- cost_per_unit (NUMERIC)
- unit_type (SMALLINT)
- credits_per_unit (INTEGER)
- config (JSONB)
- is_active (BOOLEAN)

ai_jobs

- ai_job_id (TEXT, PK)
- user_id (UUID, FK)
- project_id (UUID, FK)
- storyboard_id (TEXT)
- job_type (SMALLINT)
- status (SMALLINT)
- input_data (JSONB)
- output_data (JSONB)
- model_id (TEXT, FK)
- progress (INTEGER)
- task_id (TEXT)
- cost (NUMERIC)
- credits_used (INTEGER)

ai_usage_logs

- usage_log_id (TEXT, PK)
- user_id (UUID, FK)
- ai_job_id (TEXT, FK)
- model_id (TEXT, FK)
- units_used (NUMERIC)
- unit_type (SMALLINT)
- cost (NUMERIC)
- credits_used (INTEGER)
- extra_data (JSONB)

ai_quotas

- quota_id (TEXT, PK)
- user_id (UUID, FK)
- quota_type (TEXT)
- period (SMALLINT)
- total_quota (INTEGER)
- used_quota (INTEGER)
- reset_at (TIMESTAMPTZ)

测试验证

服务状态

# 健康检查
curl http://localhost:6170/health
# 返回: {"status":"healthy","environment":"development"}

# 查看 API 文档
open http://localhost:6170/api/docs

数据库验证

# 检查表是否创建
docker exec jointo-server-postgres psql -U jointoAI -d jointo -c "\dt"
# 应显示: ai_models, ai_jobs, ai_usage_logs, ai_quotas

API 端点验证

# 查看所有 AI 端点
curl -s http://localhost:6170/api/openapi.json | \
  python3 -c "import sys, json; print('\n'.join([k for k in json.load(sys.stdin)['paths'].keys() if 'ai' in k]))"

后续工作

必需

配置环境变量（AI API 密钥）
启动 Celery Worker
配置 Redis 服务
添加初始 AI 模型数据

可选

添加单元测试
添加集成测试
实现速率限制
添加监控和告警
优化成本计算逻辑

环境变量配置

在 server/.env 中添加：

# AI 服务配置
OPENAI_API_KEY=sk-xxx
STABILITY_API_KEY=sk-xxx
RUNWAY_API_KEY=xxx

# Celery 配置
CELERY_BROKER_URL=redis://localhost:6183/0
CELERY_RESULT_BACKEND=redis://localhost:6183/0

启动 Celery Worker

# 在 server/ 目录下
celery -A app.tasks.celery_app worker --loglevel=info

# 启动定时任务调度器
celery -A app.tasks.celery_app beat --loglevel=info

影响范围

✅ 数据库：新增 4 张表
✅ API：新增 10 个端点
✅ 依赖：新增 3 个 Python 包
✅ 配置：新增 5 个环境变量
⚠️ 服务：需要启动 Celery Worker
⚠️ 基础设施：需要 Redis 服务

兼容性

✅ 向后兼容：不影响现有功能
✅ 数据库：使用迁移脚本，安全升级
✅ API：新增端点，不修改现有端点

文档

RFC: docs/server/rfcs/134-ai-service-implementation.md
Changelog: 本文件
API 文档: http://localhost:6170/api/docs

贡献者

实现：AI Assistant
审核：待定
测试：待定

8.1 KiB Raw Blame History