戰(zhàn)：通過(guò)HTTP節(jié)點(diǎn)集成外部API構(gòu)建智能天氣助手)
在實(shí)際 AI 應(yīng)用開發(fā)中我們經(jīng)常遇到一個(gè)核心需求讓大語(yǔ)言模型LLM能夠獲取并處理實(shí)時(shí)、動(dòng)態(tài)的外部數(shù)據(jù)。無(wú)論是查詢天氣、股票價(jià)格還是調(diào)用企業(yè)內(nèi)部系統(tǒng)的接口僅僅依靠 LLM 的靜態(tài)知識(shí)庫(kù)是遠(yuǎn)遠(yuǎn)不夠的。Dify 作為一個(gè)開源的 LLM 應(yīng)用開發(fā)平臺(tái)其工作流功能為解決這個(gè)問題提供了強(qiáng)大的可視化解決方案。它允許開發(fā)者通過(guò)拖拽節(jié)點(diǎn)的方式將 HTTP 請(qǐng)求、數(shù)據(jù)處理和 LLM 調(diào)用串聯(lián)起來(lái)無(wú)需編寫復(fù)雜的膠水代碼就能構(gòu)建出功能完整的 AI 應(yīng)用。本文將圍繞“天氣查詢”這一經(jīng)典場(chǎng)景詳細(xì)演示如何在 Dify 工作流中接入外部 API。我們將使用一個(gè)公開的免費(fèi)天氣 APIUApi作為示例從零開始通過(guò)三個(gè)核心步驟配置 HTTP 請(qǐng)求節(jié)點(diǎn)、處理 API 響應(yīng)、將結(jié)果傳遞給 LLM 生成自然語(yǔ)言回復(fù)構(gòu)建一個(gè)可運(yùn)行的智能天氣查詢助手。整個(gè)過(guò)程完全在 Dify 的可視化界面中完成旨在讓讀者掌握 Dify 工作流連接外部服務(wù)的核心方法并能舉一反三應(yīng)用到其他 API 集成場(chǎng)景中。1. 理解 Dify 工作流與外部 API 集成的核心機(jī)制在開始動(dòng)手之前我們需要厘清幾個(gè)關(guān)鍵概念理解 Dify 工作流是如何與外部世界進(jìn)行交互的。這有助于我們?cè)诤罄m(xù)配置時(shí)做出正確的設(shè)計(jì)決策。1.1 Dify 工作流可視化的 LLM 應(yīng)用編排引擎Dify 工作流本質(zhì)上是一個(gè)基于節(jié)點(diǎn)Node和邊Edge的可視化編程環(huán)境。每個(gè)節(jié)點(diǎn)代表一個(gè)獨(dú)立的功能單元例如“用戶問題輸入”、“大語(yǔ)言模型”、“知識(shí)庫(kù)檢索”、“代碼執(zhí)行”或“HTTP 請(qǐng)求”。節(jié)點(diǎn)之間通過(guò)連線傳遞數(shù)據(jù)數(shù)據(jù)通常以鍵值對(duì)Key-Value的形式在變量Variable中流動(dòng)。工作流的優(yōu)勢(shì)在于其聲明式和可視化的特性。開發(fā)者無(wú)需關(guān)心線程、異步、錯(cuò)誤重試等底層細(xì)節(jié)只需關(guān)注業(yè)務(wù)邏輯的串聯(lián)。對(duì)于集成外部 API 而言最關(guān)鍵的兩個(gè)節(jié)點(diǎn)是“HTTP 請(qǐng)求”節(jié)點(diǎn)和“工具調(diào)用”節(jié)點(diǎn)后者通常用于更規(guī)范的 API 封裝。本文主要使用前者因?yàn)樗ㄓ?、更直接?.2 HTTP 請(qǐng)求節(jié)點(diǎn)連接外部服務(wù)的橋梁HTTP 請(qǐng)求節(jié)點(diǎn)是 Dify 工作流與外部 API 通信的核心。你可以將其理解為一個(gè)內(nèi)置的、可配置的 HTTP 客戶端如curl或requests庫(kù)的圖形化版本。該節(jié)點(diǎn)需要你提供以下關(guān)鍵信息URL目標(biāo) API 的完整地址。方法GET、POST、PUT、DELETE 等。請(qǐng)求頭例如Content-Type: application/json、Authorization: Bearer token。查詢參數(shù)/請(qǐng)求體傳遞給 API 的具體參數(shù)。超時(shí)時(shí)間防止長(zhǎng)時(shí)間無(wú)響應(yīng)卡死工作流。配置完成后該節(jié)點(diǎn)會(huì)執(zhí)行 HTTP 調(diào)用并將 API 返回的原始響應(yīng)通常是 JSON 或 XML 格式輸出為一個(gè)變量供后續(xù)節(jié)點(diǎn)使用。1.3 數(shù)據(jù)處理從原始響應(yīng)到 LLM 可讀內(nèi)容外部 API 的響應(yīng)往往不是 LLM 能直接處理的理想輸入。它可能包含冗余的元數(shù)據(jù)、嵌套過(guò)深的結(jié)構(gòu)或者是不友好的格式。因此在將 API 響應(yīng)喂給 LLM 之前通常需要一個(gè)數(shù)據(jù)處理環(huán)節(jié)。在 Dify 中這可以通過(guò)以下幾種方式實(shí)現(xiàn)“變量賦值器”節(jié)點(diǎn)用于提取復(fù)雜 JSON 中的特定字段并將其賦值給一個(gè)結(jié)構(gòu)更清晰的新變量?！按a執(zhí)行”節(jié)點(diǎn)如果你需要更復(fù)雜的轉(zhuǎn)換邏輯如日期格式化、數(shù)值計(jì)算可以使用 Python 或 JavaScript 代碼片段進(jìn)行處理。在 LLM 節(jié)點(diǎn)提示詞中直接引用對(duì)于簡(jiǎn)單的 JSON可以直接將整個(gè)響應(yīng)文本插入提示詞并指示 LLM 自行解析。但這依賴于 LLM 的解析能力且可能浪費(fèi) Token。一個(gè)穩(wěn)健的流程是HTTP 請(qǐng)求 - 變量賦值器提取核心數(shù)據(jù)- LLM生成友好回復(fù)。1.4 為什么選擇 UApi 作為示例為了演示的通用性和可復(fù)現(xiàn)性我們選擇一個(gè)免費(fèi)、無(wú)需認(rèn)證、返回結(jié)構(gòu)清晰的天氣 API。UApi 提供了這樣的服務(wù)。它避免了因 API 密鑰申請(qǐng)、復(fù)雜 OAuth 認(rèn)證等步驟帶來(lái)的干擾讓我們可以專注于 Dify 工作流本身的配置邏輯。掌握這個(gè)方法后你可以輕松替換成任何需要 API Key 或復(fù)雜參數(shù)的商業(yè)或私有 API。2. 環(huán)境準(zhǔn)備與 Dify 工作流基礎(chǔ)配置在開始構(gòu)建天氣查詢工作流之前你需要一個(gè)可用的 Dify 環(huán)境并熟悉其工作流編輯器的基本操作。2.1 Dify 環(huán)境準(zhǔn)備你有兩種方式獲得 Dify 環(huán)境云服務(wù)直接訪問 Dify 官方云平臺(tái)注冊(cè)賬號(hào)即可使用。這是最快的方式。本地部署參考官方 GitHub 倉(cāng)庫(kù)進(jìn)行部署。這需要你具備 Docker 和 Docker Compose 的基本知識(shí)。對(duì)于本地部署一個(gè)常見的啟動(dòng)命令如下# 克隆倉(cāng)庫(kù)假設(shè)使用穩(wěn)定版本 git clone -b stable https://github.com/langgenius/dify.git cd dify # 使用 docker-compose 啟動(dòng) docker-compose up -d部署成功后通常在瀏覽器訪問http://localhost:3000即可。無(wú)論哪種方式請(qǐng)確保你能夠登錄到 Dify 的控制臺(tái)并進(jìn)入“工作流”創(chuàng)建頁(yè)面。2.2 創(chuàng)建新的工作流并規(guī)劃節(jié)點(diǎn)登錄 Dify 后跟隨以下步驟點(diǎn)擊左側(cè)導(dǎo)航欄的“工作流”。點(diǎn)擊“創(chuàng)建工作流”按鈕。為工作流命名例如“智能天氣查詢助手”。在描述中簡(jiǎn)要說(shuō)明其功能。進(jìn)入空白的工作流畫布后你會(huì)看到左側(cè)的節(jié)點(diǎn)列表。我們的天氣查詢流程主要涉及以下幾類節(jié)點(diǎn)你可以先將它們拖拽到畫布上建立一個(gè)大致的框架開始工作流的唯一入口。對(duì)話開場(chǎng)白可選用于定義 AI 助手的初始問候語(yǔ)。問題分類器可選可用于判斷用戶意圖是否為天氣查詢實(shí)現(xiàn)更復(fù)雜的智能體。HTTP 請(qǐng)求核心節(jié)點(diǎn)用于調(diào)用天氣 API。變量賦值器核心節(jié)點(diǎn)用于處理 API 響應(yīng)。LLM核心節(jié)點(diǎn)用于生成最終回復(fù)。文本回復(fù)工作流的輸出節(jié)點(diǎn)。本節(jié)我們先搭建骨架具體配置在下一節(jié)展開。一個(gè)簡(jiǎn)單的線性結(jié)構(gòu)可以是開始-HTTP 請(qǐng)求-變量賦值器-LLM-文本回復(fù)。用連線將這些節(jié)點(diǎn)按順序連接起來(lái)。2.3 理解變量與數(shù)據(jù)流在連接節(jié)點(diǎn)時(shí)Dify 會(huì)提示你處理變量的輸入輸出。這是工作流編排的關(guān)鍵。輸出變量每個(gè)節(jié)點(diǎn)執(zhí)行后都會(huì)產(chǎn)生輸出。例如HTTP 請(qǐng)求節(jié)點(diǎn)會(huì)輸出一個(gè)包含狀態(tài)碼、響應(yīng)頭、響應(yīng)體等信息的對(duì)象。輸入變量下游節(jié)點(diǎn)可以引用上游節(jié)點(diǎn)的輸出變量。例如變量賦值器節(jié)點(diǎn)可以讀取HTTP 請(qǐng)求節(jié)點(diǎn)的響應(yīng)體。變量語(yǔ)法在需要引用變量的輸入框通常帶有{{提示你可以通過(guò){{node_id.output_key}}的格式來(lái)引用。例如{{http_request_node.body}}。在后續(xù)配置中請(qǐng)密切關(guān)注每個(gè)節(jié)點(diǎn)的輸入輸出面板確保數(shù)據(jù)能正確傳遞。3. 三步構(gòu)建天氣查詢工作流現(xiàn)在我們開始核心的配置工作。整個(gè)過(guò)程將分為三個(gè)清晰的步驟。3.1 第一步配置 HTTP 請(qǐng)求節(jié)點(diǎn)調(diào)用天氣 API首先我們需要從畫布上找到并選中之前添加的“HTTP 請(qǐng)求”節(jié)點(diǎn)對(duì)其進(jìn)行詳細(xì)配置。我們將使用 UApi 的一個(gè)公開天氣接口。節(jié)點(diǎn)基礎(chǔ)信息將節(jié)點(diǎn)重命名為“獲取天氣數(shù)據(jù)”便于識(shí)別。配置請(qǐng)求地址與方法URL填入https://api.uapi.com/user/weather/v1/current。這是一個(gè)查詢實(shí)時(shí)天氣的接口。方法選擇GET。配置查詢參數(shù)天氣查詢通常需要位置參數(shù)。我們將用戶輸入的城市名作為變量傳遞。在“參數(shù)”部分點(diǎn)擊“添加”。鍵輸入city。這是目標(biāo) API 約定的參數(shù)名。值這里需要引用用戶輸入。由于我們的流程開始于“開始”節(jié)點(diǎn)它默認(rèn)將用戶問題存儲(chǔ)在sys.query變量中。因此值應(yīng)設(shè)置為{{sys.query}}。這意味著用戶問“北京天氣怎么樣”city參數(shù)的值就是“北京”。注意實(shí)際 API 對(duì)城市名的格式可能有要求如中文、拼音、adcode。UApi 這個(gè)接口支持中文城市名。如果接入其他 API可能需要預(yù)處理城市名。配置請(qǐng)求頭可選對(duì)于此免費(fèi) API可能不需要特殊請(qǐng)求頭。但對(duì)于需要Authorization或特定Content-Type的 API需在此處添加。配置超時(shí)與重試超時(shí)設(shè)置為30秒對(duì)于天氣 API 通常足夠。重試可設(shè)置為1或2次增強(qiáng)魯棒性。處理響應(yīng)保持“輸出變量名”為默認(rèn)的body、status_code等即可。我們主要使用body。配置完成后該節(jié)點(diǎn)的輸出將包含一個(gè)body變量其值是 API 返回的原始 JSON 字符串。3.2 第二步使用變量賦值器解析和處理 API 響應(yīng)API 返回的原始 JSON 需要被提煉提取出我們關(guān)心的天氣信息如溫度、天氣狀況、濕度等并組裝成一段簡(jiǎn)潔的文本方便 LLM 生成回復(fù)。添加并連接節(jié)點(diǎn)從左側(cè)面板拖拽一個(gè)“變量賦值器”節(jié)點(diǎn)到畫布并將其放置在“HTTP 請(qǐng)求”節(jié)點(diǎn)之后。將“HTTP 請(qǐng)求”節(jié)點(diǎn)的輸出連線到“變量賦值器”節(jié)點(diǎn)的輸入。配置變量賦值器將節(jié)點(diǎn)重命名為“解析天氣數(shù)據(jù)”。在“變量”配置區(qū)域我們需要定義新的、結(jié)構(gòu)清晰的變量。點(diǎn)擊“添加變量”。變量名輸入weather_info這將是我們存儲(chǔ)處理后信息的新變量。值類型選擇“字符串”。值這是關(guān)鍵步驟。我們需要編寫一個(gè)模板從上游的body中提取字段。 假設(shè) API 返回的 JSON 結(jié)構(gòu)如下具體需查看 API 文檔{ code: 200, data: { city: 北京市, weather: 晴, temperature: 22, humidity: 65%, wind: 東南風(fēng) 3級(jí) } }在“值”的編輯框中我們可以使用 Dify 的內(nèi)置模板語(yǔ)法和JSON函數(shù)來(lái)解析城市{{JSON(body).data.city}} 天氣狀況{{JSON(body).data.weather}} 溫度{{JSON(body).data.temperature}}℃ 濕度{{JSON(body).data.humidity}} 風(fēng)力{{JSON(body).data.wind}}{{JSON(body)}}將上游的body字符串轉(zhuǎn)換為 JSON 對(duì)象。{{JSON(body).data.city}}則逐級(jí)訪問獲取城市名。重要你必須根據(jù)實(shí)際調(diào)用的 API 響應(yīng)結(jié)構(gòu)來(lái)調(diào)整這里的路徑。如果body的根節(jié)點(diǎn)直接就是數(shù)據(jù)則可能是{{JSON(body).city}}。配置錯(cuò)誤會(huì)導(dǎo)致變量為空。最可靠的方法是先運(yùn)行一次查看“HTTP 請(qǐng)求”節(jié)點(diǎn)輸出的body具體內(nèi)容。錯(cuò)誤處理進(jìn)階一個(gè)健壯的工作流應(yīng)該考慮 API 調(diào)用失敗如網(wǎng)絡(luò)錯(cuò)誤、城市不存在的情況。你可以添加一個(gè)“分支”節(jié)點(diǎn)根據(jù)“HTTP 請(qǐng)求”節(jié)點(diǎn)的status_code是否等于 200 來(lái)決定流程走向。在失敗分支中使用“變量賦值器”設(shè)置一個(gè)錯(cuò)誤信息變量然后直接跳轉(zhuǎn)到“文本回復(fù)”節(jié)點(diǎn)返回友好錯(cuò)誤提示而不再調(diào)用 LLM。完成此步驟后我們得到了一個(gè)格式工整的weather_info字符串變量包含了所有關(guān)鍵天氣信息。3.3 第三步配置 LLM 節(jié)點(diǎn)生成自然語(yǔ)言回復(fù)最后我們需要讓 LLM 根據(jù)處理好的天氣數(shù)據(jù)生成一段友好、自然的回復(fù)給用戶。添加并連接節(jié)點(diǎn)拖拽一個(gè)“LLM”節(jié)點(diǎn)到畫布放置在“變量賦值器”節(jié)點(diǎn)之后。將“變量賦值器”節(jié)點(diǎn)的輸出連線到“LLM”節(jié)點(diǎn)的輸入。選擇模型在 LLM 節(jié)點(diǎn)的配置面板中選擇一個(gè)可用的模型例如 OpenAI 的 GPT 系列、 Anthropic 的 Claude 系列或 Dify 內(nèi)置的開源模型。確保該模型已被正確配置且擁有額度。編寫提示詞這是決定回復(fù)質(zhì)量的關(guān)鍵。在“提示詞”編輯框中我們需要清晰地指示 LLM 的任務(wù)和上下文。你是一個(gè)天氣助手。請(qǐng)根據(jù)用戶的問題和以下的實(shí)時(shí)天氣數(shù)據(jù)生成一段親切、簡(jiǎn)潔的回復(fù)。 天氣數(shù)據(jù) {{weather_info}} 用戶的問題是{{sys.query}} 請(qǐng)直接給出回復(fù)不要解釋你是如何獲取數(shù)據(jù)的。{{weather_info}}引用了上一步“變量賦值器”節(jié)點(diǎn)生成的、包含格式化天氣信息的變量。{{sys.query}}再次引用了用戶的原始問題讓 LLM 的回復(fù)更有針對(duì)性。配置生成參數(shù)可以調(diào)整“溫度”、“最大生成長(zhǎng)度”等參數(shù)來(lái)控制回復(fù)的隨機(jī)性和長(zhǎng)度。對(duì)于天氣查詢溫度可以設(shè)低一些如 0.3以保證回復(fù)的穩(wěn)定性和事實(shí)準(zhǔn)確性。連接至輸出將“LLM”節(jié)點(diǎn)的輸出連線到最終的“文本回復(fù)”節(jié)點(diǎn)?！拔谋净貜?fù)”節(jié)點(diǎn)會(huì)自動(dòng)將 LLM 生成的內(nèi)容作為工作流的最終輸出返回給用戶。至此一個(gè)完整的、可運(yùn)行的天氣查詢工作流就配置完成了。點(diǎn)擊畫布右上角的“保存”按鈕然后點(diǎn)擊“發(fā)布”即可在聊天應(yīng)用或 API 中測(cè)試這個(gè)工作流。4. 運(yùn)行驗(yàn)證、調(diào)試與常見問題排查配置完成后必須進(jìn)行充分的測(cè)試以確保工作流在所有預(yù)期和異常情況下都能正確運(yùn)行。4.1 如何測(cè)試工作流Dify 提供了便捷的測(cè)試面板在工作流編輯頁(yè)面點(diǎn)擊右上角的“測(cè)試”按鈕會(huì)打開右側(cè)測(cè)試面板。在“用戶問題”輸入框中輸入測(cè)試用例例如“上海今天天氣如何”。點(diǎn)擊“運(yùn)行”。觀察畫布上節(jié)點(diǎn)的執(zhí)行狀態(tài)。成功執(zhí)行的節(jié)點(diǎn)會(huì)顯示綠色對(duì)勾失敗的節(jié)點(diǎn)會(huì)顯示紅色感嘆號(hào)。你可以點(diǎn)擊每個(gè)節(jié)點(diǎn)查看其詳細(xì)的輸入和輸出數(shù)據(jù)這是調(diào)試最重要的依據(jù)。4.2 關(guān)鍵檢查點(diǎn)與預(yù)期結(jié)果在測(cè)試過(guò)程中請(qǐng)按順序檢查以下節(jié)點(diǎn)檢查節(jié)點(diǎn)預(yù)期結(jié)果如何查看HTTP 請(qǐng)求status_code應(yīng)為 200。body應(yīng)包含結(jié)構(gòu)正確的 JSON 數(shù)據(jù)。點(diǎn)擊節(jié)點(diǎn)在“輸出”標(biāo)簽頁(yè)查看body和status_code變量。變量賦值器weather_info變量的值應(yīng)是一個(gè)格式清晰的字符串包含了從body中正確提取的溫度、天氣等信息。點(diǎn)擊節(jié)點(diǎn)在“輸出”標(biāo)簽頁(yè)查看weather_info變量的內(nèi)容。LLMoutput_text應(yīng)是一段通順的自然語(yǔ)言回復(fù)準(zhǔn)確包含了weather_info中的關(guān)鍵數(shù)據(jù)。點(diǎn)擊節(jié)點(diǎn)在“輸出”標(biāo)簽頁(yè)查看output_text。文本回復(fù)最終展示給用戶的回復(fù)應(yīng)與 LLM 的output_text一致。在測(cè)試面板的“運(yùn)行結(jié)果”區(qū)域查看最終回復(fù)。4.3 常見問題與排查路徑即使按照教程操作你也可能會(huì)遇到一些問題。下表列出了常見問題及其解決方法問題現(xiàn)象可能原因排查步驟與解決方案HTTP 請(qǐng)求節(jié)點(diǎn)失敗狀態(tài)碼非2001. API URL 錯(cuò)誤或失效。2. 查詢參數(shù)city格式不符合 API 要求。3. 網(wǎng)絡(luò)問題。1.檢查 URL確認(rèn)地址無(wú)誤可直接在瀏覽器中嘗試訪問該 URL如https://api.uapi.com/user/weather/v1/current?city北京。2.檢查參數(shù)查看節(jié)點(diǎn)的“輸入”數(shù)據(jù)確認(rèn)city參數(shù)的值是否正確傳遞?？赡苄枰獮槌鞘忻M(jìn)行 URL 編碼。3.查看錯(cuò)誤詳情點(diǎn)擊節(jié)點(diǎn)查看輸出可能有更詳細(xì)的錯(cuò)誤信息。變量賦值器輸出的weather_info為空或錯(cuò)誤1. JSON 路徑引用錯(cuò)誤。2. API 響應(yīng)結(jié)構(gòu)與預(yù)期不符。1.核對(duì) JSON 路徑仔細(xì)查看“HTTP 請(qǐng)求”節(jié)點(diǎn)輸出的body完整內(nèi)容。使用在線的 JSON 格式化工具查看其結(jié)構(gòu)。確保{{JSON(body).data.city}}這樣的路徑能準(zhǔn)確指向目標(biāo)字段。2.使用調(diào)試輸出可以在“變量賦值器”中先創(chuàng)建一個(gè)變量其值為{{body}}以確認(rèn)原始數(shù)據(jù)是否正確流入。LLM 回復(fù)未包含天氣數(shù)據(jù)或回復(fù)混亂1. 提示詞中變量引用錯(cuò)誤或未生效。2.weather_info變量?jī)?nèi)容格式混亂導(dǎo)致 LLM 誤解。1.檢查變量名確認(rèn)提示詞中{{weather_info}}的拼寫與變量賦值器中定義的變量名完全一致。2.優(yōu)化提示詞讓指令更明確。例如改為“請(qǐng)嚴(yán)格使用以下數(shù)據(jù)回答問題\n{{weather_info}}”。3.簡(jiǎn)化數(shù)據(jù)格式在變量賦值器中將天氣數(shù)據(jù)格式化為更清晰的列表或鍵值對(duì)形式。工作流運(yùn)行緩慢1. 外部 API 響應(yīng)慢。2. LLM 模型響應(yīng)慢。3. 網(wǎng)絡(luò)延遲。1.設(shè)置超時(shí)在 HTTP 請(qǐng)求節(jié)點(diǎn)中合理設(shè)置超時(shí)時(shí)間如10秒避免長(zhǎng)時(shí)間等待。2.選擇更快模型嘗試使用響應(yīng)速度更快的 LLM 模型。3.檢查節(jié)點(diǎn)依賴確保沒有不必要的串行阻塞盡可能讓可并行的節(jié)點(diǎn)并行執(zhí)行雖然本示例是線性的。錯(cuò)誤信息包含api error: 400等請(qǐng)求參數(shù)不符合 API 服務(wù)端要求。這是來(lái)自上游 API 的錯(cuò)誤。仔細(xì)閱讀 API 提供商的文檔檢查請(qǐng)求方法、請(qǐng)求頭特別是Content-Type、參數(shù)名和參數(shù)值格式是否正確。常見的 400 錯(cuò)誤是city參數(shù)缺失或值無(wú)效。4.4 使用“對(duì)話開場(chǎng)白”與“問題分類器”進(jìn)行增強(qiáng)為了讓助手更智能你可以在流程開始處添加對(duì)話開場(chǎng)白設(shè)置助手的身份和功能例如“我是一個(gè)天氣查詢助手可以告訴你全球主要城市的實(shí)時(shí)天氣?！眴栴}分類器判斷用戶輸入是否與天氣相關(guān)。如果不是可以提前結(jié)束流程或跳轉(zhuǎn)到其他處理分支。這能有效防止用戶問“講個(gè)笑話”時(shí)工作流仍去調(diào)用天氣 API 的尷尬情況。5. 生產(chǎn)環(huán)境最佳實(shí)踐與擴(kuò)展方向?qū)⒐ぷ髁鲝臏y(cè)試環(huán)境遷移到生產(chǎn)環(huán)境需要考慮更多關(guān)于穩(wěn)定性、安全性和可維護(hù)性的問題。5.1 安全性增強(qiáng)API 密鑰管理對(duì)于需要認(rèn)證的 API絕對(duì)不要將密鑰硬編碼在工作流配置中。應(yīng)使用 Dify 的“密鑰”管理功能。在 Dify 控制臺(tái)的“設(shè)置”-“密鑰”中添加你的 API Key。在 HTTP 請(qǐng)求節(jié)點(diǎn)的“請(qǐng)求頭”中通過(guò){{secrets.your_key_name}}的形式引用密鑰。輸入校驗(yàn)與清理在調(diào)用外部 API 前對(duì)用戶輸入如城市名進(jìn)行校驗(yàn)防止注入攻擊或無(wú)效請(qǐng)求?？梢允褂谩按a執(zhí)行”節(jié)點(diǎn)編寫簡(jiǎn)單的校驗(yàn)邏輯。限制與鑒權(quán)在 Dify 應(yīng)用設(shè)置中配置訪問權(quán)限和頻率限制防止濫用。5.2 穩(wěn)定性與可觀測(cè)性完備的錯(cuò)誤處理如前所述使用“分支”節(jié)點(diǎn)為 HTTP 請(qǐng)求和 LLM 調(diào)用設(shè)計(jì)失敗處理流程。例如API 失敗時(shí)可以嘗試備用 API或直接返回緩存的通用提示。設(shè)置重試機(jī)制對(duì)于可能因網(wǎng)絡(luò)波動(dòng)失敗的 HTTP 請(qǐng)求在節(jié)點(diǎn)配置中啟用重試。記錄日志在關(guān)鍵節(jié)點(diǎn)如 HTTP 請(qǐng)求前后、LLM 調(diào)用前后使用“變量賦值器”記錄日志信息或集成 Dify 的日志功能便于問題追蹤。監(jiān)控與告警監(jiān)控工作流的執(zhí)行成功率和耗時(shí)。對(duì)于關(guān)鍵業(yè)務(wù)流可以設(shè)置異常告警。5.3 性能優(yōu)化緩存策略對(duì)于天氣這類更新頻率不高的數(shù)據(jù)可以考慮引入緩存。雖然 Dify 工作流原生不支持但你可以調(diào)用一個(gè)具備緩存能力的中間件 API由你自己開發(fā)?；蛘咴凇按a執(zhí)行”節(jié)點(diǎn)中實(shí)現(xiàn)簡(jiǎn)單的內(nèi)存緩存邏輯注意多實(shí)例部署時(shí)的局限性。異步與超時(shí)為所有外部調(diào)用HTTP、LLM設(shè)置合理的超時(shí)時(shí)間避免一個(gè)慢請(qǐng)求拖垮整個(gè)工作流。精簡(jiǎn)提示詞在保證指令清晰的前提下優(yōu)化提示詞減少不必要的 Token 消耗降低成本并提升速度。5.4 擴(kuò)展應(yīng)用場(chǎng)景掌握了 HTTP 請(qǐng)求節(jié)點(diǎn)集成 API 的方法后你可以將此外延到無(wú)數(shù)場(chǎng)景金融信息查詢接入股票、匯率 API讓 AI 助手提供財(cái)經(jīng)資訊。電商集成接入商品搜索、訂單查詢 API構(gòu)建購(gòu)物助手。企業(yè)內(nèi)部系統(tǒng)連接 CRM、ERP、OA 系統(tǒng)的 API打造企業(yè)內(nèi)部知識(shí)問答和流程自動(dòng)化助手。多工具編排在一個(gè)工作流中串聯(lián)多個(gè)不同的 API 調(diào)用。例如先調(diào)用地圖 API 獲取坐標(biāo)再調(diào)用天氣 API 獲取該坐標(biāo)的天氣。與知識(shí)庫(kù)結(jié)合將 API 獲取的實(shí)時(shí)數(shù)據(jù)與本地知識(shí)庫(kù)的靜態(tài)文檔相結(jié)合讓 AI 的回答既有實(shí)時(shí)性又有深度。構(gòu)建復(fù)雜工作流時(shí)核心思路不變明確數(shù)據(jù)輸入、設(shè)計(jì)處理節(jié)點(diǎn)HTTP請(qǐng)求、變量轉(zhuǎn)換、邏輯判斷、規(guī)劃數(shù)據(jù)流、定義最終輸出。通過(guò) Dify 的可視化界面這些原本需要大量編碼的集成工作變得直觀且高效。 Dify工作流實(shí)戰(zhàn)：通過(guò)HTTP節(jié)點(diǎn)集成外部API構(gòu)建智能天氣助手
在實(shí)際 AI 應(yīng)用開發(fā)中我們經(jīng)常遇到一個(gè)核心需求讓大語(yǔ)言模型LLM能夠獲取并處理實(shí)時(shí)、動(dòng)態(tài)的外部數(shù)據(jù)。無(wú)論是查詢天氣、股票價(jià)格還是調(diào)用企業(yè)內(nèi)部系統(tǒng)的接口僅僅依靠 LLM 的靜態(tài)知識(shí)庫(kù)是遠(yuǎn)遠(yuǎn)不夠的。Dify 作為一個(gè)開源的 LLM 應(yīng)用開發(fā)平臺(tái)其工作流功能為解決這個(gè)問題提供了強(qiáng)大的可視化解決方案。它允許開發(fā)者通過(guò)拖拽節(jié)點(diǎn)的方式將 HTTP 請(qǐng)求、數(shù)據(jù)處理和 LLM 調(diào)用串聯(lián)起來(lái)無(wú)需編寫復(fù)雜的膠水代碼就能構(gòu)建出功能完整的 AI 應(yīng)用。本文將圍繞“天氣查詢”這一經(jīng)典場(chǎng)景詳細(xì)演示如何在 Dify 工作流中接入外部 API。我們將使用一個(gè)公開的免費(fèi)天氣 APIUApi作為示例從零開始通過(guò)三個(gè)核心步驟配置 HTTP 請(qǐng)求節(jié)點(diǎn)、處理 API 響應(yīng)、將結(jié)果傳遞給 LLM 生成自然語(yǔ)言回復(fù)構(gòu)建一個(gè)可運(yùn)行的智能天氣查詢助手。整個(gè)過(guò)程完全在 Dify 的可視化界面中完成旨在讓讀者掌握 Dify 工作流連接外部服務(wù)的核心方法并能舉一反三應(yīng)用到其他 API 集成場(chǎng)景中。1. 理解 Dify 工作流與外部 API 集成的核心機(jī)制在開始動(dòng)手之前我們需要厘清幾個(gè)關(guān)鍵概念理解 Dify 工作流是如何與外部世界進(jìn)行交互的。這有助于我們?cè)诤罄m(xù)配置時(shí)做出正確的設(shè)計(jì)決策。1.1 Dify 工作流可視化的 LLM 應(yīng)用編排引擎Dify 工作流本質(zhì)上是一個(gè)基于節(jié)點(diǎn)Node和邊Edge的可視化編程環(huán)境。每個(gè)節(jié)點(diǎn)代表一個(gè)獨(dú)立的功能單元例如“用戶問題輸入”、“大語(yǔ)言模型”、“知識(shí)庫(kù)檢索”、“代碼執(zhí)行”或“HTTP 請(qǐng)求”。節(jié)點(diǎn)之間通過(guò)連線傳遞數(shù)據(jù)數(shù)據(jù)通常以鍵值對(duì)Key-Value的形式在變量Variable中流動(dòng)。工作流的優(yōu)勢(shì)在于其聲明式和可視化的特性。開發(fā)者無(wú)需關(guān)心線程、異步、錯(cuò)誤重試等底層細(xì)節(jié)只需關(guān)注業(yè)務(wù)邏輯的串聯(lián)。對(duì)于集成外部 API 而言最關(guān)鍵的兩個(gè)節(jié)點(diǎn)是“HTTP 請(qǐng)求”節(jié)點(diǎn)和“工具調(diào)用”節(jié)點(diǎn)后者通常用于更規(guī)范的 API 封裝。本文主要使用前者因?yàn)樗ㄓ?、更直接?.2 HTTP 請(qǐng)求節(jié)點(diǎn)連接外部服務(wù)的橋梁HTTP 請(qǐng)求節(jié)點(diǎn)是 Dify 工作流與外部 API 通信的核心。你可以將其理解為一個(gè)內(nèi)置的、可配置的 HTTP 客戶端如curl或requests庫(kù)的圖形化版本。該節(jié)點(diǎn)需要你提供以下關(guān)鍵信息URL目標(biāo) API 的完整地址。方法GET、POST、PUT、DELETE 等。請(qǐng)求頭例如Content-Type: application/json、Authorization: Bearer token。查詢參數(shù)/請(qǐng)求體傳遞給 API 的具體參數(shù)。超時(shí)時(shí)間防止長(zhǎng)時(shí)間無(wú)響應(yīng)卡死工作流。配置完成后該節(jié)點(diǎn)會(huì)執(zhí)行 HTTP 調(diào)用并將 API 返回的原始響應(yīng)通常是 JSON 或 XML 格式輸出為一個(gè)變量供后續(xù)節(jié)點(diǎn)使用。1.3 數(shù)據(jù)處理從原始響應(yīng)到 LLM 可讀內(nèi)容外部 API 的響應(yīng)往往不是 LLM 能直接處理的理想輸入。它可能包含冗余的元數(shù)據(jù)、嵌套過(guò)深的結(jié)構(gòu)或者是不友好的格式。因此在將 API 響應(yīng)喂給 LLM 之前通常需要一個(gè)數(shù)據(jù)處理環(huán)節(jié)。在 Dify 中這可以通過(guò)以下幾種方式實(shí)現(xiàn)“變量賦值器”節(jié)點(diǎn)用于提取復(fù)雜 JSON 中的特定字段并將其賦值給一個(gè)結(jié)構(gòu)更清晰的新變量?！按a執(zhí)行”節(jié)點(diǎn)如果你需要更復(fù)雜的轉(zhuǎn)換邏輯如日期格式化、數(shù)值計(jì)算可以使用 Python 或 JavaScript 代碼片段進(jìn)行處理。在 LLM 節(jié)點(diǎn)提示詞中直接引用對(duì)于簡(jiǎn)單的 JSON可以直接將整個(gè)響應(yīng)文本插入提示詞并指示 LLM 自行解析。但這依賴于 LLM 的解析能力且可能浪費(fèi) Token。一個(gè)穩(wěn)健的流程是HTTP 請(qǐng)求 - 變量賦值器提取核心數(shù)據(jù)- LLM生成友好回復(fù)。1.4 為什么選擇 UApi 作為示例為了演示的通用性和可復(fù)現(xiàn)性我們選擇一個(gè)免費(fèi)、無(wú)需認(rèn)證、返回結(jié)構(gòu)清晰的天氣 API。UApi 提供了這樣的服務(wù)。它避免了因 API 密鑰申請(qǐng)、復(fù)雜 OAuth 認(rèn)證等步驟帶來(lái)的干擾讓我們可以專注于 Dify 工作流本身的配置邏輯。掌握這個(gè)方法后你可以輕松替換成任何需要 API Key 或復(fù)雜參數(shù)的商業(yè)或私有 API。2. 環(huán)境準(zhǔn)備與 Dify 工作流基礎(chǔ)配置在開始構(gòu)建天氣查詢工作流之前你需要一個(gè)可用的 Dify 環(huán)境并熟悉其工作流編輯器的基本操作。2.1 Dify 環(huán)境準(zhǔn)備你有兩種方式獲得 Dify 環(huán)境云服務(wù)直接訪問 Dify 官方云平臺(tái)注冊(cè)賬號(hào)即可使用。這是最快的方式。本地部署參考官方 GitHub 倉(cāng)庫(kù)進(jìn)行部署。這需要你具備 Docker 和 Docker Compose 的基本知識(shí)。對(duì)于本地部署一個(gè)常見的啟動(dòng)命令如下# 克隆倉(cāng)庫(kù)假設(shè)使用穩(wěn)定版本 git clone -b stable https://github.com/langgenius/dify.git cd dify # 使用 docker-compose 啟動(dòng) docker-compose up -d部署成功后通常在瀏覽器訪問http://localhost:3000即可。無(wú)論哪種方式請(qǐng)確保你能夠登錄到 Dify 的控制臺(tái)并進(jìn)入“工作流”創(chuàng)建頁(yè)面。2.2 創(chuàng)建新的工作流并規(guī)劃節(jié)點(diǎn)登錄 Dify 后跟隨以下步驟點(diǎn)擊左側(cè)導(dǎo)航欄的“工作流”。點(diǎn)擊“創(chuàng)建工作流”按鈕。為工作流命名例如“智能天氣查詢助手”。在描述中簡(jiǎn)要說(shuō)明其功能。進(jìn)入空白的工作流畫布后你會(huì)看到左側(cè)的節(jié)點(diǎn)列表。我們的天氣查詢流程主要涉及以下幾類節(jié)點(diǎn)你可以先將它們拖拽到畫布上建立一個(gè)大致的框架開始工作流的唯一入口。對(duì)話開場(chǎng)白可選用于定義 AI 助手的初始問候語(yǔ)。問題分類器可選可用于判斷用戶意圖是否為天氣查詢實(shí)現(xiàn)更復(fù)雜的智能體。HTTP 請(qǐng)求核心節(jié)點(diǎn)用于調(diào)用天氣 API。變量賦值器核心節(jié)點(diǎn)用于處理 API 響應(yīng)。LLM核心節(jié)點(diǎn)用于生成最終回復(fù)。文本回復(fù)工作流的輸出節(jié)點(diǎn)。本節(jié)我們先搭建骨架具體配置在下一節(jié)展開。一個(gè)簡(jiǎn)單的線性結(jié)構(gòu)可以是開始-HTTP 請(qǐng)求-變量賦值器-LLM-文本回復(fù)。用連線將這些節(jié)點(diǎn)按順序連接起來(lái)。2.3 理解變量與數(shù)據(jù)流在連接節(jié)點(diǎn)時(shí)Dify 會(huì)提示你處理變量的輸入輸出。這是工作流編排的關(guān)鍵。輸出變量每個(gè)節(jié)點(diǎn)執(zhí)行后都會(huì)產(chǎn)生輸出。例如HTTP 請(qǐng)求節(jié)點(diǎn)會(huì)輸出一個(gè)包含狀態(tài)碼、響應(yīng)頭、響應(yīng)體等信息的對(duì)象。輸入變量下游節(jié)點(diǎn)可以引用上游節(jié)點(diǎn)的輸出變量。例如變量賦值器節(jié)點(diǎn)可以讀取HTTP 請(qǐng)求節(jié)點(diǎn)的響應(yīng)體。變量語(yǔ)法在需要引用變量的輸入框通常帶有{{提示你可以通過(guò){{node_id.output_key}}的格式來(lái)引用。例如{{http_request_node.body}}。在后續(xù)配置中請(qǐng)密切關(guān)注每個(gè)節(jié)點(diǎn)的輸入輸出面板確保數(shù)據(jù)能正確傳遞。3. 三步構(gòu)建天氣查詢工作流現(xiàn)在我們開始核心的配置工作。整個(gè)過(guò)程將分為三個(gè)清晰的步驟。3.1 第一步配置 HTTP 請(qǐng)求節(jié)點(diǎn)調(diào)用天氣 API首先我們需要從畫布上找到并選中之前添加的“HTTP 請(qǐng)求”節(jié)點(diǎn)對(duì)其進(jìn)行詳細(xì)配置。我們將使用 UApi 的一個(gè)公開天氣接口。節(jié)點(diǎn)基礎(chǔ)信息將節(jié)點(diǎn)重命名為“獲取天氣數(shù)據(jù)”便于識(shí)別。配置請(qǐng)求地址與方法URL填入https://api.uapi.com/user/weather/v1/current。這是一個(gè)查詢實(shí)時(shí)天氣的接口。方法選擇GET。配置查詢參數(shù)天氣查詢通常需要位置參數(shù)。我們將用戶輸入的城市名作為變量傳遞。在“參數(shù)”部分點(diǎn)擊“添加”。鍵輸入city。這是目標(biāo) API 約定的參數(shù)名。值這里需要引用用戶輸入。由于我們的流程開始于“開始”節(jié)點(diǎn)它默認(rèn)將用戶問題存儲(chǔ)在sys.query變量中。因此值應(yīng)設(shè)置為{{sys.query}}。這意味著用戶問“北京天氣怎么樣”city參數(shù)的值就是“北京”。注意實(shí)際 API 對(duì)城市名的格式可能有要求如中文、拼音、adcode。UApi 這個(gè)接口支持中文城市名。如果接入其他 API可能需要預(yù)處理城市名。配置請(qǐng)求頭可選對(duì)于此免費(fèi) API可能不需要特殊請(qǐng)求頭。但對(duì)于需要Authorization或特定Content-Type的 API需在此處添加。配置超時(shí)與重試超時(shí)設(shè)置為30秒對(duì)于天氣 API 通常足夠。重試可設(shè)置為1或2次增強(qiáng)魯棒性。處理響應(yīng)保持“輸出變量名”為默認(rèn)的body、status_code等即可。我們主要使用body。配置完成后該節(jié)點(diǎn)的輸出將包含一個(gè)body變量其值是 API 返回的原始 JSON 字符串。3.2 第二步使用變量賦值器解析和處理 API 響應(yīng)API 返回的原始 JSON 需要被提煉提取出我們關(guān)心的天氣信息如溫度、天氣狀況、濕度等并組裝成一段簡(jiǎn)潔的文本方便 LLM 生成回復(fù)。添加并連接節(jié)點(diǎn)從左側(cè)面板拖拽一個(gè)“變量賦值器”節(jié)點(diǎn)到畫布并將其放置在“HTTP 請(qǐng)求”節(jié)點(diǎn)之后。將“HTTP 請(qǐng)求”節(jié)點(diǎn)的輸出連線到“變量賦值器”節(jié)點(diǎn)的輸入。配置變量賦值器將節(jié)點(diǎn)重命名為“解析天氣數(shù)據(jù)”。在“變量”配置區(qū)域我們需要定義新的、結(jié)構(gòu)清晰的變量。點(diǎn)擊“添加變量”。變量名輸入weather_info這將是我們存儲(chǔ)處理后信息的新變量。值類型選擇“字符串”。值這是關(guān)鍵步驟。我們需要編寫一個(gè)模板從上游的body中提取字段。 假設(shè) API 返回的 JSON 結(jié)構(gòu)如下具體需查看 API 文檔{ code: 200, data: { city: 北京市, weather: 晴, temperature: 22, humidity: 65%, wind: 東南風(fēng) 3級(jí) } }在“值”的編輯框中我們可以使用 Dify 的內(nèi)置模板語(yǔ)法和JSON函數(shù)來(lái)解析城市{{JSON(body).data.city}} 天氣狀況{{JSON(body).data.weather}} 溫度{{JSON(body).data.temperature}}℃ 濕度{{JSON(body).data.humidity}} 風(fēng)力{{JSON(body).data.wind}}{{JSON(body)}}將上游的body字符串轉(zhuǎn)換為 JSON 對(duì)象。{{JSON(body).data.city}}則逐級(jí)訪問獲取城市名。重要你必須根據(jù)實(shí)際調(diào)用的 API 響應(yīng)結(jié)構(gòu)來(lái)調(diào)整這里的路徑。如果body的根節(jié)點(diǎn)直接就是數(shù)據(jù)則可能是{{JSON(body).city}}。配置錯(cuò)誤會(huì)導(dǎo)致變量為空。最可靠的方法是先運(yùn)行一次查看“HTTP 請(qǐng)求”節(jié)點(diǎn)輸出的body具體內(nèi)容。錯(cuò)誤處理進(jìn)階一個(gè)健壯的工作流應(yīng)該考慮 API 調(diào)用失敗如網(wǎng)絡(luò)錯(cuò)誤、城市不存在的情況。你可以添加一個(gè)“分支”節(jié)點(diǎn)根據(jù)“HTTP 請(qǐng)求”節(jié)點(diǎn)的status_code是否等于 200 來(lái)決定流程走向。在失敗分支中使用“變量賦值器”設(shè)置一個(gè)錯(cuò)誤信息變量然后直接跳轉(zhuǎn)到“文本回復(fù)”節(jié)點(diǎn)返回友好錯(cuò)誤提示而不再調(diào)用 LLM。完成此步驟后我們得到了一個(gè)格式工整的weather_info字符串變量包含了所有關(guān)鍵天氣信息。3.3 第三步配置 LLM 節(jié)點(diǎn)生成自然語(yǔ)言回復(fù)最后我們需要讓 LLM 根據(jù)處理好的天氣數(shù)據(jù)生成一段友好、自然的回復(fù)給用戶。添加并連接節(jié)點(diǎn)拖拽一個(gè)“LLM”節(jié)點(diǎn)到畫布放置在“變量賦值器”節(jié)點(diǎn)之后。將“變量賦值器”節(jié)點(diǎn)的輸出連線到“LLM”節(jié)點(diǎn)的輸入。選擇模型在 LLM 節(jié)點(diǎn)的配置面板中選擇一個(gè)可用的模型例如 OpenAI 的 GPT 系列、 Anthropic 的 Claude 系列或 Dify 內(nèi)置的開源模型。確保該模型已被正確配置且擁有額度。編寫提示詞這是決定回復(fù)質(zhì)量的關(guān)鍵。在“提示詞”編輯框中我們需要清晰地指示 LLM 的任務(wù)和上下文。你是一個(gè)天氣助手。請(qǐng)根據(jù)用戶的問題和以下的實(shí)時(shí)天氣數(shù)據(jù)生成一段親切、簡(jiǎn)潔的回復(fù)。 天氣數(shù)據(jù) {{weather_info}} 用戶的問題是{{sys.query}} 請(qǐng)直接給出回復(fù)不要解釋你是如何獲取數(shù)據(jù)的。{{weather_info}}引用了上一步“變量賦值器”節(jié)點(diǎn)生成的、包含格式化天氣信息的變量。{{sys.query}}再次引用了用戶的原始問題讓 LLM 的回復(fù)更有針對(duì)性。配置生成參數(shù)可以調(diào)整“溫度”、“最大生成長(zhǎng)度”等參數(shù)來(lái)控制回復(fù)的隨機(jī)性和長(zhǎng)度。對(duì)于天氣查詢溫度可以設(shè)低一些如 0.3以保證回復(fù)的穩(wěn)定性和事實(shí)準(zhǔn)確性。連接至輸出將“LLM”節(jié)點(diǎn)的輸出連線到最終的“文本回復(fù)”節(jié)點(diǎn)?！拔谋净貜?fù)”節(jié)點(diǎn)會(huì)自動(dòng)將 LLM 生成的內(nèi)容作為工作流的最終輸出返回給用戶。至此一個(gè)完整的、可運(yùn)行的天氣查詢工作流就配置完成了。點(diǎn)擊畫布右上角的“保存”按鈕然后點(diǎn)擊“發(fā)布”即可在聊天應(yīng)用或 API 中測(cè)試這個(gè)工作流。4. 運(yùn)行驗(yàn)證、調(diào)試與常見問題排查配置完成后必須進(jìn)行充分的測(cè)試以確保工作流在所有預(yù)期和異常情況下都能正確運(yùn)行。4.1 如何測(cè)試工作流Dify 提供了便捷的測(cè)試面板在工作流編輯頁(yè)面點(diǎn)擊右上角的“測(cè)試”按鈕會(huì)打開右側(cè)測(cè)試面板。在“用戶問題”輸入框中輸入測(cè)試用例例如“上海今天天氣如何”。點(diǎn)擊“運(yùn)行”。觀察畫布上節(jié)點(diǎn)的執(zhí)行狀態(tài)。成功執(zhí)行的節(jié)點(diǎn)會(huì)顯示綠色對(duì)勾失敗的節(jié)點(diǎn)會(huì)顯示紅色感嘆號(hào)。你可以點(diǎn)擊每個(gè)節(jié)點(diǎn)查看其詳細(xì)的輸入和輸出數(shù)據(jù)這是調(diào)試最重要的依據(jù)。4.2 關(guān)鍵檢查點(diǎn)與預(yù)期結(jié)果在測(cè)試過(guò)程中請(qǐng)按順序檢查以下節(jié)點(diǎn)檢查節(jié)點(diǎn)預(yù)期結(jié)果如何查看HTTP 請(qǐng)求status_code應(yīng)為 200。body應(yīng)包含結(jié)構(gòu)正確的 JSON 數(shù)據(jù)。點(diǎn)擊節(jié)點(diǎn)在“輸出”標(biāo)簽頁(yè)查看body和status_code變量。變量賦值器weather_info變量的值應(yīng)是一個(gè)格式清晰的字符串包含了從body中正確提取的溫度、天氣等信息。點(diǎn)擊節(jié)點(diǎn)在“輸出”標(biāo)簽頁(yè)查看weather_info變量的內(nèi)容。LLMoutput_text應(yīng)是一段通順的自然語(yǔ)言回復(fù)準(zhǔn)確包含了weather_info中的關(guān)鍵數(shù)據(jù)。點(diǎn)擊節(jié)點(diǎn)在“輸出”標(biāo)簽頁(yè)查看output_text。文本回復(fù)最終展示給用戶的回復(fù)應(yīng)與 LLM 的output_text一致。在測(cè)試面板的“運(yùn)行結(jié)果”區(qū)域查看最終回復(fù)。4.3 常見問題與排查路徑即使按照教程操作你也可能會(huì)遇到一些問題。下表列出了常見問題及其解決方法問題現(xiàn)象可能原因排查步驟與解決方案HTTP 請(qǐng)求節(jié)點(diǎn)失敗狀態(tài)碼非2001. API URL 錯(cuò)誤或失效。2. 查詢參數(shù)city格式不符合 API 要求。3. 網(wǎng)絡(luò)問題。1.檢查 URL確認(rèn)地址無(wú)誤可直接在瀏覽器中嘗試訪問該 URL如https://api.uapi.com/user/weather/v1/current?city北京。2.檢查參數(shù)查看節(jié)點(diǎn)的“輸入”數(shù)據(jù)確認(rèn)city參數(shù)的值是否正確傳遞?？赡苄枰獮槌鞘忻M(jìn)行 URL 編碼。3.查看錯(cuò)誤詳情點(diǎn)擊節(jié)點(diǎn)查看輸出可能有更詳細(xì)的錯(cuò)誤信息。變量賦值器輸出的weather_info為空或錯(cuò)誤1. JSON 路徑引用錯(cuò)誤。2. API 響應(yīng)結(jié)構(gòu)與預(yù)期不符。1.核對(duì) JSON 路徑仔細(xì)查看“HTTP 請(qǐng)求”節(jié)點(diǎn)輸出的body完整內(nèi)容。使用在線的 JSON 格式化工具查看其結(jié)構(gòu)。確保{{JSON(body).data.city}}這樣的路徑能準(zhǔn)確指向目標(biāo)字段。2.使用調(diào)試輸出可以在“變量賦值器”中先創(chuàng)建一個(gè)變量其值為{{body}}以確認(rèn)原始數(shù)據(jù)是否正確流入。LLM 回復(fù)未包含天氣數(shù)據(jù)或回復(fù)混亂1. 提示詞中變量引用錯(cuò)誤或未生效。2.weather_info變量?jī)?nèi)容格式混亂導(dǎo)致 LLM 誤解。1.檢查變量名確認(rèn)提示詞中{{weather_info}}的拼寫與變量賦值器中定義的變量名完全一致。2.優(yōu)化提示詞讓指令更明確。例如改為“請(qǐng)嚴(yán)格使用以下數(shù)據(jù)回答問題\n{{weather_info}}”。3.簡(jiǎn)化數(shù)據(jù)格式在變量賦值器中將天氣數(shù)據(jù)格式化為更清晰的列表或鍵值對(duì)形式。工作流運(yùn)行緩慢1. 外部 API 響應(yīng)慢。2. LLM 模型響應(yīng)慢。3. 網(wǎng)絡(luò)延遲。1.設(shè)置超時(shí)在 HTTP 請(qǐng)求節(jié)點(diǎn)中合理設(shè)置超時(shí)時(shí)間如10秒避免長(zhǎng)時(shí)間等待。2.選擇更快模型嘗試使用響應(yīng)速度更快的 LLM 模型。3.檢查節(jié)點(diǎn)依賴確保沒有不必要的串行阻塞盡可能讓可并行的節(jié)點(diǎn)并行執(zhí)行雖然本示例是線性的。錯(cuò)誤信息包含api error: 400等請(qǐng)求參數(shù)不符合 API 服務(wù)端要求。這是來(lái)自上游 API 的錯(cuò)誤。仔細(xì)閱讀 API 提供商的文檔檢查請(qǐng)求方法、請(qǐng)求頭特別是Content-Type、參數(shù)名和參數(shù)值格式是否正確。常見的 400 錯(cuò)誤是city參數(shù)缺失或值無(wú)效。4.4 使用“對(duì)話開場(chǎng)白”與“問題分類器”進(jìn)行增強(qiáng)為了讓助手更智能你可以在流程開始處添加對(duì)話開場(chǎng)白設(shè)置助手的身份和功能例如“我是一個(gè)天氣查詢助手可以告訴你全球主要城市的實(shí)時(shí)天氣?！眴栴}分類器判斷用戶輸入是否與天氣相關(guān)。如果不是可以提前結(jié)束流程或跳轉(zhuǎn)到其他處理分支。這能有效防止用戶問“講個(gè)笑話”時(shí)工作流仍去調(diào)用天氣 API 的尷尬情況。5. 生產(chǎn)環(huán)境最佳實(shí)踐與擴(kuò)展方向?qū)⒐ぷ髁鲝臏y(cè)試環(huán)境遷移到生產(chǎn)環(huán)境需要考慮更多關(guān)于穩(wěn)定性、安全性和可維護(hù)性的問題。5.1 安全性增強(qiáng)API 密鑰管理對(duì)于需要認(rèn)證的 API絕對(duì)不要將密鑰硬編碼在工作流配置中。應(yīng)使用 Dify 的“密鑰”管理功能。在 Dify 控制臺(tái)的“設(shè)置”-“密鑰”中添加你的 API Key。在 HTTP 請(qǐng)求節(jié)點(diǎn)的“請(qǐng)求頭”中通過(guò){{secrets.your_key_name}}的形式引用密鑰。輸入校驗(yàn)與清理在調(diào)用外部 API 前對(duì)用戶輸入如城市名進(jìn)行校驗(yàn)防止注入攻擊或無(wú)效請(qǐng)求?？梢允褂谩按a執(zhí)行”節(jié)點(diǎn)編寫簡(jiǎn)單的校驗(yàn)邏輯。限制與鑒權(quán)在 Dify 應(yīng)用設(shè)置中配置訪問權(quán)限和頻率限制防止濫用。5.2 穩(wěn)定性與可觀測(cè)性完備的錯(cuò)誤處理如前所述使用“分支”節(jié)點(diǎn)為 HTTP 請(qǐng)求和 LLM 調(diào)用設(shè)計(jì)失敗處理流程。例如API 失敗時(shí)可以嘗試備用 API或直接返回緩存的通用提示。設(shè)置重試機(jī)制對(duì)于可能因網(wǎng)絡(luò)波動(dòng)失敗的 HTTP 請(qǐng)求在節(jié)點(diǎn)配置中啟用重試。記錄日志在關(guān)鍵節(jié)點(diǎn)如 HTTP 請(qǐng)求前后、LLM 調(diào)用前后使用“變量賦值器”記錄日志信息或集成 Dify 的日志功能便于問題追蹤。監(jiān)控與告警監(jiān)控工作流的執(zhí)行成功率和耗時(shí)。對(duì)于關(guān)鍵業(yè)務(wù)流可以設(shè)置異常告警。5.3 性能優(yōu)化緩存策略對(duì)于天氣這類更新頻率不高的數(shù)據(jù)可以考慮引入緩存。雖然 Dify 工作流原生不支持但你可以調(diào)用一個(gè)具備緩存能力的中間件 API由你自己開發(fā)?；蛘咴凇按a執(zhí)行”節(jié)點(diǎn)中實(shí)現(xiàn)簡(jiǎn)單的內(nèi)存緩存邏輯注意多實(shí)例部署時(shí)的局限性。異步與超時(shí)為所有外部調(diào)用HTTP、LLM設(shè)置合理的超時(shí)時(shí)間避免一個(gè)慢請(qǐng)求拖垮整個(gè)工作流。精簡(jiǎn)提示詞在保證指令清晰的前提下優(yōu)化提示詞減少不必要的 Token 消耗降低成本并提升速度。5.4 擴(kuò)展應(yīng)用場(chǎng)景掌握了 HTTP 請(qǐng)求節(jié)點(diǎn)集成 API 的方法后你可以將此外延到無(wú)數(shù)場(chǎng)景金融信息查詢接入股票、匯率 API讓 AI 助手提供財(cái)經(jīng)資訊。電商集成接入商品搜索、訂單查詢 API構(gòu)建購(gòu)物助手。企業(yè)內(nèi)部系統(tǒng)連接 CRM、ERP、OA 系統(tǒng)的 API打造企業(yè)內(nèi)部知識(shí)問答和流程自動(dòng)化助手。多工具編排在一個(gè)工作流中串聯(lián)多個(gè)不同的 API 調(diào)用。例如先調(diào)用地圖 API 獲取坐標(biāo)再調(diào)用天氣 API 獲取該坐標(biāo)的天氣。與知識(shí)庫(kù)結(jié)合將 API 獲取的實(shí)時(shí)數(shù)據(jù)與本地知識(shí)庫(kù)的靜態(tài)文檔相結(jié)合讓 AI 的回答既有實(shí)時(shí)性又有深度。構(gòu)建復(fù)雜工作流時(shí)核心思路不變明確數(shù)據(jù)輸入、設(shè)計(jì)處理節(jié)點(diǎn)HTTP請(qǐng)求、變量轉(zhuǎn)換、邏輯判斷、規(guī)劃數(shù)據(jù)流、定義最終輸出。通過(guò) Dify 的可視化界面這些原本需要大量編碼的集成工作變得直觀且高效。