205 lines
8.8 KiB
Markdown
205 lines
8.8 KiB
Markdown
# 核心功能
|
||
|
||
<cite>
|
||
**本文档中引用的文件**
|
||
- [extractor.py](file://backend/extractor.py)
|
||
- [scripter.py](file://backend/scripter.py)
|
||
- [media_fetcher.py](file://backend/media_fetcher.py)
|
||
- [data_builder.py](file://backend/data_builder.py)
|
||
- [index.ts](file://src/index.ts)
|
||
- [Root.tsx](file://src/Root.tsx)
|
||
- [types.ts](file://src/types.ts)
|
||
- [main.py](file://main.py)
|
||
- [PROJECT_README.md](file://PROJECT_README.md)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构概述](#架构概述)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖分析](#依赖分析)
|
||
7. [性能考虑](#性能考虑)
|
||
8. [故障排除指南](#故障排除指南)
|
||
9. [结论](#结论)
|
||
|
||
## 简介
|
||
本项目是一个混合型Python/Node.js系统，能够将静态的财务规划报告（PDF）和原始访谈视频自动转换为动态、个性化的3-5分钟解说视频。系统整合了动画图表、AI生成的日语解说、情境化素材片段（B-Roll）以及同步的访谈剪辑，为用户提供直观的财务规划可视化服务。整个流程由Python后端驱动，利用AI模型进行数据提取和内容生成，再通过Remotion前端引擎完成视频渲染。
|
||
|
||
## 项目结构
|
||
项目采用分层架构，清晰地分离了数据处理逻辑与视频渲染逻辑。后端（Python）负责数据提取、AI生成和模拟计算，前端（Node.js/TypeScript）则专注于程序化视频渲染。两者通过一个名为`render_props.json`的数据契约文件进行通信。
|
||
|
||
```mermaid
|
||
graph TD
|
||
subgraph "Backend (Python)"
|
||
A[extractor.py] --> B[scripter.py]
|
||
B --> C[media_fetcher.py]
|
||
C --> D[data_builder.py]
|
||
D --> E[main.py]
|
||
end
|
||
subgraph "Frontend (Node.js/TypeScript)"
|
||
F[index.ts]
|
||
G[Root.tsx]
|
||
H[CashFlowChart.tsx]
|
||
I[LifePlanChart.tsx]
|
||
end
|
||
E --> |生成| J[render_props.json]
|
||
J --> |消费| F
|
||
```
|
||
|
||
**Diagram sources**
|
||
- [PROJECT_README.md](file://PROJECT_README.md#L14-L32)
|
||
|
||
**Section sources**
|
||
- [PROJECT_README.md](file://PROJECT_README.md#L50-L79)
|
||
|
||
## 核心组件
|
||
系统的核心功能由五个关键模块构成：PDF/视频数据提取器、AI日语解说脚本生成器、B-Roll素材自动获取器、财务数据模拟与图表构建器以及最终的视频渲染合成器。这些模块协同工作，形成一个从原始输入到最终视频输出的完整流水线。
|
||
|
||
**Section sources**
|
||
- [main.py](file://main.py#L5-L11)
|
||
- [PROJECT_README.md](file://PROJECT_README.md#L7-L12)
|
||
|
||
## 架构概述
|
||
系统的整体架构遵循“后端处理，前端渲染”的模式。Python后端作为“导演”，负责协调所有AI和数据处理任务；而Node.js前端作为“引擎”，专注于高质量的视频合成。`main.py`是整个流水线的入口点，它按顺序调用各个模块，最终生成`render_props.json`文件，触发Remotion进行视频渲染。
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[PDF/视频输入] --> B[extractor.py]
|
||
B --> C[scripter.py]
|
||
C --> D[media_fetcher.py]
|
||
D --> E[data_builder.py]
|
||
E --> F[render_props.json]
|
||
F --> G[Remotion渲染]
|
||
G --> H[最终视频输出]
|
||
```
|
||
|
||
**Diagram sources**
|
||
- [main.py](file://main.py#L5-L11)
|
||
- [PROJECT_README.md](file://PROJECT_README.md#L16-L32)
|
||
|
||
## 详细组件分析
|
||
|
||
### PDF/视频数据提取器 (extractor.py)
|
||
该模块负责解析输入的PDF报告和视频文件，从中提取结构化数据。它利用Google Gemini Pro API来解析日语财务报告，并使用OpenAI Whisper API对访谈视频进行转录，获取时间戳和关键词。
|
||
|
||
**Section sources**
|
||
- [extractor.py](file://backend/extractor.py#L1-L84)
|
||
|
||
### AI日语解说脚本生成器 (scripter.py)
|
||
此模块是AI驱动内容生成的核心。它接收从PDF和视频中提取的数据，利用Google Gemini Pro生成自然流畅的日语解说脚本。脚本被划分为多个片段，每个片段都包含预计的持续时间，为后续的视频同步提供依据。
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class ScriptGenerator {
|
||
+api_key : str
|
||
+__init__(api_key : Optional[str])
|
||
+generate(pdf_data : Dict, video_data : Optional[Dict], style : str) : Dict
|
||
-_build_prompt(pdf_data : Dict, style : str) : str
|
||
}
|
||
```
|
||
|
||
**Diagram sources**
|
||
- [scripter.py](file://backend/scripter.py#L14-L69)
|
||
|
||
**Section sources**
|
||
- [scripter.py](file://backend/scripter.py#L1-L69)
|
||
|
||
### B-Roll素材自动获取器 (media_fetcher.py)
|
||
该模块根据生成的脚本内容，自动从Pexels API获取相关的背景视频素材（B-Roll）。它会从脚本中提取关键词，将日语关键词翻译成英语，然后搜索并下载匹配的视频片段，为视频增添视觉吸引力。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Script as 脚本
|
||
participant Fetcher as MediaFetcher
|
||
participant Pexels as Pexels API
|
||
Script->>Fetcher : 提供关键词列表
|
||
Fetcher->>Fetcher : 翻译关键词(日->英)
|
||
Fetcher->>Pexels : 搜索视频
|
||
Pexels-->>Fetcher : 返回视频URL
|
||
Fetcher->>Fetcher : 下载视频到本地
|
||
Fetcher-->>Script : 返回本地文件路径
|
||
```
|
||
|
||
**Diagram sources**
|
||
- [media_fetcher.py](file://backend/media_fetcher.py#L15-L72)
|
||
|
||
**Section sources**
|
||
- [media_fetcher.py](file://backend/media_fetcher.py#L1-L72)
|
||
|
||
### 财务数据模拟与图表构建器 (data_builder.py)
|
||
这是数据驱动视频渲染的关键。该模块包含一个财务模拟引擎，能够基于提取的财务数据，模拟未来几十年的资产耗尽和现金流情况。它考虑了通货膨胀、投资回报和债务复利等因素，生成精确的年度财务快照，并将其格式化为Remotion图表组件所需的格式。
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class FinancialSimulator {
|
||
+config : Dict
|
||
+inflation_rate : float
|
||
+deficit_interest_rate : float
|
||
+investment_return : float
|
||
+__init__(config : Optional[Dict])
|
||
+simulate_timeline(...) : List[Dict]
|
||
+build_cashflow_data(timeline : List[Dict]) : List[Dict]
|
||
-_get_event_cost(...) : float
|
||
-_get_event_labels(...) : List[str]
|
||
}
|
||
```
|
||
|
||
**Diagram sources**
|
||
- [data_builder.py](file://backend/data_builder.py#L15-L200)
|
||
|
||
**Section sources**
|
||
- [data_builder.py](file://backend/data_builder.py#L1-L200)
|
||
|
||
### 视频渲染合成器 (src/index.ts)
|
||
前端部分使用Remotion库进行程序化视频渲染。`index.ts`是入口文件，它注册了`Root.tsx`作为根组件。`Root.tsx`中定义了多个`<Composition>`，每个都对应一个视频片段（如资产耗尽图、现金流图），并将`render_props.json`中的数据作为属性传递给相应的React组件。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[index.ts] --> B[Root.tsx]
|
||
B --> C[Composition: LifePlanChart]
|
||
B --> D[Composition: CashFlowChart]
|
||
B --> E[Composition: DualChartView]
|
||
C --> F[LifePlanChart.tsx]
|
||
D --> G[CashFlowChart.tsx]
|
||
E --> H[DualChartView.tsx]
|
||
```
|
||
|
||
**Diagram sources**
|
||
- [src/index.ts](file://src/index.ts#L1-L6)
|
||
- [src/Root.tsx](file://src/Root.tsx#L1-L68)
|
||
|
||
**Section sources**
|
||
- [src/index.ts](file://src/index.ts#L1-L6)
|
||
- [src/Root.tsx](file://src/Root.tsx#L1-L68)
|
||
|
||
## 依赖分析
|
||
系统的主要依赖关系清晰地体现在`main.py`的流水线设计中。`VideoGeneratorPipeline`类按顺序调用`extract_pdf`、`generate_script`、`fetch_broll`和`build_render_props`等方法，形成了一个强依赖的线性流程。外部API密钥通过环境变量注入，确保了配置的安全性。
|
||
|
||
```mermaid
|
||
graph TD
|
||
main.VideoGeneratorPipeline.run[run] --> main.VideoGeneratorPipeline.extract_pdf[extract_pdf]
|
||
main.VideoGeneratorPipeline.run[run] --> main.VideoGeneratorPipeline.generate_script[generate_script]
|
||
main.VideoGeneratorPipeline.run[run] --> main.VideoGeneratorPipeline.fetch_broll[fetch_broll]
|
||
main.VideoGeneratorPipeline.run[run] --> main.VideoGeneratorPipeline.build_render_props[build_render_props]
|
||
main.VideoGeneratorPipeline.run[run] --> main.VideoGeneratorPipeline.render_video[render_video]
|
||
```
|
||
|
||
**Diagram sources**
|
||
- [main.py](file://main.py#L48-L83)
|
||
|
||
**Section sources**
|
||
- [main.py](file://main.py#L33-L305)
|
||
|
||
## 性能考虑
|
||
虽然代码中包含了一些TODO注释，表明部分功能尚未完全实现，但其架构设计已考虑到性能。例如，`media_fetcher.py`中提到了翻译缓存，以避免重复的API调用。财务模拟使用了数学公式进行高效计算。对于视频渲染，Remotion支持并行渲染和缓存，可以显著缩短生成时间。
|
||
|
||
## 故障排除指南
|
||
常见问题主要集中在API密钥和环境配置上。确保`.env`文件存在且包含有效的`GEMINI_API_KEY`、`OPENAI_API_KEY`和`PEXELS_API_KEY`。如果遇到渲染失败，检查`npm install`是否成功，并确认`frontend/src/`目录结构正确。对于PDF解析失败，需确认PDF文件可读且未加密。
|
||
|
||
**Section sources**
|
||
- [PROJECT_README.md](file://PROJECT_README.md#L218-L231)
|
||
|
||
## 结论
|
||
该项目成功地将AI驱动的内容生成与数据驱动的视频渲染相结合，创造了一个自动化视频生成的解决方案。通过模块化的设计，每个核心功能都职责明确，易于维护和扩展。未来的工作应集中在实现`TODO`中提到的功能，如Gemini和Whisper的实际集成，并优化数据流以处理更复杂的财务场景。 |