InsightFlow: The Open Cognitive Engine

开源技术白皮书 (Technical Whitepaper)

Version: 0.4.0 (Architecture Freeze)
License: Apache 2.0
Repository: 暂无

1. 愿景与宣言 (Vision & Manifesto)

在人工智能泛滥的今天，"总结 (Summarization)"已经成为廉价的商品，但"理解 (Understanding)"依然昂贵。

目前的 AI 工具（如 NotebookLM）大多停留在"聊天"层面。它们是黑盒，绑定了特定的模型，锁定了用户的数据，且输出非结构化的文本流。

InsightFlow 是 "知识领域的 ffmpeg" ：一个开源、模型中立的认知引擎。

不同于 ffmpeg 的确定性转换，InsightFlow 坦然拥抱 LLM 推理的概率性：同一份输入在不同模型下会产生不同质量的认知结构。我们通过 model_fingerprint 标记每次输出的模型来源，并提供质量评估框架，让用户自主判断和选择。

我们相信：

结构优于文本 (Structure > Text)： 真正的理解来源于建立知识的拓扑结构（思维导图），而非线性的文字摘要。
主动优于被动 (Active > Passive)： 学习不仅仅是观看，更是测试与回顾。系统必须生成交互式习题。
要素提取优于端到端 (Elements > End-to-End)： 视频不是原子单位。音频、关键帧、文稿才是可被独立处理和组合的认知原料。
主权优于便利 (Sovereignty > Convenience)： 用户拥有选择模型和掌控数据的权利。

2. 核心协议：CSP (The Protocol)

InsightFlow 的核心护城河不是某个 UI 功能，而是 CSP (Cognitive Structure Protocol)。

CSP 是一套基于 JSON 的开放标准，用于描述从非结构化数据中提取出的认知结构。它类似于编程领域的 LSP (Language Server Protocol)——解耦了"AI 推理层"和"前端渲染层"。

设计原则： 任何第三方开发者仅凭 CSP 规范文档，就能独立实现一个兼容的解析器或渲染器。这是协议"可冻结"的标准。

2.1 CSP 规范要点

CSP 规范采用 RFC 风格的关键词定义（MUST / SHOULD / MAY）：

必填字段 (MUST)：

meta.source_uri：数据来源标识
meta.model_fingerprint：生成模型标识，格式为 provider/model-name
meta.csp_version：协议版本号（用于向前兼容）
knowledge_graph.root_id：图谱根节点 ID
knowledge_graph.nodes[].id、label、summary、children

可选字段 (MAY)：

nodes[].timestamp_start / timestamp_end：时间锚点（纯音频或文档输入时可省略）
nodes[].visual_anchor：视觉锚定信息（仅当输入包含视频关键帧时存在）
quiz_layer：认知测试层（可独立生成，也可不生成）
quality：质量评估元数据

版本协商规则：

客户端 MUST 检查 csp_version 字段。
当遇到高于自身支持版本的 CSP 文档时，SHOULD 忽略未知字段并正常解析已知字段（向前兼容），MUST NOT 因未知字段而报错。
编辑器在修改并保存 CSP 文档时，MUST 保留自身不识别的未知字段（Round-Trip Safety）。即：v1.0 编辑器打开 v1.1 文件，修改后保存，不得丢失 v1.1 新增的字段。

2.2 CSP 数据结构示例

