8 月 9 日 AI 行业信息量不小OpenAI 被曝暂停 Astra 项目Grok Image 2.0 疑似开始灰度推送。对工程师来说这两条新闻单独看都只是情报真正能转化为生产力的是工具链本身。这篇文章把新闻快速带过重点讲一个今天就能动手的实操——用 Dify 搭建 Agent 工作流走完从环境部署到 API 发布的全流程。Dify 是目前开源社区关注度很高的 LLM 应用开发平台它解决的问题很实际让开发者用可视化方式把模型能力、知识库、外部工具串成一条可运行的链路。过去你要自己写函数调用、管理对话记忆、搭向量数据库现在这些步骤在 Dify 里变成了可配置节点。本文会从部署开始一步一步演示如何创建 Agent 应用、编排工作流、接入知识检索并提供一个完整可跑的简历筛选示例。读完你会得到三样东西对 Dify 架构和核心概念的清晰理解一套可直接部署的本地运行环境还有一个能落到生产项目的 Agent 工作流模板与排错清单。建议先收藏再跟着操作。1. 今日 AI 动态速览OpenAI 暂停 Astra 与 Grok Image 2.0 传闻1.1 OpenAI 暂停 Astra只把它当信号看据海外科技媒体和开发者社区讨论OpenAI 近期暂停了代号为 Astra 的项目推进相关团队的工作重心会调整。Astra 在公开信息里曾被视为 OpenAI 面向新交互形态的探索方向这次暂停更多是外界根据岗位变化、代码仓库动态和团队成员公开发言观察到的官方并没有发布详细说明。这里不建议做过度的原因推测。把这条消息放进开发者的决策框架里它只是一个信号大型模型厂商的项目管线正在高速动态调整今天还在推进的方向明天可能换优先级。这意味着如果你把自己的产品架构强耦合在某一家模型厂商的某个实验性项目上风险会很高。正确的姿势是往上抽象一层把模型当作可替换的组件把 Agent 工作流和工具封装作为自己的核心资产。1.2 Grok Image 2.0 疑似推送官方文档为准另一条消息来自图像生成方向。有用户在社交平台反馈Grok 对话中的图像生成效果出现了明显变化图片风格、提示词还原度都比之前版本有提升因此社区猜测 Grok Image 2.0 正在灰度推送。需要冷静的是这目前仍是社区观察xAI 官方没有发布完整的版本说明。如果你所在的项目依赖 Grok 的图像生成能力判断依据应该是官方接口文档和模型列表更新而不是社交平台截图。等官方版本号确认之后再去调整 Prompt 模板、评估图像质量和成本也不迟。1.3 两条新闻背后的共同判断把两条新闻放在一起可以得到一个更稳定的结论模型层迭代在加速但模型本身不会自动变成产品。OpenAI 暂停一个项目不代表对话技术退步Grok 出了新版本也不意味着每个应用都要马上接入。真正值得投入时间沉淀的是 Agent 工作流、知识库接入、工具编排这些工程化能力。下面我们进入 Dify 实操。2. 为什么用 Dify 搭建 Agent 工作流Dify 是一个开源的 LLM 应用开发平台。通俗地说它把模型接入、Prompt 编排、知识库管理、工具调用、日志监控这些环节封装成了可视化组件。开发者不需要从零写一套 Agent 框架只需要在 Web 界面上拖拽和配置节点就能构建一个可对外提供 API 服务的 Agent 应用。做一个简单的知识库问答机器人传统路径是这样的准备向量数据库比如 pgvector选一个 Embedding 模型写文档切分脚本设计 Prompt 模板处理 Session 记忆再写一轮模型 API 调用封装。这一套下来哪怕是一个 MVP至少也要花一两天。用 Dify 的话把文档传到知识库创建一个 Chatflow 应用添加知识检索节点绑定模型十分钟就能跑通一个可演示的原型。维度手写代码方案LangChain 等Dify 低代码方案上手速度需要熟悉框架 API 和 RAG 原理Web 界面可视化配置灵活度高可以任意定制中高自定义节点和工具可扩展运维成本需要自己处理日志、队列、部署平台内置运行日志和应用管理知识库管理自建向量库、分块、索引内置文档分段、检索、引用溯源工具接入写代码注册工具函数HTTP 请求节点、自定义工具、代码节点这并不代表 Dify 能替代所有后端开发而是说它真正改变的是原型和中小型应用的生产效率。适合用 Dify 的场景包括企业内部知识库问答、智能客服初筛、简历筛选、工单分类、周报自动生成、招聘助手以及任何需要把 LLM 和内部 API 串起来的流程。不适合的场景则是超大规模的定制化模型训练、对执行链路有极端控制要求、或者需要把 Agent 核心逻辑深度嵌入现有业务代码库的团队。3. Dify 核心概念应用、工作流、节点、知识库在开始部署之前先把 Dify 里的几个基础概念说清楚。**应用App**是一个对外暴露的服务单元它定义了这个 Agent 或工作流干什么、用什么模型、有哪些参数。开发者在 Dify 里创建应用后可以把它发布成 API 服务也可以通过网页嵌入分享给内部用户。Chatflow 与 Workflow是两种最常被混淆的模式。Chatflow 是聊天流适合对话式 Agent有上下文记忆能力用户可以和机器人多轮问答。Workflow 是工作流适合自动化、批量处理型任务比如简历筛选、报表生成、数据抽取。两者的本质区别在于是否面向多轮对话。简历筛选这类任务通常用 Workflow 模式因为它是一次性输入输出智能客服则更适合 Chatflow因为需要记忆对话上下文。**节点Node**是工作流的基本单元。Dify 提供了开始节点、结束节点、LLM 节点、知识检索节点、代码节点、HTTP 请求节点、条件分支节点、问题分类节点等。一个工作流本质上就是节点的有向连接图。**Agent 节点和工具Tool**需要额外解释。很多开发者容易把 Agent 和工作流混在一起。工作流是“人编排好的固定流程”节点顺序在运行前就已经确定Agent 是“让模型在运行过程中决定下一步调用什么工具”。打个比方工作流是流水线每个工位都有人负责Agent 是一个调度员他根据情况判断这个零件该送去哪个工位。Dify 的 Agent 应用就是给模型提供一组工具让它在对话中自主决定调用顺序。**知识库Knowledge**则是给 Agent 提供私有知识的模块。你把 PDF、Markdown、TXT 文件上传后Dify 会做分块和向量化。当用户提问时知识检索节点能在知识库中找到相关内容把这些内容作为上下文交给 LLM 生成回答从而避免模型一本正经地编造事实。从架构层级看Dify 从上到下依次是应用层Agent/Chatflow/Workflow、编排层节点与工具、模型层各类模型供应商、平台层API 服务、日志、权限。理解了这个分层后面配置节点时就清楚了。4. Dify 环境部署与前置条件Dify 官方提供 Docker Compose 部署、本地源码部署等多种方式。对大多数开发者Docker Compose 是最快也最容易维护的方式。4.1 环境准备需要准备的环境如下操作系统Linux 或 macOS 都可以Windows 用户推荐安装 Docker Desktop并开启 WSL2。Docker建议使用 Docker 20.10 及以上版本。Docker Compose建议使用 Compose V2也就是通过docker compose命令调用。硬件配置最低 2 核 4G 内存建议 4 核 8G。如果后续要跑本地开源模型需要更高配置。4.2 获取 Dify 源码并启动Dify 项目托管在 GitHub 的 LangGenius 组织下。部署命令如下# 1. 克隆 Dify 仓库 git clone https://github.com/langgenius/dify.git # 2. 进入 docker 目录 cd dify/docker # 3. 复制环境变量文件 cp .env.example .env # 4. 启动容器 docker compose up -d这里真正容易踩坑的是第三步和第四步。.env文件里包含了 Dify 各个服务的端口、数据库连接、密钥等配置。如果之前部署过其他应用占用了 80 端口就需要提前修改.env里的EXPOSE_NGINX_PORT之类的端口变量否则容器启动会失败。4.3 检查容器启动状态执行docker compose ps可以查看所有容器状态。Dify 主要由 api、worker、web、db、redis、sandbox、ssrf_proxy 等容器组成。正常启动后你可以看到它们的状态都是 Up。docker compose ps docker compose logs -f api worker访问http://localhost就能打开 Dify 的 Web 界面。第一次打开时需要设置管理员邮箱和密码这个账号用于登录后台一定要记住。4.4 初始化管理员账号首次进入控制台会要求设置管理员账号。这里需要填写邮箱和密码。完成后系统会引导你进入工作台。如果这一步卡住大概率是 API 容器还没有完全启动等一两分钟再刷新页面。5. 在 Dify 中配置模型并创建 Agent 应用5.1 接入模型供应商部署完成后的第一步是接入模型供应商。进入“设置”页面选择“模型供应商”找到 OpenAI 或者其他你使用的模型服务商填写 API Key。在模型供应商官方控制台创建 API Key 时要注意 Key 通常只在创建时完整显示一次建议创建后立即保存到安全的地方。Dify 支持很多模型包括 OpenAI、Anthropic、OpenAI 兼容接口、Azure OpenAI 以及 Ollama 等本地模型。如果你所在团队使用内部模型网关凡是提供 OpenAI 兼容接口的都可以通过自定义 API 地址接入。关键配置项API Key模型供应商控制台生成的密钥。Base URL默认是官方地址如果使用代理网关或私有化部署的模型服务需要修改。模型列表Dify 会自动拉取该供应商支持的模型在下拉框中选择具体要用的模型名。5.2 创建 Agent 应用登录 Dify 工作台后点击“创建空白应用”选择“Agent”模式填写应用名称和描述。应用名称建议用英文或拼音方便后续 API 路径和日志检索。描述字段会作为 Agent 的系统提示词的一部分建议写清楚这个 Agent 的职责边界。比如“简历筛选 Agent用于根据职位描述初筛候选人简历输出结构化结论。”创建完成后会进入 Agent 编排界面。主要包括会话提示词、模型选择、工具配置三个区域。5.3 配置系统提示词与模型参数在 Agent 编排界面你需要写一段 Sys Prompt明确告诉模型它的角色、任务、输出格式和约束。模型参数方面温度决定随机性一般任务建议 0.2 到 0.5最大 Token 上限根据输出长度设置比如简历筛选的最终结果以 JSON 返回那么 1000 到 2000 是合理范围。关于工具配置建议先把常用的工具加上比如 Web 搜索、维基百科、Arxiv 等内置工具。企业内部场景更多是自定义工具Dify 可以通过 OpenAPI Schema 描述来接入已有 HTTP API。外部服务也可以直接用 HTTP 请求节点而不用单独封装成工具。6. 实战搭建一个“简历筛选 Agent”工作流接下来做一个完整的实战示例这是本文的核心场景。我们的业务需求是HR 助理把职位描述和简历文本粘贴到工作流里工作流自动抽取简历关键字段、计算技能匹配度、生成初筛结论。这类任务非常适合用 Dify 的 Workflow 模式实现。6.1 工作流整体设计整个工作流包含六个节点开始节点接收两个输入变量job_description职位描述和candidate_resume简历文本。LLM 节点“简历信息抽取”从简历中抽取姓名、工作年限、技能列表、教育背景输出 JSON。知识检索节点“历史岗位标准”根据职位描述检索企业知识库补充岗位硬性要求。代码节点“匹配度计算”利用 Python 计算技能命中率得到 0 到 1 之间的分数。LLM 节点“生成筛选结论”结合前面所有结果输出是否推荐进入下一轮。结束节点返回结构化 JSON 给调用方。这个流程看起来不复杂但它覆盖了 RAG、LLM 抽取、代码计算、结构化输出四个 Agent 工作流最常用的能力。下面是节点连接关系的示意 YAML实际使用中 Dify 的工作流 DSL 文件还包含画布位置等 UI 信息这里只展示关键节点配置app: name: resume-filter-agent mode: workflow description: 根据职位描述初筛候选人简历输出结构化筛选结论 workflow: graph: nodes: - id: start type: start data: title: 简历筛选入口 variables: - variable: job_description label: 职位描述 type: text-input - variable: candidate_resume label: 简历文本 type: paragraph - id: llm_extract type: llm data: title: 简历信息抽取 model: provider: openai-compatible name: gpt-4o-mini prompt_template: - role: system text: | 你是资深招聘助理。请从简历文本中抽取以下字段 姓名、工作年限、技能列表、教育背景。 只输出 JSON不要输出解释。 格式{name: , years: 0, skills: [], education: } variables: - variable: resume value: {{#start.candidate_resume#}} - id: knowledge_retrieval type: knowledge-retrieval data: title: 查询企业岗位标准 dataset_ids: - 这里填写知识库ID query: {{#start.job_description#}} retrieval_mode: semantic_search top_k: 3 - id: code_score type: code data: title: 技能匹配度计算 code: | def main(job_description: str, extracted_json: str) - dict: import json try: data json.loads(extracted_json) except Exception: data {} required_skills [Python, Docker, Kubernetes, AWS] skills data.get(skills, []) hit [s for s in skills if s in required_skills] score round(len(hit) / len(required_skills), 2) return {score: score, hit_skills: hit, required_skills: required_skills} variables: - variable: job_description value: {{#start.job_description#}} - variable: extracted_json value: {{#llm_extract.text#}} - id: llm_conclusion type: llm data: title: 生成筛选结论 model: provider: openai-compatible name: gpt-4o-mini prompt_template: - role: system text: | 你是招聘主管的助理。请根据抽取信息和技能得分给出筛选建议。 输出 JSON {suggestion: 通过/待定/不通过, reason: 一句话理由} - id: end type: end data: title: 输出结果 outputs: - variable: result value: {{#llm_conclusion.text#}}这个简化的 DSL 结构展示了节点之间如何依赖上游变量。在 Dify 界面中你在 LLM 节点里可以通过{{#start.candidate_resume#}}这类引用语法把开始节点的输入变量传给后续节点。6.2 各节点配置说明与 Prompt先说开始节点。开始节点定义了工作流接收的外部参数。job_description是单行文本candidate_resume是多行文本。调用工作流 API 时请求体里的inputs必须包含这两个字段。LLM 节点的 Prompt 是整个工作流的灵魂。简历抽取节点的 Prompt 一定要强调“只输出 JSON”否则模型会在 JSON 前后输出解释性文字导致代码节点解析失败。这里还有一个小技巧将比较消耗 token 的抽取步骤用便宜的轻量模型比如 gpt-4o-mini把最终决策留给更强的模型。这样既控制成本又保证输出质量。知识检索节点配置时要先在 Dify 的知识库模块上传文档、完成分段和向量化然后把知识库 ID 填到节点里。这个环节实际上是 RAG 的核心作用是让 Agent 拥有企业私有信息比如“候选人必须五年以上经验”“必须是统招本科”等硬性要求。如果没有知识库可以跳过这个节点但建议体验一次因为知识库是 Agent 和外部世界隔离开的私有记忆。6.3 Python 调用工作流 API工作流配置好并发布后Dify 会生成一个 API 密钥。下面的 Python 代码演示如何调用这个工作流import requests API_URL http://localhost/v1/workflows/run API_KEY app-你的API密钥 payload { inputs: { job_description: 招聘 5 年以上经验的 Python 后端工程师熟悉 Docker、Kubernetes、AWS, candidate_resume: 张三6 年 Python 后端开发经验熟悉 Docker、Kubernetes、AWS。 }, response_mode: blocking, user: csdn-demo, } headers { Authorization: fBearer {API_KEY}, Content-Type: application/json, } resp requests.post(API_URL, jsonpayload, headersheaders) print(resp.status_code) print(resp.json())注意API_KEY需要在 Dify 应用的“访问 API”页面创建。response_mode填blocking表示同步等待结果适合耗时短的工作流如果任务耗时长可以改成streaming并处理流式返回。7. 运行结果与效果验证7.1 预期返回结果如果一切正常调用接口会返回类似下面的 JSON{ workflow_run_id: a1b2c3d4, data: { outputs: { result: {\suggestion\: \通过\, \reason\: \候选人6年经验技能完全匹配\} }, status: succeeded } }返回结果里的status字段是关键。只要它是succeeded就说明工作流跑通了。7.2 如何判断运行成功除了查看 API 返回你还可以在 Dify 的“日志与标注”页面看到每次工作流运行的详细记录。点击任意一次运行记录能看到每个节点的输入和输出这对于调试非常有帮助。如果运行失败第一步应该看 Dify 的日志页面中失败节点是哪一个。常见的情况是“简历信息抽取”节点成功但“匹配度计算”节点报错说明 LLM 输出的 JSON 格式不符合代码节点预期。这时候调整 Prompt或者让代码节点中的 JSON 解析逻辑更健壮重跑即可。7.3 失败排查的第一步工作流报错时先判断是编排问题还是模型问题。编排问题通常表现为节点输入为空、上游输出格式不符、代码节点 Python 异常。模型问题则表现为模型供应商接口超时、返回内容被截断、限制词命中。定位问题的最快方式是在 Dify 运行记录中查看每个节点的原始输入输出而不是只看上层 API 返回的报错信息。8. Dify 常见问题与排查思路结合实际使用经验下面列出几个高频问题。问题现象可能原因排查方式解决方案服务启动后无法访问 Web 界面80 端口被占用或容器未完全启动执行docker compose ps查看容器状态修改.env中的EXPOSE_NGINX_PORT重新启动模型调用报 401 或 404API Key 错误或模型名不存在在模型供应商页面核对模型列表与 Key重新生成 Key并在 Dify 下拉框中重新选择模型工作流提示“请安装缺失的包以使用此工作流”使用了依赖额外 Python 包的节点或插件查看节点说明和运行日志中的依赖信息在对应运行环境中安装缺失包或改用内置节点替代Agent 执行时报 provider 未及时响应模型供应商接口超时查看 api 容器日志确认模型接口连通性缩短模型上下文、降低输出 Token 上限、切换备用模型供应商知识库检索结果为空文档未完成分段或向量化失败在知识库文档详情中查看分段与索引状态重新处理文档检查 Embedding 模型是否可用工作流中一个节点报错导致整条链路中断上游输出格式变化下游解析失败在“日志与标注”中查看节点输入输出 JSON在代码节点增加异常兜底并打印输入日志调用 API 返回workflow not foundAPI Key 对应的应用不是工作流模式或应用未发布检查应用模式是否选成 Chatflow创建 Workflow 应用并发布后重新生成 API Key这里特别说一下“缺失包”的问题。Dify 的代码节点运行在沙箱环境中默认只包含 Python 标准库。如果你在代码节点里 import 了第三方库就需要注意沙箱是否支持。对于需要额外依赖的节点Dify 会提示在 Python 环境中安装缺失的包。建议尽量使用标准库完成任务把复杂计算放到外部服务里再通过 HTTP 请求节点回调。Agent 执行超时的问题也很常见。它通常不来自 Dify 本身而是模型供应商的响应速度。排查思路是看 api 容器日志如果日志显示等待模型响应时间过长就要考虑换更快的模型或者减少上下文长度。记住提示词越长响应越慢成本越高。9. 最佳实践与工程建议9.1 敏感信息管理API Key 是 Agent 工作流中最敏感的信息。不要把 Key 写死在 Prompt 或代码节点里。Dify 的自定义工具提供独立的凭据字段HTTP 请求节点也可以从环境变量中读取密钥。生产环境建议建立密钥轮换机制定期更新模型供应商 API Key。还有一点容易被忽略Prompt 注入。用户输入可能包含恶意指令试图让 Agent 忽略系统提示词。对于企业内部的 Agent 应用越权调用工具的风险很大。在设计工具权限时遵循最小权限原则不要让 Agent 直接获得删除数据库、修改生产配置等高风险权限必要时增加人工确认环节。9.2 工作流版本管理Dify 工作流支持导出 DSL 文件一般是 YAML 格式。团队协作时建议把 DSL 文件提交到 Git 仓库这样每次修改都有迹可循也方便 Code Review。线上应用升级前先在测试环境 Dify实战：从部署到API发布，搭建简历筛选Agent工作流
8 月 9 日 AI 行业信息量不小OpenAI 被曝暂停 Astra 项目Grok Image 2.0 疑似开始灰度推送。对工程师来说这两条新闻单独看都只是情报真正能转化为生产力的是工具链本身。这篇文章把新闻快速带过重点讲一个今天就能动手的实操——用 Dify 搭建 Agent 工作流走完从环境部署到 API 发布的全流程。Dify 是目前开源社区关注度很高的 LLM 应用开发平台它解决的问题很实际让开发者用可视化方式把模型能力、知识库、外部工具串成一条可运行的链路。过去你要自己写函数调用、管理对话记忆、搭向量数据库现在这些步骤在 Dify 里变成了可配置节点。本文会从部署开始一步一步演示如何创建 Agent 应用、编排工作流、接入知识检索并提供一个完整可跑的简历筛选示例。读完你会得到三样东西对 Dify 架构和核心概念的清晰理解一套可直接部署的本地运行环境还有一个能落到生产项目的 Agent 工作流模板与排错清单。建议先收藏再跟着操作。1. 今日 AI 动态速览OpenAI 暂停 Astra 与 Grok Image 2.0 传闻1.1 OpenAI 暂停 Astra只把它当信号看据海外科技媒体和开发者社区讨论OpenAI 近期暂停了代号为 Astra 的项目推进相关团队的工作重心会调整。Astra 在公开信息里曾被视为 OpenAI 面向新交互形态的探索方向这次暂停更多是外界根据岗位变化、代码仓库动态和团队成员公开发言观察到的官方并没有发布详细说明。这里不建议做过度的原因推测。把这条消息放进开发者的决策框架里它只是一个信号大型模型厂商的项目管线正在高速动态调整今天还在推进的方向明天可能换优先级。这意味着如果你把自己的产品架构强耦合在某一家模型厂商的某个实验性项目上风险会很高。正确的姿势是往上抽象一层把模型当作可替换的组件把 Agent 工作流和工具封装作为自己的核心资产。1.2 Grok Image 2.0 疑似推送官方文档为准另一条消息来自图像生成方向。有用户在社交平台反馈Grok 对话中的图像生成效果出现了明显变化图片风格、提示词还原度都比之前版本有提升因此社区猜测 Grok Image 2.0 正在灰度推送。需要冷静的是这目前仍是社区观察xAI 官方没有发布完整的版本说明。如果你所在的项目依赖 Grok 的图像生成能力判断依据应该是官方接口文档和模型列表更新而不是社交平台截图。等官方版本号确认之后再去调整 Prompt 模板、评估图像质量和成本也不迟。1.3 两条新闻背后的共同判断把两条新闻放在一起可以得到一个更稳定的结论模型层迭代在加速但模型本身不会自动变成产品。OpenAI 暂停一个项目不代表对话技术退步Grok 出了新版本也不意味着每个应用都要马上接入。真正值得投入时间沉淀的是 Agent 工作流、知识库接入、工具编排这些工程化能力。下面我们进入 Dify 实操。2. 为什么用 Dify 搭建 Agent 工作流Dify 是一个开源的 LLM 应用开发平台。通俗地说它把模型接入、Prompt 编排、知识库管理、工具调用、日志监控这些环节封装成了可视化组件。开发者不需要从零写一套 Agent 框架只需要在 Web 界面上拖拽和配置节点就能构建一个可对外提供 API 服务的 Agent 应用。做一个简单的知识库问答机器人传统路径是这样的准备向量数据库比如 pgvector选一个 Embedding 模型写文档切分脚本设计 Prompt 模板处理 Session 记忆再写一轮模型 API 调用封装。这一套下来哪怕是一个 MVP至少也要花一两天。用 Dify 的话把文档传到知识库创建一个 Chatflow 应用添加知识检索节点绑定模型十分钟就能跑通一个可演示的原型。维度手写代码方案LangChain 等Dify 低代码方案上手速度需要熟悉框架 API 和 RAG 原理Web 界面可视化配置灵活度高可以任意定制中高自定义节点和工具可扩展运维成本需要自己处理日志、队列、部署平台内置运行日志和应用管理知识库管理自建向量库、分块、索引内置文档分段、检索、引用溯源工具接入写代码注册工具函数HTTP 请求节点、自定义工具、代码节点这并不代表 Dify 能替代所有后端开发而是说它真正改变的是原型和中小型应用的生产效率。适合用 Dify 的场景包括企业内部知识库问答、智能客服初筛、简历筛选、工单分类、周报自动生成、招聘助手以及任何需要把 LLM 和内部 API 串起来的流程。不适合的场景则是超大规模的定制化模型训练、对执行链路有极端控制要求、或者需要把 Agent 核心逻辑深度嵌入现有业务代码库的团队。3. Dify 核心概念应用、工作流、节点、知识库在开始部署之前先把 Dify 里的几个基础概念说清楚。**应用App**是一个对外暴露的服务单元它定义了这个 Agent 或工作流干什么、用什么模型、有哪些参数。开发者在 Dify 里创建应用后可以把它发布成 API 服务也可以通过网页嵌入分享给内部用户。Chatflow 与 Workflow是两种最常被混淆的模式。Chatflow 是聊天流适合对话式 Agent有上下文记忆能力用户可以和机器人多轮问答。Workflow 是工作流适合自动化、批量处理型任务比如简历筛选、报表生成、数据抽取。两者的本质区别在于是否面向多轮对话。简历筛选这类任务通常用 Workflow 模式因为它是一次性输入输出智能客服则更适合 Chatflow因为需要记忆对话上下文。**节点Node**是工作流的基本单元。Dify 提供了开始节点、结束节点、LLM 节点、知识检索节点、代码节点、HTTP 请求节点、条件分支节点、问题分类节点等。一个工作流本质上就是节点的有向连接图。**Agent 节点和工具Tool**需要额外解释。很多开发者容易把 Agent 和工作流混在一起。工作流是“人编排好的固定流程”节点顺序在运行前就已经确定Agent 是“让模型在运行过程中决定下一步调用什么工具”。打个比方工作流是流水线每个工位都有人负责Agent 是一个调度员他根据情况判断这个零件该送去哪个工位。Dify 的 Agent 应用就是给模型提供一组工具让它在对话中自主决定调用顺序。**知识库Knowledge**则是给 Agent 提供私有知识的模块。你把 PDF、Markdown、TXT 文件上传后Dify 会做分块和向量化。当用户提问时知识检索节点能在知识库中找到相关内容把这些内容作为上下文交给 LLM 生成回答从而避免模型一本正经地编造事实。从架构层级看Dify 从上到下依次是应用层Agent/Chatflow/Workflow、编排层节点与工具、模型层各类模型供应商、平台层API 服务、日志、权限。理解了这个分层后面配置节点时就清楚了。4. Dify 环境部署与前置条件Dify 官方提供 Docker Compose 部署、本地源码部署等多种方式。对大多数开发者Docker Compose 是最快也最容易维护的方式。4.1 环境准备需要准备的环境如下操作系统Linux 或 macOS 都可以Windows 用户推荐安装 Docker Desktop并开启 WSL2。Docker建议使用 Docker 20.10 及以上版本。Docker Compose建议使用 Compose V2也就是通过docker compose命令调用。硬件配置最低 2 核 4G 内存建议 4 核 8G。如果后续要跑本地开源模型需要更高配置。4.2 获取 Dify 源码并启动Dify 项目托管在 GitHub 的 LangGenius 组织下。部署命令如下# 1. 克隆 Dify 仓库 git clone https://github.com/langgenius/dify.git # 2. 进入 docker 目录 cd dify/docker # 3. 复制环境变量文件 cp .env.example .env # 4. 启动容器 docker compose up -d这里真正容易踩坑的是第三步和第四步。.env文件里包含了 Dify 各个服务的端口、数据库连接、密钥等配置。如果之前部署过其他应用占用了 80 端口就需要提前修改.env里的EXPOSE_NGINX_PORT之类的端口变量否则容器启动会失败。4.3 检查容器启动状态执行docker compose ps可以查看所有容器状态。Dify 主要由 api、worker、web、db、redis、sandbox、ssrf_proxy 等容器组成。正常启动后你可以看到它们的状态都是 Up。docker compose ps docker compose logs -f api worker访问http://localhost就能打开 Dify 的 Web 界面。第一次打开时需要设置管理员邮箱和密码这个账号用于登录后台一定要记住。4.4 初始化管理员账号首次进入控制台会要求设置管理员账号。这里需要填写邮箱和密码。完成后系统会引导你进入工作台。如果这一步卡住大概率是 API 容器还没有完全启动等一两分钟再刷新页面。5. 在 Dify 中配置模型并创建 Agent 应用5.1 接入模型供应商部署完成后的第一步是接入模型供应商。进入“设置”页面选择“模型供应商”找到 OpenAI 或者其他你使用的模型服务商填写 API Key。在模型供应商官方控制台创建 API Key 时要注意 Key 通常只在创建时完整显示一次建议创建后立即保存到安全的地方。Dify 支持很多模型包括 OpenAI、Anthropic、OpenAI 兼容接口、Azure OpenAI 以及 Ollama 等本地模型。如果你所在团队使用内部模型网关凡是提供 OpenAI 兼容接口的都可以通过自定义 API 地址接入。关键配置项API Key模型供应商控制台生成的密钥。Base URL默认是官方地址如果使用代理网关或私有化部署的模型服务需要修改。模型列表Dify 会自动拉取该供应商支持的模型在下拉框中选择具体要用的模型名。5.2 创建 Agent 应用登录 Dify 工作台后点击“创建空白应用”选择“Agent”模式填写应用名称和描述。应用名称建议用英文或拼音方便后续 API 路径和日志检索。描述字段会作为 Agent 的系统提示词的一部分建议写清楚这个 Agent 的职责边界。比如“简历筛选 Agent用于根据职位描述初筛候选人简历输出结构化结论。”创建完成后会进入 Agent 编排界面。主要包括会话提示词、模型选择、工具配置三个区域。5.3 配置系统提示词与模型参数在 Agent 编排界面你需要写一段 Sys Prompt明确告诉模型它的角色、任务、输出格式和约束。模型参数方面温度决定随机性一般任务建议 0.2 到 0.5最大 Token 上限根据输出长度设置比如简历筛选的最终结果以 JSON 返回那么 1000 到 2000 是合理范围。关于工具配置建议先把常用的工具加上比如 Web 搜索、维基百科、Arxiv 等内置工具。企业内部场景更多是自定义工具Dify 可以通过 OpenAPI Schema 描述来接入已有 HTTP API。外部服务也可以直接用 HTTP 请求节点而不用单独封装成工具。6. 实战搭建一个“简历筛选 Agent”工作流接下来做一个完整的实战示例这是本文的核心场景。我们的业务需求是HR 助理把职位描述和简历文本粘贴到工作流里工作流自动抽取简历关键字段、计算技能匹配度、生成初筛结论。这类任务非常适合用 Dify 的 Workflow 模式实现。6.1 工作流整体设计整个工作流包含六个节点开始节点接收两个输入变量job_description职位描述和candidate_resume简历文本。LLM 节点“简历信息抽取”从简历中抽取姓名、工作年限、技能列表、教育背景输出 JSON。知识检索节点“历史岗位标准”根据职位描述检索企业知识库补充岗位硬性要求。代码节点“匹配度计算”利用 Python 计算技能命中率得到 0 到 1 之间的分数。LLM 节点“生成筛选结论”结合前面所有结果输出是否推荐进入下一轮。结束节点返回结构化 JSON 给调用方。这个流程看起来不复杂但它覆盖了 RAG、LLM 抽取、代码计算、结构化输出四个 Agent 工作流最常用的能力。下面是节点连接关系的示意 YAML实际使用中 Dify 的工作流 DSL 文件还包含画布位置等 UI 信息这里只展示关键节点配置app: name: resume-filter-agent mode: workflow description: 根据职位描述初筛候选人简历输出结构化筛选结论 workflow: graph: nodes: - id: start type: start data: title: 简历筛选入口 variables: - variable: job_description label: 职位描述 type: text-input - variable: candidate_resume label: 简历文本 type: paragraph - id: llm_extract type: llm data: title: 简历信息抽取 model: provider: openai-compatible name: gpt-4o-mini prompt_template: - role: system text: | 你是资深招聘助理。请从简历文本中抽取以下字段 姓名、工作年限、技能列表、教育背景。 只输出 JSON不要输出解释。 格式{name: , years: 0, skills: [], education: } variables: - variable: resume value: {{#start.candidate_resume#}} - id: knowledge_retrieval type: knowledge-retrieval data: title: 查询企业岗位标准 dataset_ids: - 这里填写知识库ID query: {{#start.job_description#}} retrieval_mode: semantic_search top_k: 3 - id: code_score type: code data: title: 技能匹配度计算 code: | def main(job_description: str, extracted_json: str) - dict: import json try: data json.loads(extracted_json) except Exception: data {} required_skills [Python, Docker, Kubernetes, AWS] skills data.get(skills, []) hit [s for s in skills if s in required_skills] score round(len(hit) / len(required_skills), 2) return {score: score, hit_skills: hit, required_skills: required_skills} variables: - variable: job_description value: {{#start.job_description#}} - variable: extracted_json value: {{#llm_extract.text#}} - id: llm_conclusion type: llm data: title: 生成筛选结论 model: provider: openai-compatible name: gpt-4o-mini prompt_template: - role: system text: | 你是招聘主管的助理。请根据抽取信息和技能得分给出筛选建议。 输出 JSON {suggestion: 通过/待定/不通过, reason: 一句话理由} - id: end type: end data: title: 输出结果 outputs: - variable: result value: {{#llm_conclusion.text#}}这个简化的 DSL 结构展示了节点之间如何依赖上游变量。在 Dify 界面中你在 LLM 节点里可以通过{{#start.candidate_resume#}}这类引用语法把开始节点的输入变量传给后续节点。6.2 各节点配置说明与 Prompt先说开始节点。开始节点定义了工作流接收的外部参数。job_description是单行文本candidate_resume是多行文本。调用工作流 API 时请求体里的inputs必须包含这两个字段。LLM 节点的 Prompt 是整个工作流的灵魂。简历抽取节点的 Prompt 一定要强调“只输出 JSON”否则模型会在 JSON 前后输出解释性文字导致代码节点解析失败。这里还有一个小技巧将比较消耗 token 的抽取步骤用便宜的轻量模型比如 gpt-4o-mini把最终决策留给更强的模型。这样既控制成本又保证输出质量。知识检索节点配置时要先在 Dify 的知识库模块上传文档、完成分段和向量化然后把知识库 ID 填到节点里。这个环节实际上是 RAG 的核心作用是让 Agent 拥有企业私有信息比如“候选人必须五年以上经验”“必须是统招本科”等硬性要求。如果没有知识库可以跳过这个节点但建议体验一次因为知识库是 Agent 和外部世界隔离开的私有记忆。6.3 Python 调用工作流 API工作流配置好并发布后Dify 会生成一个 API 密钥。下面的 Python 代码演示如何调用这个工作流import requests API_URL http://localhost/v1/workflows/run API_KEY app-你的API密钥 payload { inputs: { job_description: 招聘 5 年以上经验的 Python 后端工程师熟悉 Docker、Kubernetes、AWS, candidate_resume: 张三6 年 Python 后端开发经验熟悉 Docker、Kubernetes、AWS。 }, response_mode: blocking, user: csdn-demo, } headers { Authorization: fBearer {API_KEY}, Content-Type: application/json, } resp requests.post(API_URL, jsonpayload, headersheaders) print(resp.status_code) print(resp.json())注意API_KEY需要在 Dify 应用的“访问 API”页面创建。response_mode填blocking表示同步等待结果适合耗时短的工作流如果任务耗时长可以改成streaming并处理流式返回。7. 运行结果与效果验证7.1 预期返回结果如果一切正常调用接口会返回类似下面的 JSON{ workflow_run_id: a1b2c3d4, data: { outputs: { result: {\suggestion\: \通过\, \reason\: \候选人6年经验技能完全匹配\} }, status: succeeded } }返回结果里的status字段是关键。只要它是succeeded就说明工作流跑通了。7.2 如何判断运行成功除了查看 API 返回你还可以在 Dify 的“日志与标注”页面看到每次工作流运行的详细记录。点击任意一次运行记录能看到每个节点的输入和输出这对于调试非常有帮助。如果运行失败第一步应该看 Dify 的日志页面中失败节点是哪一个。常见的情况是“简历信息抽取”节点成功但“匹配度计算”节点报错说明 LLM 输出的 JSON 格式不符合代码节点预期。这时候调整 Prompt或者让代码节点中的 JSON 解析逻辑更健壮重跑即可。7.3 失败排查的第一步工作流报错时先判断是编排问题还是模型问题。编排问题通常表现为节点输入为空、上游输出格式不符、代码节点 Python 异常。模型问题则表现为模型供应商接口超时、返回内容被截断、限制词命中。定位问题的最快方式是在 Dify 运行记录中查看每个节点的原始输入输出而不是只看上层 API 返回的报错信息。8. Dify 常见问题与排查思路结合实际使用经验下面列出几个高频问题。问题现象可能原因排查方式解决方案服务启动后无法访问 Web 界面80 端口被占用或容器未完全启动执行docker compose ps查看容器状态修改.env中的EXPOSE_NGINX_PORT重新启动模型调用报 401 或 404API Key 错误或模型名不存在在模型供应商页面核对模型列表与 Key重新生成 Key并在 Dify 下拉框中重新选择模型工作流提示“请安装缺失的包以使用此工作流”使用了依赖额外 Python 包的节点或插件查看节点说明和运行日志中的依赖信息在对应运行环境中安装缺失包或改用内置节点替代Agent 执行时报 provider 未及时响应模型供应商接口超时查看 api 容器日志确认模型接口连通性缩短模型上下文、降低输出 Token 上限、切换备用模型供应商知识库检索结果为空文档未完成分段或向量化失败在知识库文档详情中查看分段与索引状态重新处理文档检查 Embedding 模型是否可用工作流中一个节点报错导致整条链路中断上游输出格式变化下游解析失败在“日志与标注”中查看节点输入输出 JSON在代码节点增加异常兜底并打印输入日志调用 API 返回workflow not foundAPI Key 对应的应用不是工作流模式或应用未发布检查应用模式是否选成 Chatflow创建 Workflow 应用并发布后重新生成 API Key这里特别说一下“缺失包”的问题。Dify 的代码节点运行在沙箱环境中默认只包含 Python 标准库。如果你在代码节点里 import 了第三方库就需要注意沙箱是否支持。对于需要额外依赖的节点Dify 会提示在 Python 环境中安装缺失的包。建议尽量使用标准库完成任务把复杂计算放到外部服务里再通过 HTTP 请求节点回调。Agent 执行超时的问题也很常见。它通常不来自 Dify 本身而是模型供应商的响应速度。排查思路是看 api 容器日志如果日志显示等待模型响应时间过长就要考虑换更快的模型或者减少上下文长度。记住提示词越长响应越慢成本越高。9. 最佳实践与工程建议9.1 敏感信息管理API Key 是 Agent 工作流中最敏感的信息。不要把 Key 写死在 Prompt 或代码节点里。Dify 的自定义工具提供独立的凭据字段HTTP 请求节点也可以从环境变量中读取密钥。生产环境建议建立密钥轮换机制定期更新模型供应商 API Key。还有一点容易被忽略Prompt 注入。用户输入可能包含恶意指令试图让 Agent 忽略系统提示词。对于企业内部的 Agent 应用越权调用工具的风险很大。在设计工具权限时遵循最小权限原则不要让 Agent 直接获得删除数据库、修改生产配置等高风险权限必要时增加人工确认环节。9.2 工作流版本管理Dify 工作流支持导出 DSL 文件一般是 YAML 格式。团队协作时建议把 DSL 文件提交到 Git 仓库这样每次修改都有迹可循也方便 Code Review。线上应用升级前先在测试环境