Dify工作流实战：通过HTTP节点集成外部API构建智能天气助手

在实际 AI 应用开发中我们经常遇到一个核心需求让大语言模型LLM能够获取并处理实时、动态的外部数据。无论是查询天气、股票价格还是调用企业内部系统的接口仅仅依靠 LLM 的静态知识库是远远不够的。Dify 作为一个开源的 LLM 应用开发平台其工作流功能为解决这个问题提供了强大的可视化解决方案。它允许开发者通过拖拽节点的方式将 HTTP 请求、数据处理和 LLM 调用串联起来无需编写复杂的胶水代码就能构建出功能完整的 AI 应用。本文将围绕“天气查询”这一经典场景详细演示如何在 Dify 工作流中接入外部 API。我们将使用一个公开的免费天气 APIUApi作为示例从零开始通过三个核心步骤配置 HTTP 请求节点、处理 API 响应、将结果传递给 LLM 生成自然语言回复构建一个可运行的智能天气查询助手。整个过程完全在 Dify 的可视化界面中完成旨在让读者掌握 Dify 工作流连接外部服务的核心方法并能举一反三应用到其他 API 集成场景中。1. 理解 Dify 工作流与外部 API 集成的核心机制在开始动手之前我们需要厘清几个关键概念理解 Dify 工作流是如何与外部世界进行交互的。这有助于我们在后续配置时做出正确的设计决策。1.1 Dify 工作流可视化的 LLM 应用编排引擎Dify 工作流本质上是一个基于节点Node和边Edge的可视化编程环境。每个节点代表一个独立的功能单元例如“用户问题输入”、“大语言模型”、“知识库检索”、“代码执行”或“HTTP 请求”。节点之间通过连线传递数据数据通常以键值对Key-Value的形式在变量Variable中流动。工作流的优势在于其声明式和可视化的特性。开发者无需关心线程、异步、错误重试等底层细节只需关注业务逻辑的串联。对于集成外部 API 而言最关键的两个节点是“HTTP 请求”节点和“工具调用”节点后者通常用于更规范的 API 封装。本文主要使用前者因为它更通用、更直接。1.2 HTTP 请求节点连接外部服务的桥梁HTTP 请求节点是 Dify 工作流与外部 API 通信的核心。你可以将其理解为一个内置的、可配置的 HTTP 客户端如curl或requests库的图形化版本。该节点需要你提供以下关键信息URL目标 API 的完整地址。方法GET、POST、PUT、DELETE 等。请求头例如Content-Type: application/json、Authorization: Bearer token。查询参数/请求体传递给 API 的具体参数。超时时间防止长时间无响应卡死工作流。配置完成后该节点会执行 HTTP 调用并将 API 返回的原始响应通常是 JSON 或 XML 格式输出为一个变量供后续节点使用。1.3 数据处理从原始响应到 LLM 可读内容外部 API 的响应往往不是 LLM 能直接处理的理想输入。它可能包含冗余的元数据、嵌套过深的结构或者是不友好的格式。因此在将 API 响应喂给 LLM 之前通常需要一个数据处理环节。在 Dify 中这可以通过以下几种方式实现“变量赋值器”节点用于提取复杂 JSON 中的特定字段并将其赋值给一个结构更清晰的新变量。“代码执行”节点如果你需要更复杂的转换逻辑如日期格式化、数值计算可以使用 Python 或 JavaScript 代码片段进行处理。在 LLM 节点提示词中直接引用对于简单的 JSON可以直接将整个响应文本插入提示词并指示 LLM 自行解析。但这依赖于 LLM 的解析能力且可能浪费 Token。一个稳健的流程是HTTP 请求 - 变量赋值器提取核心数据- LLM生成友好回复。1.4 为什么选择 UApi 作为示例为了演示的通用性和可复现性我们选择一个免费、无需认证、返回结构清晰的天气 API。UApi 提供了这样的服务。它避免了因 API 密钥申请、复杂 OAuth 认证等步骤带来的干扰让我们可以专注于 Dify 工作流本身的配置逻辑。掌握这个方法后你可以轻松替换成任何需要 API Key 或复杂参数的商业或私有 API。2. 环境准备与 Dify 工作流基础配置在开始构建天气查询工作流之前你需要一个可用的 Dify 环境并熟悉其工作流编辑器的基本操作。2.1 Dify 环境准备你有两种方式获得 Dify 环境云服务直接访问 Dify 官方云平台注册账号即可使用。这是最快的方式。本地部署参考官方 GitHub 仓库进行部署。这需要你具备 Docker 和 Docker Compose 的基本知识。对于本地部署一个常见的启动命令如下# 克隆仓库假设使用稳定版本 git clone -b stable https://github.com/langgenius/dify.git cd dify # 使用 docker-compose 启动 docker-compose up -d部署成功后通常在浏览器访问http://localhost:3000即可。无论哪种方式请确保你能够登录到 Dify 的控制台并进入“工作流”创建页面。2.2 创建新的工作流并规划节点登录 Dify 后跟随以下步骤点击左侧导航栏的“工作流”。点击“创建工作流”按钮。为工作流命名例如“智能天气查询助手”。在描述中简要说明其功能。进入空白的工作流画布后你会看到左侧的节点列表。我们的天气查询流程主要涉及以下几类节点你可以先将它们拖拽到画布上建立一个大致的框架开始工作流的唯一入口。对话开场白可选用于定义 AI 助手的初始问候语。问题分类器可选可用于判断用户意图是否为天气查询实现更复杂的智能体。HTTP 请求核心节点用于调用天气 API。变量赋值器核心节点用于处理 API 响应。LLM核心节点用于生成最终回复。文本回复工作流的输出节点。本节我们先搭建骨架具体配置在下一节展开。一个简单的线性结构可以是开始-HTTP 请求-变量赋值器-LLM-文本回复。用连线将这些节点按顺序连接起来。2.3 理解变量与数据流在连接节点时Dify 会提示你处理变量的输入输出。这是工作流编排的关键。输出变量每个节点执行后都会产生输出。例如HTTP 请求节点会输出一个包含状态码、响应头、响应体等信息的对象。输入变量下游节点可以引用上游节点的输出变量。例如变量赋值器节点可以读取HTTP 请求节点的响应体。变量语法在需要引用变量的输入框通常带有{{提示你可以通过{{node_id.output_key}}的格式来引用。例如{{http_request_node.body}}。在后续配置中请密切关注每个节点的输入输出面板确保数据能正确传递。3. 三步构建天气查询工作流现在我们开始核心的配置工作。整个过程将分为三个清晰的步骤。3.1 第一步配置 HTTP 请求节点调用天气 API首先我们需要从画布上找到并选中之前添加的“HTTP 请求”节点对其进行详细配置。我们将使用 UApi 的一个公开天气接口。节点基础信息将节点重命名为“获取天气数据”便于识别。配置请求地址与方法URL填入https://api.uapi.com/user/weather/v1/current。这是一个查询实时天气的接口。方法选择GET。配置查询参数天气查询通常需要位置参数。我们将用户输入的城市名作为变量传递。在“参数”部分点击“添加”。键输入city。这是目标 API 约定的参数名。值这里需要引用用户输入。由于我们的流程开始于“开始”节点它默认将用户问题存储在sys.query变量中。因此值应设置为{{sys.query}}。这意味着用户问“北京天气怎么样”city参数的值就是“北京”。注意实际 API 对城市名的格式可能有要求如中文、拼音、adcode。UApi 这个接口支持中文城市名。如果接入其他 API可能需要预处理城市名。配置请求头可选对于此免费 API可能不需要特殊请求头。但对于需要Authorization或特定Content-Type的 API需在此处添加。配置超时与重试超时设置为30秒对于天气 API 通常足够。重试可设置为1或2次增强鲁棒性。处理响应保持“输出变量名”为默认的body、status_code等即可。我们主要使用body。配置完成后该节点的输出将包含一个body变量其值是 API 返回的原始 JSON 字符串。3.2 第二步使用变量赋值器解析和处理 API 响应API 返回的原始 JSON 需要被提炼提取出我们关心的天气信息如温度、天气状况、湿度等并组装成一段简洁的文本方便 LLM 生成回复。添加并连接节点从左侧面板拖拽一个“变量赋值器”节点到画布并将其放置在“HTTP 请求”节点之后。将“HTTP 请求”节点的输出连线到“变量赋值器”节点的输入。配置变量赋值器将节点重命名为“解析天气数据”。在“变量”配置区域我们需要定义新的、结构清晰的变量。点击“添加变量”。变量名输入weather_info这将是我们存储处理后信息的新变量。值类型选择“字符串”。值这是关键步骤。我们需要编写一个模板从上游的body中提取字段。 假设 API 返回的 JSON 结构如下具体需查看 API 文档{ code: 200, data: { city: 北京市, weather: 晴, temperature: 22, humidity: 65%, wind: 东南风 3级 } }在“值”的编辑框中我们可以使用 Dify 的内置模板语法和JSON函数来解析城市{{JSON(body).data.city}} 天气状况{{JSON(body).data.weather}} 温度{{JSON(body).data.temperature}}℃ 湿度{{JSON(body).data.humidity}} 风力{{JSON(body).data.wind}}{{JSON(body)}}将上游的body字符串转换为 JSON 对象。{{JSON(body).data.city}}则逐级访问获取城市名。重要你必须根据实际调用的 API 响应结构来调整这里的路径。如果body的根节点直接就是数据则可能是{{JSON(body).city}}。配置错误会导致变量为空。最可靠的方法是先运行一次查看“HTTP 请求”节点输出的body具体内容。错误处理进阶一个健壮的工作流应该考虑 API 调用失败如网络错误、城市不存在的情况。你可以添加一个“分支”节点根据“HTTP 请求”节点的status_code是否等于 200 来决定流程走向。在失败分支中使用“变量赋值器”设置一个错误信息变量然后直接跳转到“文本回复”节点返回友好错误提示而不再调用 LLM。完成此步骤后我们得到了一个格式工整的weather_info字符串变量包含了所有关键天气信息。3.3 第三步配置 LLM 节点生成自然语言回复最后我们需要让 LLM 根据处理好的天气数据生成一段友好、自然的回复给用户。添加并连接节点拖拽一个“LLM”节点到画布放置在“变量赋值器”节点之后。将“变量赋值器”节点的输出连线到“LLM”节点的输入。选择模型在 LLM 节点的配置面板中选择一个可用的模型例如 OpenAI 的 GPT 系列、 Anthropic 的 Claude 系列或 Dify 内置的开源模型。确保该模型已被正确配置且拥有额度。编写提示词这是决定回复质量的关键。在“提示词”编辑框中我们需要清晰地指示 LLM 的任务和上下文。你是一个天气助手。请根据用户的问题和以下的实时天气数据生成一段亲切、简洁的回复。 天气数据 {{weather_info}} 用户的问题是{{sys.query}} 请直接给出回复不要解释你是如何获取数据的。{{weather_info}}引用了上一步“变量赋值器”节点生成的、包含格式化天气信息的变量。{{sys.query}}再次引用了用户的原始问题让 LLM 的回复更有针对性。配置生成参数可以调整“温度”、“最大生成长度”等参数来控制回复的随机性和长度。对于天气查询温度可以设低一些如 0.3以保证回复的稳定性和事实准确性。连接至输出将“LLM”节点的输出连线到最终的“文本回复”节点。“文本回复”节点会自动将 LLM 生成的内容作为工作流的最终输出返回给用户。至此一个完整的、可运行的天气查询工作流就配置完成了。点击画布右上角的“保存”按钮然后点击“发布”即可在聊天应用或 API 中测试这个工作流。4. 运行验证、调试与常见问题排查配置完成后必须进行充分的测试以确保工作流在所有预期和异常情况下都能正确运行。4.1 如何测试工作流Dify 提供了便捷的测试面板在工作流编辑页面点击右上角的“测试”按钮会打开右侧测试面板。在“用户问题”输入框中输入测试用例例如“上海今天天气如何”。点击“运行”。观察画布上节点的执行状态。成功执行的节点会显示绿色对勾失败的节点会显示红色感叹号。你可以点击每个节点查看其详细的输入和输出数据这是调试最重要的依据。4.2 关键检查点与预期结果在测试过程中请按顺序检查以下节点检查节点预期结果如何查看HTTP 请求status_code应为 200。body应包含结构正确的 JSON 数据。点击节点在“输出”标签页查看body和status_code变量。变量赋值器weather_info变量的值应是一个格式清晰的字符串包含了从body中正确提取的温度、天气等信息。点击节点在“输出”标签页查看weather_info变量的内容。LLMoutput_text应是一段通顺的自然语言回复准确包含了weather_info中的关键数据。点击节点在“输出”标签页查看output_text。文本回复最终展示给用户的回复应与 LLM 的output_text一致。在测试面板的“运行结果”区域查看最终回复。4.3 常见问题与排查路径即使按照教程操作你也可能会遇到一些问题。下表列出了常见问题及其解决方法问题现象可能原因排查步骤与解决方案HTTP 请求节点失败状态码非2001. API URL 错误或失效。2. 查询参数city格式不符合 API 要求。3. 网络问题。1.检查 URL确认地址无误可直接在浏览器中尝试访问该 URL如https://api.uapi.com/user/weather/v1/current?city北京。2.检查参数查看节点的“输入”数据确认city参数的值是否正确传递。可能需要为城市名进行 URL 编码。3.查看错误详情点击节点查看输出可能有更详细的错误信息。变量赋值器输出的weather_info为空或错误1. JSON 路径引用错误。2. API 响应结构与预期不符。1.核对 JSON 路径仔细查看“HTTP 请求”节点输出的body完整内容。使用在线的 JSON 格式化工具查看其结构。确保{{JSON(body).data.city}}这样的路径能准确指向目标字段。2.使用调试输出可以在“变量赋值器”中先创建一个变量其值为{{body}}以确认原始数据是否正确流入。LLM 回复未包含天气数据或回复混乱1. 提示词中变量引用错误或未生效。2.weather_info变量内容格式混乱导致 LLM 误解。1.检查变量名确认提示词中{{weather_info}}的拼写与变量赋值器中定义的变量名完全一致。2.优化提示词让指令更明确。例如改为“请严格使用以下数据回答问题\n{{weather_info}}”。3.简化数据格式在变量赋值器中将天气数据格式化为更清晰的列表或键值对形式。工作流运行缓慢1. 外部 API 响应慢。2. LLM 模型响应慢。3. 网络延迟。1.设置超时在 HTTP 请求节点中合理设置超时时间如10秒避免长时间等待。2.选择更快模型尝试使用响应速度更快的 LLM 模型。3.检查节点依赖确保没有不必要的串行阻塞尽可能让可并行的节点并行执行虽然本示例是线性的。错误信息包含api error: 400等请求参数不符合 API 服务端要求。这是来自上游 API 的错误。仔细阅读 API 提供商的文档检查请求方法、请求头特别是Content-Type、参数名和参数值格式是否正确。常见的 400 错误是city参数缺失或值无效。4.4 使用“对话开场白”与“问题分类器”进行增强为了让助手更智能你可以在流程开始处添加对话开场白设置助手的身份和功能例如“我是一个天气查询助手可以告诉你全球主要城市的实时天气。”问题分类器判断用户输入是否与天气相关。如果不是可以提前结束流程或跳转到其他处理分支。这能有效防止用户问“讲个笑话”时工作流仍去调用天气 API 的尴尬情况。5. 生产环境最佳实践与扩展方向将工作流从测试环境迁移到生产环境需要考虑更多关于稳定性、安全性和可维护性的问题。5.1 安全性增强API 密钥管理对于需要认证的 API绝对不要将密钥硬编码在工作流配置中。应使用 Dify 的“密钥”管理功能。在 Dify 控制台的“设置”-“密钥”中添加你的 API Key。在 HTTP 请求节点的“请求头”中通过{{secrets.your_key_name}}的形式引用密钥。输入校验与清理在调用外部 API 前对用户输入如城市名进行校验防止注入攻击或无效请求。可以使用“代码执行”节点编写简单的校验逻辑。限制与鉴权在 Dify 应用设置中配置访问权限和频率限制防止滥用。5.2 稳定性与可观测性完备的错误处理如前所述使用“分支”节点为 HTTP 请求和 LLM 调用设计失败处理流程。例如API 失败时可以尝试备用 API或直接返回缓存的通用提示。设置重试机制对于可能因网络波动失败的 HTTP 请求在节点配置中启用重试。记录日志在关键节点如 HTTP 请求前后、LLM 调用前后使用“变量赋值器”记录日志信息或集成 Dify 的日志功能便于问题追踪。监控与告警监控工作流的执行成功率和耗时。对于关键业务流可以设置异常告警。5.3 性能优化缓存策略对于天气这类更新频率不高的数据可以考虑引入缓存。虽然 Dify 工作流原生不支持但你可以调用一个具备缓存能力的中间件 API由你自己开发。或者在“代码执行”节点中实现简单的内存缓存逻辑注意多实例部署时的局限性。异步与超时为所有外部调用HTTP、LLM设置合理的超时时间避免一个慢请求拖垮整个工作流。精简提示词在保证指令清晰的前提下优化提示词减少不必要的 Token 消耗降低成本并提升速度。5.4 扩展应用场景掌握了 HTTP 请求节点集成 API 的方法后你可以将此外延到无数场景金融信息查询接入股票、汇率 API让 AI 助手提供财经资讯。电商集成接入商品搜索、订单查询 API构建购物助手。企业内部系统连接 CRM、ERP、OA 系统的 API打造企业内部知识问答和流程自动化助手。多工具编排在一个工作流中串联多个不同的 API 调用。例如先调用地图 API 获取坐标再调用天气 API 获取该坐标的天气。与知识库结合将 API 获取的实时数据与本地知识库的静态文档相结合让 AI 的回答既有实时性又有深度。构建复杂工作流时核心思路不变明确数据输入、设计处理节点HTTP请求、变量转换、逻辑判断、规划数据流、定义最终输出。通过 Dify 的可视化界面这些原本需要大量编码的集成工作变得直观且高效。