{
  "meta": {
    "csp_version": "1.0",
    "source_uri": "local://lectures/transformer.mp4",
    "source_type": "video",
    "model_fingerprint": "openai/gpt-4o",
    "generated_at": "2025-01-15T10:30:00Z",
    "elements_used": ["transcript", "keyframes"]
  },
  "knowledge_graph": {
    "root_id": "root_01",
    "nodes": [
      {
        "id": "node_05",
        "label": "Self-Attention Mechanism",
        "summary": "核心机制：计算序列中每个元素与其他元素的相关性...",
        "depth": 2,
        "timestamp_start": 124.5,
        "timestamp_end": 180.2,
        "visual_anchor": {
          "frame_time": 125.0,
          "ocr_text": "Attention(Q, K, V) = softmax(QK^T / sqrt(d_k))V",
          "bbox": [120, 80, 640, 200]
        },
        "children": ["node_06", "node_07"]
      }
    ]
  },
  "quiz_layer": [
    {
      "id": "quiz_01",
      "question": "为什么在 Self-Attention 中需要 Scale 操作？",
      "type": "conceptual",
      "linked_node_id": "node_05",
      "options": [
        "防止梯度消失",
        "防止点积结果过大导致 softmax 饱和",
        "减少计算量"
      ],
      "correct_index": 1,
      "explanation": "当维度 d_k 较大时，点积的方差也会变大..."
    }
  ],
  "quality": {
    "node_count": 15,
    "max_depth": 4,
    "quiz_count": 8,
    "coverage_ratio": 0.85
  }
}

关于 visual_anchor.bbox： 格式为 [x, y, width, height]（像素坐标，相对于原始关键帧分辨率）。MAY 字段，v1.0 阶段不强制要求，但预留该字段以支持未来的播放器内高亮框选功能。

2.3 CSP JSON Schema

完整的 JSON Schema 定义文件将作为独立文档 CSP_SPEC.md 发布，并附带 csp-schema.json 供自动校验。Phase 1 将提供 CSP 验证器 CLI 工具：

insightflow validate graph.json
# ✓ CSP v1.0 compliant
# ✓ 15 nodes, max depth 4
# ⚠ 2 nodes missing timestamp (acceptable for audio-only input)

2.4 关于向量索引 (Embedding)

CSP 是一个存储与交换格式，不包含向量索引数据。Embedding 向量属于运行时数据，由前端或应用层按需生成并存储在本地向量库（ChromaDB / Qdrant）中。

设计理由：Embedding 模型可能频繁更换，向量维度和距离度量方式也不统一。将其排除在 CSP 之外，保证了协议的简洁性和跨工具兼容性。

如果未来需要语义搜索功能（如"在我的所有笔记中搜索与 Attention 机制相关的内容"），应用层 SHOULD 在加载 CSP 时自动对 nodes[].summary 生成 Embedding 并建立本地索引。

3. 模型策略：API 优先 (Model Strategy: API-First)

InsightFlow 采用 API 优先、本地扩展 的模型策略。

3.1 设计理念

LLM 推理的核心瓶颈不在本地计算，而在模型质量和上下文窗口。对于绝大多数用户（尤其是学生和研究者），云端 API 提供了最佳的性价比和最稳定的输出质量。

因此：

默认路径： 通过 API 调用云端模型（OpenAI / Anthropic / DeepSeek 等）。开箱即用，无需 GPU。
扩展路径： 通过 Ollama 接入本地模型。作为可选插件，适用于隐私敏感场景或离线环境。
不做的事： InsightFlow 不内置模型权重，不管理 GPU 资源，不做模型训练或微调。

3.2 模型网关 (Model Gateway)

通过 LiteLLM 实现统一接口，支持 100+ 模型提供商：

# config.yaml
default_provider: "openai"

strategies:
  structuring:
    primary: "openai/gpt-4o"
    fallback: "deepseek/deepseek-chat"
  quiz_generation:
    primary: "anthropic/claude-sonnet-4-5-20250514"
    fallback: "openai/gpt-4o-mini"

# 可选：本地模型扩展
extensions:
  ollama:
    enabled: false
    endpoint: "http://localhost:11434"
    models:
      structuring: "llama3:8b-instruct"

3.3 模型推荐矩阵

使用场景	推荐模型	备注
结构化提取 (Structuring)	GPT-4o / Claude Sonnet	JSON 输出稳定性最高
长文本分析	DeepSeek-V2 / Claude Sonnet	高性价比 + 长上下文
习题生成 (Quiz)	GPT-4o / Claude Sonnet	需要强推理能力
本地隐私 (扩展)	Llama 3 8B via Ollama	需自行承担质量差异

