14 KiB

Raw Blame History

AI 服务功能实施总结

日期: 2026-02-03
类型: 功能实施总结
影响范围: 后端 AI 服务完整实现

概述

基于 4 个需求文档完成了 AI 服务功能的完整实现，包括 Service 层、Repository 层和 API 路由层。

需求文档

docs/requirements/backend/04-services/ai/ai-service.md - AI 生成服务
docs/requirements/backend/04-services/ai/ai-prompt-system-service.md - AI 提示词系统
docs/requirements/backend/04-services/ai/ai-conversation-service.md - AI 对话记录服务
docs/requirements/backend/04-services/ai/ai-conversation-mention-system.md - AI 对话 @ 提及系统

实施状态

✅ 已完成（阶段 1）

1. Service 层实现

✅ AIService - AI 生成服务
- 图片生成
- 视频生成
- 音效生成
- 配音生成
- 字幕生成
- 文本处理
- 剧本解析
- 任务状态管理
- 模型查询
- 使用统计
✅ AIPromptSystemService - AI 提示词系统服务
- 提示词 CRUD
- 默认提示词管理
- 版本管理
- Skills 配置管理
✅ AIConversationService - AI 对话记录服务
- 对话会话管理（创建/查询/更新/删除）
- 消息管理（发送/查询）
- 上下文管理
- 多态关联（分镜/角色/场景/道具/资源/音效/配音）
- 标签系统（区分变体）
- @ 提及功能（解析/验证/构建）
- AI 生成触发

2. Repository 层实现

✅ AIRepository - AI 任务数据访问
✅ AIPromptSystemRepository - AI 提示词数据访问
✅ AIConversationRepository - AI 对话数据访问
✅ AIConversationMessageRepository - AI 对话消息数据访问

3. API 路由层实现

✅ ai_conversations.py - AI 对话 API（9 个端点）

POST   /api/v1/ai/conversations                          # 创建对话会话
GET    /api/v1/ai/conversations                          # 获取对话会话列表
GET    /api/v1/ai/conversations/{conversation_id}        # 获取对话会话详情
PATCH  /api/v1/ai/conversations/{conversation_id}        # 更新对话会话
DELETE /api/v1/ai/conversations/{conversation_id}        # 删除对话会话
POST   /api/v1/ai/conversations/{conversation_id}/messages              # 发送消息
GET    /api/v1/ai/conversations/{conversation_id}/messages              # 获取消息列表
GET    /api/v1/ai/conversations/{conversation_id}/mentionable-resources # 获取可提及资源
POST   /api/v1/ai/conversations/{conversation_id}/generate              # 触发 AI 生成

✅ ai_prompts.py - AI 提示词管理 API（7 个端点）

POST   /api/v1/admin/ai-prompts                    # 创建提示词（管理员）
GET    /api/v1/admin/ai-prompts                    # 获取提示词列表（管理员）
GET    /api/v1/admin/ai-prompts/{prompt_id}        # 获取提示词详情（管理员）
PATCH  /api/v1/admin/ai-prompts/{prompt_id}        # 更新提示词（管理员）
DELETE /api/v1/admin/ai-prompts/{prompt_id}        # 删除提示词（管理员）
POST   /api/v1/admin/ai-prompts/{prompt_id}/set-default  # 设置默认提示词（管理员）
GET    /api/v1/admin/ai-prompts/default/{prompt_type}    # 获取默认提示词（公开）

✅ ai_models.py - AI 模型查询 API（1 个端点）

GET /api/v1/ai/models  # 获取可用的 AI 模型列表

✅ ai_jobs.py - AI 任务管理 API（5 个端点）

GET    /api/v1/ai/jobs/{job_id}        # 查询任务状态
POST   /api/v1/ai/jobs/{job_id}/cancel # 取消任务
GET    /api/v1/ai/jobs                 # 批量查询用户任务
GET    /api/v1/ai/jobs/statistics      # 获取任务统计信息
GET    /api/v1/ai/jobs/usage/stats     # 获取使用统计

4. Schema 定义

✅ ai_conversation.py - AI 对话相关 Schema
- ConversationCreateRequest
- ConversationUpdateRequest
- MessageCreateRequest
- GenerateRequest

5. 路由注册

✅ 已在 server/app/api/v1/__init__.py 中注册所有新路由

🔄 待实施（阶段 2-4）

阶段 2: Celery 异步任务实现

创建 app/tasks/ai_tasks.py
实现异步生成任务
- generate_image_task
- generate_video_task
- generate_sound_task
- generate_voice_task
- generate_subtitle_task
- process_text_task
- parse_screenplay_task
实现任务状态回调
实现任务失败重试
实现任务进度更新

