已合并
docs: 新增dflow异步流水框架和UDF子模块设计文档 #4043
lining23666创建于 7月17日
docs: 新增dflow异步流水框架和UDF子模块设计文档 #4043
已合并
lining23666创建于 7月17日
lining23666成员
7月17日

Pull Request

描述

新增 dflow (DataFlow) 异步流水框架的设计文档,以及 UDF(用户自定义函数)子模块的独立设计文档。

dflow.md 覆盖以下内容:

  • 特性背景:host-device 交互瓶颈痛点,DataFlow 的核心价值(多模型串接下沉执行、异步流水、低门槛自定义处理)
  • 用户使用场景:多模型串接、UDF 自定义处理、批处理聚合、多实例负载均衡
  • 对外接口:C++/Python 构图 API(FlowGraph/FlowNode/ProcessPoint)、运行接口(DFlowSession)、数据类型(FlowMsg/rtMbuf)
  • 具体实现:
    • 编译层:PNE 引擎机制(NPU/CPU/UDF 三引擎)、多级缓存、编译 Pass
    • 模型抽象层:FlowModel/UdfModel/GraphModel/SerializedModel、ModelRelation、OM 序列化
    • 部署层:多节点主从部署(头节点→从调度节点→子从调度节点→执行器进程)、进程层级体系、通信链路、模型执行(Host/NPU 静态/NPU 动态)
    • 执行层:异构执行器、数据对齐、事务追踪
    • UDF 执行位置与多实例部署配置
  • 端到端数据流和关键设计总结

udf.md 覆盖以下内容:

  • UDF 框架调用链路(SO 加载注册、Processor 初始化、运行时调度)
  • 调度核心:FlowFuncProcessor 10 态状态机、事件驱动重调度、看门狗、挂起/恢复
  • 数据对齐与两种输入模式(Reader 驱动/FlowMsgQueue 流式)
  • 上下文体系、消息抽象、负载均衡、异常处理、内置 UDF(TimeBatch/CountBatch)

同时在 AGENTS.md 架构文档表中注册 dflow.md 的触发词和涉及目录。

变更类型

  • 🐛 Bug 修复
  • ✨ 新功能
  • 💄 代码风格更新(格式化,局部变量)
  • ♻️ 重构(既不修复错误也不增加功能的代码变动)
  • 📦 构建过程或辅助工具的变动
  • 📝 文档内容更新

关联的Issue

如何测试

  1. 检查文档格式和链接是否正确
  2. 检查 Mermaid 图表是否可正常渲染

核对清单

  • 我的代码遵循了项目的代码风格
  • 我已对代码进行了自测
  • 我已更新了相关的文档
  • 我在标题中使用了合适的类型标签(如:feat:, fix:
  • 我已经详细阅读了贡献指南(CONTRIBUTING.md),并遵守了其中的所有规定

其他信息

变更文件:AGENTS.md(+1)、dflow.md(+646)、udf.md(+464),共 1111 行新增。

likedislike
Pull Request已成功合入, 合并人@CANN-robot
(感谢 lining23666 的贡献)
Llining23666成员
7月17日 创建了 pull request,commit 26c94aa4
atomgit-bot
atomgit-bot
7月17日 评论:

变更摘要

此 PR 主要新增了 dflow(DataFlow)异步流水框架和 UDF(用户自定义函数)子模块的特性设计文档,并在 AGENTS.md 中注册了 dflow.md 的触发词与涉及目录。文档以中文编写,系统性地覆盖了 dflow 的背景动机、用户场景、对外接口、核心实现架构(PNE 编译引擎、FlowModel/ModelRelation 模型抽象层、多节点主从部署、异构执行器与数据对齐),以及 UDF 框架的完整设计(SO 加载注册、状态机调度、消息抽象、异常处理、内置 UDF 与进程层级体系),为后续特性开发提供了详细的设计参考。

主要改动

  • 新增 docs/dflow.md 设计文档:全面阐述 dflow 异步流水框架的特性背景、用户场景、C++/Python 对外接口、PNE 编译引擎机制、FlowModel/ModelRelation 模型抽象、多节点主从部署策略及异构执行器数据对齐等实现细节。
  • 新增 docs/zh/udf.md 独立设计文档:详细定义 UDF 子模块的 SO 动态加载注册、状态机调度流程、消息抽象接口、异常处理机制、内置 UDF 清单及头节点→从调度节点→子从调度节点→执行器进程的层级部署架构。
  • 更新 AGENTS.md 架构文档表:将 dflow.md 纳入架构文档索引,注册其触发词和涉及目录,便于后续 AI 辅助开发时自动检索相关设计上下文。
likedislike
atomgit-bot
atomgit-bot
7月17日 评论:

代码审查

审查总结

本次审查了 3 个文件的所有变更:

文件 结果
AGENTS.md 无问题 — 新增的表格行格式正确,与现有条目一致,触发词和目录路径与实际代码结构匹配
docs/zh/design/modules/dflow/dflow.md 无问题 — 纯设计文档,无不安全命令、无硬编码密钥、无默认不安全配置、Mermaid 图表语法正确
docs/zh/design/modules/dflow/udf.md 1 个 P3 发现 — 状态机图中 kSuspend 状态缺失入边

发现统计:P0: 0, P1: 0, P2: 0, P3: 1

整体风险评估:低风险。本次变更为纯文档新增,内容为 dflow 异步流水框架及 UDF 子模块的特性设计文档。唯一发现的问题是 udf.md 中状态机 Mermaid 图的一处不完整性(kSuspend 状态缺少入边),正文已覆盖该信息,不影响安全或生产使用,属于文档一致性改进建议。

⚠️ 已识别出整体风险,但无法提取行内评论,请参考整体评估。

likedislike
CANN-robotCANN-robot成员
7月17日 添加了label:cann-cla/yes
CANN-robot
CANN-robot成员
7月17日 评论:

Thanks for your pull-request.
The full list of commands accepted by me can be found at here
You can get sig-info at here


PR Approval Progress

Congratulations! All modules have met the lgtm and approve requirements.

Module Approval Details

module lgtm status approve status
repo-cann/ge stevenaw0, xchu42, zhanj (3/2) zhanj (1/1)

💡 Tip:

  • Committer can comment /approve or /lgtm
  • Commenting /approve implies both code review (lgtm) and intent to merge (approve)

CLA Signature Pass

lining23666, thanks for your pull request. All authors of the commits have signed the CLA. 👍

likedislike
此处折叠了59条消息 查看更多
xchu42
xchu42成员
26 天前 评论:

/lgtm

likedislike
CANN-robotCANN-robot成员
26 天前 添加了label:lgtm
zhanj
zhanj成员
26 天前 评论:

/approve

likedislike
CANN-robotCANN-robot成员
26 天前 添加了label:approved
CANN-robotCANN-robot成员
26 天前 合入了pull request