4. 要素提取管线 (Element Extraction Pipeline)

InsightFlow 的核心设计原则：视频不是原子输入，要素才是。

我们不直接将视频"喂给"模型做端到端总结。而是先将视频分解为独立的认知要素（Elements），再将要素组合后送入 LLM 进行结构化推理。

4.1 要素类型

┌──────────────┐
│   Video      │
│   (.mp4)     │
└──────┬───────┘
       │ Extract
       ▼
┌──────────────────────────────────────────┐
│  Elements (可独立处理、存储、组合)          │
│                                          │
│  📝 Transcript  (WhisperX → .srt/.json)  │
│  🖼️ Keyframes   (场景切换检测 → .jpg)      │
│  📄 Slide OCR   (关键帧 OCR → .txt)       │
│  🎵 Audio       (原始音轨 → .wav)         │
└──────────────────┬───────────────────────┘
                   │ Compose & Reason (LLM API)
                   ▼
            ┌─────────────┐
            │  CSP JSON   │
            └─────────────┘

4.2 各要素的处理方式

Transcript（转录文稿）——核心要素：

工具：WhisperX（基于 CTranslate2，支持单词级时间戳和说话人分离）
输出：带时间戳的 SRT/JSON 格式文稿
这是最核心的要素，几乎所有结构化推理都基于它

Keyframes（关键帧）：

工具：场景切换检测（PySceneDetect）+ 固定间隔采样
输出：带时间戳的图片序列
用途：为思维导图节点提供视觉上下文

Slide OCR（幻灯片文字提取）：

工具：对关键帧执行 OCR（Tesseract / PaddleOCR）
清洗管线 (Denoising)： 视频 OCR 的原始输出噪音极高（台标、字幕条、弹幕、水印）。提取后必须经过去噪处理：
- 相邻帧去重： 计算连续帧 OCR 文本的编辑距离（Levenshtein），相似度 > 90% 的帧丢弃重复文本
- 区域过滤： 排除固定位置的文本区域（如画面顶部/底部的台标和字幕条）
- 语义过滤： 过滤与主题无关的短文本片段（如"点赞""关注"）
输出：经清洗的、带坐标和时间戳的文字块
用途：捕获视频中"说了但没写"和"写了但没说"的信息差

Audio（原始音轨）：

工具：ffmpeg 提取
输出：.wav 文件
用途：为 WhisperX 提供输入；未来可做情感分析等扩展

4.3 为什么不做端到端视频总结？

端到端视频理解（直接将视频帧序列送入多模态大模型）是一个令人兴奋的方向，但目前存在明确的工程限制：

成本： GPT-4o Vision 处理一小时视频的关键帧，API 费用可能超过 $10
上下文窗口： 大量帧 + 转录文稿经常超出模型上下文限制
可控性： 端到端模型的输出难以调试和复现

因此，端到端视频理解被列为 Phase 3 的实验性功能。Phase 1-2 专注于要素提取 + 文本推理的成熟管线。

4.4 组合策略 (Composition Strategy)

从要素到 CSP 的推理过程采用分层组合：

Step 1: Transcript → 粗粒度结构（章节划分、主题识别）
Step 2: Transcript + Slide OCR → 细粒度结构（知识点、公式、定义）
Step 3: Structure + Keyframes → 视觉锚定（为节点关联对应画面）
Step 4: Structure → Quiz 生成（基于结构化知识点出题）

每一步都是独立的 LLM 调用，可以单独调试、缓存和替换模型。

5. 系统架构 (System Architecture)

5.1 技术栈选型 (The Stack)

Frontend： Tauri v2 + Next.js 14
- Vidstack 播放器 + React Flow 脑图
- 通过 Tauri Rust 桥接层打包为跨平台原生应用
- 注：核心 UI 体积约几十 MB。AI 运行时（Python 环境 + 模型依赖）需额外安装，详见 §8 已知风险
Backend： Python Sidecar
- 被 Tauri 进程管理的独立 Python 进程
- 负责要素提取、AI 编排和 CSP 生成
- 原因：AI 生态（WhisperX, LiteLLM, PySceneDetect）在 Python 上是一等公民
AI Gateway： LiteLLM
- 统一接口层，支持 100+ 模型提供商
ASR Engine： WhisperX
- 强制对齐（Forced Alignment），毫秒级单词时间戳

