liaoweiran
/
AI-video-lifeplan-demo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
AI-video-lifeplan-demo/.qoder/repowiki/zh/content/架构设计/AI生成.md

14 KiB
Raw Permalink Blame History

AI生成

**本文引用的文件** - [main.py](file://main.py) - [PROJECT_README.md](file://PROJECT_README.md) - [requirements.txt](file://requirements.txt) - [backend/scripter.py](file://backend/scripter.py) - [backend/extractor.py](file://backend/extractor.py) - [backend/data_builder.py](file://backend/data_builder.py) - [backend/media_fetcher.py](file://backend/media_fetcher.py) - [backend/video_processor/schemas.py](file://backend/video_processor/schemas.py) - [backend/video_processor/utils.py](file://backend/video_processor/utils.py) - [tests/test_video_cli.py](file://tests/test_video_cli.py) - [tests/test_video_processor.py](file://tests/test_video_processor.py)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考量
  8. 故障排查指南
  9. 结论
  10. 附录

简介

本项目是一个“自动人生规划视频生成器”，通过将PDF版人生规划报告与采访视频，结合AI生成的自然日语旁白、图表动画与B-Roll素材，最终合成3-5分钟的个性化解释性视频。其中，scripter.py模块负责使用Google Gemini Pro API将结构化的财务数据转化为自然流畅的日语旁白脚本。本文围绕该模块展开，详细说明提示词工程设计（如何整合客户数据、财务预测与视频节奏要求）、在主流程中的位置与输入输出格式、以及面向初学者的流程图与面向高级开发者的实现细节与优化建议。

项目结构

  • 后端Python模块位于 backend/，包含：
    • scripter.py：脚本生成器（当前为占位实现）
    • extractor.py：PDF与视频抽取器（当前为占位实现）
    • data_builder.py：财务模拟与图表数据构建
    • media_fetcher.py：B-Roll素材抓取（当前为占位实现）
    • video_processor/：视频处理工具与数据结构（供未来集成）
  • 前端Remotion渲染引擎位于 frontend/，通过 render_props.json 与后端对接
  • main.py 作为入口，编排整个流水线
graph TB
A["main.py<br/>入口与流水线编排"] --> B["backend/scripter.py<br/>脚本生成器"]
A --> C["backend/extractor.py<br/>PDF/视频抽取器"]
A --> D["backend/data_builder.py<br/>财务模拟与图表数据"]
A --> E["backend/media_fetcher.py<br/>B-Roll素材抓取"]
A --> F["frontend/<br/>Remotion渲染引擎"]
G["backend/video_processor/schemas.py<br/>视频处理数据结构"] -. 可选集成 .-> A
H["backend/video_processor/utils.py<br/>FFmpeg工具集"] -. 可选集成 .-> A

图表来源

章节来源

核心组件

  • 脚本生成器（ScriptGenerator）：封装Gemini Pro调用、提示词构建、响应解析与时长估计
  • PDF/视频抽取器（PDFExtractor/VideoExtractor）：从PDF与视频中提取结构化数据与时间戳
  • 财务模拟器（FinancialSimulator）：基于参数模拟资产枯竭与现金流，生成图表所需数据
  • B-Roll素材抓取器（MediaFetcher）：根据关键词检索并下载B-Roll素材
  • 视频处理工具（VideoProcessor）：提供视频分析与切片等能力（可选）

章节来源

架构总览

脚本生成在整体流水线中的位置如下：

sequenceDiagram
participant U as "用户"
participant M as "main.py<br/>VideoGeneratorPipeline"
participant X as "extractor.py<br/>PDF/视频抽取"
participant S as "scripter.py<br/>ScriptGenerator"
participant D as "data_builder.py<br/>财务模拟"
participant R as "Remotion<br/>前端渲染"
U->>M : 运行命令行
M->>X : 提取PDF/视频数据
X-->>M : 返回结构化数据
M->>S : 生成旁白脚本
S-->>M : 返回脚本片段与同步点
M->>D : 构建图表数据
D-->>M : 返回资产/现金流数据
M->>R : 写入render_props.json并触发渲染
R-->>U : 输出MP4视频

图表来源

章节来源

详细组件分析

ScriptGenerator（脚本生成器）

  • 职责
    • 初始化：从环境变量读取API密钥，校验可用性
    • generate：接收PDF数据与可选视频数据，返回包含分段、总时长与同步点的结构化脚本
    • _build_prompt：构建提示词（当前为占位），应整合客户信息、财务预测、风格约束与输出格式要求
  • 输入输出
    • 输入：pdf_data（结构化财务数据）、video_data（可选，含转录与时间戳）、style（友好/专业/随意）
    • 输出：包含segments（脚本文本、时长、类型）、total_duration、sync_points
  • 设计要点
    • 风格控制：通过style参数与提示词工程控制语气与专业度
    • 结构化输出：要求模型以JSON格式返回segments，便于后续解析与时长估算
    • 多模态融合：将视频转录的时间戳与脚本同步点对齐，提升节奏一致性
classDiagram
class ScriptGenerator {
+api_key : str
+__init__(api_key)
+generate(pdf_data, video_data, style) Dict
-_build_prompt(pdf_data, style) str
}

图表来源

章节来源

提示词工程设计（Prompt Engineering）

  • 数据整合
    • 客户数据：姓名、年龄、退休年龄、寿命预期、资产、收入、支出等
    • 财务预测：来自data_builder.py的资产枯竭与现金流数据，用于生成“现状”“趋势”“风险预警”等段落
    • 视频节奏：来自extractor.py的视频转录与时间戳，用于生成“配合画面”的过渡与强调段落
  • 风格与语气
    • friendly：自然、温和、易懂
    • professional：严谨、准确、适合正式场合
    • casual：轻松、口语化、贴近日常
  • 输出约束
    • JSON格式，包含segments数组，每段含id、text、duration、type
    • 总时长控制在3-5分钟范围内
  • 同步点
    • 在脚本中标注chart/intro/transition等类型，便于后续与图表动画与B-Roll素材对齐

提示词模板设计要点（概念性说明，不对应具体代码）：

  • 角色设定：你是专业的财务顾问，用日语向客户讲解其人生规划
  • 上下文：提供客户画像与财务预测摘要
  • 任务：生成一段自然流畅的旁白，包含引言、现状分析、趋势解读、风险提示与建议
  • 风格：根据style参数调整语气
  • 输出：严格遵循JSON结构，包含分段文本与时长

章节来源

main.py 中的 generate_script 方法

  • 位置：VideoGeneratorPipeline.generate_script
  • 功能：调用后端脚本生成模块，返回结构化脚本
  • 当前实现：占位返回mock脚本，包含segments列表
  • 实际实现建议：调用ScriptGenerator.generate，传入pdf_data与video_data，解析返回的JSON并估算每段时长
flowchart TD
Start(["进入 generate_script"]) --> CheckArgs["检查输入参数<br/>pdf_data, video_data"]
CheckArgs --> CallGen["调用 ScriptGenerator.generate(...)"]
CallGen --> ParseResp["解析返回的JSON结构<br/>segments, total_duration, sync_points"]
ParseResp --> EstimateDur["估算每段时长<br/>按目标时长比例分配"]
EstimateDur --> ReturnScript["返回结构化脚本"]

图表来源

章节来源

财务数据与脚本的衔接

  • data_builder.py 模块根据pdf_data生成资产枯竭与现金流数据，供前端图表使用
  • scripter.py 应在提示词中引用这些数据摘要，使脚本内容与图表一致
  • 通过style参数与提示词工程，确保脚本语气与数据呈现相匹配

章节来源

B-Roll素材与脚本的协同

  • media_fetcher.py 的fetch_broll函数可根据脚本关键词检索B-Roll素材
  • 关键词提取：从segments.text中抽取主题词，如“資産”“将来”“リスク”等
  • 同步：将脚本的sync_points与B-Roll片段起止时间对齐，提升观看体验

章节来源

视频处理（可选集成）

  • schemas.py 定义了VideoSegment、KeyMoment、VideoAnalysisResult等数据结构
  • utils.py 提供FFmpeg封装，支持时长查询、音频提取、视频切片
  • 可选策略：audio-first或direct，用于抽取视频转录与时间戳，辅助scripter生成更贴合画面的脚本

章节来源

依赖关系分析

  • main.py 依赖 backend/scripter.py 生成脚本，依赖 backend/data_builder.py 生成图表数据
  • backend/scripter.py 依赖环境变量中的GEMINI_API_KEY
  • backend/media_fetcher.py 依赖PEXELS_API_KEY
  • backend/extractor.py 依赖GEMINI_API_KEY与OPENAI_API_KEY
  • 视频处理模块与main.py之间为可选集成
graph LR
M["main.py"] --> SG["backend/scripter.py"]
M --> DB["backend/data_builder.py"]
M --> MF["backend/media_fetcher.py"]
M --> EX["backend/extractor.py"]
SG --> ENV1["GEMINI_API_KEY"]
MF --> ENV2["PEXELS_API_KEY"]
EX --> ENV3["GEMINI_API_KEY/OPENAI_API_KEY"]

图表来源

章节来源

性能考量

  • API调用成本控制
    • 使用缓存：对重复的提示词与翻译结果进行缓存，减少Gemini/Whisper调用次数
    • 批量请求：合并相似请求，避免频繁往返
  • 响应解析与结构化
    • 强制JSON输出，减少后处理开销
    • 对异常响应进行重试与降级策略
  • 渲染阶段
    • render_props.json尽量紧凑，避免冗余字段
    • 图表数据按需生成，避免不必要的计算

[本节为通用建议，无需特定文件引用]

故障排查指南

  • API密钥缺失
    • 确认 .env 文件存在且包含有效密钥
    • GEMINI_API_KEY、OPENAI_API_KEY、PEXELS_API_KEY
  • FFmpeg依赖
    • 使用测试脚本检查依赖安装情况
    • 若未安装，按提示安装FFmpeg与ffprobe
  • 渲染失败
    • 确认前端依赖已安装
    • 检查render_props.json结构是否符合前端schema

章节来源

结论

scripter.py模块是将结构化财务数据转化为自然日语旁白的关键环节。通过精心设计的提示词工程，将客户数据、财务预测与视频节奏要求有机融合，可生成既专业又富有人情味的脚本。在主流水线中，它位于PDF/视频抽取之后、图表数据构建之前，为后续B-Roll与渲染阶段提供高质量的文本基础。随着各模块逐步完善，系统将形成一条从数据到视频的完整自动化管线。

[本节为总结性内容，无需特定文件引用]

附录

实际代码示例（路径指引）

  • 调整生成风格
  • 添加新的解说段落类型
  • 解析与扩展脚本结构
    • 在返回后对segments进行二次加工，参考：main.py

API与配置清单

  • 环境变量
    • GEMINI_API_KEY：Google Gemini API
    • OPENAI_API_KEY：OpenAI Whisper
    • PEXELS_API_KEY：Pexels B-Roll
  • 依赖安装

章节来源