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 应用，添加知识检索节点，绑定模型，十分钟就能跑通一个可演示的原型。

这并不代表 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 工作流整体设计

整个工作流包含六个节点：

1. 开始节点：接收两个输入变量，job_description（职位描述）和candidate_resume（简历文本）。
2. LLM 节点“简历信息抽取”：从简历中抽取姓名、工作年限、技能列表、教育背景，输出 JSON。
3. 知识检索节点“历史岗位标准”：根据职位描述检索企业知识库，补充岗位硬性要求。
4. 代码节点“匹配度计算”：利用 Python 计算技能命中率，得到 0 到 1 之间的分数。
5. LLM 节点“生成筛选结论”：结合前面所有结果，输出是否推荐进入下一轮。
6. 结束节点：返回结构化 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": f"Bearer {API_KEY}", "Content-Type": "application/json", } resp = requests.post(API_URL, json=payload, headers=headers) 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 常见问题与排查思路

结合实际使用经验，下面列出几个高频问题。

这里特别说一下“缺失包”的问题。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。线上应用升级前，先在测试环境