304 lines
14 KiB
Markdown
304 lines
14 KiB
Markdown
# AI生成
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [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)
|
||
</cite>
|
||
|
||
## 目录
|
||
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 作为入口，编排整个流水线
|
||
|
||
```mermaid
|
||
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
|
||
```
|
||
|
||
**图表来源**
|
||
- [main.py](file://main.py#L48-L84)
|
||
- [backend/scripter.py](file://backend/scripter.py#L14-L69)
|
||
- [backend/extractor.py](file://backend/extractor.py#L15-L84)
|
||
- [backend/data_builder.py](file://backend/data_builder.py#L150-L200)
|
||
- [backend/media_fetcher.py](file://backend/media_fetcher.py#L15-L72)
|
||
- [backend/video_processor/schemas.py](file://backend/video_processor/schemas.py#L12-L91)
|
||
- [backend/video_processor/utils.py](file://backend/video_processor/utils.py#L13-L164)
|
||
|
||
**章节来源**
|
||
- [main.py](file://main.py#L48-L84)
|
||
- [PROJECT_README.md](file://PROJECT_README.md#L132-L141)
|
||
|
||
## 核心组件
|
||
- 脚本生成器（ScriptGenerator）：封装Gemini Pro调用、提示词构建、响应解析与时长估计
|
||
- PDF/视频抽取器（PDFExtractor/VideoExtractor）：从PDF与视频中提取结构化数据与时间戳
|
||
- 财务模拟器（FinancialSimulator）：基于参数模拟资产枯竭与现金流，生成图表所需数据
|
||
- B-Roll素材抓取器（MediaFetcher）：根据关键词检索并下载B-Roll素材
|
||
- 视频处理工具（VideoProcessor）：提供视频分析与切片等能力（可选）
|
||
|
||
**章节来源**
|
||
- [backend/scripter.py](file://backend/scripter.py#L14-L69)
|
||
- [backend/extractor.py](file://backend/extractor.py#L15-L84)
|
||
- [backend/data_builder.py](file://backend/data_builder.py#L15-L115)
|
||
- [backend/media_fetcher.py](file://backend/media_fetcher.py#L15-L72)
|
||
- [backend/video_processor/schemas.py](file://backend/video_processor/schemas.py#L12-L91)
|
||
- [backend/video_processor/utils.py](file://backend/video_processor/utils.py#L13-L164)
|
||
|
||
## 架构总览
|
||
脚本生成在整体流水线中的位置如下：
|
||
|
||
```mermaid
|
||
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视频
|
||
```
|
||
|
||
**图表来源**
|
||
- [main.py](file://main.py#L48-L84)
|
||
- [backend/scripter.py](file://backend/scripter.py#L22-L49)
|
||
- [backend/data_builder.py](file://backend/data_builder.py#L150-L200)
|
||
|
||
**章节来源**
|
||
- [main.py](file://main.py#L48-L84)
|
||
- [PROJECT_README.md](file://PROJECT_README.md#L132-L141)
|
||
|
||
## 详细组件分析
|
||
|
||
### ScriptGenerator（脚本生成器）
|
||
- 职责
|
||
- 初始化：从环境变量读取API密钥，校验可用性
|
||
- generate：接收PDF数据与可选视频数据，返回包含分段、总时长与同步点的结构化脚本
|
||
- _build_prompt：构建提示词（当前为占位），应整合客户信息、财务预测、风格约束与输出格式要求
|
||
- 输入输出
|
||
- 输入：pdf_data（结构化财务数据）、video_data（可选，含转录与时间戳）、style（友好/专业/随意）
|
||
- 输出：包含segments（脚本文本、时长、类型）、total_duration、sync_points
|
||
- 设计要点
|
||
- 风格控制：通过style参数与提示词工程控制语气与专业度
|
||
- 结构化输出：要求模型以JSON格式返回segments，便于后续解析与时长估算
|
||
- 多模态融合：将视频转录的时间戳与脚本同步点对齐，提升节奏一致性
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class ScriptGenerator {
|
||
+api_key : str
|
||
+__init__(api_key)
|
||
+generate(pdf_data, video_data, style) Dict
|
||
-_build_prompt(pdf_data, style) str
|
||
}
|
||
```
|
||
|
||
**图表来源**
|
||
- [backend/scripter.py](file://backend/scripter.py#L14-L69)
|
||
|
||
**章节来源**
|
||
- [backend/scripter.py](file://backend/scripter.py#L14-L69)
|
||
|
||
### 提示词工程设计（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结构，包含分段文本与时长
|
||
|
||
**章节来源**
|
||
- [backend/scripter.py](file://backend/scripter.py#L22-L49)
|
||
- [backend/data_builder.py](file://backend/data_builder.py#L150-L200)
|
||
- [backend/extractor.py](file://backend/extractor.py#L23-L41)
|
||
|
||
### main.py 中的 generate_script 方法
|
||
- 位置：VideoGeneratorPipeline.generate_script
|
||
- 功能：调用后端脚本生成模块，返回结构化脚本
|
||
- 当前实现：占位返回mock脚本，包含segments列表
|
||
- 实际实现建议：调用ScriptGenerator.generate，传入pdf_data与video_data，解析返回的JSON并估算每段时长
|
||
|
||
```mermaid
|
||
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["返回结构化脚本"]
|
||
```
|
||
|
||
**图表来源**
|
||
- [main.py](file://main.py#L115-L134)
|
||
- [backend/scripter.py](file://backend/scripter.py#L22-L49)
|
||
|
||
**章节来源**
|
||
- [main.py](file://main.py#L115-L134)
|
||
|
||
### 财务数据与脚本的衔接
|
||
- data_builder.py 模块根据pdf_data生成资产枯竭与现金流数据，供前端图表使用
|
||
- scripter.py 应在提示词中引用这些数据摘要，使脚本内容与图表一致
|
||
- 通过style参数与提示词工程，确保脚本语气与数据呈现相匹配
|
||
|
||
**章节来源**
|
||
- [backend/data_builder.py](file://backend/data_builder.py#L150-L200)
|
||
- [backend/scripter.py](file://backend/scripter.py#L22-L49)
|
||
|
||
### B-Roll素材与脚本的协同
|
||
- media_fetcher.py 的fetch_broll函数可根据脚本关键词检索B-Roll素材
|
||
- 关键词提取：从segments.text中抽取主题词，如“資産”“将来”“リスク”等
|
||
- 同步：将脚本的sync_points与B-Roll片段起止时间对齐，提升观看体验
|
||
|
||
**章节来源**
|
||
- [backend/media_fetcher.py](file://backend/media_fetcher.py#L15-L72)
|
||
- [backend/scripter.py](file://backend/scripter.py#L22-L49)
|
||
|
||
### 视频处理（可选集成）
|
||
- schemas.py 定义了VideoSegment、KeyMoment、VideoAnalysisResult等数据结构
|
||
- utils.py 提供FFmpeg封装，支持时长查询、音频提取、视频切片
|
||
- 可选策略：audio-first或direct，用于抽取视频转录与时间戳，辅助scripter生成更贴合画面的脚本
|
||
|
||
**章节来源**
|
||
- [backend/video_processor/schemas.py](file://backend/video_processor/schemas.py#L12-L91)
|
||
- [backend/video_processor/utils.py](file://backend/video_processor/utils.py#L13-L164)
|
||
- [tests/test_video_cli.py](file://tests/test_video_cli.py#L1-L161)
|
||
- [tests/test_video_processor.py](file://tests/test_video_processor.py#L1-L143)
|
||
|
||
## 依赖关系分析
|
||
- 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之间为可选集成
|
||
|
||
```mermaid
|
||
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"]
|
||
```
|
||
|
||
**图表来源**
|
||
- [main.py](file://main.py#L48-L84)
|
||
- [backend/scripter.py](file://backend/scripter.py#L17-L21)
|
||
- [backend/media_fetcher.py](file://backend/media_fetcher.py#L18-L22)
|
||
- [backend/extractor.py](file://backend/extractor.py#L18-L21)
|
||
|
||
**章节来源**
|
||
- [requirements.txt](file://requirements.txt#L1-L34)
|
||
- [PROJECT_README.md](file://PROJECT_README.md#L106-L111)
|
||
|
||
## 性能考量
|
||
- 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
|
||
|
||
**章节来源**
|
||
- [PROJECT_README.md](file://PROJECT_README.md#L106-L111)
|
||
- [tests/test_video_cli.py](file://tests/test_video_cli.py#L68-L91)
|
||
- [backend/video_processor/utils.py](file://backend/video_processor/utils.py#L148-L164)
|
||
|
||
## 结论
|
||
scripter.py模块是将结构化财务数据转化为自然日语旁白的关键环节。通过精心设计的提示词工程，将客户数据、财务预测与视频节奏要求有机融合，可生成既专业又富有人情味的脚本。在主流水线中，它位于PDF/视频抽取之后、图表数据构建之前，为后续B-Roll与渲染阶段提供高质量的文本基础。随着各模块逐步完善，系统将形成一条从数据到视频的完整自动化管线。
|
||
|
||
[本节为总结性内容，无需特定文件引用]
|
||
|
||
## 附录
|
||
|
||
### 实际代码示例（路径指引）
|
||
- 调整生成风格
|
||
- 在调用处设置style参数，参考：[backend/scripter.py](file://backend/scripter.py#L22-L49)
|
||
- 添加新的解说段落类型
|
||
- 在提示词中新增类型定义与样例，参考：[backend/scripter.py](file://backend/scripter.py#L50-L59)
|
||
- 解析与扩展脚本结构
|
||
- 在返回后对segments进行二次加工，参考：[main.py](file://main.py#L115-L134)
|
||
|
||
### API与配置清单
|
||
- 环境变量
|
||
- GEMINI_API_KEY：Google Gemini API
|
||
- OPENAI_API_KEY：OpenAI Whisper
|
||
- PEXELS_API_KEY：Pexels B-Roll
|
||
- 依赖安装
|
||
- Python依赖：参考 [requirements.txt](file://requirements.txt#L1-L34)
|
||
|
||
**章节来源**
|
||
- [PROJECT_README.md](file://PROJECT_README.md#L106-L111)
|
||
- [requirements.txt](file://requirements.txt#L1-L34) |