From ae8861cf9de532ee4ac393edb7ccf94544dd8015 Mon Sep 17 00:00:00 2001 From: Momentry Studio Date: Thu, 15 Oct 2026 12:37:19 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20Pipeline=20?= =?UTF-8?q?=E5=9B=9B=E9=98=B6=E6=AE=B5=E4=B8=AD=E6=96=87=E8=AF=B4=E6=98=8E?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增文档: 1. PIPELINE_STAGES_EXPLANATION.md - 详细说明 - 四阶段总览 - 各阶段详细说明 - 进度计算方式 - 依赖关系 - 用户操作指南 - 常见问题 2. PIPELINE_STAGES_QUICK_REF.md - 快速参考 - 简洁表格总览 - 关键信息快速查看 - 进度计算公式 - 使用提示 四阶段说明: 1. 处理器 (Processors) - 30% - 原始媒体分析 - ASR、人脸检测、OCR等 2. 知识图谱 (Knowledge Graph) - 35% - 构建人物关系网络 - TKG Nodes + Edges 3. 片段提取 (Moment Extraction) - 6% - AI 内容理解 - 场景分析、片段分割 4. 数据整合 (Integration) - 29% - 数据入库存储 - 人脸追踪、去重 用途: - 用户理解处理流程 - 开发者参考架构 - 技术文档支持 语言: 中文 --- docs/PIPELINE_STAGES_EXPLANATION.md | 478 ++++++++++++++++++++++++++++ docs/PIPELINE_STAGES_QUICK_REF.md | 130 ++++++++ 2 files changed, 608 insertions(+) create mode 100644 docs/PIPELINE_STAGES_EXPLANATION.md create mode 100644 docs/PIPELINE_STAGES_QUICK_REF.md diff --git a/docs/PIPELINE_STAGES_EXPLANATION.md b/docs/PIPELINE_STAGES_EXPLANATION.md new file mode 100644 index 0000000..50f3f9c --- /dev/null +++ b/docs/PIPELINE_STAGES_EXPLANATION.md @@ -0,0 +1,478 @@ +# Pipeline 四阶段进度说明 + +**更新时间**: 2026-10-12 +**版本**: v0.1.0 + +--- + +## 📊 四阶段总览 + +Momentry Studio 的视频处理流程分为四个主要阶段，每个阶段负责不同的处理任务： + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Pipeline 处理流程 │ +└─────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 阶段 1: 处理器 (Processors) - 30% │ +│ 原始媒体分析：ASR、人脸检测、OCR、姿态估计等 │ +└─────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 阶段 2: 知识图谱 (Knowledge Graph) - 35% │ +│ 构建人物关系图、场景关联、对话网络 │ +└─────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 阶段 3: 片段提取 (Moment Extraction) - 6% │ +│ 智能片段识别、场景理解、关键时刻提取 │ +└─────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ 阶段 4: 数据整合 (Integration) - 29% │ +│ 数据入库、人脸追踪、去重、最终整合 │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## 📝 各阶段详细说明 + +### 阶段 1: 处理器 (Processors) + +**权重**: 30% + +**状态图标**: +- ✓ (绿色): 已完成 +- ○ (蓝色): 处理中 +- ✗ (红色): 失败 +- ○ (灰色): 等待中 + +--- + +#### 功能说明 + +**原始媒体分析阶段**，对视频文件进行基础分析，提取原始数据。 + +**包含的处理器**: +- **ASR (语音识别)**: 将视频中的语音转换为文字 +- **FACE (人脸检测)**: 检测视频中的人脸位置和特征 +- **OCR (文字识别)**: 识别视频画面中的文字内容 +- **POSE (姿态估计)**: 分析人物的姿态和动作 +- **APPEARANCE (外观检测)**: 检测人物的外观特征 +- **CUT (镜头切换)**: 识别视频的场景切换点 + +--- + +#### 进度含义 + +- **0%**: 未开始处理 +- **50%**: 部分处理器完成 +- **100%**: 所有处理器完成 + +--- + +#### 示例场景 + +``` +○ Processors: 0% +→ 正在等待处理开始 + +○ Processors: 60% +→ ASR 完成，FACE 处理中 + +✓ Processors: 100% +→ 所有处理器完成，可以进入下一阶段 +``` + +--- + +### 阶段 2: 知识图谱 (Knowledge Graph) + +**权重**: 35% + +**状态图标**: +- ✓ (绿色): 已完成 +- ○ (蓝色): 处理中 +- ✗ (红色): 失败 +- ○ (灰色): 等待中 + +--- + +#### 功能说明 + +**知识图谱构建阶段**，将处理器提取的原始数据构建成结构化的知识图谱。 + +**包含的步骤**: +- **TKG Nodes (图节点构建)**: + - 人物节点 (face_track_nodes) + - 物品节点 (object_nodes) + - 对话节点 (text_region_nodes) + +- **TKG Edges (图边构建)**: + - 人物关系 (face_face_edges) + - 共现关系 (co_occurrence_edges) + - 说话关系 (speaker_face_edges) + +--- + +#### 进度含义 + +- **0%**: 未开始构建 +- **50%**: 节点构建完成，边构建中 +- **100%**: 知识图谱构建完成 + +--- + +#### 示例场景 + +``` +○ Knowledge Graph: 0% +→ 等待处理器阶段完成 + +○ Knowledge Graph: 50% +→ 人物节点构建完成，正在建立人物关系 + +✓ Knowledge Graph: 100% +→ 知识图谱完整构建，可以识别视频中的人物关系 +``` + +--- + +#### 实际应用 + +**知识图谱的作用**: +- 识别视频中出现的所有人物 +- 分析人物之间的关系 +- 追踪人物在视频中的出现轨迹 +- 支持人脸搜索和身份识别 + +--- + +### 阶段 3: 片段提取 (Moment Extraction) + +**权重**: 6% + +**状态图标**: +- ✓ (绿色): 已完成 +- ○ (蓝色): 处理中 +- ✗ (红色): 失败 +- ○ (灰色): 等待中 + +--- + +#### 功能说明 + +**智能片段识别阶段**，使用 AI 模型识别视频中的关键时刻和场景内容。 + +**包含的步骤**: +- **VLM Summary (视觉语言模型总结)**: + - 分析整个视频的内容 + - 生成视频摘要 + +- **Scene VLM (场景理解)**: + - 分析每个场景的内容 + - 识别场景中的人物、物品、动作 + +- **Moment Chunks (片段分割)**: + - 将视频分割成有意义的片段 + - 标记每个片段的关键信息 + +--- + +#### 进度含义 + +- **0%**: 未开始 AI 分析 +- **33%**: 部分场景分析完成 +- **100%**: 所有场景和片段分析完成 + +--- + +#### 示例场景 + +``` +○ Moment Extraction: 0% +→ 等待知识图谱构建完成 + +○ Moment Extraction: 66% +→ VLM 总结完成，场景理解中 + +✓ Moment Extraction: 100% +→ 视频内容完全理解，可以回答关于视频的问题 +``` + +--- + +#### 实际应用 + +**片段提取的作用**: +- 支持自然语言搜索视频内容 +- 快速定位关键场景 +- 理解视频中的事件和情节 +- 提供智能问答功能 + +--- + +### 阶段 4: 数据整合 (Integration) + +**权重**: 29% + +**状态图标**: +- ✓ (绿色): 已完成 +- ○ (蓝色): 处理中 +- ✗ (红色): 失败 +- ○ (灰色): 等待中 + +--- + +#### 功能说明 + +**数据整合与入库阶段**，将所有处理结果整合并存储到数据库。 + +**包含的步骤**: +- **Rule1 Ingestion (规则1入库)**: + - PostgreSQL 数据库入库 + - 存储句子块和关系数据 + +- **Rule2 Ingestion (规则2入库)**: + - Qdrant 向量数据库入库 + - 存储人脸和文本向量 + +- **Face Tracing (人脸追踪)**: + - 追踪人脸在视频中的轨迹 + - 建立人脸出现序列 + +- **Face Dedup (人脸去重)**: + - 去除重复的人脸检测结果 + - 合并同一人的多次检测 + +--- + +#### 进度含义 + +- **0%**: 未开始数据整合 +- **50%**: 部分数据已入库 +- **100%**: 所有数据整合完成 + +--- + +#### 示例场景 + +``` +○ Integration: 0% +→ 等待所有分析完成 + +○ Integration: 75% +→ PostgreSQL 入库完成，Qdrant 入库中 + +✓ Integration: 100% +→ 所有数据已整合，视频处理完全完成 +``` + +--- + +#### 实际应用 + +**数据整合的作用**: +- 使视频数据可搜索 +- 支持快速查询 +- 提供数据持久化 +- 支持跨视频关联 + +--- + +## 📊 进度计算说明 + +### 总体进度计算 + +**计算公式**: +``` +总体进度 = (阶段1进度 × 30%) + (阶段2进度 × 35%) + (阶段3进度 × 6%) + (阶段4进度 × 29%) +``` + +--- + +### 计算示例 + +**示例 1: 处理器阶段完成** +``` +Processors: 100% × 30% = 30% +Knowledge Graph: 0% × 35% = 0% +Moment Extraction: 0% × 6% = 0% +Integration: 0% × 29% = 0% + +总体进度 = 30% +``` + +--- + +**示例 2: 知识图谱阶段完成** +``` +Processors: 100% × 30% = 30% +Knowledge Graph: 100% × 35% = 35% +Moment Extraction: 0% × 6% = 0% +Integration: 0% × 29% = 0% + +总体进度 = 65% +``` + +--- + +**示例 3: 全部完成** +``` +Processors: 100% × 30% = 30% +Knowledge Graph: 100% × 35% = 35% +Moment Extraction: 100% × 6% = 6% +Integration: 100% × 29% = 29% + +总体进度 = 100% +``` + +--- + +## 🔄 阶段依赖关系 + +``` +阶段 1: 处理器 + │ + ├─> 提取原始数据 + │ - 人脸位置 + │ - 语音文字 + │ - 场景切换点 + │ + └─> 必须完成后才能进入下一阶段 + +阶段 2: 知识图谱 + │ + ├─> 构建关系网络 + │ - 人物关系 + │ - 场景关联 + │ - 对话网络 + │ + └─> 必须完成后才能进入下一阶段 + +阶段 3: 片段提取 + │ + ├─> AI 内容理解 + │ - 场景分析 + │ - 片段分割 + │ - 内容总结 + │ + └─> 可以与阶段 4 并行 + +阶段 4: 数据整合 + │ + ├─> 数据入库 + │ - PostgreSQL + │ - Qdrant + │ - 人脸数据 + │ + └─> 最后阶段，完成后整个流程结束 +``` + +--- + +## 🎯 用户操作指南 + +### 查看进度 + +1. **打开 Library 页面** +2. **选择文件** +3. **右键菜单 → Pipeline Progress** +4. **查看各阶段进度** + +--- + +### 理解进度状态 + +| 图标 | 颜色 | 状态 | 说明 | +|-----|------|------|------| +| ✓ | 绿色 | 已完成 | 阶段已成功完成 | +| ○ | 蓝色 | 处理中 | 阶段正在处理 | +| ✗ | 红色 | 失败 | 阶段处理失败 | +| ○ | 灰色 | 等待中 | 阶段等待开始 | + +--- + +### 判断处理是否正常 + +**正常流程**: +``` +1. Processors 开始处理 (○ → ○) +2. Processors 完成 (✓) +3. Knowledge Graph 开始 (○) +4. 依次完成所有阶段 +``` + +**异常情况**: +``` +✗ Processors: 失败 +→ 检查错误日志 +→ 可能是视频文件问题 + +○ Processors: 长时间卡住 +→ 检查系统资源 +→ 可能是处理队列堵塞 +``` + +--- + +## 📚 相关文档 + +- **技术文档**: `docs/MARKBASE_THREE_LAYER_ARCHITECTURE.md` +- **API 文档**: `docs/ADMIN_API_REFERENCE.md` +- **部署指南**: `INSTALLATION_GUIDE.md` + +--- + +## 🆘 常见问题 + +### Q: 为什么有的阶段显示 0%？ + +**A**: 阶段按顺序执行，当前阶段必须完成后才能进入下一阶段。 + +--- + +### Q: 为什么总体进度不等于各阶段平均值？ + +**A**: 每个阶段有不同的权重，知识图谱阶段权重最高 (35%)，片段提取最低 (6%)。 + +--- + +### Q: 如何加速处理？ + +**A**: +1. 使用更高性能的硬件 +2. 减少并发处理的文件数 +3. 关闭不需要的处理器 + +--- + +### Q: 处理失败怎么办？ + +**A**: +1. 查看错误日志 +2. 检查视频文件是否损坏 +3. 检查系统资源是否充足 +4. 重新处理文件 + +--- + +## 📊 权重分配原因 + +| 阶段 | 权重 | 原因 | +|-----|------|------| +| **Processors** | 30% | 基础分析，必须完整完成 | +| **Knowledge Graph** | 35% | 核心价值，关系构建最重要 | +| **Moment Extraction** | 6% | AI 增强，可选功能 | +| **Integration** | 29% | 数据入库，保证可用性 | + +--- + +**最后更新**: 2026-10-12 +**版本**: v0.1.0 \ No newline at end of file diff --git a/docs/PIPELINE_STAGES_QUICK_REF.md b/docs/PIPELINE_STAGES_QUICK_REF.md new file mode 100644 index 0000000..aeb0781 --- /dev/null +++ b/docs/PIPELINE_STAGES_QUICK_REF.md @@ -0,0 +1,130 @@ +# Pipeline 四阶段快速参考 + +--- + +## 📊 四阶段总览 + +| 阶段 | 名称 | 权重 | 主要功能 | +|-----|------|------|---------| +| **1** | 处理器 | 30% | 原始媒体分析 | +| **2** | 知识图谱 | 35% | 关系网络构建 | +| **3** | 片段提取 | 6% | AI 内容理解 | +| **4** | 数据整合 | 29% | 数据入库存储 | + +--- + +## 🎯 阶段 1: 处理器 (Processors) + +**权重**: 30% + +**功能**: 原始媒体分析 + +**包含**: +- ASR: 语音识别 +- FACE: 人脸检测 +- OCR: 文字识别 +- POSE: 姿态估计 +- APPEARANCE: 外观检测 +- CUT: 镜头切换 + +**状态**: +- ✓ 完成 +- ○ 处理中 +- ✗ 失败 +- ○ 等待 + +--- + +## 🧠 阶段 2: 知识图谱 (Knowledge Graph) + +**权重**: 35% + +**功能**: 构建人物关系网络 + +**包含**: +- TKG Nodes: 人物/物品/对话节点 +- TKG Edges: 人物关系/共现关系 + +**应用**: +- 人物识别 +- 关系分析 +- 人脸搜索 + +--- + +## 🤖 阶段 3: 片段提取 (Moment Extraction) + +**权重**: 6% + +**功能**: AI 智能内容理解 + +**包含**: +- VLM Summary: 视频总结 +- Scene VLM: 场景理解 +- Moment Chunks: 片段分割 + +**应用**: +- 自然语言搜索 +- 关键场景定位 +- 智能问答 + +--- + +## 💾 阶段 4: 数据整合 (Integration) + +**权重**: 29% + +**功能**: 数据入库和整合 + +**包含**: +- Rule1: PostgreSQL 入库 +- Rule2: Qdrant 向量入库 +- Face Tracing: 人脸追踪 +- Face Dedup: 人脸去重 + +**应用**: +- 数据持久化 +- 快速查询 +- 跨视频关联 + +--- + +## 📈 进度计算 + +**公式**: +``` +总体进度 = 阶段1 × 30% + 阶段2 × 35% + 阶段3 × 6% + 阶段4 × 29% +``` + +**示例**: +``` +✓ Processors: 100% → 30% +✓ Knowledge Graph: 100% → 35% +○ Moment Extraction: 50% → 3% +○ Integration: 0% → 0% + +总体 = 68% +``` + +--- + +## 🔄 依赖关系 + +``` +处理器 → 知识图谱 → 片段提取 ┐ + ├→ 数据整合 + ┘ +``` + +--- + +## 📌 使用提示 + +1. **查看进度**: Library → 右键 → Pipeline Progress +2. **状态图标**: ✓ (完成) ○ (处理中) ✗ (失败) ○ (等待) +3. **处理顺序**: 按阶段依次执行 +4. **失败处理**: 查看日志，检查资源，重新处理 + +--- + +**详细说明**: `docs/PIPELINE_STAGES_EXPLANATION.md` \ No newline at end of file