Dify工作流实战：零代码接入外部API，快速扩展AI应用能力-平芜编程栈

这次我们来看一个非常实用的 AI 应用开发技巧：如何利用 Dify 平台，通过可视化拖拽的方式，轻松接入外部 API 服务。整个过程不需要写一行代码，就能让大模型具备查询实时天气、获取股票信息、调用翻译服务等外部能力。对于想快速构建 AI 应用、但又不想深陷代码泥潭的开发者或产品经理来说，这无疑是一条捷径。

Dify 作为一个开源的 LLM 应用开发平台，其核心价值在于将复杂的 AI 应用开发流程标准化、可视化。它最大的特点之一就是强大的工作流编排能力，允许你像搭积木一样，将大模型、知识库、代码解释器以及我们今天要重点讲解的“HTTP 请求”节点连接起来，构建出功能丰富的智能体或应用。

本文将聚焦于一个具体场景：为你的 AI 助手添加天气查询功能。我们将使用一个公开、免费的天气 API（UApi）作为示例，在 Dify 工作流中通过三个核心步骤完成配置。你会看到，从创建 HTTP 请求节点到解析返回数据，再到让大模型组织成友好回复，整个过程都在图形化界面中完成。无论你是想验证一个想法，还是需要快速集成某个第三方服务，这个方法都能显著提升你的效率。

1. 核心能力速览

在深入操作之前，我们先快速了解 Dify 工作流接入外部 API 的核心特性和优势。

能力项	说明
核心功能	通过可视化工作流，无需编码即可调用任意 HTTP/HTTPS 接口，扩展大模型能力。
技术门槛	极低。只需了解基本的 API 概念（如 URL、请求方法、参数）即可上手。
部署方式	支持 SaaS 云端使用（Dify Cloud）和本地私有化部署。本文演示基于 SaaS 版本，本地部署流程类似。
硬件要求	无特殊要求。使用 SaaS 版时仅需浏览器；本地部署则需满足 Docker 或 Python 环境。
关键节点	“HTTP 请求”节点：用于发送请求并接收响应。 “代码”节点：可选，用于复杂的数据预处理或后处理。
适合场景	1. 快速为聊天助手添加实时信息查询（天气、汇率、新闻）。 2. 连接企业内部系统（CRM、ERP）实现数据查询。 3. 构建自动化流程，如接收用户输入后触发外部服务。
是否支持批量	工作流本身设计用于处理单次对话或请求。可通过“循环”节点或外部调度实现批量调用，但通常更适用于实时交互场景。
是否支持 API	Dify 工作流本身可以作为 API 发布，供外部系统调用。这意味着你构建的“天气查询工作流”也能变成一个 API 服务。

从表格可以看出，Dify 工作流的核心优势在于降低集成复杂度和提升开发速度。你不需要关心网络请求库、错误处理、异步调用等底层细节，只需关注业务逻辑的拼接。

2. 适用场景与使用边界

适合谁用？

AI 应用开发者：希望快速验证想法，将大模型与外部数据/服务结合，构建功能更丰富的智能体。
产品经理或业务人员：想亲自设计并测试一些自动化流程，无需等待开发排期。
学生或研究者：用于学习 LLM 应用架构和 API 集成原理，可视化界面更直观。

能解决什么问题？

信息实时性：让大模型摆脱“知识截止日期”的限制，能查询最新天气、股价、新闻。
功能扩展性：弥补大模型在计算、检索特定数据库、操作硬件等方面的不足。
流程自动化：将多个步骤（用户输入 -> 调用 API -> 处理结果 -> 生成回复）串联成一个自动执行的管道。

不适合什么场景？

超高性能、低延迟要求：可视化工作流会增加少量开销，对于微秒级响应的场景，直接编码仍是首选。
极其复杂的业务逻辑：当数据处理需要大量条件判断、循环或复杂算法时，全部用工作流节点拼接可能变得难以维护，此时“代码”节点或自定义插件是更好的补充。
需要处理大量二进制数据（如文件上传/下载到第三方）：虽然可能实现，但配置会相对复杂。

