8.3 KiB

Raw Blame History

Changelog: AI Prompt System v2.0 - 剧本解析接口增强

日期: 2026-02-07
类型: 功能增强 (Feature Enhancement)
模块: AI 服务 / 剧本解析
影响范围: API、Service、Celery Task

📋 变更摘要

为 /api/v1/screenplays/{screenplay_id}/parse 接口新增 2 个用户可见参数，支持个性化剧本解析需求。

🎯 新增功能

1. 用户可见参数（置顶显示）

参数名	类型	必填	默认值	说明
`customRequirements`	string	否	-	用户个性化要求（如：增加特写镜头、强调情绪变化等），最大 500 字符
`storyboardCount`	integer	否	10	期望生成的分镜数量，范围：3-12

2. 高级选项参数（前端可选传递）

保留原有 6 个高级参数：

model: AI 模型名称
autoCreateElements: 是否自动创建元素
autoCreateTags: 是否自动创建标签
autoCreateStoryboards: 是否自动创建分镜
temperature: 温度参数
maxTokens: 最大 token 数

🔧 技术实现

1. Schema 层（`app/schemas/screenplay.py`）

class ScreenplayParseRequest(BaseModel):
    # 用户可见参数（置顶）
    custom_requirements: Optional[str] = Field(
        None,
        alias="customRequirements",
        description="用户个性化要求",
        max_length=500
    )
    
    storyboard_count: int = Field(
        10,
        alias="storyboardCount",
        description="期望生成的分镜数量（范围：3-12）",
        ge=3,
        le=12
    )
    
    # 高级选项（6 个原有参数保持不变）
    # ...

2. API 层（`app/api/v1/screenplays.py`）

✅ 新增日志记录：记录 custom_requirements 和 storyboard_count
✅ 参数传递：将新参数传递给 AIService.parse_screenplay()

3. Service 层（`app/services/ai_service.py`）

✅ 方法签名更新：parse_screenplay() 新增 2 个参数
✅ 日志记录：记录新参数
✅ 参数持久化：将新参数存入 task_params 和 input_data
✅ Celery 任务调用：传递新参数到 parse_screenplay_task.delay()

4. Celery 任务层（`app/tasks/ai_tasks.py`）

4.1 参数接收

def parse_screenplay_task(
    self,
    job_id: str,
    user_id: str,
    screenplay_id: str,
    screenplay_content: str,
    custom_requirements: Optional[str] = None,
    storyboard_count: int = 10,
    model: str = 'gpt-4',
    # ...
):

4.2 动态提示词构建

基础提示词 → 用户要求注入 → 分镜数量注入 → 完整提示词

# 1. 基础提示词（参考 docs/prompts/screenplay-ai-parse-prompt.md）
system_prompt = """
# 系统角色
你是一个专业的影视剧本分析专家...

# 任务说明
请分析以下剧本，提取所有角色、场景、道具信息...
"""

# 2. 动态注入用户个性化要求
if custom_requirements:
    system_prompt += f"""
## 用户特殊要求
{custom_requirements}

请在分析剧本时特别注意以上用户要求...
"""

# 3. 动态注入分镜数量要求
system_prompt += f"""
## 分镜生成要求
- **目标分镜数量**：{storyboard_count} 个
- **分镜分布**：根据剧情节奏和关键情节合理分配分镜数量
...
"""

📦 数据流

Frontend Request (JSON)
  ↓
API Layer (screenplays.py)
  ↓ 接收参数 + 权限校验
Service Layer (ai_service.py)
  ↓ 积分扣除 + 任务创建
Celery Task (ai_tasks.py)
  ↓ 动态构建提示词
AI Provider (OpenAI/Claude)
  ↓ 返回解析结果
Database Storage

🧪 测试建议

1. 单元测试

# tests/services/test_ai_service.py
async def test_parse_screenplay_with_custom_requirements():
    """测试带个性化要求的剧本解析"""
    result = await ai_service.parse_screenplay(
        user_id=user_id,
        screenplay_id=screenplay_id,
        screenplay_content="剧本内容...",
        custom_requirements="增加人物特写镜头",
        storyboard_count=8
    )
    assert result['status'] == 'pending'

2. 集成测试

# tests/api/test_screenplays.py
async def test_parse_screenplay_api_with_new_params():
    """测试新参数的 API 调用"""
    response = await client.post(
        f"/api/v1/screenplays/{screenplay_id}/parse",
        json={
            "customRequirements": "强调情绪变化",
            "storyboardCount": 12,
            "model": "gpt-4"
        }
    )
    assert response.status_code == 202

3. 参数验证测试

# tests/schemas/test_screenplay.py
def test_storyboard_count_validation():
    """测试分镜数量范围验证"""
    # 正常范围
    request = ScreenplayParseRequest(storyboard_count=10)
    assert request.storyboard_count == 10
    
    # 低于最小值
    with pytest.raises(ValidationError):
        ScreenplayParseRequest(storyboard_count=2)
    
    # 高于最大值
    with pytest.raises(ValidationError):
        ScreenplayParseRequest(storyboard_count=13)

📝 前端集成示例

Request Body

{
  "customRequirements": "增加人物特写镜头，注重情感表达",
  "storyboardCount": 10,
  "model": "gpt-4",
  "autoCreateElements": true,
  "autoCreateTags": true,
  "autoCreateStoryboards": true,
  "temperature": 0.7,
  "maxTokens": 4000
}

Response

{
  "code": 200,
  "message": "剧本解析任务已提交，请使用 jobId 查询任务状态",
  "data": {
    "jobId": "uuid-v7-job-id",
    "taskId": "celery-task-id",
    "status": "pending",
    "estimatedCredits": 50
  }
}

🎨 UI 建议

前端表单设计

┌─────────────────────────────────────┐
│ 剧本解析设置                         │
├─────────────────────────────────────┤
│ 📝 个性化要求（选填）                │
│ ┌─────────────────────────────────┐ │
│ │ 例如：增加特写镜头、强调情绪变化 │ │
│ └─────────────────────────────────┘ │
│                                     │
│ 🎬 分镜数量（3-12）                  │
│ ┌─────────────────────────────────┐ │
│ │ [滑块] 10                        │ │
│ └─────────────────────────────────┘ │
│                                     │
│ [高级选项 ▼]                         │
│                                     │
│ [开始解析]                           │
└─────────────────────────────────────┘

🚀 部署检查清单

Schema 更新
API 路由更新
Service 层更新
Celery 任务更新
动态提示词构建
代码 Lint 检查通过
单元测试编写
集成测试编写
前端联调测试
生产环境验证

📚 相关文档

⚠️ 注意事项

参数优先级：用户个性化要求会附加到基础提示词之后，不会覆盖核心指令
分镜数量控制：AI 会尝试生成目标数量的分镜，但可能根据剧本长度自动调整
积分消耗：新参数不影响积分计算规则（仍按剧本字符数计算）
向后兼容：所有新参数均为可选，旧版前端调用不受影响

🔄 后续优化方向

AI Skill Registry 集成：将提示词模板迁移到 ai_skills_registry 表
多阶段解析：支持长剧本的分批次解析（参考 Two-Stage Parsing Strategy）
提示词版本管理：支持提示词的 A/B 测试和版本回滚
预设模板：提供"动作片"、"文艺片"等预设个性化要求模板

变更人员: AI Agent (Claude Sonnet 4.5)
审核状态: Pending
版本: v1.0.0

8.3 KiB Raw Blame History