16 KiB

Raw Permalink Blame History

数据提取

**本文引用的文件列表** - [backend/extractor.py](file://backend/extractor.py) - [backend/data_builder.py](file://backend/data_builder.py) - [backend/video_processor/schemas.py](file://backend/video_processor/schemas.py) - [backend/video_processor/utils.py](file://backend/video_processor/utils.py) - [backend/investigate_video_extraction.py](file://backend/investigate_video_extraction.py) - [backend/investigate_subtitle_extraction.py](file://backend/investigate_subtitle_extraction.py) - [frontend/src/render-props-types.ts](file://frontend/src/render-props-types.ts) - [PROJECT_README.md](file://PROJECT_README.md) - [requirements.txt](file://requirements.txt)

简介

本文件聚焦于“数据提取”模块，系统性阐述两类输入数据的提取与结构化流程：

PDF 报告（财务规划类）：通过大模型解析并抽取结构化信息（如客户基本信息、资产/收入/支出、重大事件、保险建议等）。
访谈视频：通过音频转写与时间戳抽取，生成可用于视频剪辑与B-Roll素材匹配的结构化片段。

同时，文档说明数据提取后的内部表示形式、与后续脚本生成与数据构建模块的数据契约关系，并给出常见问题与扩展方法。

项目结构

数据提取相关的核心文件分布如下：

提取层：backend/extractor.py（待实现）、backend/video_processor/utils.py（FFmpeg工具）、backend/investigate_video_extraction.py 与 backend/investigate_subtitle_extraction.py（演示实现）
结构化输出与契约：backend/video_processor/schemas.py（视频分析结果结构）、frontend/src/render-props-types.ts（前端渲染契约）
数据构建：backend/data_builder.py（基于PDF提取参数进行财务模拟）

graph TB
subgraph "输入"
PDF["PDF 报告"]
VIDEO["访谈视频"]
end
subgraph "提取层"
EX["extractor.py<br/>PDF/视频提取接口待实现"]
VU["video_processor/utils.py<br/>FFmpeg 工具"]
IVV["investigate_video_extraction.py<br/>视频提取演示"]
ISV["investigate_subtitle_extraction.py<br/>字幕/转写演示"]
end
subgraph "结构化输出"
VS["schemas.py<br/>VideoSegment/KeyMoment/VideoAnalysisResult"]
RP["render-props-types.ts<br/>前端渲染契约"]
end
subgraph "后续模块"
DB["data_builder.py<br/>财务模拟与图表数据"]
end
PDF --> EX
VIDEO --> EX
VIDEO --> VU
EX --> VS
VS --> RP
EX --> DB
DB --> RP

图表来源

章节来源

核心组件

PDF 提取器（PDFExtractor）：面向财务规划PDF，期望返回结构化数据（客户信息、财务数据、重大事件、保险建议等），当前为占位实现，需接入大模型API完成解析。
视频提取器（VideoExtractor）：面向访谈视频，期望返回转写文本、时间戳片段、推荐B-Roll片段等，当前为占位实现，需接入Whisper与FFmpeg。
视频处理工具（FFmpeg封装）：提供视频时长查询、音频提取、视频切片等能力，支撑视频提取流程。
视频结构化模式（schemas.py）：定义视频片段、关键时刻、完整分析结果的标准结构，确保与前端契约一致。
数据构建（data_builder.py）：消费PDF提取结果，进行财务模拟与图表数据转换，输出与前端契约一致的结构。

章节来源

架构总览

下图展示了从原始文件到结构化数据再到前端渲染的整体流程。

sequenceDiagram
participant U as "用户"
participant EX as "extractor.py"
participant VU as "FFmpeg 工具"
participant IV as "视频提取演示"
participant IS as "字幕提取演示"
participant VS as "schemas.py"
participant DB as "data_builder.py"
participant RP as "render-props-types.ts"
U->>EX : 提供 PDF/视频
EX->>EX : 占位实现待完成
EX->>VU : 使用 FFmpeg 获取时长/提取音频视频流程
EX->>IV : 参考演示实现上传视频、结构化抽取
EX->>IS : 参考演示实现字幕/转写
EX-->>VS : 输出 VideoSegment/KeyMoment/VideoAnalysisResult
EX-->>DB : 输出 PDF 结构化数据
DB-->>RP : 输出图表数据资产枯竭/现金流
VS-->>RP : 输出视频片段与脚本同步点

图表来源

详细组件分析

PDF 提取流程与内部表示

输入：财务规划PDF（日文）。
处理目标：结构化关键信息，便于后续财务模拟与脚本生成。
当前状态：占位实现，需接入大模型API完成PDF解析与结构化输出。
内部表示（预期）：包含客户信息、财务数据、重大事件、保险建议等字段，作为data_builder的输入。

flowchart TD
Start(["开始：接收 PDF 路径"]) --> CheckKey["检查环境变量<br/>GEMINI_API_KEY"]
CheckKey --> KeyOK{"密钥存在？"}
KeyOK --> |否| RaiseErr["抛出异常：缺少 API 密钥"]
KeyOK --> |是| Upload["上传 PDF 至 Gemini API"]
Upload --> Prompt["构造提示词<br/>要求结构化 JSON 输出"]
Prompt --> Parse["解析响应并校验结构"]
Parse --> Done(["返回结构化数据"])
RaiseErr --> End(["结束"])
Done --> End

图表来源

backend/extractor.py

章节来源

backend/extractor.py

视频元数据与转写流程（FFmpeg + Whisper）

元数据提取：使用ffprobe获取视频时长；使用ffmpeg提取音频（采样率、编码等可配置）。
转写与时间戳：参考演示脚本，先提取音频，再调用Whisper API进行转写与时间戳抽取。
片段结构化：输出VideoSegment/KeyMoment等结构，便于后续B-Roll匹配与视频剪辑。

sequenceDiagram
participant V as "视频文件"
participant U as "FFmpeg 工具"
participant W as "Whisper API"
participant S as "schemas.py"
participant R as "render-props-types.ts"
V->>U : get_video_duration()
U-->>V : 返回时长秒
V->>U : extract_audio()
U-->>V : 输出音频文件
V->>W : 上传音频并请求转写
W-->>V : 返回转写文本与时间戳
V->>S : 组装 VideoSegment/KeyMoment
S-->>R : 输出符合前端契约的结构

图表来源

章节来源

视频结构化模式（schemas.py）

VideoSegment：视频片段，包含起止时间、描述、转写、重要性、标签、说话人等。
KeyMoment：关键时刻，包含时间戳、类型（引述/图表/情感/动作）、内容与上下文。
VideoAnalysisResult：完整分析结果，包含源视频路径、总时长、策略、片段列表、关键时刻列表与额外元数据。

classDiagram
class VideoSegment {
+float start_time
+float end_time
+string description
+string transcript
+string importance
+string[] tags
+string speaker
+float duration
+to_dict() dict
}
class KeyMoment {
+float timestamp
+string type
+string content
+string context
+to_dict() dict
}
class VideoAnalysisResult {
+string source_video
+float duration
+string strategy
+VideoSegment[] segments
+KeyMoment[] key_moments
+dict metadata
+to_dict() dict
+get_high_importance_segments() VideoSegment[]
+get_quotes() KeyMoment[]
}
VideoAnalysisResult --> VideoSegment : "包含"
VideoAnalysisResult --> KeyMoment : "包含"

图表来源

backend/video_processor/schemas.py

章节来源

backend/video_processor/schemas.py

数据契约与前后端衔接

前端契约（render-props-types.ts）：定义YearlySnapshot、CashFlowData、ScriptSegment、AssetCollection等类型，确保后端生成的数据与前端渲染一致。
后端数据构建（data_builder.py）：将PDF提取参数转化为财务模拟时间线与图表数据，输出与前端契约一致的结构。

erDiagram
YEARLYSNAPSHOT {
int year
int repAge
int spouseAge
int income
int expenditure
int assetBalance
string[] events
boolean isCritical
}
CASHFLOWDATA {
int year
int age
int totalIncome
int livingExpense
int housingExpense
int educationExpense
int taxExpense
int eventExpense
int totalExpense
int netCashFlow
int assetBalance
}
RENDERPROPS {
string title
string currencyUnit
int duration
string clientName
string generatedAt
}
RENDERPROPS ||--o{ YEARLYSNAPSHOT : "assetDepletion.timeline"
RENDERPROPS ||--o{ CASHFLOWDATA : "cashFlow.timeline"

图表来源

章节来源

依赖关系分析

外部依赖：Google Gemini（PDF/视频理解）、OpenAI Whisper（音频转写）、FFmpeg/ffprobe（媒体处理）、Pexels（B-Roll素材检索，当前占位）。
内部耦合：extractor.py 与 video_processor/utils.py、video_processor/schemas.py 存在潜在协作关系；data_builder.py 依赖 PDF 提取结果；前端契约约束后端输出。

graph LR
REQ["requirements.txt"] --> GEM["google-generativeai"]
REQ --> OAI["openai"]
REQ --> FFPY["ffmpeg-python"]
REQ --> REQ["requests"]
EX["extractor.py"] --> GEM
EX --> OAI
EX --> FFPY
VU["video_processor/utils.py"] --> FFPY
VS["video_processor/schemas.py"] --> RP["render-props-types.ts"]
DB["data_builder.py"] --> RP

图表来源

章节来源

requirements.txt

性能考量

API成本控制：视频/音频上传与转写会产生Token/调用费用，应优先选择合适粒度（电影级摘要 vs 秒级/词级时间戳）以平衡精度与成本。
媒体处理优化：音频提取采用流复制（stream copy）可避免重编码，提升速度；批量处理时注意并发与资源限制。
缓存与复用：翻译与API调用结果可缓存，减少重复请求；视频片段与B-Roll素材可本地缓存以降低网络开销。

故障排查指南

API密钥缺失
- 现象：初始化PDF/视频提取器时报错。
- 排查：确认环境变量是否正确设置；检查.env文件是否存在且包含有效密钥。
FFmpeg/ffprobe不可用
- 现象：获取视频时长或提取音频失败。
- 排查：安装FFmpeg/ffprobe并加入PATH；使用工具函数检测可用性。
PDF格式不兼容或加密
- 现象：PDF解析失败或返回空数据。
- 排查：确认PDF可读且未加密；若为扫描版PDF，考虑OCR预处理；优先使用大模型直接解析PDF而非本地库。
视频/音频质量差导致转写不准
- 现象：转写文本与实际内容不符。
- 排查：提高音频采样率、清理背景噪音；必要时人工校正关键片段。

章节来源

结论

当前数据提取模块处于占位阶段，PDF与视频提取逻辑尚未实现，但已明确技术栈与数据契约。
建议优先完成以下工作：PDF解析（Gemini API）、视频转写（Whisper）、FFmpeg工具链完善、结构化输出规范化（schemas）。
完成后，数据将严格遵循前端契约，无缝衔接财务模拟与视频渲染流程。

附录

接口调用方式与错误处理（基于现有占位实现）

PDF提取
- 函数入口：extract_pdf_data
- 类入口：PDFExtractor.extract
- 错误处理：当前抛出未实现异常，需补充API调用与参数校验。
视频提取
- 函数入口：extract_video_data
- 类入口：VideoExtractor.extract
- 错误处理：当前抛出未实现异常，需补充FFmpeg与Whisper调用。
FFmpeg工具
- 获取时长：get_video_duration
- 提取音频：extract_audio
- 切片视频：slice_video
- 检测安装：check_ffmpeg_installed

章节来源

扩展自定义解析器的方法

PDF解析器扩展
- 在PDFExtractor中实现extract方法，调用Gemini API并按预期字段返回。
- 建议：增加参数校验、响应解析与schema验证。
视频解析器扩展
- 在VideoExtractor中实现extract方法，调用Whisper API并解析时间戳。
- 建议：支持多粒度（电影级/秒级/词级）与多策略（视频直传/音频转写）。
媒体处理扩展
- 在video_processor/utils.py中新增工具函数，统一管理FFmpeg命令与错误处理。
契约一致性
- 保持输出结构与frontend/src/render-props-types.ts一致，避免前后端不匹配。

章节来源

16 KiB Raw Permalink Blame History Unescape Escape

数据提取

目录

简介

项目结构

核心组件

架构总览

详细组件分析

PDF 提取流程与内部表示

视频元数据与转写流程（FFmpeg + Whisper）

视频结构化模式（schemas.py）

数据契约与前后端衔接

依赖关系分析

性能考量

故障排查指南

结论

附录

接口调用方式与错误处理（基于现有占位实现）

扩展自定义解析器的方法

16 KiB

Raw Permalink Blame History