Yuxu Ge
文章 · 2026-02-16

InsightFlow：开放认知引擎

开源技术白皮书 (Technical Whitepaper)

版本： 0.4.0 (架构冻结)
许可证： Apache 2.0
代码仓库： 暂无

1. 愿景与宣言

在人工智能泛滥的时代，摘要已经成为商品，但理解仍然昂贵。

今天的大多数 AI 工具——NotebookLM、ChatPDF——运作在对话层。它们是黑盒：绑定单一模型，锁定用户数据，产出非结构化文本流。

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

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

我们相信：

2. 核心协议：CSP

InsightFlow 的护城河不是 UI 功能。它是 CSP（认知结构协议）。

CSP 是一套开放 JSON 标准，用于描述从非结构化数据提取的认知结构。类似编程领域的 LSP（语言服务器协议），它解耦了"AI 推理"和"前端渲染"。

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

2.1 CSP 规范

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

必填字段：

可选字段：

版本协商规则：

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]（像素坐标，相对于原始关键帧分辨率）。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 关于向量嵌入

CSP 是存储和交换格式，不包含嵌入向量。向量是运行时数据，由前端或应用层按需生成，存储在本地向量库（ChromaDB / Qdrant）。

设计理由：嵌入模型频繁更换，维度和距离度量不统一。将其排除在 CSP 外，保证协议简洁性和跨工具兼容性。

若后续需要语义搜索（如"在我的笔记中搜索 Attention 机制相关内容"），应用层应在加载 CSP 时自动对 nodes[].summary 生成嵌入并建立本地索引。

3. 模型策略：API 优先

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

3.1 设计理念

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

因此：

3.2 模型网关

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 模型推荐矩阵

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

4. 要素提取管线

核心原则：视频不是原子单位；要素才是。

我们不直接将视频端到端地送给模型做总结。而是先将视频分解为独立的认知要素，再组合后送入 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 各要素处理方式

转录文稿——核心要素：

关键帧：

幻灯片 OCR：

音频：

4.3 为什么不做端到端视频理解？

端到端视频理解（直接送帧序列给多模态 LLM）很诱人，但面临明确的工程限制：

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

4.4 组合策略

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

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

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

5. 系统架构

5.1 技术栈

5.2 数据流向

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 调用）。本地模式作为可选功能：

6. 质量评估框架

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

6.1 结构完整性指标

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

6.2 语义质量评估

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

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

6.3 社区基准数据集

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

7. 路线图

Phase 1：协议与 CLI（v0.1）

目标：冻结 CSP v1.0；完成要素提取管线。

交付物：

Phase 2：播放器（v0.5 – MVP）

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

交付物：

Phase 3：工作台（v1.0）

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

交付物：

8. 已知风险

8.1 Python Sidecar 打包分发

风险等级：高

WhisperX 依赖 CTranslate2（进而依赖 CUDA 或 CPU 后端），PySceneDetect 依赖 OpenCV。完整 Python 环境 + GPU 依赖打包后膨胀至 2GB+；跨环境易崩溃（Windows DLL 缺失、macOS Metal 兼容性）。

应对策略：

8.2 Prompt 稳定性

风险等级：高

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

应对策略：

8.3 OCR 噪音

风险等级：中

视频 OCR 充满噪音（标识、字幕、水印）。未清洗就喂给 LLM，噪音淹没有效信号。

应对策略：三层去噪（相邻帧去重、区域过滤、语义过滤）见 §4.2。

9. 竞品对比

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

10. 贡献指南

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

贡献方向

Issue 标签体系

11. 闭幕辞

InsightFlow 不是学习的替代品。它通过要素提取和结构化推理消除学习中的摩擦。

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

加入我们。为你的第二大脑构建引擎。

© 2026 Yuxu Ge ·