# 剧本解析切换回 GPT-4o Mini 模型

**日期**: 2026-02-09  
**类型**: 配置调整  
**影响范围**: 剧本解析 AI 任务

## 背景

在尝试使用 Gemini 2.5 Flash 进行剧本解析时，发现 Gemini 模型返回的是自然语言解释而非 JSON 格式数据，导致解析失败。

### 问题表现

```
AI 返回内容：
好的，我将根据您提供的剧本内容，将其拆解为结构化的 JSON 格式场景和镜头信息。
由于剧本中没有明确的镜头细节（如景别、运镜、时长），我将根据剧本描述和电影叙事惯例进行合理推断和补充...
```

错误信息：
```
JSONDecodeError: Expecting value: line 1 column 1 (char 0)
```

### 根本原因

1. Gemini 模型不支持 OpenAI 的 `response_format={'type': 'json_object'}` 参数
2. Gemini 倾向于返回自然语言解释，即使在 System Prompt 中要求 JSON 格式
3. 需要针对 Gemini 模型进行专门的 Prompt 优化和响应处理

## 解决方案

**临时方案**：切换回 GPT-4o Mini 模型

- GPT-4o Mini 支持 `response_format` 参数，能够强制返回 JSON 格式
- 稳定可靠，已经过充分测试
- 性价比高，适合剧本解析任务

**长期方案**（待实施）：

1. 优化 AIHubMix Provider，针对 Gemini 模型：
   - 在 System Prompt 中添加更强的 JSON 格式约束
   - 实现响应后处理，提取 JSON 内容
   - 添加重试机制

2. 优化 AI Skill Prompt：
   - 在 Prompt 开头和结尾都强调"只返回 JSON，不要任何解释"
   - 提供 JSON 示例
   - 使用更明确的格式要求

## 修改内容

### 1. 修改剧本解析 API 默认模型

**文件**: `server/app/api/v1/screenplays.py`

```python
# 修改前
model='gemini-2.5-flash',  # 使用 Gemini 2.5 Flash（性价比最高，支持结构化输出）

# 修改后
model='gpt-4o-mini',  # 使用 GPT-4o Mini（稳定可靠，JSON 格式输出）
```

### 2. 重启服务

```bash
docker restart jointo-server-app
```

## 测试验证

### 测试步骤

1. 上传剧本文件
2. 触发剧本解析
3. 验证 AI 返回 JSON 格式数据
4. 验证元素和分镜正确创建

### 预期结果

- ✅ AI 返回标准 JSON 格式
- ✅ 角色、场景、道具正确提取
- ✅ 分镜正确生成
- ✅ `scene_count` 和 `character_count` 正确更新

## 后续计划

1. **短期**（1-2 周）：
   - 监控 GPT-4o Mini 的解析质量和成本
   - 收集用户反馈

2. **中期**（1 个月）：
   - 实现 Gemini 模型的专门优化
   - 添加模型选择功能（让用户选择使用哪个模型）

3. **长期**（2-3 个月）：
   - 实现多模型对比测试
   - 根据任务类型自动选择最优模型
   - 实现模型降级和重试机制

## 相关文档

- [剧本解析 AI 格式兼容性修复](./2026-02-09-screenplay-ai-parse-format-compatibility-fix.md)
- [切换到 Gemini 2.5 Flash](./2026-02-09-switch-to-gemini-2.5-flash-for-screenplay-parsing.md)
- [AI Skill Prompt 格式强化](./2026-02-09-ai-skill-prompt-format-enforcement.md)

## 技术债务

- [ ] 实现 Gemini 模型的 JSON 格式优化
- [ ] 添加模型选择 UI
- [ ] 实现多模型对比测试框架
- [ ] 优化 AI Skill Prompt 以支持更多模型