安全与合规边界

API 密钥管理：在配置 HTTP 请求时，如需 API Key，务必使用 Dify 提供的“加密”字段功能存储，避免在日志或界面中明文暴露。
请求频率与配额：遵守你所调用的第三方 API 的使用条款，注意调用频率限制和配额，避免因工作流被频繁触发而导致 API 被封。
数据隐私：如果处理用户敏感信息并通过工作流传给第三方 API，需确保该 API 提供商符合相关的数据隐私法规（如 GDPR）。
服务稳定性：外部 API 的可用性不在你的控制范围内，在设计工作流时应考虑添加超时设置和错误处理分支。

3. 环境准备与前置条件

由于我们以 Dify SaaS 平台为例，环境准备非常简单。如果你想在本地部署 Dify，则需要额外步骤。

3.1 使用 Dify Cloud (SaaS)

这是最快开始的方式。

账号：访问 Dify 官网并注册一个账号。
浏览器：推荐使用最新版的 Chrome、Edge 或 Firefox。
网络：确保能正常访问 Dify 云端服务及你将要调用的目标 API（本例中的天气 API）。

3.2 本地部署 Dify (可选)

如果你需要数据私有化或定制化开发，可以选择本地部署。

操作系统：Linux (Ubuntu 20.04+ 推荐), macOS, 或 Windows (WSL2 推荐)。
Docker 与 Docker Compose：这是最推荐的部署方式。确保已安装最新稳定版。
硬件：最低 4GB RAM，2核 CPU。如果需运行本地模型，则需要更高配置和 GPU。
端口：默认占用 3000（前端）和 5001（后端）端口，确保其未被占用。
磁盘空间：至少 10GB 可用空间，用于存放 Docker 镜像和日志。

3.3 目标 API 准备

本例将使用UApi的免费天气接口。你需要：

获取一个免费的 API Key（通常注册即可）。
了解其接口地址、请求方法和参数。例如，一个典型的天气查询接口可能如下：
- 地址：https://api.uapi.com/weather/now
- 方法：GET
- 参数：city(城市名)，key(你的 API Key)

请提前准备好这些信息，我们将在下一步直接使用。

4. 创建你的第一个 API 工作流

现在，我们进入核心实操环节。登录你的 Dify 控制台，按照以下步骤操作。

4.1 创建新应用与工作流

在 Dify 控制台，点击“创建新应用”。
选择“工作流”类型，输入应用名称，例如“智能天气助手”。
点击创建后，你会进入一个空白的画布，这就是你的工作流编辑器。

4.2 拖拽并配置“HTTP 请求”节点

这是连接外部世界的桥梁。

在画布左侧的节点列表中，找到“工具”分类，将“HTTP 请求”节点拖到画布中央。
点击该节点进行配置：
- URL：填入天气 API 的完整地址，例如https://api.uapi.com/weather/now。
- 方法：选择GET（根据 API 文档选择）。
- 请求头：点击“添加”。如果需要，在此处添加Content-Type或Authorization等。对于简单的 GET 请求，可能不需要。
- 参数：点击“添加参数”。这里添加查询参数。
  - 名称：city
  - 值类型：选择“变量”
  - 值：从下拉菜单中选择sys.query。这表示使用用户对话中输入的问题作为城市名来源。更精确的做法是先用 LLM 节点提取城市实体，这里为简化，我们假设用户输入直接是城市名。
