MFlow02-项目学习指南

MFlow02-项目学习指南

面向Python初级开发者的快速入门文档
源码地址：https://github.com/FlowElement-ai/m_flow

🎯 核心设计思想：用一个生活场景来理解

比喻：智能图书馆记忆系统

想象一个超级智能的图书馆，它不仅仅是把书放在架子上，而是像人脑一样工作：

传统RAG系统（普通图书馆）

你问："为什么Maria在周一站会上生气？" → 图书馆员搜索所有包含"站会"、"生气"这些词的书 → 找到《如何开好每日站会》这本书 ❌ 问题：书里有这些词，但不是你想要的答案

M-flow系统（智能记忆图书馆）

你问："为什么Maria在周一站会上生气？" → 系统找到一张便利贴："Maria没被告知截止日期"（精确锚点） → 顺着这张便利贴找到所属文件夹：截止日期沟通问题（主题） → 文件夹属于：周一站会记录（完整事件包） → 返回整个事件：包含Maria的抱怨 + 周末更改截止日期的背景 ✅ 成功：通过一条证据链找到完整答案

核心区别：

• 传统系统：匹配词汇相似度（向量距离）
• M-flow：沿着证据路径推理（图上的路径成本）

🏗️ 系统架构图

┌─────────────────────────────────────────────────────────────────┐ │ M-flow 系统架构 │ └─────────────────────────────────────────────────────────────────┘ 用户输入 │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ API层 (m_flow/api/) - 对外接口 │ │ ├── add / memorize / learn - 添加记忆 │ │ ├── search / query - 检索记忆 │ │ └── ingest - 批量导入 │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 处理管线 (m_flow/pipeline/) - 数据处理流水线 │ │ ├── 文档分块 (chunking) │ │ ├── LLM信息提取 (extraction) │ │ └── 多阶段处理 (stages 1-5) │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 核心数据模型 (m_flow/core/) - 四层锥形图结构 │ │ │ │ ┌─────────┐ │ │ │ Entity │ ← 尖端：最精确的匹配点（人名、工具名） │ │ └────┬────┘ │ │ │ 属于 │ │ ┌────▼────┐ │ │ │FacetPoint│ ← 原子事实："P99目标<500ms" │ │ └────┬────┘ │ │ │ 属于 │ │ ┌────▼────┐ │ │ │ Facet │ ← 主题维度：性能目标讨论 │ │ └────┬────┘ │ │ │ 属于 │ │ ┌────▼────┐ │ │ │ Episode │ ← 底座：完整事件包（最终返回的结果） │ │ └─────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 存储适配器层 (m_flow/adapters/) - 多种后端支持 │ │ ├── 图数据库 (Neo4j, Kuzu) - 存储知识图结构 │ │ ├── 向量数据库 (Chroma, pgvector) - 向量搜索 │ │ ├── 关系数据库 (PostgreSQL) - 结构化数据 │ │ └── 缓存 (Redis, 文件系统) - 加速访问 │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 底层基础设施 │ │ ├── LLM后端 (OpenAI, Anthropic等) - 大模型调用 │ │ ├── 共享工具 (m_flow/shared/) - 日志、配置等 │ │ └── 异常处理、工具函数 │ └─────────────────────────────────────────────────────────────┘

📦 核心模块说明（7个关键模块）

1️⃣API接口层(m_flow/api/)

职责：对外提供的统一操作接口

• add/- 添加原始文档
• memorize/- 将文档转化为记忆
• learn/- 从文档中学习并存储
• search/- 检索相关记忆（核心功能）
• ingest/- 批量导入文档

为什么重要：这是你使用M-flow时直接调用的部分

2️⃣数据模型层(m_flow/core/)

职责：定义核心数据结构

• domain/models/- Episode（事件）、Facet（主题）、FacetPoint（事实点）、Entity（实体）
• models/- 图节点和边的抽象
• 锥形图的四层结构都在这里定义

为什么重要：理解数据如何被组织的关键

3️⃣处理管线(m_flow/pipeline/)

职责：将原始文档转化为图结构的处理流程

• 分解文档 → 提取信息 → 构建图节点 → 建立关系
• 包含5个阶段的处理任务
• 支持自定义管线

为什么重要：理解"数据如何进入系统"的流程

4️⃣记忆引擎(m_flow/memory/)

职责：核心记忆管理

• episodic/- 情景记忆（发生了什么事）
• procedural/- 程序记忆（如何做某事）

为什么重要：这是"记忆如何被存储和检索"的核心

5️⃣存储适配器(m_flow/adapters/)

职责：连接不同的存储后端

• graph/- 图数据库适配器（Neo4j, Kuzu等）
• vector/- 向量数据库适配器（Chroma, pgvector等）
• relational/- 关系数据库适配器（PostgreSQL）
• cache/- 缓存适配器（Redis, 文件系统）

