mirror of
https://github.com/linyqh/NarratoAI.git
synced 2025-12-10 18:02:51 +00:00
8ad81d27b6
在多个文件中修正了JSON格式输出，确保使用标准格式 `{` 和 `}`，并移除双大括号 `{{` 和 `}}`。这些更改提升了系统对LLM生成内容的解析能力，确保输出的JSON格式有效且符合要求，增强了整体用户体验。
268 lines
7.3 KiB
Markdown
268 lines
7.3 KiB
Markdown
# 提示词管理系统文档
|
||
|
||
## 概述
|
||
|
||
本项目实现了统一的提示词管理系统，用于集中管理三个核心功能的提示词：
|
||
- **纪录片解说** - 视频帧分析和解说文案生成
|
||
- **短剧混剪** - 字幕分析和爆点提取
|
||
- **短剧解说** - 剧情分析和解说脚本生成
|
||
|
||
## 系统架构
|
||
|
||
```
|
||
app/services/prompts/
|
||
├── __init__.py # 模块初始化
|
||
├── base.py # 基础提示词类
|
||
├── manager.py # 提示词管理器
|
||
├── registry.py # 提示词注册机制
|
||
├── template.py # 模板渲染引擎
|
||
├── validators.py # 输出验证器
|
||
├── exceptions.py # 异常定义
|
||
├── documentary/ # 纪录片解说提示词
|
||
│ ├── __init__.py
|
||
│ ├── frame_analysis.py # 视频帧分析
|
||
│ └── narration_generation.py # 解说文案生成
|
||
├── short_drama_editing/ # 短剧混剪提示词
|
||
│ ├── __init__.py
|
||
│ ├── subtitle_analysis.py # 字幕分析
|
||
│ └── plot_extraction.py # 爆点提取
|
||
└── short_drama_narration/ # 短剧解说提示词
|
||
├── __init__.py
|
||
├── plot_analysis.py # 剧情分析
|
||
└── script_generation.py # 解说脚本生成
|
||
```
|
||
|
||
## 核心特性
|
||
|
||
### 1. 统一管理
|
||
- 所有提示词集中在 `app/services/prompts/` 模块中
|
||
- 按功能模块分类组织
|
||
- 支持版本控制和回滚
|
||
|
||
### 2. 模型类型适配
|
||
- **TextPrompt**: 文本模型专用
|
||
- **VisionPrompt**: 视觉模型专用
|
||
- **ParameterizedPrompt**: 支持参数化
|
||
|
||
### 3. 参数化支持
|
||
- 动态参数替换
|
||
- 参数验证
|
||
- 模板渲染
|
||
|
||
### 4. 输出验证
|
||
- 严格的JSON格式验证
|
||
- 特定业务场景验证（解说文案、剧情分析等）
|
||
- 自定义验证规则
|
||
|
||
## 使用方法
|
||
|
||
### 基本用法
|
||
|
||
```python
|
||
from app.services.prompts import PromptManager
|
||
|
||
# 获取纪录片解说的视频帧分析提示词
|
||
prompt = PromptManager.get_prompt(
|
||
category="documentary",
|
||
name="frame_analysis",
|
||
parameters={
|
||
"video_theme": "荒野建造",
|
||
"custom_instructions": "请特别关注建造过程的细节"
|
||
}
|
||
)
|
||
|
||
# 获取短剧解说的剧情分析提示词
|
||
prompt = PromptManager.get_prompt(
|
||
category="short_drama_narration",
|
||
name="plot_analysis",
|
||
parameters={"subtitle_content": "字幕内容..."}
|
||
)
|
||
```
|
||
|
||
### 高级功能
|
||
|
||
```python
|
||
# 搜索提示词
|
||
results = PromptManager.search_prompts(
|
||
keyword="分析",
|
||
model_type=ModelType.TEXT
|
||
)
|
||
|
||
# 获取提示词详细信息
|
||
info = PromptManager.get_prompt_info(
|
||
category="documentary",
|
||
name="narration_generation"
|
||
)
|
||
|
||
# 验证输出
|
||
validated_data = PromptManager.validate_output(
|
||
output=llm_response,
|
||
category="documentary",
|
||
name="narration_generation"
|
||
)
|
||
```
|
||
|
||
## 已注册的提示词
|
||
|
||
### 纪录片解说 (documentary)
|
||
- `frame_analysis` - 视频帧分析提示词
|
||
- `narration_generation` - 解说文案生成提示词
|
||
|
||
### 短剧混剪 (short_drama_editing)
|
||
- `subtitle_analysis` - 字幕分析提示词
|
||
- `plot_extraction` - 爆点提取提示词
|
||
|
||
### 短剧解说 (short_drama_narration)
|
||
- `plot_analysis` - 剧情分析提示词
|
||
- `script_generation` - 解说脚本生成提示词
|
||
|
||
## 迁移指南
|
||
|
||
### 旧代码迁移
|
||
|
||
**之前的用法：**
|
||
```python
|
||
from app.services.SDE.prompt import subtitle_plot_analysis_v1
|
||
prompt = subtitle_plot_analysis_v1
|
||
```
|
||
|
||
**新的用法：**
|
||
```python
|
||
from app.services.prompts import PromptManager
|
||
prompt = PromptManager.get_prompt(
|
||
category="short_drama_narration",
|
||
name="plot_analysis",
|
||
parameters={"subtitle_content": content}
|
||
)
|
||
```
|
||
|
||
### 已更新的文件
|
||
- `app/services/SDE/short_drama_explanation.py`
|
||
- `app/services/SDP/utils/step1_subtitle_analyzer_openai.py`
|
||
- `app/services/generate_narration_script.py`
|
||
|
||
## 扩展指南
|
||
|
||
### 添加新提示词
|
||
|
||
1. 在相应分类目录下创建新的提示词类：
|
||
|
||
```python
|
||
from ..base import TextPrompt, PromptMetadata, ModelType, OutputFormat
|
||
|
||
class NewPrompt(TextPrompt):
|
||
def __init__(self):
|
||
metadata = PromptMetadata(
|
||
name="new_prompt",
|
||
category="your_category",
|
||
version="v1.0",
|
||
description="提示词描述",
|
||
model_type=ModelType.TEXT,
|
||
output_format=OutputFormat.JSON,
|
||
parameters=["param1", "param2"]
|
||
)
|
||
super().__init__(metadata)
|
||
|
||
def get_template(self) -> str:
|
||
return "您的提示词模板内容..."
|
||
```
|
||
|
||
2. 在 `__init__.py` 中注册：
|
||
|
||
```python
|
||
def register_prompts():
|
||
new_prompt = NewPrompt()
|
||
PromptManager.register_prompt(new_prompt, is_default=True)
|
||
```
|
||
|
||
### 添加新分类
|
||
|
||
1. 创建新的分类目录
|
||
2. 实现提示词类
|
||
3. 在主模块的 `__init__.py` 中导入并注册
|
||
|
||
## 测试
|
||
|
||
运行测试脚本验证系统功能：
|
||
|
||
```bash
|
||
python test_prompt_system.py
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **模板参数**: 使用 `${parameter_name}` 格式
|
||
2. **JSON格式**: 模板中的JSON示例使用标准格式 `{` 和 `}`，不要使用双大括号
|
||
3. **参数验证**: 必需参数会自动验证
|
||
4. **版本管理**: 支持多版本共存，默认使用最新版本
|
||
5. **输出验证**: 建议对LLM输出进行验证以确保格式正确
|
||
6. **JSON解析**: 系统提供强大的JSON解析兼容性，自动处理各种格式问题
|
||
|
||
## JSON解析优化
|
||
|
||
系统提供了强大的JSON解析兼容性，能够处理LLM生成的各种格式问题：
|
||
|
||
### 支持的格式修复
|
||
|
||
1. **双大括号修复**: 自动将 `{{` 和 `}}` 转换为标准的 `{` 和 `}`
|
||
2. **代码块提取**: 自动从 ````json` 代码块中提取JSON内容
|
||
3. **额外文本处理**: 自动提取大括号包围的JSON内容，忽略前后的额外文本
|
||
4. **尾随逗号修复**: 自动移除对象和数组末尾的多余逗号
|
||
5. **注释移除**: 自动移除 `//` 和 `#` 注释
|
||
6. **引号修复**: 自动修复单引号和缺失的属性名引号
|
||
|
||
### 解析策略
|
||
|
||
系统采用多重解析策略，按优先级依次尝试：
|
||
|
||
```python
|
||
strategies = [
|
||
("直接解析", lambda s: json.loads(s)),
|
||
("修复双大括号", _fix_double_braces),
|
||
("提取代码块", _extract_code_block),
|
||
("提取大括号内容", _extract_braces_content),
|
||
("修复常见格式问题", _fix_common_json_issues),
|
||
("修复引号问题", _fix_quote_issues),
|
||
("修复尾随逗号", _fix_trailing_commas),
|
||
("强制修复", _force_fix_json),
|
||
]
|
||
```
|
||
|
||
### 使用示例
|
||
|
||
```python
|
||
from webui.tools.generate_short_summary import parse_and_fix_json
|
||
|
||
# 处理双大括号JSON
|
||
json_str = '{{ "items": [{{ "_id": 1, "name": "test" }}] }}'
|
||
result = parse_and_fix_json(json_str) # 自动修复并解析
|
||
|
||
# 处理有额外文本的JSON
|
||
json_str = '这是一些文本\n{"items": []}\n更多文本'
|
||
result = parse_and_fix_json(json_str) # 自动提取JSON部分
|
||
```
|
||
|
||
## 性能优化
|
||
|
||
- 提示词模板会被缓存
|
||
- 支持批量操作
|
||
- 异步渲染支持（未来版本）
|
||
- JSON解析采用多策略优化，确保高成功率
|
||
|
||
## 故障排除
|
||
|
||
### 常见问题
|
||
|
||
1. **模板渲染错误**: 检查参数名称和格式
|
||
2. **提示词未找到**: 确认分类、名称和版本正确
|
||
3. **输出验证失败**: 检查LLM输出格式是否符合要求
|
||
|
||
### 日志调试
|
||
|
||
系统使用 loguru 记录详细日志，可通过日志排查问题：
|
||
|
||
```python
|
||
from loguru import logger
|
||
logger.debug("调试信息")
|
||
```
|