权威来源#

版本与界面说明#

本章在 2026-07-22 按 Dify Cloud 最新官方文档和你当前的中文画布核对。以实际 Dify Cloud 画布和最新官方英文文档为准；中文标签用于帮助你在界面中定位。

旧教程常把入口写成独立的 User Input 节点。你当前的 Workflow 画布中，真实入口是 开始（Start）节点，其中的“用户输入”是一组可配置的字段，不是另一个要拖进画布的节点。

你截图里的 userinput.files LEGACY 是旧的文件输入兼容字段；本章是文本 RAG，忽略它即可。若 Dify 后续改名，以节点图标和“变量选择器中上游节点输出”这两个事实为准，不要照抄社区文章里的旧标签。

本章学到哪里，不学到哪里#

本章要真正完成：

1. 用 Dify Cloud 或现有 Dify 实例配置聊天模型和 Embedding 模型。
2. 创建知识库并先通过 Test Retrieval 验证证据。
3. 创建一个“知识检索 Workflow”，并将它发布为 Workflow Tool。
4. 搭建主 Agent Workflow，让 Agent 自己调用检索工具再回答。
5. 在运行追踪中看见 Agent -> tool call -> tool result -> Agent final answer。
6. 用 FastAPI 服务端调用 POST /workflows/run，同时处理 HTTP 失败和工作流内部失败。

本章暂时不做：

• 不自己部署 Dify；自托管、Docker、反向代理和升级放到部署阶段。
• 不开发模型插件或工具插件。
• 不做复杂的 Loop、Iteration、多 Agent、Human Input；本章只使用一个检索工具。
• 不把 Dify 当作权限系统；API Key、用户身份、知识权限仍由服务端负责。

本章使用哪种 Dify#

本章优先使用 Dify Cloud 或你已经能打开的 Dify 实例，不要求现在自托管。两者的画布概念相同，主要差别是登录地址和 API Base URL。

1
Dify Cloud 常见 API Base URL：https://api.dify.ai/v1
2
自托管 API Base URL：以实例“API Access / 访问 API”页面显示的地址为准

不要凭记忆手写 Base URL；发布应用后，从应用的 API 页面复制。中文画布里的 开始 对应英文 Start；“用户输入”是开始节点里的字段。Knowledge Retrieval / LLM / Output 分别对应知识检索、LLM、输出。

先分清：Dify 知识库不是项目数据库#

Dify 这里的“知识库”不是你项目里的 SQL/ORM 数据库，也不是项目本地的向量库。Dify Cloud 是独立运行的服务，默认无法读取你项目中的 database.py、SQL 表、Chroma 或其他本地存储。

本章选择的知识库，必须是在 Dify 的 Knowledge / 知识库 页面中创建并上传资料后形成的可检索索引。要让项目数据库中的内容进入 Dify，后续需要通过文件同步、HTTP Request、数据源或自定义工具接入；本章的检索工具只负责调用这个 Dify 知识库。

当前章节的数据来源边界是：

1
Dify 知识库中的文档
2
  -> Dify 分块与索引
3
  -> 检索 Workflow 的 result
4
  -> Agent 工具返回
5
  -> Agent 最终回答

不是：

1
项目 SQL/ORM 数据库
2
  -> Dify 知识检索

一句话理解#

Dify 是把模型、知识库、Prompt 和流程节点配置在画布上的平台；它不替代你理解 RAG，而是把你已经写过的 RAG 流程变成可观察、可配置的应用。

先看真实对象长什么样#

本章主要操作的是 Dify 的工作流画布里的对象，而不是 Python 类：

先在 Dify Studio 创建 Workflow，不是 Chatflow 或 Chatbot。Workflow 使用 Output 节点把结果返回给 API 调用者；Chatflow 对应的是 Answer 节点。工作流可以明确地把输入、节点输出和最终输出连成一条线。

1
检索工具 Workflow：
2
开始（query） -> Knowledge Retrieval -> Output(results)
3

