MFlow02-项目学习指南
MFlow02-项目学习指南
面向Python初级开发者的快速入门文档
源码地址：https://github.com/FlowElement-ai/m_flow
文章目录
- MFlow02-项目学习指南
- 🎯 核心设计思想：用一个生活场景来理解
- 比喻：智能图书馆记忆系统
- 传统RAG系统（普通图书馆）
- M-flow系统（智能记忆图书馆）
- 🏗️ 系统架构图
- 📦 核心模块说明（7个关键模块）
- 1️⃣ **API接口层** (`m_flow/api/`)
- 2️⃣ **数据模型层** (`m_flow/core/`)
- 3️⃣ **处理管线** (`m_flow/pipeline/`)
- 4️⃣ **记忆引擎** (`m_flow/memory/`)
- 5️⃣ **存储适配器** (`m_flow/adapters/`)
- 6️⃣ **信息摄入** (`m_flow/ingestion/`)
- 7️⃣ **LLM集成** (`m_flow/llm/`)
- 🎯 根据你的关注点，可以忽略这些
- 场景A：**只关心核心检索功能**（最常见）
- 场景B：**只关心如何添加记忆**
- 场景C：**只关心数据结构**
- 📚 推荐学习路径
- 第一步：理解概念（1-2小时）
- 第二步：看简单示例（1-2小时）
- 第三步：追踪核心流程（2-3小时）
- 第四步：深入数据模型（2-3小时）
- 第五步：理解存储适配器（2-3小时）
- 🤔 常见疑问
- Q1: 为什么需要四层结构？
- Q2: 什么是"路径成本"？
- Q3: 为什么不只用向量搜索？
- 📌 核心概念速查表
- 🚀 快速开始命令
🎯 核心设计思想：用一个生活场景来理解
比喻：智能图书馆记忆系统
想象一个超级智能的图书馆，它不仅仅是把书放在架子上，而是像人脑一样工作：
传统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小时）
- 阅读
README.md的前100行 - 阅读本文档
- 理解"锥形图"和"路径成本检索"的概念
第二步：看简单示例（1-2小时）
# 运行最简单的示例cdexamples/python/ python simple_example.py第三步：追踪核心流程（2-3小时）
- 从
m_flow/api/v1/search/search.py开始 - 看它如何调用
m_flow/memory/episodic/ - 理解向量搜索 + 图传播的组合
第四步：深入数据模型（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用图结构补充这些不足
📌 核心概念速查表
| 术语 | 含义 | 生活比喻 |
|---|---|---|
| Episode | 事件包 | 一个完整的故事（如"周一站会记录"） |
| Facet | 主题维度 | 故事的某个角度（如"截止日期讨论"） |
| FacetPoint | 事实点 | 具体的一句话（如"Maria没被告知截止日期"） |
| Entity | 实体 | 跨故事的人/物（如"Maria"出现在多个会议中） |
| 路径成本 | 相关性评分 | 找答案需要"走多少步、多偏" |
| 锥形图 | 数据组织结构 | 从精确到抽象的倒金字塔 |
🚀 快速开始命令
# 1. 安装依赖pipinstall-e.# 2. 运行简单示例cdexamples/python python simple_example.py# 3. 启动Web界面（可选）python-mm_flow.api.v1.ui最后提醒：
- 🎯 先理解概念，再看代码
- 🎯 从简单示例开始，不要一开始就深入细节
- 🎯 关注数据流动：输入 → 处理 → 存储 → 检索
- 🎯 不需要理解所有模块，专注你关心的部分
祝你学习顺利！🎉