阶段 3: AI Provider 集成

集成 ai_providers 目录中的 AI 服务
- aihubmix_provider.py - AIHubMix 提供商
- 其他提供商（如有）
实现统一的 Provider 接口
实现 Provider 路由和负载均衡
实现 Provider 错误处理和降级
实现文件上传到 OSS
实现文件去重（SHA256 校验）

阶段 4: 测试和优化

编写单元测试
- Service 层测试
- Repository 层测试
- API 路由测试
编写集成测试
- 完整的对话流程测试
- AI 生成任务测试
- @ 提及功能测试
性能优化
- 数据库查询优化
- 缓存策略
- 并发控制
文档完善
- API 文档
- 使用指南
- 故障排查

核心功能特性

1. AI 对话系统

多态关联 + 标签系统：

支持 7 种目标类型（分镜/角色/场景/道具/资源/音效/配音）
支持 5 种媒体类型（图片/视频/音频/3D模型/文本）
支持标签系统（区分同一对象的不同变体）
完整的对话隔离（类型/对象/变体/用户）

@ 提及功能：

自动解析消息中的 @ 提及标记
验证所有提及的资源
构建 metadata（mentions + reference_images）
支持多种资源类型提及

AI 生成触发：

从对话触发 AI 生成任务
自动提取参考图
支持多种生成类型
任务状态自动回复

2. AI 提示词系统

提示词管理：

完整的 CRUD 操作
版本管理
默认提示词管理
Skills 配置管理

权限控制：

管理接口：仅管理员可访问
公开接口：供内部服务调用

3. AI 任务管理

任务状态管理：

任务创建和状态跟踪
任务取消和积分退还
任务进度更新
任务结果存储

统计和查询：

批量查询用户任务
任务统计信息
使用统计
成本分析

4. AI 模型管理

模型查询：

获取可用的 AI 模型列表
按模型类型筛选
返回模型定价信息
支持多种 AI 提供商

技术规范

符合 jointo-tech-stack 规范

✅ 异步操作: 所有数据库操作使用 async/await
✅ 统一响应格式: 使用 success_response() 和 error_response()
✅ 完整的错误处理: try-except + exc_info=True
✅ %-formatting 日志: logger.error("错误: %s", str(e), exc_info=True)
✅ 依赖注入: 使用 Depends(get_db) 和 Depends(get_current_user)
✅ 类型提示: 完整的 Python 类型注解
✅ UUID v7: 所有 ID 参数使用 UUID 类型
✅ TIMESTAMPTZ: 所有时间字段使用 TIMESTAMPTZ
✅ SMALLINT 枚举: 所有枚举类型使用 SMALLINT 存储
✅ 无物理外键: 应用层保证引用完整性

应用层引用完整性保证

三层保证机制：

Repository 层：提供 exists() 方法检查记录是否存在
Service 层：创建/更新前验证所有关联 ID，使用事务确保原子性
后台任务：定期检查孤儿记录并告警

验证示例：

# 验证目标对象是否存在
if not await self._validate_target(target_type, target_id):
    raise ValidationError("目标对象不存在")

# 验证标签是否存在
if tag_id:
    if not await self._validate_tag(tag_id, target_type, target_id):
        raise ValidationError("标签不存在或不属于该对象")

依赖关系

Service 层依赖

AIConversationService → AIService
AIService → CreditService
AIConversationService → ScreenplayTagService（标签验证）

Repository 层依赖

AIConversationRepository → ai_conversations 表
AIConversationMessageRepository → ai_conversation_messages 表
AIRepository → ai_jobs 表
AIPromptSystemRepository → ai_prompts 表

核心依赖

get_db: 数据库会话
get_current_user: 当前用户认证
require_admin: 管理员权限验证

文件清单

新增文件

server/app/api/v1/ai_conversations.py - AI 对话 API
server/app/api/v1/ai_prompts.py - AI 提示词管理 API
server/app/api/v1/ai_models.py - AI 模型查询 API
server/app/api/v1/ai_jobs.py - AI 任务管理 API
server/app/schemas/ai_conversation.py - AI 对话 Schema
docs/server/changelogs/2026-02-03-ai-api-routes-implementation.md - API 路由实现文档
docs/server/changelogs/2026-02-03-ai-services-implementation-summary.md - 本文档

修改文件

server/app/api/v1/__init__.py - 注册新路由

已存在文件（无需修改）