- 认证：如果 API 需要 Key，不建议放在 URL 参数中。可以在“参数”或“请求头”中添加。例如，在“参数”中添加：
  - 名称：key
  - 值类型：选择“常量”
  - 值：你的实际API密钥（对于生产环境，建议在“环境变量”中设置，此处引用变量{{#env.API_KEY#}}）
配置完成后，节点右上角显示“已配置”。

4.3 添加“文本生成”节点并连接

HTTP 节点获取到的是原始数据（通常是 JSON），需要让 LLM 来理解和组织成人类可读的回复。

从左侧“基础”分类中，拖拽一个“LLM”节点（如 GPT-3.5/4， Claude，或你配置的本地模型）到画布。
将“HTTP 请求”节点的输出端口（绿色圆点）拖拽连接到“LLM”节点的输入端口。
配置 LLM 节点：
- 选择模型：根据你的可用性和需求选择，例如gpt-3.5-turbo。
- 系统提示词：输入指令，告诉 LLM 如何处-理来自 HTTP 请求的数据。
```
你是一个天气助手。我将提供给你从天气 API 获取的原始 JSON 数据。 你的任务是以友好、清晰的方式向用户汇报天气情况。 请直接输出天气信息，不要提及“根据数据”或“JSON显示”等字眼。 如果数据中缺少关键信息或出错，请礼貌地告知用户暂时无法获取天气。
```
- 上下文：在“上下文”区域，你需要将 HTTP 返回的结果引入。点击“添加变量”，选择“节点”，然后选中你之前配置的“HTTP 请求”节点。其输出变量（如result或body）会自动出现在列表中。在提示词中，通过{{#}}引用这个变量，例如：
```
以下是天气 API 返回的数据： {{#HTTP请求.body#}} 请根据以上数据生成天气报告。
```
- 其他参数：温度（Temperature）、最大生成长度等保持默认或按需调整。

4.4 设置工作流入口与发布

从左侧“开始”分类中，拖拽“开始”节点到画布。
将“开始”节点连接到“HTTP 请求”节点。
点击画布右上角的“发布”按钮。首次发布需要配置“对话开场白”和“提示词”。开场白可以设置为“你好，我可以为你查询天气，请告诉我城市名。”。
发布后，点击“预览”即可在右侧聊天窗口进行测试。

至此，一个最简单的“用户输入城市名 -> 调用天气 API -> LLM 生成回复”的工作流就搭建完成了。整个过程通过拖拽和表单填写完成，无需编码。

5. 功能测试与效果验证

让我们来完整地测试这个工作流。

5.1 测试准备

确保你的工作流已保存并发布。
在 Dify 应用界面的右侧，找到“预览”或“对话”窗口。

5.2 基础功能测试

测试用例1：正常查询
- 输入：“北京”
- 预期结果：工作流应成功调用 API，LLM 节点应生成一段包含北京当前天气、温度、湿度、风力等信息的自然语言描述。
- 成功标准：回复内容准确、通顺，且信息来源于 API 返回的真实数据。
测试用例2：城市名不明确
- 输入：“纽约”
- 预期结果：API 可能返回多个“纽约”的结果或错误。观察 LLM 在系统提示词指导下如何处理不明确或错误的数据。理想情况是它能给出一个合理的回复，如“请问您指的是美国纽约州纽约市吗？”
- 成功标准：工作流没有崩溃，LLM 能处理异常输入并给出友好回应。
测试用例3：API 异常模拟
- 操作：临时在 HTTP 请求节点中修改一个错误的 API Key。
- 输入：“上海”
- 预期结果：HTTP 请求节点应返回 401 或其他错误状态码。观察 LLM 的回复是否符合系统提示词中“礼貌告知无法获取”的设定。
- 成功标准：工作流能优雅地处理后端服务错误，并向用户反馈。

5.3 工作流运行详情查看

Dify 提供了一个强大的功能：运行跟踪。在测试对话的每条回复旁边，点击“查看工作流运行”或类似按钮。你可以清晰地看到：

工作流每个节点的执行状态（成功/失败）。
“HTTP 请求”节点具体的请求 URL、发送的参数、返回的原始状态码和 Body。
“LLM”节点接收到的上下文、发送给模型的完整提示词以及模型的原始回复。这个功能对于调试和验证数据流转至关重要。

6. 进阶：优化工作流与错误处理

基础工作流能跑通，但要健壮、实用，还需要优化。

6.1 使用“参数提取器”节点净化输入

目前我们假设用户直接输入城市名。现实中，用户可能说“今天北京天气怎么样？”。我们可以用 LLM 来提取关键实体。

在“开始”节点后，插入一个“LLM”节点，专门用于提取城市。
配置该节点的提示词为：“请从用户的问题中提取城市名称，只输出城市名，不要其他任何文字。用户问题：{{#sys.query#}}”。
将这个 LLM 节点的输出（即提取出的城市名）作为变量，连接到“HTTP 请求”节点的city参数值上。这样，无论用户如何提问，我们都能获得干净的城市参数。

6.2 为 HTTP 请求添加错误处理分支

默认情况下，HTTP 请求失败可能导致整个工作流中断。我们可以使用“判断”节点来分流。

在“HTTP 请求”节点后，拖入一个“判断”节点。
配置判断条件。例如，判断HTTP请求.status是否等于200。
将“HTTP 请求”节点的输出连接到“判断”节点。
“判断”节点有两个输出分支：“是”（状态码为200）和“否”。
- “是”分支：连接至主“LLM”节点，正常生成天气报告。
- “否”分支：可以连接另一个“LLM”节点或直接连接一个“回答”节点，直接告诉用户“天气服务暂时不可用，请稍后再试”。

6.3 解析复杂的 JSON 响应

有些 API 返回的 JSON 结构嵌套很深，你可能只需要其中的几个字段。虽然可以在主 LLM 的提示词里说明，但更高效的方式是先用“代码”节点进行预处理。

在“HTTP 请求”节点和主“LLM”节点之间，插入一个“代码”节点（Python）。

在代码编辑器中，你可以编写 Python 代码来解析inputs（即上一个节点的输出）。

# 假设 inputs 包含 ‘body‘ 字段，其值是 API 返回的 JSON 字符串 import json data = json.loads(inputs[‘body‘]) # 提取所需字段 city = data[‘location‘][‘name‘] temp = data[‘now‘][‘temp‘] condition = data[‘now‘][‘text‘] # 输出一个结构更清晰的新字典 output = { “city“: city, “temperature“: temp, “weather_condition“: condition }

代码节点的输出（output字典）将作为一个新变量，可以被后续的 LLM 节点更简洁地引用，例如{{#代码.output#}}。

7. 将工作流发布为 API 服务

你构建的这个天气查询工作流，不仅可以用于聊天界面，还能直接发布为独立的 API，集成到你的其他应用系统中。

在 Dify 应用概览页面，找到“访问方式”或“API 访问”选项卡。
点击“创建 API 密钥”，为你的应用生成一个密钥。
Dify 会提供该工作流的 API 端点（Endpoint）和调用示例。

你可以使用curl、Postman 或任何编程语言来调用它。

curl -X POST \ https://api.dify.ai/v1/workflows/run \ -H ‘Authorization: Bearer YOUR_APP_API_KEY‘ \ -H ‘Content-Type: application/json‘ \ -d ‘{ “inputs“: { “query“: “上海现在的天气“ } }‘

调用后，你将获得一个包含工作流完整输出的 JSON 响应，其中就包含了 LLM 生成的天气报告。

这意味着，你通过可视化搭建的流程，瞬间变成了一个拥有自然语言理解和外部数据获取能力的微服务。

8. 常见问题与排查方法

在搭建和测试过程中，你可能会遇到以下问题：

问题现象	可能原因	排查方式	解决方案
HTTP 请求节点失败，状态码 4xx	1. API URL 错误。 2. 缺少必要参数或参数值错误。 3. API Key 无效或过期。 4. 请求头配置有误。	1. 在工作流运行详情中，检查该节点发出的完整请求 URL 和头部。 2. 复制到 Postman 中单独测试。	1. 核对 API 文档，修正 URL 和参数。 2. 检查 API Key 是否正确，并确保其在 Dify 中正确配置（建议使用环境变量）。
HTTP 请求节点失败，状态码 5xx	1. 目标 API 服务端内部错误。 2. 网络超时。	1. 查看节点返回的响应体，看是否有服务商错误信息。 2. 检查网络连通性。	1. 稍后重试。 2. 联系 API 服务提供商。 3. 在 Dify 的 HTTP 请求节点设置中增加超时时间。
LLM 节点未使用 API 返回的数据	1. 上下文变量未正确引用。 2. 变量名拼写错误。	1. 在 LLM 节点配置中，检查“上下文”里是否添加了 HTTP 请求节点变量。 2. 检查提示词中`{{#变量名#}}`的拼写是否与上下文中的变量名完全一致。	1. 重新在上下文区域添加变量。 2. 使用变量选择器点选，避免手动输入。
LLM 回复格式不符合预期	系统提示词指令不够清晰。	查看运行详情中，LLM 节点实际收到的提示词内容。	优化系统提示词，给出更明确、更具体的指令和输出格式示例。
工作流发布后调用 API 无响应	1. 应用未成功发布。 2. API 密钥权限不足。 3. 输入参数结构不对。	1. 在 Dify 控制台确认应用状态为“已发布”。 2. 检查 API 调用时`inputs`的结构是否与工作流“开始”节点定义的输入变量匹配。	1. 重新发布应用。 2. 在“API 访问”页面查看调用示例，严格按照示例结构构造请求体。
本地部署 Dify 无法访问外网 API	Docker 容器网络配置问题。	在 Dify 容器内执行`curl`命令测试是否能访问目标 API 地址。	检查 Docker 网络模式，或为 Docker 容器配置正确的代理。

9. 最佳实践与使用建议

为了让你的 Dify API 工作流更可靠、更易维护，可以参考以下建议：

环境变量管理密钥：永远不要在节点配置中硬编码 API Key、密码等敏感信息。务必使用 Dify 的“环境变量”功能，在配置时引用{{#env.VAR_NAME#}}。
为 HTTP 请求设置超时和重试：在 HTTP 请求节点的高级设置中，配置合理的超时时间（如30秒）。对于非关键任务，可以配置重试逻辑，或使用“判断”节点在失败时转向备用 API。
结构化输出：如果后续需要将工作流结果与其他系统集成，建议让 LLM 输出 JSON 等结构化数据。可以在系统提示词中明确要求：“请以 JSON 格式输出，包含 city, temperature, condition 字段。”
版本控制与迭代：Dify 支持发布新版本。当对工作流进行重大修改时，先保存为新版本并进行充分测试，然后再更新到生产环境。
监控与日志：定期查看 Dify 控制台的工作流运行日志和错误统计。对于高频使用的 API，关注其响应时间和成功率。
合规使用第三方 API：严格遵守你所用 API 的服务条款，特别是关于调用频率、数据缓存、商业用途等规定。合理设计工作流，避免触发限流。

10. 总结

通过以上步骤，我们完成了一次完整的 Dify 工作流接入外部 API 的实战。从拖拽节点、配置参数，到测试调试、发布为 API，整个过程直观且高效。这种方法的核心价值在于：

降低门槛：让不擅长编程的人也能构建功能强大的 AI 应用原型。
提升效率：可视化编排避免了重复的脚手架代码编写，专注于业务逻辑。
便于调试：图形化的运行跟踪让数据流转一目了然，快速定位问题。
灵活扩展：工作流可以轻松组合多个 API 和 LLM 调用，实现复杂逻辑。

天气查询只是一个起点。你可以举一反三，将同样的方法应用于查询汇率、搜索新闻、提交工单、查询数据库等无数场景。下次当你需要让 AI 应用“动起来”，去连接外部真实世界的数据和服务时，不妨先打开 Dify，试试用工作流来搭建。

Dify工作流实战：零代码接入外部API，快速扩展AI应用能力