5.2 数据流向 (Data Flow)

User drags video ──→ Python Sidecar
                        │
                        ├── [Extract] WhisperX → Transcript
                        ├── [Extract] PySceneDetect → Keyframes
                        ├── [Extract] OCR + Denoise → Slide Text
                        │
                        ├── [Compose] LLM (API) → CSP JSON
                        │
                        └── [Output] CSP JSON ──→ Tauri Frontend
                                                    │
                                                    ├── React Flow (Mind Map)
                                                    ├── Vidstack (Player)
                                                    └── Quiz Cards

5.3 离线 / 本地模式说明

默认模式下，InsightFlow 需要网络连接（用于 API 调用）。本地模式作为扩展功能提供：

要素提取层（WhisperX, OCR）： 始终在本地运行，无需网络
LLM 推理层： 默认使用云端 API；启用 Ollama 扩展后可完全离线
VLM 视觉分析： 仅在云端 API 模式下可用（本地 VLM 对显存要求高，不作为标准功能）

6. 质量评估框架 (Quality Evaluation)

CSP 的价值取决于输出质量。InsightFlow 提供两层质量评估机制：

6.1 结构完整性指标 (Structural Metrics)

自动计算，写入 CSP 的 quality 字段：

node_count：知识节点总数
max_depth：图谱最大深度
quiz_count：生成的习题数量
coverage_ratio：转录文稿被知识节点覆盖的比例（0-1）
orphan_nodes：无父节点的孤立节点数（应为 0）

6.2 语义质量评估 (Semantic Evaluation)

通过 LLM-as-Judge 模式进行自动评估（可选，需额外 API 调用）：

Faithfulness： 知识节点是否忠于原始内容（无幻觉）
Completeness： 关键概念是否被覆盖
Hierarchy： 父子节点关系是否合理

评估结果附加在 CSP 的 quality.semantic_eval 字段中。

6.3 社区基准数据集

Phase 2 将发布一个开源评估数据集：

10+ 个不同学科的视频（数学、编程、历史、生物）
人工标注的参考 CSP（Gold Standard）
标准化评估脚本

7. 路线图 (Roadmap)

Phase 1: The Protocol & CLI (v0.1)

目标： 定义 CSP v1.0 规范，打通要素提取管线。

交付物：

CSP_SPEC.md + csp-schema.json（协议规范与 JSON Schema）
insightflow Python 库（pip install）
CLI 工具：
- insightflow ingest <video> --model openai/gpt-4o → 一键完成提取 + 推理，输出 CSP JSON
- insightflow extract <video> → 仅提取要素（transcript, keyframes, ocr）
- insightflow reason <elements-dir> --model openai/gpt-4o → 仅对已提取要素进行结构化推理
- insightflow validate <csp.json> → 校验 CSP 合规性
Docker 镜像（含 WhisperX + 依赖）
Phase 1 不尝试打包 GUI，CLI + Docker 是唯一分发方式

Phase 2: The Player (v0.5 - MVP)

目标： 第一个可用的桌面端 GUI + 质量评估基准。

交付物：

基于 Tauri 的桌面应用（需用户自行安装 Python 环境，类似 Stable Diffusion WebUI 的安装模式）
核心交互：左侧播放器 (Vidstack) + 右侧思维导图 (React Flow)
点击脑图节点跳转视频时间点
社区基准评估数据集
基础 Quiz 生成与交互界面

Phase 3: The Workstation (v1.0)

目标： 完整的学习工作台 + 生态系统。

交付物：

Plugin System：社区插件（Anki 导出、Obsidian 同步、Notion 集成）
端到端视频理解（实验性）：直接使用多模态模型处理视频帧
Visual Search：搜索视频画面中的内容
多语言支持：自动翻译与跨语言对齐
Collaborative Mode：多人协作编辑知识图谱

