NarratoAI/docs/short_drama_narration_optimization.md

短剧解说功能优化说明

概述

本次优化解决了短剧解说功能中原始字幕信息缺失的问题，确保生成的解说文案与视频时间戳正确匹配。

问题分析

原始问题

1. 参数化调用错误：SubtitleAnalyzer 在获取 PlotAnalysisPrompt 时传入空参数字典，导致模板中的占位符无法被正确替换
2. 数据传递链断裂：解说脚本生成阶段无法直接访问原始字幕的时间戳信息
3. 时间戳信息丢失：生成的解说文案与视频画面时间戳不匹配

根本原因

• 提示词模板期望参数化方式接收字幕内容，但实际使用了简单的字符串拼接
• 解说脚本生成时只能访问剧情分析结果，无法获取原始字幕的准确时间戳

解决方案

1. 修复参数化调用问题

修改文件: app/services/SDE/short_drama_explanation.py

修改内容:

# 修改前
self.prompt_template = PromptManager.get_prompt(
    category="short_drama_narration",
    name="plot_analysis",
    parameters={}  # 空参数字典
)
prompt = f"{self.prompt_template}\n\n{subtitle_content}"  # 字符串拼接

# 修改后
if self.custom_prompt:
    prompt = f"{self.custom_prompt}\n\n{subtitle_content}"
else:
    prompt = PromptManager.get_prompt(
        category="short_drama_narration",
        name="plot_analysis",
        parameters={"subtitle_content": subtitle_content}  # 正确传入参数
    )

2. 增强解说脚本生成的数据访问

修改文件: app/services/prompts/short_drama_narration/script_generation.py

修改内容:

# 添加 subtitle_content 参数支持
parameters=["drama_name", "plot_analysis", "subtitle_content"]

# 优化提示词模板，添加原始字幕信息
template = """
下面<plot>中的内容是短剧的剧情概述：
<plot>
${plot_analysis}
</plot>

下面<subtitles>中的内容是短剧的原始字幕（包含准确的时间戳信息）：
<subtitles>
${subtitle_content}
</subtitles>

重要要求：
6. **时间戳必须严格基于<subtitles>中的原始时间戳**，确保与视频画面精确匹配
11. **确保每个解说片段的时间戳都能在原始字幕中找到对应的时间范围**
"""

3. 更新方法签名和调用

修改内容:

# 方法签名更新
def generate_narration_script(
    self, 
    short_name: str, 
    plot_analysis: str, 
    subtitle_content: str = "",  # 新增参数
    temperature: float = 0.7
) -> Dict[str, Any]:

# 调用时传入原始字幕内容
prompt = PromptManager.get_prompt(
    category="short_drama_narration",
    name="script_generation",
    parameters={
        "drama_name": short_name,
        "plot_analysis": plot_analysis,
        "subtitle_content": subtitle_content  # 传入原始字幕
    }
)

使用方法

基本用法

from app.services.SDE.short_drama_explanation import analyze_subtitle, generate_narration_script

# 1. 分析字幕
analysis_result = analyze_subtitle(
    subtitle_file_path="path/to/subtitle.srt",
    api_key="your_api_key",
    model="your_model",
    base_url="your_base_url"
)

# 2. 读取原始字幕内容
with open("path/to/subtitle.srt", 'r', encoding='utf-8') as f:
    subtitle_content = f.read()

# 3. 生成解说脚本（现在包含原始字幕信息）
narration_result = generate_narration_script(
    short_name="短剧名称",
    plot_analysis=analysis_result["analysis"],
    subtitle_content=subtitle_content,  # 传入原始字幕内容
    api_key="your_api_key",
    model="your_model",
    base_url="your_base_url"
)

完整示例

# 完整的短剧解说生成流程
subtitle_path = "path/to/your/subtitle.srt"

# 步骤1：分析字幕
analysis_result = analyze_subtitle(
    subtitle_file_path=subtitle_path,
    api_key="your_api_key",
    model="gemini-2.0-flash",
    base_url="https://api.narratoai.cn/v1/chat/completions",
    save_result=True
)

if analysis_result["status"] == "success":
    # 步骤2：读取原始字幕内容
    with open(subtitle_path, 'r', encoding='utf-8') as f:
        subtitle_content = f.read()
    
    # 步骤3：生成解说脚本
    narration_result = generate_narration_script(
        short_name="我的短剧",
        plot_analysis=analysis_result["analysis"],
        subtitle_content=subtitle_content,  # 关键：传入原始字幕
        api_key="your_api_key",
        model="gemini-2.0-flash",
        base_url="https://api.narratoai.cn/v1/chat/completions",
        save_result=True
    )
    
    if narration_result["status"] == "success":
        print("解说脚本生成成功！")
        print(narration_result["narration_script"])

优化效果

修改前

• ❌ 字幕内容无法正确嵌入提示词
• ❌ 解说脚本生成时缺少原始时间戳信息
• ❌ 生成的时间戳可能不准确或缺失

修改后

• ✅ 字幕内容正确嵌入到剧情分析提示词中
• ✅ 解说脚本生成时可访问完整的原始字幕信息
• ✅ 生成的解说文案时间戳与视频画面精确匹配
• ✅ 保持时间连续性和逻辑顺序
• ✅ 支持时间片段的合理拆分

测试验证

运行测试脚本验证修改效果：

python3 test_short_drama_narration.py

测试覆盖：

1. ✅ 剧情分析提示词参数化功能
2. ✅ 解说脚本生成提示词参数化功能
3. ✅ SubtitleAnalyzer集成功能

注意事项

1. 向后兼容性：修改保持了原有API的向后兼容性
2. 参数传递：确保在调用 generate_narration_script 时传入 subtitle_content 参数
3. 时间戳准确性：生成的解说文案时间戳现在严格基于原始字幕
4. 模块化设计：保持了提示词管理系统的模块化架构

相关文件

• app/services/SDE/short_drama_explanation.py - 主要功能实现
• app/services/prompts/short_drama_narration/plot_analysis.py - 剧情分析提示词
• app/services/prompts/short_drama_narration/script_generation.py - 解说脚本生成提示词
• test_short_drama_narration.py - 测试脚本