NarratoAI/docs/prompt_management_system.md

提示词管理系统文档

概述

本项目实现了统一的提示词管理系统，用于集中管理三个核心功能的提示词：

• 纪录片解说 - 视频帧分析和解说文案生成
• 短剧混剪 - 字幕分析和爆点提取
• 短剧解说 - 剧情分析和解说脚本生成

系统架构

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格式验证
• 特定业务场景验证（解说文案、剧情分析等）
• 自定义验证规则

使用方法

基本用法

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": "字幕内容..."}
)

高级功能

# 搜索提示词
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 - 解说脚本生成提示词

迁移指南

旧代码迁移

之前的用法：

from app.services.SDE.prompt import subtitle_plot_analysis_v1
prompt = subtitle_plot_analysis_v1

新的用法：

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. 在相应分类目录下创建新的提示词类：

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 中注册：

def register_prompts():
    new_prompt = NewPrompt()
    PromptManager.register_prompt(new_prompt, is_default=True)

添加新分类

1. 创建新的分类目录
2. 实现提示词类
3. 在主模块的 __init__.py 中导入并注册

测试

运行测试脚本验证系统功能：

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. 引号修复: 自动修复单引号和缺失的属性名引号

解析策略

系统采用多重解析策略，按优先级依次尝试：

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),
]

使用示例

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 记录详细日志，可通过日志排查问题：

from loguru import logger
logger.debug("调试信息")