462 lines
18 KiB
Markdown
462 lines
18 KiB
Markdown
# 故障排除
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [PROJECT_README.md](file://PROJECT_README.md)
|
||
- [verify_structure.py](file://verify_structure.py)
|
||
- [main.py](file://main.py)
|
||
- [requirements.txt](file://requirements.txt)
|
||
- [package.json](file://package.json)
|
||
- [backend/extractor.py](file://backend/extractor.py)
|
||
- [backend/scripter.py](file://backend/scripter.py)
|
||
- [backend/media_fetcher.py](file://backend/media_fetcher.py)
|
||
- [backend/data_builder.py](file://backend/data_builder.py)
|
||
- [tests/test_video_cli.py](file://tests/test_video_cli.py)
|
||
- [tests/test_video_processor.py](file://tests/test_video_processor.py)
|
||
- [.env.example](file://.env.example)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能注意事项](#性能注意事项)
|
||
8. [故障排除指南](#故障排除指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
本指南面向使用本项目的用户与开发者，聚焦“常见问题现象—根本原因—解决方案”的闭环排查流程，并结合项目内置的结构验证脚本，帮助快速定位缺失文件、环境变量、依赖安装与渲染失败等问题。同时提供可操作的诊断步骤与修复命令，降低技术支持门槛。
|
||
|
||
## 项目结构
|
||
项目采用“Python 后端 + Node.js 前端（Remotion）”的混合架构，数据通过中间产物 JSON 在两端之间传递。关键目录与文件包括：
|
||
- assets/0_input：原始输入（PDF、MP4）
|
||
- assets/1_processed：中间产物（提取结果、翻译缓存、B-Roll下载等）
|
||
- assets/2_output：最终输出（生成的视频）
|
||
- backend：Python 模块（PDF/视频解析、脚本生成、媒体抓取、数据模拟）
|
||
- frontend：Remotion 前端工程（React + TypeScript + Recharts）
|
||
- 根目录配置：.env、requirements.txt、package.json、remotion.config.ts、verify_structure.py、main.py
|
||
|
||
```mermaid
|
||
graph TB
|
||
A["main.py<br/>主入口与流水线编排"] --> B["backend.extractor.py<br/>PDF/视频解析"]
|
||
A --> C["backend.scripter.py<br/>脚本生成"]
|
||
A --> D["backend.media_fetcher.py<br/>B-Roll抓取"]
|
||
A --> E["backend.data_builder.py<br/>财务模拟/图表数据"]
|
||
A --> F["assets/1_processed/render_props.json<br/>数据契约"]
|
||
F --> G["frontend/src/index.ts<br/>Remotion渲染入口"]
|
||
G --> H["frontend/src/components/*<br/>图表与合成组件"]
|
||
H --> I["最终视频输出<br/>assets/2_output/*.mp4"]
|
||
```
|
||
|
||
图示来源
|
||
- [main.py](file://main.py#L1-L305)
|
||
- [backend/extractor.py](file://backend/extractor.py#L1-L84)
|
||
- [backend/scripter.py](file://backend/scripter.py#L1-L69)
|
||
- [backend/media_fetcher.py](file://backend/media_fetcher.py#L1-L72)
|
||
- [backend/data_builder.py](file://backend/data_builder.py#L1-L200)
|
||
|
||
章节来源
|
||
- [PROJECT_README.md](file://PROJECT_README.md#L50-L80)
|
||
- [PROJECT_README.md](file://PROJECT_README.md#L132-L141)
|
||
|
||
## 核心组件
|
||
- 主入口与流水线编排：负责参数解析、目录准备、步骤调度与调用各模块、保存 render_props.json 并触发 Remotion 渲染。
|
||
- 数据提取器：封装 PDF 与视频解析接口，读取环境变量中的 API Key，抛出明确错误提示。
|
||
- 脚本生成器：根据 PDF 与可选视频内容生成自然语言脚本，同样依赖环境变量。
|
||
- 媒体抓取器：基于关键词从 Pexels 抓取 B-Roll 视频，依赖 Pexels API Key。
|
||
- 数据构建器：执行财务模拟，生成资产枯竭与现金流图表数据，供前端渲染使用。
|
||
- 结构验证脚本：校验目录与文件完整性、导入可用性、CLI 可用性，辅助迁移与初始化。
|
||
|
||
章节来源
|
||
- [main.py](file://main.py#L33-L301)
|
||
- [backend/extractor.py](file://backend/extractor.py#L15-L84)
|
||
- [backend/scripter.py](file://backend/scripter.py#L14-L69)
|
||
- [backend/media_fetcher.py](file://backend/media_fetcher.py#L15-L72)
|
||
- [backend/data_builder.py](file://backend/data_builder.py#L1-L200)
|
||
- [verify_structure.py](file://verify_structure.py#L1-L136)
|
||
|
||
## 架构总览
|
||
下图展示从输入到输出的端到端流程，以及关键错误点的定位位置。
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant U as "用户"
|
||
participant M as "main.py"
|
||
participant X as "extractor.py"
|
||
participant S as "scripter.py"
|
||
participant MF as "media_fetcher.py"
|
||
participant DB as "data_builder.py"
|
||
participant R as "Remotion渲染"
|
||
participant O as "assets/2_output"
|
||
U->>M : 运行命令传入PDF/可选视频
|
||
M->>X : 提取PDF/视频数据
|
||
X-->>M : 返回结构化数据或报错
|
||
M->>S : 生成脚本
|
||
S-->>M : 返回脚本或报错
|
||
M->>MF : 抓取B-Roll
|
||
MF-->>M : 返回资源或报错
|
||
M->>DB : 构建图表数据
|
||
DB-->>M : 返回render_props.json
|
||
M->>R : 触发渲染npx remotion render
|
||
R-->>O : 输出最终视频
|
||
```
|
||
|
||
图示来源
|
||
- [main.py](file://main.py#L48-L225)
|
||
- [backend/extractor.py](file://backend/extractor.py#L23-L42)
|
||
- [backend/scripter.py](file://backend/scripter.py#L22-L48)
|
||
- [backend/media_fetcher.py](file://backend/media_fetcher.py#L25-L41)
|
||
- [backend/data_builder.py](file://backend/data_builder.py#L150-L200)
|
||
|
||
## 详细组件分析
|
||
|
||
### 组件A：主入口与流水线编排
|
||
- 功能要点
|
||
- 参数解析与配置合并（支持 --pdf/--video/--config/--output/--dry-run）
|
||
- 自动创建 assets 子目录
|
||
- 步骤顺序：PDF 解析 → 视频解析（可选）→ 脚本生成 → B-Roll 抓取 → 图表数据构建 → 保存 render_props.json → 触发渲染
|
||
- 渲染命令通过 npx remotion render 执行，当前处于占位状态（注释掉实际子进程调用）
|
||
- 关键错误点
|
||
- 缺少必要参数时直接报错
|
||
- 渲染阶段若未启用实际子进程调用，会显示占位信息而非真实错误
|
||
- 优化建议
|
||
- 在渲染阶段取消注释子进程调用，确保错误能被上层捕获
|
||
- 将 dry-run 与渲染阶段解耦，便于独立调试
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start(["开始"]) --> Parse["解析参数与配置"]
|
||
Parse --> MkDirs["创建assets子目录"]
|
||
MkDirs --> Step1["Step 1: PDF解析"]
|
||
Step1 --> Step2["Step 2: 视频解析可选"]
|
||
Step2 --> Step3["Step 3: 生成脚本"]
|
||
Step3 --> Step4["Step 4: 抓取B-Roll"]
|
||
Step4 --> Step5["Step 5: 构建图表数据"]
|
||
Step5 --> SaveProps["保存render_props.json"]
|
||
SaveProps --> Render["触发Remotion渲染"]
|
||
Render --> End(["结束"])
|
||
```
|
||
|
||
图示来源
|
||
- [main.py](file://main.py#L48-L225)
|
||
|
||
章节来源
|
||
- [main.py](file://main.py#L228-L301)
|
||
|
||
### 组件B：数据提取器（PDF/视频）
|
||
- 功能要点
|
||
- PDFExtractor：从 PDF 中抽取结构化数据，需要 GEMINI_API_KEY
|
||
- VideoExtractor：对视频进行转录与时间戳抽取，需要 OPENAI_API_KEY
|
||
- 错误处理
|
||
- 若环境变量缺失，直接抛出异常，提示缺少对应 API Key
|
||
- 诊断要点
|
||
- 确认 .env 文件存在且包含有效密钥
|
||
- 确认网络可达与配额充足
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class PDFExtractor {
|
||
+__init__(api_key)
|
||
+extract(pdf_path) Dict
|
||
}
|
||
class VideoExtractor {
|
||
+__init__(api_key)
|
||
+extract(video_path) Dict
|
||
}
|
||
PDFExtractor <.. VideoExtractor : "均依赖环境变量"
|
||
```
|
||
|
||
图示来源
|
||
- [backend/extractor.py](file://backend/extractor.py#L15-L84)
|
||
|
||
章节来源
|
||
- [backend/extractor.py](file://backend/extractor.py#L15-L84)
|
||
|
||
### 组件C：脚本生成器
|
||
- 功能要点
|
||
- 基于 PDF 与可选视频内容生成自然语言脚本，需要 GEMINI_API_KEY
|
||
- 错误处理
|
||
- 环境变量缺失时抛出异常
|
||
- 诊断要点
|
||
- 配置 .env 并确认 Gemini API 可用
|
||
|
||
章节来源
|
||
- [backend/scripter.py](file://backend/scripter.py#L14-L48)
|
||
|
||
### 组件D：媒体抓取器（B-Roll）
|
||
- 功能要点
|
||
- 依据关键词从 Pexels 搜索并下载 B-Roll，需要 PEKELS_API_KEY
|
||
- 错误处理
|
||
- 环境变量缺失时抛出异常
|
||
- 诊断要点
|
||
- 配置 .env 并确认 Pexels API 可用
|
||
|
||
章节来源
|
||
- [backend/media_fetcher.py](file://backend/media_fetcher.py#L15-L41)
|
||
|
||
### 组件E：数据构建器（财务模拟）
|
||
- 功能要点
|
||
- 使用默认通胀率、赤字利率、投资回报率等参数进行年金模拟，生成资产枯竭与现金流数据
|
||
- 错误处理
|
||
- 无显式异常处理，需在上游保证输入数据合法
|
||
- 诊断要点
|
||
- 确保 PDF 解析返回的数据字段齐全
|
||
|
||
章节来源
|
||
- [backend/data_builder.py](file://backend/data_builder.py#L150-L200)
|
||
|
||
## 依赖关系分析
|
||
- Python 依赖
|
||
- dotenv：加载 .env
|
||
- ffmpeg-python、requests：媒体处理与网络请求
|
||
- tqdm、rich：进度与日志
|
||
- Node.js 依赖
|
||
- remotion、react、recharts：渲染引擎与图表
|
||
- 开发工具链：ESLint、TypeScript、Prettier
|
||
- 外部服务
|
||
- Google Gemini API（PDF 解析、脚本生成）
|
||
- OpenAI Whisper（音频转录）
|
||
- Pexels API（B-Roll）
|
||
|
||
```mermaid
|
||
graph LR
|
||
subgraph "Python"
|
||
P1["dotenv"]
|
||
P2["ffmpeg-python"]
|
||
P3["requests"]
|
||
P4["tqdm/rich"]
|
||
end
|
||
subgraph "Node.js"
|
||
N1["remotion"]
|
||
N2["react/recharts"]
|
||
N3["typescript/eslint/prettier"]
|
||
end
|
||
subgraph "外部服务"
|
||
E1["Gemini API"]
|
||
E2["OpenAI Whisper"]
|
||
E3["Pexels API"]
|
||
end
|
||
P1 --> E1
|
||
P2 --> E2
|
||
P3 --> E3
|
||
N1 --> E3
|
||
```
|
||
|
||
图示来源
|
||
- [requirements.txt](file://requirements.txt#L1-L34)
|
||
- [package.json](file://package.json#L1-L43)
|
||
|
||
章节来源
|
||
- [requirements.txt](file://requirements.txt#L1-L34)
|
||
- [package.json](file://package.json#L1-L43)
|
||
|
||
## 性能注意事项
|
||
- API 调用成本与配额
|
||
- Gemini、Whisper、Pexels 均有配额限制，建议在本地或 CI 中合理控制并发与重试策略
|
||
- 渲染性能
|
||
- Remotion 渲染耗时与图表复杂度、B-Roll 视频长度相关，建议先使用 dry-run 生成数据以验证流程
|
||
- 本地依赖
|
||
- FFmpeg 安装与可用性直接影响视频转录与处理，建议在测试前单独验证
|
||
|
||
[本节为通用指导，不直接分析具体文件]
|
||
|
||
## 故障排除指南
|
||
|
||
### 一、环境变量与密钥问题
|
||
- 现象
|
||
- “API 密钥未找到”
|
||
- 根因
|
||
- .env 文件缺失或未正确填写；或运行环境中未加载 .env
|
||
- 修复步骤
|
||
- 复制示例文件并填写密钥
|
||
- 复制命令参考：[PROJECT_README.md](file://PROJECT_README.md#L99-L111)
|
||
- 示例文件路径：[.env.example](file://.env.example#L1-L23)
|
||
- 确认密钥类型与来源
|
||
- Gemini：用于 PDF 解析与脚本生成
|
||
- OpenAI：用于 Whisper 转录
|
||
- Pexels：用于 B-Roll 下载
|
||
- 验证方法
|
||
- 运行结构验证脚本，检查后端模块导入是否成功
|
||
- 参考：[verify_structure.py](file://verify_structure.py#L75-L97)
|
||
|
||
章节来源
|
||
- [PROJECT_README.md](file://PROJECT_README.md#L97-L111)
|
||
- [.env.example](file://.env.example#L1-L23)
|
||
- [verify_structure.py](file://verify_structure.py#L75-L97)
|
||
|
||
### 二、PDF 提取失败
|
||
- 现象
|
||
- PDF 解析阶段报错或返回空数据
|
||
- 根因
|
||
- PDF 不可读或受密码保护；Gemini API 额度不足或网络异常
|
||
- 修复步骤
|
||
- 确保输入 PDF 可打开且非加密
|
||
- 检查 .env 中 GEMINI_API_KEY 是否正确
|
||
- 如为首次使用，确认 API 已激活并有足够配额
|
||
- 验证方法
|
||
- 使用 verify_structure.py 的导入测试，确认 extractor 模块可用
|
||
- 参考：[verify_structure.py](file://verify_structure.py#L75-L97)
|
||
- 查看 extractor 抛出的异常信息（缺少密钥时会直接报错）
|
||
- 参考：[backend/extractor.py](file://backend/extractor.py#L18-L22)
|
||
|
||
章节来源
|
||
- [PROJECT_README.md](file://PROJECT_README.md#L228-L231)
|
||
- [backend/extractor.py](file://backend/extractor.py#L18-L22)
|
||
- [verify_structure.py](file://verify_structure.py#L75-L97)
|
||
|
||
### 三、视频转录失败
|
||
- 现象
|
||
- 视频解析阶段报错或无法生成时间戳
|
||
- 根因
|
||
- 缺少 OPENAI_API_KEY；FFmpeg 未安装或不可用；视频格式不受支持
|
||
- 修复步骤
|
||
- 安装 FFmpeg 并确保在 PATH 中
|
||
- 参考：[tests/test_video_cli.py](file://tests/test_video_cli.py#L71-L80)
|
||
- 确认 .env 中 OPENAI_API_KEY 已设置
|
||
- 使用独立测试工具检查依赖
|
||
- 参考：[tests/test_video_cli.py](file://tests/test_video_cli.py#L68-L91)
|
||
- 验证方法
|
||
- 运行单元测试（需 OPENAI_API_KEY），验证音频优先策略
|
||
- 参考：[tests/test_video_processor.py](file://tests/test_video_processor.py#L113-L140)
|
||
|
||
章节来源
|
||
- [tests/test_video_cli.py](file://tests/test_video_cli.py#L68-L91)
|
||
- [tests/test_video_processor.py](file://tests/test_video_processor.py#L113-L140)
|
||
- [backend/extractor.py](file://backend/extractor.py#L48-L51)
|
||
|
||
### 四、B-Roll 抓取失败
|
||
- 现象
|
||
- B-Roll 获取阶段报错或返回空结果
|
||
- 根因
|
||
- 缺少 PEKELS_API_KEY；网络异常；关键词为空
|
||
- 修复步骤
|
||
- 确认 .env 中 PEKELS_API_KEY 已设置
|
||
- 检查网络连通性与 API 配额
|
||
- 验证方法
|
||
- 运行结构验证脚本，确认 media_fetcher 模块可用
|
||
- 参考：[verify_structure.py](file://verify_structure.py#L75-L97)
|
||
- 查看 media_fetcher 抛出的异常信息（缺少密钥时会直接报错）
|
||
- 参考：[backend/media_fetcher.py](file://backend/media_fetcher.py#L18-L21)
|
||
|
||
章节来源
|
||
- [PROJECT_README.md](file://PROJECT_README.md#L228-L231)
|
||
- [backend/media_fetcher.py](file://backend/media_fetcher.py#L18-L21)
|
||
- [verify_structure.py](file://verify_structure.py#L75-L97)
|
||
|
||
### 五、Remotion 渲染失败
|
||
- 现象
|
||
- 渲染阶段报错或无输出
|
||
- 根因
|
||
- Node.js 依赖未安装；Remotion 配置不正确；前端组件缺失；渲染命令未启用
|
||
- 修复步骤
|
||
- 安装 Node.js 依赖
|
||
- 参考：[PROJECT_README.md](file://PROJECT_README.md#L91-L95)
|
||
- 依赖清单：[package.json](file://package.json#L1-L43)
|
||
- 确认 frontend/src 目录结构与组件注册正确
|
||
- 参考：[PROJECT_README.md](file://PROJECT_README.md#L50-L80)
|
||
- 检查 remotion.config.ts 是否存在
|
||
- 参考：[PROJECT_README.md](file://PROJECT_README.md#L56-L58)
|
||
- 在 main.py 中启用渲染子进程调用（当前为占位）
|
||
- 参考：[main.py](file://main.py#L217-L225)
|
||
- 验证方法
|
||
- 使用 verify_structure.py 的 CLI 测试，确认 main.py --help 可用
|
||
- 参考：[verify_structure.py](file://verify_structure.py#L98-L121)
|
||
|
||
章节来源
|
||
- [PROJECT_README.md](file://PROJECT_README.md#L91-L95)
|
||
- [PROJECT_README.md](file://PROJECT_README.md#L50-L80)
|
||
- [package.json](file://package.json#L1-L43)
|
||
- [main.py](file://main.py#L217-L225)
|
||
- [verify_structure.py](file://verify_structure.py#L98-L121)
|
||
|
||
### 六、项目目录结构完整性检查
|
||
- 现象
|
||
- 运行后提示某些文件缺失或导入失败
|
||
- 根因
|
||
- 迁移或克隆后遗漏关键目录/文件
|
||
- 修复步骤
|
||
- 使用结构验证脚本一次性检查所有必需项
|
||
- 参考：[verify_structure.py](file://verify_structure.py#L12-L74)
|
||
- 若缺失，请对照项目结构补充
|
||
- 参考：[PROJECT_README.md](file://PROJECT_README.md#L50-L80)
|
||
- 验证方法
|
||
- 运行导入测试，确认 backend 包与子模块均可导入
|
||
- 参考：[verify_structure.py](file://verify_structure.py#L75-L97)
|
||
- 运行 CLI 测试，确认 main.py --help 可用
|
||
- 参考：[verify_structure.py](file://verify_structure.py#L98-L121)
|
||
|
||
章节来源
|
||
- [verify_structure.py](file://verify_structure.py#L12-L74)
|
||
- [verify_structure.py](file://verify_structure.py#L75-L97)
|
||
- [verify_structure.py](file://verify_structure.py#L98-L121)
|
||
- [PROJECT_README.md](file://PROJECT_README.md#L50-L80)
|
||
|
||
### 七、Dry Run 与数据验证
|
||
- 现象
|
||
- 希望跳过渲染阶段，仅生成数据
|
||
- 根因
|
||
- 未使用 --dry-run 参数
|
||
- 修复步骤
|
||
- 使用 --dry-run 生成 render_props.json，随后手动检查
|
||
- 参考：[PROJECT_README.md](file://PROJECT_README.md#L126-L130)
|
||
- 验证方法
|
||
- 检查 assets/1_processed/render_props.json 是否生成
|
||
- 参考：[main.py](file://main.py#L72-L77)
|
||
|
||
章节来源
|
||
- [PROJECT_README.md](file://PROJECT_README.md#L126-L130)
|
||
- [main.py](file://main.py#L72-L77)
|
||
|
||
### 八、Python 依赖缺失
|
||
- 现象
|
||
- 导入 backend 模块时报错或功能受限
|
||
- 根因
|
||
- requirements.txt 未安装或版本不匹配
|
||
- 修复步骤
|
||
- 安装 Python 依赖
|
||
- 参考：[PROJECT_README.md](file://PROJECT_README.md#L87-L90)
|
||
- 依赖清单：[requirements.txt](file://requirements.txt#L1-L34)
|
||
- 验证方法
|
||
- 运行 verify_structure.py 的导入测试
|
||
- 参考：[verify_structure.py](file://verify_structure.py#L75-L97)
|
||
|
||
章节来源
|
||
- [PROJECT_README.md](file://PROJECT_README.md#L87-L90)
|
||
- [requirements.txt](file://requirements.txt#L1-L34)
|
||
- [verify_structure.py](file://verify_structure.py#L75-L97)
|
||
|
||
## 结论
|
||
本指南围绕“环境变量、API 密钥、依赖安装、数据提取、脚本生成、B-Roll 抓取、财务模拟、Remotion 渲染”八个关键环节，提供了系统化的诊断与修复路径。配合 verify_structure.py 的结构检查与 dry-run 数据验证，可显著降低问题定位成本，提升整体使用体验。
|
||
|
||
[本节为总结性内容，不直接分析具体文件]
|
||
|
||
## 附录
|
||
|
||
### A. 常见命令速查
|
||
- 安装 Python 依赖
|
||
- 参考：[PROJECT_README.md](file://PROJECT_README.md#L87-L90)
|
||
- 安装 Node.js 依赖
|
||
- 参考：[PROJECT_README.md](file://PROJECT_README.md#L91-L95)
|
||
- 运行结构验证
|
||
- 参考：[verify_structure.py](file://verify_structure.py#L128-L136)
|
||
- 生成数据（跳过渲染）
|
||
- 参考：[PROJECT_README.md](file://PROJECT_README.md#L126-L130)
|
||
- 检查 FFmpeg 依赖
|
||
- 参考：[tests/test_video_cli.py](file://tests/test_video_cli.py#L71-L80)
|
||
|
||
### B. 关键文件清单
|
||
- 环境变量模板：[.env.example](file://.env.example#L1-L23)
|
||
- Python 依赖清单：[requirements.txt](file://requirements.txt#L1-L34)
|
||
- Node.js 依赖清单：[package.json](file://package.json#L1-L43)
|
||
- 主入口与流水线：[main.py](file://main.py#L1-L305)
|
||
- 结构验证脚本：[verify_structure.py](file://verify_structure.py#L1-L136)
|
||
- 数据提取器：[backend/extractor.py](file://backend/extractor.py#L1-L84)
|
||
- 脚本生成器：[backend/scripter.py](file://backend/scripter.py#L1-L69)
|
||
- 媒体抓取器：[backend/media_fetcher.py](file://backend/media_fetcher.py#L1-L72)
|
||
- 数据构建器：[backend/data_builder.py](file://backend/data_builder.py#L1-L200)
|
||
- 视频处理测试工具：[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) |