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/- 关系数据库适配器PostgreSQLcache/- 缓存适配器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最后提醒 先理解概念再看代码 从简单示例开始不要一开始就深入细节 关注数据流动输入 → 处理 → 存储 → 检索 不需要理解所有模块专注你关心的部分祝你学习顺利