为什么重要：支持多种数据库，你可以根据需求选择

6️⃣信息摄入(m_flow/ingestion/)

职责：处理各种来源的输入数据

• documents/- 文档处理
• chunking/- 文本分块
• web_scraper/- 网页抓取
• schema/- 数据结构定义

为什么重要：理解"各种数据如何进入系统"

7️⃣LLM集成(m_flow/llm/)

职责：与大模型的交互

• backends/- 支持多种LLM提供商
• prompts/- 提示词模板
• extraction/- 信息提取

为什么重要：理解系统如何使用大模型提取结构化信息

🎯 根据你的关注点，可以忽略这些

场景A：只关心核心检索功能（最常见）

可以忽略：

❌ m_flow-frontend/ # 前端界面（React代码） ❌ m_flow-mcp/ # MCP协议相关 ❌ m_flow-starter-kit/ # 示例项目模板 ❌ mflow_workers/ # 分布式任务处理 ❌ examples/ # 示例代码（学习后可看） ❌ docs/ # 详细文档（初学可略过） ❌ coreference/ # 指代消解（NLP高级功能） ❌ deployment/ # 部署相关 ❌ scripts/ # 辅助脚本 ❌ .github/ # CI/CD配置

应关注：

✅ m_flow/api/v1/search/ # 检索的核心逻辑 ✅ m_flow/core/ # 数据模型 ✅ m_flow/memory/episodic/ # 记忆存储和检索 ✅ m_flow/adapters/graph/ # 图数据库操作

场景B：只关心如何添加记忆

可以忽略：

❌ m_flow-frontend/ ❌ m_flow-mcp/ ❌ mflow_workers/ ❌ coreference/ ❌ deployment/

应关注：

✅ m_flow/api/v1/add/ # 添加文档接口 ✅ m_flow/api/v1/memorize/ # 记忆化处理 ✅ m_flow/ingestion/ # 数据摄入 ✅ m_flow/pipeline/ # 处理管线

场景C：只关心数据结构

可以忽略：

❌ m_flow-frontend/ ❌ m_flow-mcp/ ❌ mflow_workers/ ❌ examples/ ❌ deployment/ ❌ scripts/

应关注：

✅ m_flow/core/domain/models/ # Episode, Facet, FacetPoint, Entity ✅ m_flow/core/models/ # 图节点和边 ✅ m_flow/adapters/graph/ # 图模式定义

📚 推荐学习路径

第一步：理解概念（1-2小时）

1. 阅读README.md的前100行
2. 阅读本文档
3. 理解"锥形图"和"路径成本检索"的概念

第二步：看简单示例（1-2小时）

# 运行最简单的示例cdexamples/python/ python simple_example.py

第三步：追踪核心流程（2-3小时）

1. 从m_flow/api/v1/search/search.py开始
2. 看它如何调用m_flow/memory/episodic/
3. 理解向量搜索 + 图传播的组合

第四步：深入数据模型（2-3小时）

阅读m_flow/core/domain/models/下的文件：

• Episode.py- 事件包
• EntityType.py- 实体类型
• MemoryTriplet.py- 记忆三元组

第五步：理解存储适配器（2-3小时）

选择一个图数据库（建议从Kuzu开始，因为它是嵌入式的）：

• m_flow/adapters/graph/kuzu/adapter.py

🤔 常见疑问

Q1: 为什么需要四层结构？

A: 不同问题需要不同粒度的答案

• 宽泛问题 → Episode（完整事件）
• 中等问题 → Facet（某个主题）
• 精确问题 → FacetPoint（具体事实）
• 实体查询 → Entity（跨事件关联）

Q2: 什么是"路径成本"？

A: 想象你在找答案：

• 起点：查询匹配到的锚点（向量距离近 = 成本低）
• 中途：沿着边移动（边越相关 = 成本越低）
• 终点：到达某个Episode
• 总成本 = 起点距离 + 边成本 + 跳数惩罚
• 选择成本最低的路径 = 最相关的答案

Q3: 为什么不只用向量搜索？

A: 向量搜索的局限：

• 无法处理跨文档关联
• 无法理解文档间的结构关系
• 容易被"相似但无关"的内容干扰
• M-flow用图结构补充这些不足

📌 核心概念速查表

🚀 快速开始命令

# 1. 安装依赖pipinstall-e.# 2. 运行简单示例cdexamples/python python simple_example.py# 3. 启动Web界面（可选）python-mm_flow.api.v1.ui

最后提醒：

• 🎯 先理解概念，再看代码
• 🎯 从简单示例开始，不要一开始就深入细节
• 🎯 关注数据流动：输入 → 处理 → 存储 → 检索
• 🎯 不需要理解所有模块，专注你关心的部分

祝你学习顺利！🎉