server/app/services/ai_service.py - AI 生成服务（已完整）
server/app/services/ai_conversation_service.py - AI 对话服务（已完整）
server/app/services/ai_prompt_system_service.py - AI 提示词服务（已完整）
server/app/repositories/ai_repository.py - AI 任务数据访问（已完整）
server/app/repositories/ai_conversation_repository.py - AI 对话数据访问（已完整）
server/app/repositories/ai_conversation_message_repository.py - AI 对话消息数据访问（已完整）
server/app/repositories/ai_prompt_system_repository.py - AI 提示词数据访问（已完整）
server/app/services/ai_providers/aihubmix_provider.py - AIHubMix 提供商（已存在）

后续工作计划

优先级 P0（必须完成）

Celery 异步任务实现（阶段 2）
- 创建 app/tasks/ai_tasks.py
- 实现所有异步生成任务
- 实现任务状态回调
- 实现任务失败重试
AI Provider 集成（阶段 3）
- 集成 aihubmix_provider.py
- 实现统一的 Provider 接口
- 实现文件上传到 OSS
- 实现文件去重

优先级 P1（重要）

测试覆盖（阶段 4）
- 编写单元测试
- 编写集成测试
- 测试覆盖率 > 80%
性能优化
- 数据库查询优化
- 缓存策略
- 并发控制

优先级 P2（可选）

文档完善
- API 文档（Swagger/OpenAPI）
- 使用指南
- 故障排查
监控和告警
- 任务失败告警
- 性能监控
- 成本监控

验证清单

所有 Service 方法使用 async/await
所有 API 路由使用统一响应格式
所有 API 路由有完整的错误处理
所有 API 路由有日志记录
所有 API 路由有类型提示
所有 API 路由已注册到主路由器
代码通过 getDiagnostics 检查
符合 jointo-tech-stack 规范
应用层保证引用完整性
编写单元测试
编写集成测试
性能测试
文档完善

注意事项

积分扣除: 触发 AI 生成时会扣除用户积分，需确保积分充足
任务取消: 只能取消 pending 或 processing 状态的任务
@ 提及: 消息中的 @ 提及会自动解析和验证
参考图: 参考图会自动从消息 metadata 中提取并传递给 AI Service
权限控制: AI 提示词管理接口需要管理员权限
对话隔离: 不同类型/对象/变体/用户的对话完全隔离
标签验证: 标签必须属于对应的对象，且元素类型必须匹配

测试建议

1. 对话会话测试

# 创建对话会话
curl -X POST http://localhost:8000/api/v1/ai/conversations \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "target_type": 1,
    "target_id": "uuid",
    "media_type": 1,
    "project_id": "uuid",
    "title": "测试对话"
  }'

2. 发送消息（带 @ 提及）

curl -X POST http://localhost:8000/api/v1/ai/conversations/{conversation_id}/messages \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "请生成一个角色形象，参考 @resource:uuid"
  }'

3. 触发 AI 生成

curl -X POST http://localhost:8000/api/v1/ai/conversations/{conversation_id}/generate \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": "uuid",
    "generation_type": "image",
    "params": {
      "width": 1024,
      "height": 1024
    }
  }'

总结

阶段 1 已完成 AI 服务功能的核心实现，包括：

✅ Service 层完整实现（3 个服务）
✅ Repository 层完整实现（4 个仓库）
✅ API 路由层完整实现（4 个路由文件，22 个端点）
✅ Schema 定义完整
✅ 路由注册完成
✅ 符合 jointo-tech-stack 规范
✅ 应用层保证引用完整性

后续需要完成：

🔄 Celery 异步任务实现（阶段 2）
🔄 AI Provider 集成（阶段 3）
🔄 测试和优化（阶段 4）

当前实现已经为后续工作打下了坚实的基础，可以开始进行阶段 2 的 Celery 异步任务实现。

14 KiB Raw Blame History

AI 服务功能实施总结

概述

需求文档

实施状态

✅ 已完成（阶段 1）

1. Service 层实现

2. Repository 层实现

3. API 路由层实现

4. Schema 定义

5. 路由注册

🔄 待实施（阶段 2-4）

阶段 2: Celery 异步任务实现

阶段 3: AI Provider 集成

阶段 4: 测试和优化

核心功能特性

1. AI 对话系统

2. AI 提示词系统

3. AI 任务管理

4. AI 模型管理

技术规范

符合 jointo-tech-stack 规范

应用层引用完整性保证

依赖关系

Service 层依赖

Repository 层依赖

核心依赖

文件清单

新增文件

修改文件

已存在文件（无需修改）

后续工作计划

优先级 P0（必须完成）

优先级 P1（重要）

优先级 P2（可选）

验证清单

相关文档

需求文档

架构文档

实施文档

注意事项

测试建议

1. 对话会话测试

2. 发送消息（带 @ 提及）

3. 触发 AI 生成

总结

14 KiB

Raw Blame History