8. 已知风险与技术挑战 (Known Risks)

本节列出已识别的工程风险，团队对此保持清醒认知。

8.1 Python Sidecar 打包分发

风险等级：高

WhisperX 依赖 CTranslate2（进而依赖 CUDA 或 CPU 后端），PySceneDetect 依赖 OpenCV。完整的 Python 环境 + GPU 依赖打包后可能膨胀至 2GB+，且在不同用户环境（Windows DLL 缺失、macOS 的 Metal 兼容性）下容易崩溃。

应对策略：

Phase 1 完全回避此问题：仅提供 CLI + Docker，不做 GUI 打包
Phase 2 采用"用户自装 Python 环境"模式（参考 Stable Diffusion WebUI 的 webui.sh 一键脚本）
长期探索 Conda 环境锁定或 Nix 可复现构建

8.2 Prompt 稳定性

风险等级：高

让不同能力等级的 LLM（从 GPT-4o 到 Llama 3 8B）都稳定输出合规的 CSP JSON，是最难的工程挑战。弱模型容易输出格式错误、字段缺失或产生幻觉。

应对策略：

CSP 验证器作为硬性关卡：不合规的 JSON 直接拒绝并重试
为不同能力等级的模型维护独立的 Prompt 模板
社区贡献的 Prompt 需附带模型兼容性标签

8.3 OCR 噪音

风险等级：中

视频 OCR 的原始输出充满噪音（台标、弹幕、水印）。如果不加清洗就喂给 LLM，噪音会淹没有效信号。

应对策略： 已在要素提取管线中设计三层去噪（相邻帧去重、区域过滤、语义过滤），详见 §4.2。

9. 竞品对比 (Comparison)

特性	NotebookLM	ChatPDF / Wrappers	InsightFlow
核心隐喻	聊天机器人	文档阅读器	认知引擎
输入处理	端到端黑盒	文本提取	要素提取 + 组合推理
数据隐私	云端（必须上传）	云端/混合	要素本地提取，推理可选云/本地
输出产物	文本摘要	文本问答	结构化图谱（CSP 协议）
模型选择	Gemini Only	厂商绑定	API 优先 + 本地扩展
质量评估	无	无	结构 + 语义双重评估
扩展性	无	弱	开源插件系统

10. 贡献指南 (Contributing)

InsightFlow 是社区驱动的项目。我们欢迎以下方向的贡献：

如何开始

# 1. Clone
git clone https://github.com/insightflow-org/insightflow.git
cd insightflow

# 2. 安装开发依赖
pip install -e ".[dev]"

# 3. 运行测试
pytest tests/

# 4. 一键处理视频
insightflow ingest examples/sample.mp4 --model openai/gpt-4o

# 5. 或分步执行
insightflow extract examples/sample.mp4 --output-dir ./elements
insightflow reason ./elements --model openai/gpt-4o --output graph.json
insightflow validate graph.json

贡献方向

CSP 规范讨论： 在 Issues 中参与协议设计，提出字段建议或边界情况
Prompt Engineering： 针对不同学科（数学、编程、历史）调优结构化提取的提示词
模型适配： 让更多模型（特别是开源模型）稳定输出合规的 CSP JSON
前端开发： React Flow 脑图渲染优化、Vidstack 播放器集成
评估数据集： 为不同学科贡献标注过的参考 CSP
插件开发（Phase 2+）： Anki / Obsidian / Notion 导出器

Issue 标签体系

csp-spec：协议规范相关
extraction：要素提取管线
reasoning：LLM 结构化推理
frontend：UI 与交互
good-first-issue：适合新贡献者的入门任务

11. 结语

InsightFlow 不是为了取代人类的学习，而是为了通过要素提取和结构化推理，消除学习过程中的摩擦力。

我们不生产知识，我们是知识的结构化引擎。

Join us. Build the engine for your second brain.