4
主 Agent Workflow：
5
开始（question） -> Agent(tools=[检索工具]) -> Output(answer)

这条线和你第 13、23、24 章的 RAG 闭环仍是同一件事，但检索动作由 Agent 通过工具发起，而不是工作流固定先检索一次。

开始前：让四个真实对象先可用#

先不要连画布。准备好下面四个对象后，再搭最小流程：

1. 打开 Integrations > Model Provider，安装并配置一个可用的聊天模型（使用工作区提供的额度或填入自己的 Provider API Key）。**成功标准：**打开 LLM 节点时能在模型下拉列表中选中它。
2. 确认可用的 Embedding 模型。使用 High Quality 索引时，Dify 要通过 Embedding 模型生成向量；只有聊天模型但没有 Embedding 模型，知识库可能无法完成高质量索引。Rerank 模型本章可选，不作为启动条件。
3. 打开 Knowledge，新建知识库并上传一份明确写有退款规则的文档，例如包含“退款须在购买后 7 天内申请”。本章选择 High Quality 和一个可用的 Embedding 模型，分块先保留默认值。**成功标准：**文档状态显示为 Completed，而不是处理中或失败。
4. 在该知识库的 Test Retrieval 中输入“退款需要几天内申请？”。**成功标准：**返回的前几个片段能直接看到“7 天内申请”或文档中的等价退款规则；拿不到这条证据就先修文档、分块或检索设置，不要连画布、更不要调 Prompt。

如果你要检索自己的项目资料，请确认第 3 步上传的是项目资料的文件副本，而不是以为 Dify 会自动读取项目数据库。Dify Cloud 不会自动连接本机或项目中的数据库。

三个模型角色不要混：

本章先固定检索变量，不同时乱调：

1
Top K：先用 3
2
Score Threshold：先关闭或保持默认
3
Rerank：先关闭

只有 Test Retrieval 明显召回错误时，才一次改一个变量并重新测试。这和你第 24、25 章学过的 RAG 单变量调试完全相同。

前置对照（可跳过）：固定 RAG#

这一关只用来理解 Dify 的知识库、检索结果和 Context 的基本关系，不是本章最终作品。最终作品必须让 Agent 通过工具调用检索。

1
变量名：question
2
显示名称：问题
3
字段类型：文本（string）
4
必填：是
5
最大长度：先留空
6
默认值：先留空
7
隐藏并预填：关闭

1
开始 -> 知识检索 -> LLM

1
list[chunk]

1
docs = get_vector_store().similarity_search(query, k=3)

1
退款需要几天内申请？

1
你是知识库问答助手。
2
仅根据下面的检索结果回答；检索结果没有答案时，明确说“知识库中没有找到依据”。
3

4
问题：{{通过变量选择器插入 开始/question}}
5

6
检索结果：{{通过变量选择器插入 Context}}

1
answer

1
{
2
  "data": {
3
    "outputs": {
4
      "answer": "请在购买后 7 天内申请退款。"
5
    }
6
  }
7
}

第二关：把检索做成可调用工具#

先单独测试“检索工具 Workflow”。输入：

1
退款需要几天内申请？

按顺序查看检索工具的输入和输出：

1
开始节点输出 query
2
-> Knowledge Retrieval 输入 query，输出 result: list[chunk]
3
-> Output 输出 results

这一步只验证“工具能不能搜索并返回证据”，还没有让 Agent 参与。Dify 的节点日志是调试证据，不能只看最后回答“像不像对”。

这一关的检查表：

第三关：用 Agent 节点复现上一章的工具循环#

1
开始（query） -> 知识检索（query=query） -> 输出（results）

1
输入 query -> 搜索知识库 -> 返回 result

1
开始（question） -> Agent -> 输出（answer）

1
你是知识库问答 Agent。
2
遇到需要知识库证据的问题时，调用 search_knowledge 工具。
3
把用户问题整理成适合检索的 query，再根据工具返回的 results 回答。
4
只能依据工具返回的资料回答；没有足够证据时，明确说“知识库中没有找到依据”。
5
不要编造工具没有返回的事实。

