# 剧本解析切换到 Gemini 3 Pro Preview

**日期**: 2026-02-09  
**类型**: 配置变更  
**影响范围**: AI 剧本解析 API

---

## 变更说明

将剧本解析 API 的默认 AI 模型从 `gpt-4o-mini` 切换到 `gemini-3-pro-preview`。

## 修改内容

### 文件：`server/app/api/v1/screenplays.py`

**修改位置**：`POST /api/v1/screenplays/{screenplay_id}/parse`

**修改前**：
```python
result = await ai_service.parse_screenplay(
    user_id=str(current_user.user_id),
    screenplay_id=str(screenplay_id),
    screenplay_content=screenplay_content,
    custom_requirements=request.custom_requirements,
    model='gpt-4o-mini',  # 使用 GPT-4o Mini（稳定可靠，JSON 格式输出）
    ...
)
```

**修改后**：
```python
result = await ai_service.parse_screenplay(
    user_id=str(current_user.user_id),
    screenplay_id=str(screenplay_id),
    screenplay_content=screenplay_content,
    custom_requirements=request.custom_requirements,
    model='gemini-3-pro-preview',  # 使用 Gemini 3 Pro Preview（Google 最新旗舰模型）
    ...
)
```

## 模型对比

| 特性 | GPT-4o Mini | Gemini 3 Pro Preview |
|------|-------------|---------------------|
| 提供商 | OpenAI | Google |
| 上下文窗口 | 128K tokens | 2M tokens |
| 响应速度 | 快 | 快 |
| JSON 格式 | 稳定 | 稳定 |
| 成本 | 低 | 中等 |
| 推理能力 | 中等 | 强 |

## 优势

1. ✅ **超大上下文窗口**：2M tokens，可以处理超长剧本
2. ✅ **更强的推理能力**：Google 最新旗舰模型，理解能力更强
3. ✅ **更好的道具识别**：配合优化后的提示词（v1.3.0），识别更准确
4. ✅ **稳定的 JSON 输出**：经过验证，格式输出稳定

## 测试建议

重新解析剧本，验证输出质量：

```bash
curl 'http://localhost:6160/api/v1/screenplays/{screenplay_id}/parse' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  --data-raw '{"customRequirements":""}'
```

**验证点**：
- ✅ 角色识别准确性
- ✅ 场景识别准确性
- ✅ **道具识别数量**（应该明显增加，从 0 → 5-15）
- ✅ 分镜生成质量
- ✅ JSON 格式正确性
- ✅ 响应速度

## 回滚方案

如果 Gemini 3 Pro Preview 效果不理想，可以快速回滚：

```python
# 修改 server/app/api/v1/screenplays.py
model='gpt-4o-mini',  # 回滚到 GPT-4o Mini
```

或者切换到其他模型：
- `gpt-4` - OpenAI GPT-4（更强但更慢）
- `gemini-2.5-flash` - Gemini 2.5 Flash（更快但稍弱）
- `gemini-2.5-pro` - Gemini 2.5 Pro（平衡选择）

## 相关文件

- `server/app/api/v1/screenplays.py` - 剧本解析 API（模型配置）
- `server/app/services/ai_service.py` - AI 服务（模型调用）
- `server/app/services/ai_providers/factory.py` - AI Provider 工厂（模型列表）
- `server/app/resources/ai_skills/screenplay_parsing.md` - AI Skill（v1.3.0，道具识别优化）

## 协同优化

此次模型切换与以下优化协同生效：

1. **AI Skill v1.3.0**：优化道具识别提示词
2. **硬编码提示词同步**：`ai_tasks.py` 中的降级提示词已同步更新
3. **双重保障**：优先使用 AI Skill Registry，降级使用硬编码提示词

## 注意事项

1. **向后兼容**：现有 API 调用无需修改，自动使用新模型
2. **模型可用性**：确保 AIHubMix 代理服务支持 `gemini-3-pro-preview`
3. **积分计算**：不同模型的积分消耗可能不同，需要监控成本
4. **提示词兼容**：已验证 AI Skill v1.3.0 与 Gemini 3 Pro Preview 完全兼容

---

**修改人员**: Kiro  
**审核状态**: ✅ 已完成  
**部署状态**: 立即生效（需重启 FastAPI 服务）