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/故障排除.md

18 KiB
Raw Blame History

故障排除

**本文引用的文件** - [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)

目录

  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
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"]

图示来源

章节来源

核心组件

  • 主入口与流水线编排：负责参数解析、目录准备、步骤调度与调用各模块、保存 render_props.json 并触发 Remotion 渲染。
  • 数据提取器：封装 PDF 与视频解析接口，读取环境变量中的 API Key，抛出明确错误提示。
  • 脚本生成器：根据 PDF 与可选视频内容生成自然语言脚本，同样依赖环境变量。
  • 媒体抓取器：基于关键词从 Pexels 抓取 B-Roll 视频，依赖 Pexels API Key。
  • 数据构建器：执行财务模拟，生成资产枯竭与现金流图表数据，供前端渲染使用。
  • 结构验证脚本：校验目录与文件完整性、导入可用性、CLI 可用性，辅助迁移与初始化。

章节来源

架构总览

下图展示从输入到输出的端到端流程，以及关键错误点的定位位置。

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 : 输出最终视频

图示来源

详细组件分析

组件A：主入口与流水线编排

  • 功能要点
    • 参数解析与配置合并（支持 --pdf/--video/--config/--output/--dry-run）
    • 自动创建 assets 子目录
    • 步骤顺序：PDF 解析 → 视频解析（可选）→ 脚本生成 → B-Roll 抓取 → 图表数据构建 → 保存 render_props.json → 触发渲染
    • 渲染命令通过 npx remotion render 执行，当前处于占位状态（注释掉实际子进程调用）
  • 关键错误点
    • 缺少必要参数时直接报错
    • 渲染阶段若未启用实际子进程调用，会显示占位信息而非真实错误
  • 优化建议
    • 在渲染阶段取消注释子进程调用，确保错误能被上层捕获
    • 将 dry-run 与渲染阶段解耦，便于独立调试
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(["结束"])

图示来源

章节来源

组件B：数据提取器（PDF/视频）

  • 功能要点
    • PDFExtractor：从 PDF 中抽取结构化数据，需要 GEMINI_API_KEY
    • VideoExtractor：对视频进行转录与时间戳抽取，需要 OPENAI_API_KEY
  • 错误处理
    • 若环境变量缺失，直接抛出异常，提示缺少对应 API Key
  • 诊断要点
    • 确认 .env 文件存在且包含有效密钥
    • 确认网络可达与配额充足
classDiagram
class PDFExtractor {
+__init__(api_key)
+extract(pdf_path) Dict
}
class VideoExtractor {
+__init__(api_key)
+extract(video_path) Dict
}
PDFExtractor <.. VideoExtractor : "均依赖环境变量"

图示来源

章节来源

组件C：脚本生成器

  • 功能要点
    • 基于 PDF 与可选视频内容生成自然语言脚本，需要 GEMINI_API_KEY
  • 错误处理
    • 环境变量缺失时抛出异常
  • 诊断要点
    • 配置 .env 并确认 Gemini API 可用

章节来源

组件D：媒体抓取器（B-Roll）

  • 功能要点
    • 依据关键词从 Pexels 搜索并下载 B-Roll，需要 PEKELS_API_KEY
  • 错误处理
    • 环境变量缺失时抛出异常
  • 诊断要点
    • 配置 .env 并确认 Pexels API 可用

章节来源

组件E：数据构建器（财务模拟）

  • 功能要点
    • 使用默认通胀率、赤字利率、投资回报率等参数进行年金模拟，生成资产枯竭与现金流数据
  • 错误处理
    • 无显式异常处理，需在上游保证输入数据合法
  • 诊断要点
    • 确保 PDF 解析返回的数据字段齐全

章节来源

依赖关系分析

  • 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）
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

图示来源

章节来源

性能注意事项

  • API 调用成本与配额
    • Gemini、Whisper、Pexels 均有配额限制，建议在本地或 CI 中合理控制并发与重试策略
  • 渲染性能
    • Remotion 渲染耗时与图表复杂度、B-Roll 视频长度相关，建议先使用 dry-run 生成数据以验证流程
  • 本地依赖
    • FFmpeg 安装与可用性直接影响视频转录与处理，建议在测试前单独验证

[本节为通用指导，不直接分析具体文件]

故障排除指南

一、环境变量与密钥问题

  • 现象
    • “API 密钥未找到”
  • 根因
    • .env 文件缺失或未正确填写；或运行环境中未加载 .env
  • 修复步骤
    • 复制示例文件并填写密钥
    • 确认密钥类型与来源
      • Gemini：用于 PDF 解析与脚本生成
      • OpenAI：用于 Whisper 转录
      • Pexels：用于 B-Roll 下载
  • 验证方法

章节来源

二、PDF 提取失败

  • 现象
    • PDF 解析阶段报错或返回空数据
  • 根因
    • PDF 不可读或受密码保护；Gemini API 额度不足或网络异常
  • 修复步骤
    • 确保输入 PDF 可打开且非加密
    • 检查 .env 中 GEMINI_API_KEY 是否正确
    • 如为首次使用，确认 API 已激活并有足够配额
  • 验证方法
    • 使用 verify_structure.py 的导入测试，确认 extractor 模块可用
    • 查看 extractor 抛出的异常信息（缺少密钥时会直接报错）

章节来源

三、视频转录失败

  • 现象
    • 视频解析阶段报错或无法生成时间戳
  • 根因
    • 缺少 OPENAI_API_KEY；FFmpeg 未安装或不可用；视频格式不受支持
  • 修复步骤
  • 验证方法

章节来源

四、B-Roll 抓取失败

  • 现象
    • B-Roll 获取阶段报错或返回空结果
  • 根因
    • 缺少 PEKELS_API_KEY；网络异常；关键词为空
  • 修复步骤
    • 确认 .env 中 PEKELS_API_KEY 已设置
    • 检查网络连通性与 API 配额
  • 验证方法

章节来源

五、Remotion 渲染失败

  • 现象
    • 渲染阶段报错或无输出
  • 根因
    • Node.js 依赖未安装；Remotion 配置不正确；前端组件缺失；渲染命令未启用
  • 修复步骤
  • 验证方法
    • 使用 verify_structure.py 的 CLI 测试，确认 main.py --help 可用

章节来源

六、项目目录结构完整性检查

  • 现象
    • 运行后提示某些文件缺失或导入失败
  • 根因
    • 迁移或克隆后遗漏关键目录/文件
  • 修复步骤
  • 验证方法

章节来源

七、Dry Run 与数据验证

  • 现象
    • 希望跳过渲染阶段，仅生成数据
  • 根因
    • 未使用 --dry-run 参数
  • 修复步骤
    • 使用 --dry-run 生成 render_props.json，随后手动检查
  • 验证方法
    • 检查 assets/1_processed/render_props.json 是否生成

章节来源

八、Python 依赖缺失

  • 现象
    • 导入 backend 模块时报错或功能受限
  • 根因
    • requirements.txt 未安装或版本不匹配
  • 修复步骤
  • 验证方法

章节来源

结论

本指南围绕“环境变量、API 密钥、依赖安装、数据提取、脚本生成、B-Roll 抓取、财务模拟、Remotion 渲染”八个关键环节，提供了系统化的诊断与修复路径。配合 verify_structure.py 的结构检查与 dry-run 数据验证，可显著降低问题定位成本，提升整体使用体验。

[本节为总结性内容，不直接分析具体文件]

附录

A. 常见命令速查

B. 关键文件清单