1
退款需要几天内申请？

1
question
2
  -> Agent 判断需要知识库
3
  -> tool call: search_knowledge(query=...)
4
  -> 检索 Workflow 返回 results
5
  -> Agent 读取 results
6
  -> Agent final answer

1
开始（Start，内部字段 task）
2
  -> Agent(model + tools + strategy + max iterations)
3
  -> Output(answer)

1
Agent 选择工具 ≠ Agent 获得无限权限
2
工具安装成功 ≠ 工具参数可信
3
Maximum Iterations ≠ 权限控制

第四关：从 FastAPI 调用已发布工作流#

发布 Workflow 后，Dify 给出 API Base URL 和应用 API Key。Key 只能放服务端环境变量，不能放前端或提交到 Git。

.env：

1
DIFY_API_BASE=https://api.dify.ai/v1
2
DIFY_API_KEY=app-替换为你的应用密钥

DIFY_API_BASE 必须包含 Dify API 页面给出的版本路径，例如 /v1。不要把 Web 应用访问地址当作 API Base URL。

1
import os
2

3
import httpx
4

5

6
async def run_dify_workflow(question: str, user_id: str) -> str:
7
    try:
8
        async with httpx.AsyncClient(timeout=60) as client:
9
            response = await client.post(
10
                f"{os.environ['DIFY_API_BASE']}/workflows/run",
11
                headers={
12
                    "Authorization": f"Bearer {os.environ['DIFY_API_KEY']}",
13
                    "Content-Type": "application/json",
14
                },
15
                json={
16
                    "inputs": {"question": question},
17
                    "response_mode": "blocking",
18
                    "user": user_id,
19
                },
20
            )
21
            response.raise_for_status()
22
    except httpx.HTTPError as exc:
23
        raise RuntimeError("Dify workflow request failed") from exc
24

25
    payload = response.json()
26
    data = payload.get("data", {})
27

28
    if data.get("status") != "succeeded":
29
        error = data.get("error") or "unknown workflow error"
30
        raise RuntimeError(f"Dify workflow failed: {error}")
31

32
    answer = data.get("outputs", {}).get("answer")
33
    if not isinstance(answer, str):
34
        raise RuntimeError("Dify workflow did not return string output: answer")
35

36
    return answer

为什么 response.raise_for_status() 后还要检查 data.status？

1
HTTP 401/404/500
2
-> Dify API 请求本身失败
3
-> raise_for_status() 能发现
4

5
HTTP 200，但 data.status == "failed"
6
-> 请求到达 Dify，但某个工作流节点执行失败
7
-> 必须检查 data.status 和 data.error

把它接到 FastAPI 路由：

1
from fastapi import APIRouter, Depends
2
from pydantic import BaseModel, Field
3

4
from app.routers.auth import get_current_user
5

6

7
router = APIRouter(prefix="/dify", tags=["dify"])
8

9

10
class DifyQuestion(BaseModel):
11
    question: str = Field(min_length=1, max_length=1000)
12

13

14
@router.post("/rag")
15
async def ask_dify(
16
    request: DifyQuestion,
17
    current_user: dict = Depends(get_current_user),
18
):
19
    answer = await run_dify_workflow(
20
        question=request.question,
21
        user_id=f"user:{current_user['id']}",
22
    )
23
    return {"answer": answer}

这里只要求看懂连接关系，不要求本章重新学习 APIRouter、Pydantic 或 Depends：

1
前端 -> FastAPI 完成认证 -> FastAPI 调 Dify -> FastAPI 返回自己的响应

这里每个对象的职责：

user 不是登录凭证：Dify 不会认证它，绝不能直接相信前端传来的任意字符串。先由你的后端完成会话或 Token 验证，再从已认证用户派生稳定值，例如 user:{account_id}。它用于让 Dify 关联同一用户的运行与已选资源，不是知识库的授权机制；知识库访问控制仍应由你的后端、Dify 工作区权限和应用配置分别负责。

