| # 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. 目录结构与模块划分 | |
| ```text | |
| 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 数据格式示例 | |
| ```json | |
| { | |
| "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. 开发环境搭建 | |
| ```bash | |
| # 克隆仓库 | |
| 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 | |
| ```bash | |
| python -m lec2note.scripts.run_pipeline \ | |
| --video example.mp4 \ | |
| --output notes.md | |
| ``` | |
| --- | |
| ## 6. 部署指南 | |
| ### 6.1 Docker Compose | |
| ```bash | |
| docker compose up -d --build | |
| ``` |