17 · Dify 初识与核心概念：把 Agent 工程"可视化"

本章目标：认识 Dify 这条不写代码的路线——用可视化界面编排 RAG、Agent、工作流，把前 16 章学过的每一个概念在图形化工具里对号入座。它不是来替代你写代码的，而是给你多一个"更快出活"的选项。

本章你将学到

1. Dify 是什么、它解决了什么问题（以及它不解决什么）；
2. "可视化编排"与"代码编排"（LangChain / LangGraph）的定位关系与选型标准；
3. 把前 16 章的概念映射到 Dify 的五大核心组件：模型管理 / 知识库 / 工作流 / 工具与 Agent / 发布与可观测；
4. 一张"何时用 Dify、何时写代码、怎么混用"的决策清单。

前置知识

• 至少完成第 05 章（RAG 链路）与第 08 章（工具与 Agent）——否则你会"会用界面，但不知道界面在封装什么"；
• 第 14 章的全代码实现，是第 18 章在 Dify 里复刻的对照物（本章多处引用它）。

17.1 Dify 是什么

Dify 是一个开源（Community Edition 可在 GitHub 获取、可自托管）的 LLM 应用开发平台：把模型管理、知识库（RAG）、可视化工作流编排、工具调用、Agent、应用发布与日志这些"AI 应用的通用骨架"做成开箱即用的界面，让你不写胶水代码就搭出一个能上线的应用。

一句话定位：前 16 章里我们用 Python 一行行手搓的东西，Dify 把它们变成了界面上拖一拖、配一配。

它和你已经熟悉的两条路线的关系：

路线一：全代码       路线二：Java 生态      路线三：可视化平台
LangChain/LangGraph  LangChain4j/Spring AI   Dify（本章）
(Python，前 7-14 章)   (第 13 章)            (低代码，17-18 章)
     │                    │                       │
     └──────── 同一套心智模型：RAG / Agent / 工具 / 记忆 ────────┘

Dify 提供的核心能力（全部图形化，不用写代码）：

Dify 不替你做的事（要记牢，这是选型边界）：

• 不替你写业务逻辑：真正的下单、退票、查订单，还是得你在 Java / Python 侧实现，Dify 通过"自定义工具"去调它；
• 不保证生产级工程化：复杂权限、大规模高并发、深度私有化改造，仍要自己兜（第 12 章的清单照样适用）；
• 不替代深度定制的控制流：高度自定义的图、多 Agent 复杂协作，代码方案（第 10 章）更灵活。

版本说明：Dify 迭代很快（云版与开源 Community Edition 节奏不同），且界面在持续改版。本章与第 18 章按 Dify 1.x 的核心概念写作，节点名称、API 路径等以你部署版本的官方文档 / 实际界面为准，概念与思路不变。

17.2 可视化编排 vs 代码编排：怎么选

这是本章最实用的一张表。多数团队不是二选一，而是混用。

选型口诀：

1. 知识库问答类、运营要能自己改 → 先上 Dify，别写代码；
2. 复杂编排 / 深度集成 / 要极致可控 → 写代码（或 Java 生态，第 13 章）；
3. 两条腿走路（最推荐）→ Dify 做应用层（对话、RAG、Agent），你的 Java 服务通过自定义工具被 Dify 调用；复杂模块再用代码单独实现。

类比：Dify ≈ 你们团队的低代码平台 / 表单引擎，代码 ≈ 核心业务系统。低代码平台解决 80% 的重复搭建，核心逻辑永远留给你自己。

17.3 概念映射：把前 16 章翻译成 Dify

读完下面这张表，Dify 对你就不再是黑盒——每个界面上出现的词，你都能指出它在原理上对应什么。

17.4 应用类型与编排方式

Dify 里"应用"是部署和发布的基本单位。类型决定对话形态，编排方式决定复杂程度：

两种编排方式：

• 基础编排（简单聊天 / 文本生成）：只配 Prompt + 模型，适合极简场景；
• 高级编排（工作流 / 对话流）：画布拖节点，处理复杂逻辑——这是 Dify 的核心玩法。

第 14 章那个"意图识别 → 分派 → 政策问答 / 航班查询 / 转人工"的客服系统，在 Dify 里就是一张对话流画布：开始 → 问题分类 → 条件分支 →（知识检索 + LLM）→ 直接回复。第 18 章会把它一步步搭出来。

17.5 核心组件一：模型管理

在"设置 → 模型供应商"里接入你的模型。Dify 支持几十家供应商，关键认知：

• OpenAI 兼容格式是一条通用通道：DeepSeek / 通义千问 / 智谱 GLM 等都提供 OpenAI 兼容端点，填 base_url + API Key 即可（和第 02 章 .env 的思路完全一样）；
• 也可以接 Ollama 本地模型（离线、免费，但并发与效果看机器）。

