DEVELOPER_GUIDE.md

Lec2Note 开发者指南 (Developer Guide)

1. 项目概述

Lec2Note 致力于提供一个端到端的 “视频讲座自动生成笔记” 解决方案。
通过多模态分析技术，深度融合视频画面与音频内容，生成 图文并茂、结构清晰 的笔记。

1.1 核心流程

1. 基于字幕的精细分块：将 ASR 生成的每一句话视为独立的 micro-chunk，并在句末时间点精确截取关键帧。
2. 分层合并策略
   • 阶段一·视觉预合并：仅根据视觉相似度合并连续 micro-chunks。
   • 阶段二·语义合并：在视觉合并结果上再根据文本语义相似度合并。
3. 多模态信息提取与采样
   • 文本：拼接主题块包含的全部字幕文本。
   • 图像：采样该主题块的关键帧（最多 6 张）。
4. 分块笔记生成：调用多模态 LLM，为每个主题块生成独立笔记。
5. 全局笔记合成：再次调用 LLM，对所有分块笔记进行整合、去重与润色。

1.2 目标使用场景

• 学术课程录播
• 会议 / 研讨会记录
• 企业内部培训视频

---

2. 技术栈

层级	主要技术	说明
语言	Python 3.9+	主代码基于 Python
视频 / 图像处理	OpenCV, Pillow	截图、图像处理、图像相似度计算 (SSIM / pHash)
OCR	PaddleOCR / Tesseract	提取关键帧中的幻灯片文字
ASR	Whisper / Faster-Whisper	生成句子级时间戳
语义分析	Sentence Transformers	计算文本语义相似度
LLM	Gemini-2.5-pro	多模态模型，生成笔记
Web 框架	FastAPI	提供 RESTful & WebSocket 服务
任务编排	Prefect / Celery	批处理与重试机制
数据库	SQLite (dev) / PostgreSQL (prod)	存储元数据与任务状态
容器	Docker & Docker Compose	一键部署

---

3. 目录结构与模块划分

Lec2Note/
├── docs/                    # 设计文档 & 会议记录
├── lec2note/                # 源码包 (Python)
│   ├── ingestion/           # 音频处理 & ASR
│   ├── vision/              # 视频画面处理模块
│   │   ├── frame_extractor.py
│   │   ├── image_comparator.py
│   │   ├── image_sampler.py
│   │   └── ocr_processor.py
│   ├── segmentation/        # 分块与合并模块
│   │   ├── sentence_chunker.py
│   │   └── chunk_merger.py
│   ├── processing/          # 多模态信息融合与 LLM 生成
│   ├── synthesis/           # 全局笔记整合与导出
│   ├── assets/              # 静态模板 (Markdown/HTML)
│   └── api/                 # FastAPI 路由
├── scripts/                 # CLI 脚本 & 任务调度
├── tests/                   # PyTest 单元与集成测试
├── Dockerfile
├── docker-compose.yml
└── README.md

---

4. 核心功能说明

4.1 分块与合并策略

1. 生成句块：sentence_chunker.run() 根据 ASR 输出生成 {start, end, text, keyframe_path} 的 sentence_chunks。
2. 分层合并：chunk_merger.run() 先视觉预合并，再语义合并，得到 topic_chunks。
3. 关键帧采样：image_sampler.sample() 均匀采样关键帧，最多保留 6 张。
4. 输出：最终得到包含文本及代表性截图的 final_chunks。

4.2 信息提取 (Extraction)

对采样后的截图进行 OCR，丰富文本信息。

4.3 图文融合与生成 (Processing)

• Prompt 构建：在文本中插入 [IMAGE_n] 占位符，并附上对应图像列表。
• LLM 调用：processor.generate_note_chunk() 使用多模态 LLM 生成 Markdown 格式笔记。

4.4 笔记合成 (Synthesis)

assembler.merge() 收集所有 note_chunk 文本，构建新 Prompt，调用 LLM 进行去重、重排与润色，输出完整笔记。

4.5 API 一览

方法	路径	功能
POST	/upload	上传视频 → 返回任务 ID
GET	/status/{id}	查询任务进度
GET	/notes/{id}	获取生成的图文笔记

4.6 内部模块接口

模块	关键类 / 方法	输入	输出	说明
ingestion.whisper_runner	WhisperRunner.transcribe()	音频路径	[{start, end, text}, …]	句子级 ASR 结果
vision.frame_extractor	FrameExtractor.capture_at()	视频路径, 时间戳列表	图片路径列表	精确截图
vision.image_comparator	ImageComparator.get_similarity()	两张图片路径	相似度 (0-1)	pHash / SSIM
vision.image_sampler	ImageSampler.sample()	图片路径列表, max_n	采样后路径列表	均匀采样
segmentation.sentence_chunker	SentenceChunker.run()	字幕列表, 视频路径	sentence_chunks	生成微型块
segmentation.chunk_merger	ChunkMerger.run()	sentence_chunks	final_chunks	分层合并
processing.processor	Processor.generate_note()	final_chunk	NoteChunk	调用 LLM
synthesis.assembler	Assembler.merge()	NoteChunk 列表	Markdown/HTML	全局整合

4.7 数据格式示例

{
  "start": 0.0,
  "end": 25.4,
  "text": "欢迎来到 Lec2Note 课程。今天我们介绍多模态笔记生成。首先，我们会讲解系统的核心流程...",
  "representative_frames": [
    "frames/kf_3.20s.png",
    "frames/kf_15.80s.png",
    "frames/kf_22.10s.png"
  ]
}

4.8 健壮性：错误处理与重试

• 任务原子性：每步定义为独立任务。
• 自动重试：针对网络/LLM 失败采用指数退避重试。
• 失败隔离：单任务失败不会阻断整体流程，可记录后续排查。

---

5. 开发环境搭建

# 克隆仓库
git clone git@github.com:your_org/lec2note.git
cd lec2note

# (可选) 创建虚拟环境
python -m venv .venv && source .venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 设置环境变量
export OPENAI_API_KEY="YOUR_KEY"

# 运行单元测试
pytest -q

5.1 快速运行本地 Pipeline

python -m lec2note.scripts.run_pipeline \
    --video example.mp4 \
    --output notes.md

---

6. 部署指南

6.1 Docker Compose

docker compose up -d --build