docs/v1.0/server/changelogs/2026-02-03-ai-api-routes-implementation.md

AI API 路由层实现

日期: 2026-02-03
类型: 功能实现
影响范围: 后端 API 层

概述

完成 AI 服务功能的 API 路由层实现，包括 AI 对话、提示词管理、模型查询和任务管理 4 个模块的完整 REST API。

实施内容

1. AI 对话 API (ai_conversations.py)

路由前缀: /api/v1/ai/conversations

核心功能:

• ✅ 对话会话管理（创建/查询/更新/删除）
• ✅ 消息管理（发送/查询）
• ✅ @ 提及功能（获取可提及资源）
• ✅ AI 生成触发（从对话触发生成任务）

关键特性:

• 支持多态关联（分镜/角色/场景/道具/资源/音效/配音）
• 支持标签系统（区分变体）
• 支持多维度筛选（项目/目标类型/目标对象/标签/媒体类型/状态）
• 自动解析消息中的 @ 提及标记
• 自动提取参考图并传递给 AI Service

API 端点:

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 生成

2. AI 提示词管理 API (ai_prompts.py)

路由前缀: /api/v1/admin/ai-prompts

核心功能:

• ✅ 提示词 CRUD（创建/查询/更新/删除）
• ✅ 默认提示词管理
• ✅ 提示词版本管理
• ✅ Skills 配置管理

权限控制:

• 管理接口：仅管理员可访问
• 公开接口：GET /default/{prompt_type} 供内部服务调用

API 端点:

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}    # 获取默认提示词（公开）

3. AI 模型查询 API (ai_models.py)

路由前缀: /api/v1/ai/models

核心功能:

• ✅ 获取可用的 AI 模型列表
• ✅ 按模型类型筛选（文本/图片/视频/音频）
• ✅ 返回模型定价信息

返回信息:

• 模型名称和显示名称
• 提供商信息
• 定价信息（成本/积分）
• 模型配置
• 是否为测试版

API 端点:

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

4. AI 任务管理 API (ai_jobs.py)

路由前缀: /api/v1/ai/jobs

核心功能:

• ✅ 任务状态查询
• ✅ 任务取消（退还积分）
• ✅ 批量查询用户任务
• ✅ 任务统计信息
• ✅ 使用统计

关键特性:

• 支持多维度筛选（任务类型/状态/时间范围）
• 支持自定义排序
• 提供详细的统计数据（总成本/总积分/成功率等）

API 端点:

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     # 获取使用统计

技术规范

符合 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 类型

Schema 定义

创建了 server/app/schemas/ai_conversation.py，包含：

• ConversationCreateRequest: 创建对话会话请求
• ConversationUpdateRequest: 更新对话会话请求
• MessageCreateRequest: 发送消息请求
• GenerateRequest: 触发 AI 生成请求

路由注册

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

from app.api.v1 import (
    # ... 其他路由
    ai_conversations,
    ai_prompts,
    ai_models,
    ai_jobs,
)

api_router.include_router(ai_conversations.router)
api_router.include_router(ai_prompts.router)
api_router.include_router(ai_models.router)
api_router.include_router(ai_jobs.router)

依赖关系

Service 层依赖

• AIConversationService: 对话会话和消息管理
• AIPromptSystemService: 提示词管理
• AIService: AI 生成、模型查询、任务管理

Repository 层依赖

• AIConversationRepository: 对话数据访问
• AIPromptSystemRepository: 提示词数据访问
• AIRepository: AI 任务数据访问

核心依赖

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

后续工作

阶段 2: Celery 异步任务实现

• 创建 app/tasks/ai_tasks.py
• 实现异步生成任务
• 实现任务状态回调
• 实现任务失败重试

阶段 3: AI Provider 集成

• 集成 ai_providers 目录中的 AI 服务
• 实现统一的 Provider 接口
• 实现 Provider 路由和负载均衡
• 实现 Provider 错误处理和降级

阶段 4: 测试和优化

• 编写单元测试
• 编写集成测试
• 性能优化
• 文档完善

测试建议

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": "测试对话"
  }'

# 发送消息（带 @ 提及）
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"
  }'

2. 提示词管理测试

# 创建提示词（管理员）
curl -X POST http://localhost:8000/api/v1/admin/ai-prompts \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "角色生成提示词",
    "prompt_type": 1,
    "prompt_content": "生成一个角色形象...",
    "skills_data": {},
    "version": "1.0.0"
  }'

# 获取默认提示词
curl http://localhost:8000/api/v1/admin/ai-prompts/default/1

3. 模型查询测试

# 获取所有可用模型
curl http://localhost:8000/api/v1/ai/models \
  -H "Authorization: Bearer <token>"

# 按类型筛选
curl "http://localhost:8000/api/v1/ai/models?model_type=2" \
  -H "Authorization: Bearer <token>"

4. 任务管理测试

# 查询任务状态
curl http://localhost:8000/api/v1/ai/jobs/{job_id} \
  -H "Authorization: Bearer <token>"

# 取消任务
curl -X POST http://localhost:8000/api/v1/ai/jobs/{job_id}/cancel \
  -H "Authorization: Bearer <token>"

# 获取使用统计
curl http://localhost:8000/api/v1/ai/jobs/usage/stats \
  -H "Authorization: Bearer <token>"

相关文档

• 需求文档: docs/requirements/backend/04-services/ai/
• 架构文档: docs/architecture/changelogs/2026-02-03-ai-conversation-system-implementation.md
• Service 实现: server/app/services/ai_*.py
• Repository 实现: server/app/repositories/ai_*.py

影响范围

新增文件

• server/app/api/v1/ai_conversations.py
• server/app/api/v1/ai_prompts.py
• server/app/api/v1/ai_models.py
• server/app/api/v1/ai_jobs.py
• server/app/schemas/ai_conversation.py

修改文件

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

无影响

• 现有 API 路由
• 数据库结构
• 前端代码

注意事项

1. 权限控制: AI 提示词管理接口需要管理员权限
2. 积分扣除: 触发 AI 生成时会扣除用户积分，需确保积分充足
3. 任务取消: 只能取消 pending 或 processing 状态的任务
4. @ 提及: 消息中的 @ 提及会自动解析和验证
5. 参考图: 参考图会自动从消息 metadata 中提取并传递给 AI Service

验证清单

• 所有路由函数使用 async/await
• 所有路由使用统一响应格式
• 所有路由有完整的错误处理
• 所有路由有日志记录
• 所有路由有类型提示
• 所有路由已注册到主路由器
• 代码通过 getDiagnostics 检查
• 符合 jointo-tech-stack 规范