系统模型分工（一个应用可能同时用到三种模型，Dify 让你分别指定）：

• Embedding 模型选定后不要随便换：换了必须重建知识库索引（第 6.8 节的坑，Dify 只是帮你强制了这个流程）；
• 控制台能看到每个应用的 token 用量与费用——这就是第 12.4 节"成本监控"的现成实现。

17.6 核心组件二：知识库（RAG 图形化）

知识库是 Dify 最常用的模块，把第 5-6 章的所有旋钮搬到了界面：

入库流程：上传文档（PDF / Word / Markdown / 网页）→ 分段 → 索引。

检索配置（决定"怎么召回"）：

• 每个知识库可以单独测召回：输入一个问题，界面直接显示命中了哪些段、相似度多少——这就是第 6.1 节"先看检索"的诊断动作，Dify 内置了；
• 多知识库 + 元数据过滤：可为知识库打标签，应用按标签决定用哪个库（对应第 6.8 节"按部门/租户过滤"的雏形，生产级权限仍建议放后端）。

17.7 核心组件三：可视化工作流（节点）

高级编排的画布上，节点是处理单元，连线是数据流：上游节点的输出成为下游节点的输入变量（{{node.output}}）。常用节点：

两种画布的区别：

• 工作流（Workflow）：一次输入跑一遍，面向"任务"（生成摘要、处理一批数据）；
• 对话流（Chatflow）：带会话上下文的多轮对话，面向"对话"（客服、助手），可以引用历史消息。

对读到这里的人来说，Dify 画布就是 LangGraph 的图形化：节点 = 你的函数，连线 = State 的流转。唯一要适应的是"配置靠填表单、变量靠拖拽"而不是写代码。

17.8 核心组件四：工具与 Agent

工具是把"外部世界"接进 Dify 的入口：

• 内置工具：网页搜索、代码解释器、网页抓取等；

• 自定义工具：用 OpenAPI（Swagger）描述文件把你后端的 REST 接口导入——Dify 据此生成工具 Schema，模型就能调它。这是你 Java 服务与 Dify 协作的官方姿势（第 18 章实践）：

  • 你的 Java 接口（如 GET /api/flight/status?flightNo=CA1501）写一份 OpenAPI 描述；
  • Dify 里"创建自定义工具 → 粘贴 OpenAPI 描述"→ 生成工具；
  • 模型在对话中自主决定调用它，真正执行仍在你的 Java 服务（权限、校验、审计都在你那端，安全边界和第 08、12 章一致）。

Agent 应用：把"手写 ReAct 循环"（第 02 章 while 循环、第 10 章 create_react_agent）变成开关——勾选工具 + 知识库，模型自己决定"要不要查、查什么、要不要调工具、调完再答"。Agent 里还能配 Agent 推理模型（单独指定比默认更聪明的模型跑决策），对应第 12.4.3 节"模型分级"。

17.9 发布与 API

应用编排完 → 发布。发布后的三种访问方式：

三种 API 对应三种应用类型：

请求都带 Authorization: Bearer app-xxx，响应可 blocking（一次性返回）或 streaming（SSE 流式，对应第 12.5 章 Java 侧 WebClient 透传流式）。

一次对话 API 调用（预览，第 18 章会完整实践）：

curl -X POST "http://localhost/v1/chat-messages" \
  -H "Authorization: Bearer app-xxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "inputs": {},
        "query": "航班起飞前4小时内退票，手续费是多少？",
        "response_mode": "blocking",
        "conversation_id": "",
        "user": "u-20261009"
      }'

运行后输出（模拟，实际结果取决于模型与运行数据）：

{
  "message_id": "a3fe1f52-2a1f-4e3f-9c0b-8f4e...",
  "conversation_id": "1c7d55fb-...",
  "mode": "chat",
  "answer": "航班起飞前 4 小时内退票，收取票面价 40% 的手续费（依据资料[1]）。",
  "metadata": {
    "usage": {"prompt_tokens": 812, "completion_tokens": 96, "total_tokens": 908}
  }
}

第二次提问时把返回的 conversation_id 传回去，Dify 就"记得"上下文（第 09 章 Checkpointer 的云端形态）。

17.10 可观测与迭代

发布不是终点。Dify 自带的应用观测能覆盖第 12 章相当一部分：

Dify 给了你应用层的可观测；系统层的（QPS、并发、基础设施、审计）仍要自己接（第 12 章清单不变）。

17.11 何时选 Dify：一张决策清单

把它贴到团队 Wiki，遇到新需求先过一遍：