想得到 SSE 时把 response_mode 改为 streaming，并用流式 HTTP 客户端消费 text/event-stream。这和你第 18 章的 WebSocket 不同：Dify 这里是服务器向客户端推送事件。

第五关：发布、日志与四次验证#

画布右上角的单次测试用于检查当前草稿；FastAPI 调用的是已经发布的版本。改完节点后必须重新 Publish。

发布后依次验证：

1. 命中问题：“退款需要几天内申请？”回答必须包含文档证据。
2. **未命中问题：**知识库没有答案时，必须明确说没有依据，不能编造。
3. **API 调用：**FastAPI 能取得 data.outputs.answer，同时记录 workflow_run_id 便于排查。
4. **故意失败：**暂时把 Output 的变量名改错或断开一个节点，确认你能在运行详情或 Logs 里找到失败节点；验证后恢复。

排错顺序固定为：

1
先看 data.status / data.error
2
-> 再用 workflow_run_id 找运行记录
3
-> 找第一个失败或输出异常的节点
4
-> 检查该节点输入变量
5
-> 最后才改 Prompt

Dify Logs 可能保存完整输入、输出和上下文。本章只上传虚构的退款规则，不上传真实客户资料、Token、API Key 或私人对话。

常见坑#

1. 只给 LLM 传问题，没有传检索结果：这不是 RAG，模型会凭已有知识回答。
2. 把检索节点输出当作最终答案：它只是证据片段，仍需 LLM 组织回答。
3. 修改画布后没有 Publish：测试画布能运行，不代表 API 使用的是最新版。
4. 把 API Key 放前端：任何拿到浏览器代码的人都可能调用你的 Dify 应用。
5. 只配置聊天模型，没有可用的 Embedding 模型：High Quality 知识库无法完成正常语义索引。
6. 把 result 直接当字符串手打进 Prompt：它实际是 chunk 数组，应先绑定到 LLM Context。
7. 只检查 HTTP 状态码：工作流节点可能在 HTTP 200 响应中以 data.status="failed" 结束。
8. 把 Workflow 与 Chatflow API 混用：本章 Workflow 调 /workflows/run；Chatflow 的消息接口和会话语义不同。
9. 把 Agent 的最大迭代次数设得很大：错误工具选择会循环消耗 Token，入门练习先限制为 3。
10. 以为 Dify 知识检索会自动读取项目 SQL/ORM 数据库：Dify Cloud 只搜索已添加到 Dify 知识库并完成索引的资料。

三遍主动练习#

本章边界与检查点#

本章学习 Dify 如何用 Workflow Tool 复现你已掌握的 RAG，并让 Agent 通过工具循环完成检索增强生成；不学习插件开发、复杂 Agent 路由或 Dify 的生产部署。

你能回答下面九条，就可以进入下一章：

1. 为什么检索 Workflow 要有自己的 query 输入，而主 Agent Workflow 使用 question？
2. Workflow Tool 的 query、results 分别是什么？
3. 为什么主 Workflow 里不直接放知识检索节点，而是让 Agent 调用检索工具？
4. Dify Agent 节点和 bind_tools + ToolNode + tools_condition 分别如何对应？
5. 一次 Agentic RAG 的真实调用顺序是什么？什么时候应该结束循环？
6. 为什么 Agent 仍需要 Maximum Iterations、参数校验和权限控制？
7. 为什么要先单独测试检索 Workflow，再测试主 Agent Workflow？
8. 如果追踪中只有 Agent 最终回答，没有 tool call，应该检查什么？
9. POST /workflows/run 的 inputs、user、response_mode 分别负责什么？为什么 HTTP 200 后仍需检查 data.status？

教学方式：具体锚点优先。先在画布中创建真实节点并测试一次，再为它们命名和解释架构。