如果你最近在研究 AI 应用落地大概率会频繁看到deer-flow这个名字。简单说它是一个开源的 AI 工作流编排平台把大模型、知识库、工具调用、业务系统串成可视化流水线。第一次在 GitHub 上看到时我的第一反应是又一个 n8n 的变体但真正把它部署起来跑完一个完整场景后我改变了看法它对中文语境下的 AI Agent 编排做了很多贴地气的设计尤其适合需要把大模型快速接进现有业务系统的团队。这篇文章我会从一个实际使用者的角度完整讲清楚 deer-flow 能做什么、核心机制是怎么设计的、如何部署和二次开发以及我在踩坑过程中总结的经验。如果你正在选型 AI 编排工具或者准备把一个 AI 应用从 demo 推向生产环境这篇应该能帮你省下不少试错的时间。1. 为什么我会盯上 deer-flowAI 工作流编排的选型思考1.1 轮子对比从 n8n、Node-RED 到自研的纠结先说背景。我们团队当时需要在两周内交付一个内部知识问答系统需求很简单用户上传文档系统自动切片、向量化然后通过大模型做检索增强问答。但真正动手后发现简单需求背后藏着一堆流程问题文档要格式解析、长文本要切片、向量库要维护、大模型调用要处理超时、回答要附带引用来源。市面上现有的工具我基本都试过。n8n 很强大节点生态丰富但它的设计重心是通用自动化AI 相关的节点需要自己拼装编排一个 RAG 流程要把 HTTP Request、Wait、Function 这些底层节点串起来配置起来非常痛苦。Node-RED 更适合 IoT 场景在前端交互和 AI 应用可视化方面比较薄弱。自研的话两周内搞定流程引擎、可视化编辑器、节点通信、日志系统基本不现实。后来在技术社区看到 deer-flow 的讨论发现它在设计上是直接面向 AI 应用场景的流程即代码、节点即服务而且是专门为 LLM 应用的编排打造的不是通用自动化工具的AI 插件模式。这让我决定深入试一下。1.2 deer-flow 的设计思路把 AI 应用当成一条流水线deer-flow 的核心抽象不算复杂一个流程就是一张有向无环图节点是处理单元节点之间有边和渠道的连接。你通过拖拽节点把大模型调用、参数提取、知识检索、条件分支这些能力串联起来最终形成一个完整的 AI 应用。这里面有一个关键设计也是我后来觉得它和 n8n 类工具最大的差异点deer-flow 天然把 Agent 的角色拆成了任务规划和任务执行两个层面。换句话说它不要求你把整个复杂任务写在一个巨大的 prompt 里而是允许你定义多个 Agent一个负责拆解目标另一些负责具体干活。这个思路在多轮对话、复杂工具调用的场景下非常实用后面我会专门讲。提示如果你之前用过 n8n 或者 Node-RED可以把 deer-flow 理解成一款为 LLM 应用重新设计过的 workflow 引擎而不是简单的替代品。2. 快速跑起 deer-flow从部署到第一个 Agent 流程2.1 部署方式选择Docker Compose 还是源码启动deer-flow 的部署非常友好官方提供了 Docker Compose 方案这是我最推荐的方式尤其适合本地验证和小规模试运行。我当时的部署环境是一台 4C8G 的 Linux 服务器实测跑起来很稳。git clone https://github.com/deer-flow/deer-flow.git cd deer-flow docker compose up -d启动后前端服务和管理后台会分别映射到本地的端口。默认配置下前端工作台端口是8081后端 API 服务端口是8080。打开浏览器访问http://服务器IP:8081就能看到可视化编排界面。如果你需要在本地做二次开发建议采用源码方式启动后端是 Java Spring Boot 项目前端是 Vue Ant Design Vue。源码启动有几个前置条件需要注意JDK 17 或更高版本Node.js 18npm 9后端依赖的中间件Redis、PostgreSQL需要提前装好我个人的建议是先无脑用 Docker 跑通一遍确认功能和预期一致后再决定是否切换到源码模式做定制。不要一上来就折腾源码环境容易把精力耗在环境配置上。2.2 第一次创建流程把大模型接入编排图打开工作台后左侧是节点库中间是画布右侧是属性配置面板。第一次使用时需要先配置一个大模型服务节点也就是把 LLM 接入进来。deer-flow 支持多款主流大模型 API常用的有 OpenAI 兼容接口、通义千问、文心一言、智谱、Ollama 本地模型等。大多数情况下你只需要填三个东西API Key在模型服务商的控制台创建模型名称例如gpt-4o-mini或qwen-plusAPI 地址官方地址一般有默认值如果是自建网关或代理服务改成自己的地址即可当时我接的是本地的 Ollama 服务地址填http://localhost:11434/v1模型名填qwen2.5:7b直接就通了。这里有个细节deer-flow 对大模型节点做了统一的接口抽象如果你用的是 OpenAI 兼容协议基本可以无缝接入不需要额外写适配代码。2.3 核心要素拆解流程、节点、触发、上下文跑通第一个流程之前有几个基本概念需要理清否则后面编排复杂流程时会晕流程整个业务逻辑的有向无环图一个流程可以理解为一个应用。节点流程中的处理单元每个节点有特定的输入和输出数据结构。触发流程的入口方式支持 Web 页面手动触发、定时触发类似 cron、以及 API 触发外部系统调用。上下文流程运行期间共享的数据容器节点之间通过上下文传递数据。我记得第一次用的时候卡在最基础的问题上节点和节点之间到底怎么传值。后来才搞明白deer-flow 的节点输出会写入指定的上下文 key 中下游节点通过{节点ID.输出字段}这种模板语法引用上游数据。比如上游是一个文档解析节点输出content字段下游的文本切片节点就可以在配置里写{文档解析.content}来拿到原文。这个设计其实很像 Unix 管道每个节点只关心自己的输入输出节点之间通过约定好的数据格式衔接。这种解耦方式让流程的可维护性大大提高而且方便做单元测试。3. 核心机制背后的原理为什么这样设计3.1 双 Agent 模式任务规划与任务执行分离deer-flow 最让我惊艳的一点是它在流程引擎层面内置了任务规划和任务执行两类 Agent 节点的协作机制。传统做法是你在代码里写死一个 Agent让它自己决定调用哪些工具。问题是模型一旦在复杂场景下自由发挥很容易跑偏。deer-flow 的做法是任务规划 Agent 负责理解用户意图拆解出步骤清单任务执行 Agent 负责一步步执行清单中的操作每一步的结果再回流给规划层决定下一步动作。我当时用这个机制做了一个客服工单分类流程规划 Agent 先判断用户的问题是咨询、投诉、还是售后然后执行 Agent 根据类型调用不同的处理节点最后再由汇总节点生成回复文案。如果没有这种双 Agent 协作单靠一个大模型 prompt 做多分支决策分类准确率和稳定性都会差不少。3.2 会话记忆与上下文管理上下文管理是 AI 应用绕不开的痛点。早期我自研工具的时候经常遇到一个问题用户多轮对话后模型把前面的信息忘了。deer-flow 用一套比较轻量的会话记忆机制解决了这个问题。流程中可以配置一个记忆节点底层使用 Redis 做会话存储支持固定窗口的最近 N 轮对话记录。节点在每次触发时会自动把历史消息注入到 prompt 上下文中。这个自动注入看似简单实际解决了大模型的无状态问题——你把状态放在工作流引擎里模型只负责处理当前轮次的输入输出。需要注意一点记忆窗口设置不建议过大。设成 20 轮可能很爽但 token 消耗会显著上升响应速度也会变慢。我一般建议业务场景控制在 6~10 轮。3.3 流式日志与过程可视化生产环境排障最怕黑盒。deer-flow 的前端控制台支持实时日志流WebSocket 推送可以看到每个节点的运行状态、输入输出数据、耗时、token 用量。这个功能极大降低了排障成本。有一次我做一个异步任务流程跑着跑着某节点一直不结束。打开日志流一看发现是上游文档解析节点抛了一个解析异常日志里直接明晃晃地显示了异常堆栈。换做以前自研的系统这条报错可能要翻半天服务日志才能定位到。3.4 与业务系统对接的 SDK Embedding 方式如果只是画个流程图、在后台玩一玩那还不够。真正的价值在于把流程嵌入到现有业务系统里。deer-flow 提供了SDK Embedding模式在后端工程里引入对应的 SDK 依赖通过一个 API 方法直接触发工作流然后在流程里配置返回节点把结果同步返回给业务系统。前端也可以通过 iframe 或 Web 组件的方式把对话交互嵌入到现有页面中。我当时把它嵌进了一个企业微信内部的 H5 应用用户在 H5 里输入问题后端调用 deer-flow 的流程申请接口流程内部完成检索和大模型生成最终把回复通过 WebSocket 实时推回页面。整个对接过程大概花了一个工作日体验非常顺滑。4. 二次开发扩展一个自定义节点并给前端配上配置面板4.1 后端节点开发的基本套路用现成节点拼装流程能覆盖 80% 的场景但总有一些业务逻辑需要自己实现这时候二次开发就不可避免了。deer-flow 的后端基于 Java Spring Boot扩展一个节点需要做几件事新建一个类并继承抽象节点类实现execute方法。在execute方法中获取输入参数执行你的业务逻辑把结果写入输出上下文。加上节点类型注解这样前端节点库就能识别到新节点。我当时写了一个数据库查询节点大概逻辑是接收 SQL 和连接配置执行查询把结果集转成 JSON 返回。整个过程比我想象的简单因为框架已经把流程编排、参数注入、异常处理这些基础设施都做好了你只需要聚焦业务逻辑本身。下面是简化后的核心代码结构方便你理解节点开发的骨架Component public class DatabaseQueryNode extends AbstractNode { Override public Object execute(NodeContext context) { // 1. 从上下文中获取输入参数 String sql context.getInput(sql); String datasourceId context.getInput(datasourceId); // 2. 执行真正的查询逻辑这里省略数据源管理细节 ListMapString, Object result query(datasourceId, sql); // 3. 把结果写入输出 return result; } }4.2 前端节点的配置面板组件后端节点写完后前端工作台不会自动识别这个节点的配置表单。你还需要为它写一个配置面板组件。这一步对纯后端工程师来说可能有点劝退因为涉及 Vue 组件的编写。不过 deer-flow 的扩展机制设计得还不错你可以参考现有的基础节点组件改成自己需要的表单。通常需要处理几种控件文本框输入 SQL、下拉框选择数据源、开关是否开启超时告警等。在 Vue 项目中自定义节点的注册方式大致是这样import CustomNodeConfig from ./CustomNodeConfig.vue; registerNode(databaseQuery, { component: CustomNodeConfig, icon: database, label: 数据库查询 });注册完成后刷新工作台页面左侧节点库就会出现你的新节点拖拽到画布后右侧属性区会展示你写好的配置面板。这套机制对团队协作很友好后端同学负责节点逻辑前端同学负责配置面板互相不阻塞。4.3 二次开发时踩过的几个坑开发过程中专门踩过一些坑在这里记一下供参考节点类务必加上Component注解否则框架扫描不到节点不会出现在流程里而且不报错只是静默失效非常隐蔽。上下文的数据类型要保持一致。上游输出是字符串下游当 JSON 对象的字段去引用运行时会直接解析报错。建议在上游节点里先把数据格式转换干净。开发完新节点后需要重启后端服务才能生效。如果你用 Docker 启动记得重新构建镜像或挂载源码目录。5. 实际场景跑通案例一个周报自动生成流程5.1 流程设计理论讲再多不如一个完整案例来得实在。我拿一个内部一直在用的周报自动生成流程举例把这个流程从设计到配置完整走一遍。这个流程的需求是每周五下午自动读取过去一周的代码提交记录、需求工单状态、线上告警数量汇总后调用大模型生成一份结构化周报推送到群机器人。流程设计如下定时触发节点配置0 0 16 * * 5也就是每周五下午 16:00。数据收集节点并行调用三个数据源分别拉取代码提交记录、需求列表、告警统计。数据清洗节点把三个数据源的结果统一成 日期 事件 影响范围 的格式。大模型生成节点把清洗后的数据拼接成 prompt调用大模型生成周报草稿。人工确认节点把草稿发送到审核群等待负责人确认确认后触发下一步不确认则流程结束。推送节点把确认后的内容发布到正式周报群。5.2 节点配置和参数这里有一个关键设计我把数据收集做成了三个独立的节点而不是一个大节点。这样做的好处是任何一个数据源出现故障只需要看对应节点的日志不影响其他数据源的数据。同时节点可以在画布上独立重跑排查问题不用把整个流程跑一遍。大模型生成节点的 prompt 模板我是这么写的你是一名研发团队的技术助理。请根据以下的工作数据生成一份简洁的周报包含本周完成事项、存在问题、下周计划。 每个部分不超过5条要点用中文回答。数据如下{清洗后的数据}这里用到了上下文引用语法{清洗后的数据}运行时会把上游节点的输出自动填充进去。5.3 运行效果和调优记录第一次跑通后生成的周报比较平后来我在 prompt 里加了一句要求重点突出风险事项用一句总结开头。修改后效果立刻好了很多领导反馈说周报有重点了。另外建议配置一个失败通知节点。我第一次运行就碰到过问题数据收集节点中需求工单的接口返回了限流错误整个流程中断了到下周才发现。后来我在每个关键节点后挂了异常分支接了一个失败通知节点一旦节点抛错群机器人马上报警。从此周报流程基本处于无人值守状态。6. 常见问题与排查技巧实录6.1 流程不执行或节点卡住遇到这种情况我的排查顺序是先看流程定义是否保存并已发布。deer-flow 中修改流程后需要显式发布否则修改不生效这个问题新手很容易踩。打开实时日志定位到卡住的节点。检查该节点的输入数据是否完整。很多时候卡住是因为引用了一个不存在的上下文字段导致节点一直在等待数据。最常见的原因就是没有发布或字段名拼写错误。6.2 前端无法连接后台 / WebSocket 断连WebSocket 断开一般集中在两种场景一是反向代理没有开启 WebSocket 升级支持二是浏览器和服务器之间存在超时断连。如果你用 Nginx 代理需要确保配置了proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_read_timeout 3600s;同时在部署环境里调长 WebSocket 空闲超时时间。这个问题通常只在生产环境出现本地调试很少遇到。6.3 多轮对话上下文串话上下文串话是指用户 A 的问题在用户 B 的会话里出现了。多数原因是没有正确传入会话 ID或者会话 ID 在客户端被复用。deer-flow 支持在触发流程时显式传递sessionId参数。同一个会话使用同一个 ID不同会话需要使用不同的 ID。建议在业务侧创建会话时生成 UUID 作为sessionId而不是用用户 ID 直接充当。这样同一个用户开多个会话时上下文不会互相污染。6.4 资源规划与部署建议最后聊一下部署资源。我在 4C8G 的机器上跑得很稳但如果并发量上来建议重点观察 Redis 和大模型调用端的负载。单机部署时我比较推荐用 Docker Compose 把 MySQL、Redis、deer-flow 后端、deer-flow 前端打成一个 compose 服务。如果之后要扩展可以在数据库和 Redis 前面加一层负载均衡把后端水平扩容。deer-flow 的工作流引擎是无状态的节点执行的状态都存在 Redis 里所以横向扩展的压力不大。7. 写在最后的几条经验在我用 deer-flow 构建了几套不同场景的 AI 应用之后沉淀下来的经验主要有几条第一能可视化编排的就不要急着写代码流程引擎帮你解决了状态管理、日志追踪、重试机制这些隐形工作这些恰恰是最容易在自研时被忽略却又很重要的部分第二节点的粒度不要贪大大节点功能多但排障时非常痛苦小节点反而让整个流程更清晰第三prompt 不要写死在代码里放到流程节点的配置里这样调整 prompt 不用重新发版运营同学也可以参与调优。最后说一个不算技巧的技巧遇到流程运行结果不对的时候先把各个节点的实际输出打印出来看看数据在哪一步开始变形的。deer-flow 的日志系统做得不错只要你肯多看几眼绝大多数问题都很直观。希望这篇分享能让你少走一些弯路。