1. 是不是知识库问答 / 客服 / 运营要改内容？ → Dify，别写代码；
2. 是不是"一次调用 + 工具循环"就能覆盖的 MVP？ → Dify，快速验证；
3. 产品 / 运营需要自助调整？ → Dify（他们改 Prompt 和知识，不用排队等工程师）；
4. 涉及深度定制控制流、复杂多 Agent、严格性能预算？ → 写代码（第 10 / 12 / 14 章）；
5. 两者都要？ → Dify 做应用层，Java / Python 服务做执行层，用自定义工具对接（第 18 章就是这条路）。

小结

• Dify 是可视化编排路线：模型管理、知识库、工作流、工具、Agent、发布与日志全图形化，前 16 章的概念在界面上一一对应；
• 它不替你写业务逻辑：真正的交易与权限在你自己后端，Dify 通过自定义工具（OpenAPI）去调；
• 选型：知识库问答、快速 MVP、运营自助 → Dify；深度定制、复杂编排、极致可控 → 代码；生产团队通常是两条腿：Dify 做应用层 + 你的服务做执行层；
• 可观测省心：应用日志、token 成本、标注纠错开箱即用；系统层工程化（第 12 章）仍需自己兜。

下一章，我们把第 14 章的客服系统在 Dify 里完整搭一遍：第 18 章。

练习

1. 打开 Dify 控制台，把知识库检索设置里的"向量检索 / 全文检索 / 混合检索"各跑一遍召回测试，记录同一问题三种模式命中的段落差异——对应第 6.3 节的观察。
2. 把"系统模型"里的 Embedding 模型换成另一个，重建索引，再问同一个问题，观察回答变化（体会第 6.8 节"换模型必须全量重建"）。
3. 用"问题分类器"节点做一个三分类（政策 / 航班 / 其他），对比它和你手写 classify_node（第 14 章）的准确率。
4. 在应用日志里找出一次"答得差"的对话，判断是检索没召回还是生成了没依据的内容（第 6.1 节归因）。

参考答案

<details>
<summary>练习1（三种检索模式对比）</summary>

在知识库检索设置里切换模式，同一问题（如"航班延误能赔多少钱"）：

• 向量检索：语义命中 d5（延误赔偿），但对"赔"字这类精确词不敏感；
• 全文检索：命中含"延误""赔偿"字眼的段落，可能带进不相关的（比如同时提到延误的行李条款）；
• 混合检索：两路融合，既保语义又保词法——通常召回最稳，配合 Rerank 效果最好（第 6.3-6.4 节结论在界面上复现）。

观察点：命中的段落 id 集合、相似度分数分布。若你的数据上三种几乎无差别，说明语料简单，纯向量够用。
</details>

<details>
<summary>练习2（换 Embedding 模型）</summary>

把 Embedding 模型从 A 换成 B 后，先重建知识库索引再问：

• 索引未重建时：新旧向量混在一个集合里，相似度整体乱掉（回答可能明显变差或召回错误段落）——Dify 会在界面上提示你重建；
• 重建后：一切恢复正常。

结论：Dify 帮你强制了"换模型 = 全量重建"这个纪律（第 6.8 节），但你必须理解为什么——向量空间不兼容。
</details>

<details>
<summary>练习3（问题分类器 vs 手写 classify）</summary>

在对话流里加"问题分类器"节点，类别设 policy / flight / other，用 20 条问题测准确率，和手写版（第 14 章 classify_node，同样的模型）对比：

• 两者本质都是一次带约束的 LLM 调用（第 03 章结构化输出），准确率通常接近；
• Dify 版优势：界面可调类别描述、可加 few-shot 示例，运营也能改；
• 手写版优势：逻辑在你代码里，能接自定义后处理。

结论：准确率差异通常不大，选哪个取决于"谁需要改它"。
</details>

<details>
<summary>练习4（日志归因）</summary>

找一次回答差的对话，在应用日志里看两步：

1. 命中了哪些段落、score 多少：若该命中的没命中 / 分数低 → 检索问题（调 Top-K、Score 阈值、检索模式、分块）；
2. 答案是否用了命中段落：命中了但答案没依据 / 编造 → 生成问题（改系统提示词"只依据资料回答"、加标注示例）。

这就是第 6.1 节"先看检索再怪模型"的日常版，Dify 把原始数据都记在日志里了。
</details>

延伸阅读

• 第 18 章：把本章概念落成可运行的客服应用
• Dify 官方文档（模型供应商、知识库、工作流节点、API，以你部署版本的文档为准）
• 概念对照：第 05 章、第 06 章、第 08 章、第 09 章、第 14 章
• 工程化清单（Dify 同样适用）：第 12 章