18 · Dify 实战：搭建智能客服

本章目标：用 Dify 零代码复刻第 14 章的客服系统——知识库政策问答 + 航班实时查询工具 + 意图分派 + 人工兜底，并把它发布成 API 供 Java 侧调用。全程对照代码版（第 14 章）看"同一件事，两种做法"。

本章你将学到

1. Docker Compose 自托管 Dify，初始化并接入模型供应商（含国产模型 + Embedding + Rerank 的分工）；
2. 建知识库：分段、索引、混合检索配置与召回测试；
3. 用 OpenAPI 描述把 Java 航班接口变成 Dify 自定义工具；
4. 搭一张对话流画布：意图分类 → 条件分支 → 政策 / 航班 / 兜底；
5. 用 Agent 应用模式挂知识库 + 工具，让模型自主决策；
6. 发布为 WebApp / iframe，并给 Java 侧开放 API（/v1/chat-messages）；
7. Dify 场景的生产注意点与"迁回代码"的路径。

前置知识

• 第 17 章：Dify 概念与选型；
• 第 05-06 章：RAG 链路与检索配置（本章配置项对应它们）；
• 第 14 章：本章要复刻的代码版系统。

18.1 目标与架构

我们要在 Dify 里搭的系统，和第 14 章的 customer_service_graph.py 完全同构：

用户消息 ──▶ 意图分类 ──▶ 分支：
              policy   → 知识检索（退改签规则库）→ LLM 作答
              flight   → 工具（航班查询，真实执行在 Java 服务）
              其他     → 兜底话术（转人工提示）

全程不需要写 Python。唯一要写的代码是你的 Java 航班接口（真实数据在你后端）。

18.2 部署与初始化

18.2.1 Docker Compose 自托管

Dify Community Edition 官方推荐 Docker Compose 部署。到 Dify 仓库取 docker/ 目录，然后：

cd docker
docker compose up -d

运行后输出（模拟，实际结果取决于你的机器与镜像版本）：

[+] Running 11/11
 ✔ Network docker_ssrf_proxy_network       Created
 ✔ Container docker-db-1                   Started
 ✔ Container docker-redis-1                Started
 ✔ Container docker-web-1                  Started
 ✔ Container docker-api-1                  Started
 ✔ Container docker-worker-1               Started
 ✔ Container docker-weaviate-1             Started
 ✔ Container docker-sandbox-1              Started
 ✔ Container docker-plugin_daemon-1        Started
 ✔ Container docker-ssrf_proxy-1           Started
 ✔ Container docker-nginx-1                Started

几秒后访问 http://localhost：

$ curl -I http://localhost
HTTP/1.1 200 OK

首次访问会要求设置管理员账号（邮箱 + 密码），随后登录进控制台。组件概览（对你有用的是）：

生产部署注意事项（容量、备份、HTTPS、升级）见 18.9。以官方部署文档为准——Dify 的编排结构随版本有调整。

18.2.2 接入模型供应商

在"设置 → 模型供应商"接入模型。我们按"国产模型 + 分工配置"为例：

也可以接"OpenAI 兼容"自定义供应商：填 base_url + API Key + 模型名（和第 02 章 .env 同一套思路）。配好后在"系统模型"里指定默认推理 / Embedding 模型：

系统模型设置（模拟界面）：
  推理模型     : DeepSeek  deepseek-chat          ✔ 已连接
  Embedding 模型: 智谱    embedding-3               ✔ 已连接
  Rerank 模型  : 智谱    rerank                     ✔ 已连接（可选）

和第 14 章代码版对比：ChatOpenAI(model=..., base_url=...) 一次配置，这里变成了控制台里填一张表单。Embedding 模型选定后别乱换——换了要重建知识库索引（第 6.8 节的坑，Dify 会提醒你）。

18.3 建知识库：政策问答的"检索层"

把第 5 章的 rules.txt（蓝天航空退改签规则）做成知识库。

入库：知识库 → 创建 → 上传文档 rules.txt。分段用通用（自动）模式，设置分块长度与重叠（默认 500 / 50 附近，中文语料按实际效果调，第 5.4 节讲过的道理）：

分段设置（模拟界面）：
  分段模式   : 通用
  分段长度   : 500 字符
  分段重叠   : 50 字符
  索引方式   : 高质量（Embedding）   [推荐]

检索配置（对应第 6.3 / 6.4 节的旋钮）：

检索设置（模拟界面）：
  检索模式   : 混合检索             ← 向量 + 全文（RRF 融合）
  Top-K      : 3                    ← 第 5.8 节 k
  Score 阈值 : 0.5                  ← 低于 0.5 不返回
  Rerank 模型: 智谱 rerank          ← 混合检索建议配精排

召回测试：输入一个问题，界面直接展示命中了哪些段、相似度多少（这就是第 6.1 节"先看检索"的内置版）：

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

召回测试：航班起飞前4小时内退票，手续费是多少？
  命中 3 段，最高分 0.87：
  [1] 0.87 航班起飞前 4 小时内申请退票，收取票面价 40% 的手续费。…
  [2] 0.72 航班起飞前 4 小时至 24 小时内申请退票，收取票面价 20% 的手续费。…
  [3] 0.58 航班起飞后申请退票，收取票面价 60% 的手续费。…

如果该命中的没排进 Top-K / 分数低于阈值，先按第 6.1 节归因：分块粒度、检索模式、Score 阈值、Rerank 是否生效。界面测试完，再进工作流。

18.4 自定义工具：把 Java 航班接口暴露给模型

航班状态在你们 Java 服务里，Dify 通过"自定义工具"调它。你的 Java 接口（示意）：

// Java 侧已有的接口：航班状态查询
@RestController
public class FlightController {
    @GetMapping("/api/flight/status")
    public FlightStatus status(@RequestParam String flightNo) {
        // 真实场景查航班系统；这里 mock
        return new FlightStatus(flightNo, "延误约 40 分钟", "预计 14:20 起飞");
    }
}

Dify 里：工具 → 创建自定义工具 → 粘贴 OpenAPI 描述。描述文件让它"认识"这个接口：

openapi: 3.0.0
info:
  title: 蓝天航空航班状态查询
  version: 1.0.0
servers:
  - url: http://your-java-service/api
paths:
  /flight/status:
    get:
      operationId: get_flight_status
      summary: 查询航班实时状态
      parameters:
        - name: flightNo
          in: query
          required: true
          schema:
            type: string
            description: 航班号，如 CA1501
      responses:
        "200":
          description: 航班状态
          content:
            application/json:
              schema:
                type: object
                properties:
                  flightNo:
                    type: string
                  status:
                    type: string
                  eta:
                    type: string

导入成功后，工具列表里出现 get_flight_status（模拟界面）：

自定义工具（1）
  ┌──────────────────┬──────────────────────────┬──────────────┐
  │ name             │ summary                  │ 端点          │
  ├──────────────────┼──────────────────────────┼──────────────┤
  │ get_flight_status│ 查询航班实时状态          │ GET /flight/status│
  └──────────────────┴──────────────────────────┴──────────────┘

和代码版对照（第 8 章）：

安全边界不变（第 12.3 节）：Dify 只负责"让模型决定调它、把参数传给它"；真正执行、鉴权、审计都在你的 Java 服务。Dify 侧的"外部请求"会经过 ssrf_proxy 防内网探测，但你仍要确认工具接口本身做了权限校验。

18.5 搭对话流：意图分派 + 政策问答 + 航班查询

新建应用 → 选 对话流（Chatflow），进入画布。我们搭四类节点，和 14.5 的图一一对应：

开始 ──▶ 问题分类器（intent）
            │
            ├─ policy ──▶ 知识检索 ──▶ LLM ──▶ 直接回复
            ├─ flight ──▶ 工具(get_flight_status) ──▶ 直接回复
            └─ 其他 ────▶ 直接回复（转人工提示）

18.5.1 问题分类器（对应 classify_node）

18.5.2 条件分支（对应 route_by_intent）

IF 分类结果 == policy 走政策分支，== flight 走航班分支，否则走兜底。

18.5.3 政策分支：知识检索 + LLM（对应 policy_node）

• 知识检索节点：选 18.3 的知识库，引用 sys.query（用户原话）；
• LLM 节点：系统提示词和第 14 章同款约束：

你是蓝天航空客服。只依据【上下文】回答，资料里没有就明说"资料中没有相关信息"，
不要编造。回答末尾标注依据的资料编号，如（依据 [1]）。

上下文变量引用知识检索节点的输出：{{#context#}}（Dify 用 # 包裹上游节点名引用变量，节点名别乱改，方便后续维护）。

18.5.4 航班分支：工具节点（对应 flight_node）

工具节点选 18.4 的 get_flight_status，参数填 sys.query 让模型从问句里提取航班号。模型负责从"CA1501 延误了吗"里抽出 flightNo=CA1501，真正查询走你的 Java 接口。

18.5.5 兜底：直接回复

抱歉，这类问题建议转人工处理：请拨打 95599 客服专线，或留下联系方式，我们会尽快联系您。

18.5.6 画布调试

Dify 支持节点级调试：从某个节点往后跑，或整条跑。整条跑一遍（模拟）：

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

用户：CA1501 现在延误了吗？
[问题分类器] intent = flight
[工具] get_flight_status(flightNo="CA1501") → "延误约 40 分钟，预计 14:20 起飞"
[直接回复] CA1501 当前延误约 40 分钟，预计 14:20 起飞，请留意航司短信通知。

用户：航班起飞前4小时内退票，手续费是多少？
[问题分类器] intent = policy
[知识检索] 命中 3 段，Top1 相似度 0.87
[LLM] 航班起飞前 4 小时内退票，收取票面价 40% 的手续费（依据 [1]）。

用户：你们几点上班？
[问题分类器] intent = other
[直接回复] 抱歉，这类问题建议转人工处理：请拨打 95599 客服专线…

对照第 14 章 chat("s-001", ...) 的输出去看：同一套分派逻辑，这里全是界面配置。画布上的节点就是第 09 章图的节点——只是用鼠标连线代替 add_edge。

18.6 Agent 应用模式：让模型自主决策

如果你不想画分支，Dify 的 Agent 应用把第 02 / 10 章的 ReAct 循环也封装好了：建一个 Agent 应用，勾选知识库 + 勾选工具，配一个"Agent 推理模型"，剩下交给模型：

Agent 应用设置（模拟界面）：
  知识库   : 蓝天航空退改签规则
  工具     : get_flight_status ✔
  Agent 推理模型 : DeepSeek deepseek-chat   ← 可单独指定更强的模型（12.4.3）

模型会自己决定：问政策 → 检索知识库；问航班 → 调工具；都不需要 → 直接答。和第 10 章 create_react_agent 是同一套心智，区别只是你不用写 @tool、bind_tools、循环控制。

取舍（第 17.2 节的落地）：

• 对话流 + 分支：可控、省 token、行为可预测——适合"意图明确、分支固定"的客服（我们 18.5 的做法）；
• Agent 应用：灵活、能处理交叉问题（如"CA1501 延误了，退票要扣多少钱"一次搞定）——但更耗 token、更难预测。

多数生产客服是对话流为主、关键节点内嵌 Agent 或工具。

18.7 发布与嵌入

应用编排完点"发布"。三种形态：

• WebApp：得到一条分享链接，浏览器里直接对话；
• 嵌入：复制 iframe 代码嵌进现有系统：

<iframe src="https://your-dify/app/xxxxxxxx" style="width:100%;height:600px;border:none;"></iframe>

• 访问 API：在"访问 API"页生成 app-xxx 的 API Key（只发布应用后可见）——Java 侧正式接入走这里。

18.8 Java 侧接入：用 API 调 Dify

18.8.1 先拿 curl 验证

发布后生成 API Key，先 curl 冒烟（对应第 2 章的"先跑通再谈架构"）：

curl -X POST "http://localhost/v1/chat-messages" \
  -H "Authorization: Bearer app-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "inputs": {},
        "query": "CA1501 现在延误了吗？",
        "response_mode": "blocking",
        "user": "u-20261009"
      }'

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

{"message_id":"a3fe1f52-2a1f-4e3f-9c0b-...",
 "conversation_id":"1c7d55fb-...",
 "mode":"chat",
 "answer":"CA1501 当前延误约 40 分钟，预计 14:20 起飞，请留意航司短信通知。",
 "metadata":{"usage":{"prompt_tokens":620,"completion_tokens":48,"total_tokens":668}}}

18.8.2 Java Feign 客户端

和第 12.5 / 14.7章的姿势一致——一个客户端接口 + 一次调用：

// Java：Feign 客户端调 Dify 对话 API
@FeignClient(name = "dify", url = "${dify.base-url}",
             configuration = DifyFeignConfig.class)
public interface DifyChatClient {

    @PostMapping("/v1/chat-messages")
    DifyChatResp chat(@RequestBody DifyChatReq req);
}

// 请求体：query = 用户消息，conversation_id = 续会话，user = 会话归属
public record DifyChatReq(String query, String conversationId, String user) {}

// 响应：answer 是回答，conversationId 存下来，下次传回
public record DifyChatResp(String messageId, String conversationId,
                           String mode, String answer) {}

字段名注意：Dify API 的请求/响应字段是 snake_case（conversation_id、message_id），上面的 Java record 用的是 camelCase。接入时给 Jackson 配 PropertyNamingStrategies.SNAKE_CASE，或给字段加 @JsonProperty("conversation_id")，否则 Dify 收不到 conversation_id，每次请求都会被当成新会话。

Feign 配置里注入 Authorization: Bearer app-xxx（API Key 放配置中心 / 环境变量，别写死——第 2.3 节的纪律）。

18.8.3 多轮会话：conversation_id

conversation_id 就是 Dify 的记忆键（第 09 章 Checkpointer 的云端形态）：

// 第一次：conversationId 传空 → 拿到新会话
DifyChatResp r1 = client.chat(new DifyChatReq("帮我查 CA1501", "", "u-1"));
String convId = r1.conversationId();

// 第二次：带上 convId → Dify 记得上文
DifyChatResp r2 = client.chat(new DifyChatReq("那它的票价呢？", convId, "u-1"));

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

r1.answer      = 好的，我来查一下 CA1501 的当前状态。
r1.conversationId = 1c7d55fb-9a2b-...
r2.answer      = 您刚才在问 CA1501——它在 2026-10-09 的经济舱票价约 780 元。

会话亲和：user 字段用于区分多用户隔离。多副本 / 高可用时，Dify 本身就是独立服务，Java 侧把它当普通后端调即可（没有第 12.5.3 节"同副本亲和"的包袱——记忆在 Dify 侧）。

18.8.4 流式

前端要打字机效果，response_mode 改 streaming，响应是 SSE：Java 侧用 WebClient 按 data: 行解析拼接（和第 12.5 章"Java 侧 WebClient 透传"同一套）。

18.9 生产注意点（Dify 场景版）

Dify 省了应用层代码，但第 12 章的清单一项都没省，只是换了个地方：

一句话：Dify 帮你把"应用的壳"做完了，业务安全边界、评估、容量还是你的活。对照第 14 章上线清单逐条过一遍，能打勾的直接打勾，打不了勾的就是你要自己补的。

18.10 从 Dify 迁回代码：什么时候、怎么搬

Dify 适合快速上线，但规模一大（深度定制、复杂图、严格性能 / 成本预算）就需要迁回代码。路径是增量的，不是推倒重来：

1. 把画布翻译成图：每个节点 → LangGraph 一个节点函数，变量引用 → State 字段（第 09 章）——画布就是现成的设计文档；
2. 先迁检索：知识库导出的分段与检索配置，对应第 5-6 章代码（RecursiveCharacterTextSplitter + 混合检索 + Rerank）；
3. 再迁控制流：问题分类器 → classify_node，条件分支 → conditional_edges（第 10 / 14 章）；
4. 工具原样保留：自定义工具调的就是你的 Java 接口，迁回后代码直接调同一个接口，零改动。

什么时候动手迁：并发 / 定制需求超过 Dify 平台的舒适区（第 17.2 节判断表），或运营不再需要自助改。别为了"用代码"而迁——Dify 还在每天帮你省着开发量。

小结

• Dify 客服 = 知识库（检索）+ 自定义工具（Java 接口）+ 对话流（意图分派）+ 直接回复（兜底），和第 14 章代码版一一对应，但全程界面配置；
• 自定义工具是 Dify ↔ Java 的桥：模型决定调用、参数由模型填、执行与安全在 Java 侧（第 12.3 章边界不变）；
• 对话流 vs Agent：客服优先对话流（可控、省 token），交叉复杂问题用 Agent / 工具兜底；
• Java 接入：/v1/chat-messages + conversation_id 续会话，Feign / WebClient 就能调，Dify 的记忆天然免去"会话亲和"负担；
• 生产清单没省：日志成本、标注纠错、权限与工具安全、备份升级，都是你的活（第 12 章逐条对照）；
• 迁移是增量：画布当设计文档，先迁检索再迁控制流，工具接口复用。

到这里，你已经掌握了同一条"知识库 + 工具 + 编排"主线的三种落地方式：Python 代码（第 7-14 章）、Java 生态（第 13 章）、可视化平台（第 17-18 章）。按团队与场景选，而不是被工具绑架。

练习

1. 用 Docker Compose 部署一个 Dify，接入你的国产模型供应商，跑通 18.3 的召回测试。
2. 把你的一个真实只读接口（如查询类）写成 OpenAPI 描述导入 Dify，验证模型能从一句话里提取参数并调用成功。
3. 在 18.5 对话流里加一个"参数提取"节点：从"帮我查 CA1501 和 MU5102 两个航班"里抽出两个航班号，再用迭代节点逐个查询——体会结构化输出 + 循环的图形化。
4. 用 Java 的 Feign / WebClient 调你发布的 Dify 应用，实现多轮对话（保存 conversation_id），对比与第 14 章代码版的接入成本。
5. 把 Dify 应用日志里 20 条真实问答抽出来，用第 12 章的 LLM-as-judge 打分，建立你自己的基线指标。

参考答案

<details>
<summary>练习1（部署 + 召回测试）</summary>

步骤：docker compose up -d → 首次登录设管理员 → 配模型供应商（推理 + Embedding，DeepSeek 需另配 Embedding 供应商）→ 建知识库传 rules.txt → 配混合检索 + Score 阈值 0.5 → 召回测试。

预期：问"退票手续费多少"应命中 3 段左右、最高分 0.8+。若最高分偏低，检查：Embedding 模型是否已连接、索引是否重建、检索模式是否混合 + 是否配了 Rerank（第 6 章顺序）。全程和第 5 章手写版对比着看，你会更清楚界面背后在干什么。
</details>

<details>
<summary>练习2（真实接口导入自定义工具）</summary>

要点三件事：

1. 只暴露只读接口：导入前确认接口无副作用（写操作别进工具，或进工具后强制加审批，第 12.3 节）；
2. 参数描述要写清楚：OpenAPI 里 description 是模型理解参数的唯一依据——"flightNo: 航班号，如 CA1501"这种描述越具体，模型提取越准（对应第 8 章 @tool docstring 的作用）；
3. 测试：对话里问一句带干扰词的话（"帮我看看那个 CA1501 飞得怎么样"），看模型是否只提出 CA1501。若提错，优化参数描述 / 给示例。

失败排查：工具调用超时报错 → 检查你的服务地址是否可从 Dify 容器访问（网络 / SSRF 白名单）；鉴权失败 → OpenAPI 里配置 API Key / Bearer 校验方式。
</details>

<details>
<summary>练习3（参数提取 + 迭代）</summary>

对话流里：问题分类器(flight) → 参数提取（模型抽取 flightNos 数组）→ 迭代节点（对每个航班号调工具）→ 聚合 → 直接回复。

• 参数提取对应第 03 章结构化输出：节点配 schema（{"flightNos": {"type": "array", "items": {"type": "string"}}}）与提取说明，模型返回符合 JSON 的数组；
• 迭代节点对数组逐项执行，可引用 item 变量——这就是第 10 章"循环"的图形化；
• 验证点：输入两个航班号，输出应包含两条状态。若只返回一条，检查迭代节点的输出变量是否正确拼接。

一句话："抽取结构化字段 → 循环处理 → 聚合"是工作流里最常复用的三段式，对应代码里的 with_structured_output + for 循环。
</details>

<details>
<summary>练习4（Java 接入对比）</summary>

Dify 版接入代码只有：一个 Feign 接口 + 一个请求/响应 record（18.8.2），约 20 行；第 14 章代码版要部署 Python 服务、配 Checkpointer、处理工具循环。对比结论：

• 用 Dify，应用层（意图分派、检索、工具循环、记忆）全在平台，Java 只写"调用 + 业务"；
• 用代码，你能完全控制每一步，但要维护整条链路。

判断标准不是"哪个代码少"而是"谁需要改它"（第 17.2 节）：运营常改 → Dify；要深度定制 → 代码。接入成本的差异本身也是选型输入之一。
</details>

<details>
<summary>练习5（Dify 日志 + LLM-as-judge 基线）</summary>

1. 取日志：应用日志 → 导出 / 复制 20 条 question + answer（带命中的段落更佳）；
2. 打分：用第 12.1.3 节的 judge_answer 脚本逐条打分（忠实度 / 完整度 / 清晰度 0-5）；
3. 建基线：平均分 + 最低分样本清单。对最低分样本归因（第 6.1 节口诀）：检索没召回 → 调检索配置；召回了答得歪 → 改提示词 / 加标注示例；
4. 回归：每次改动（改提示词、改检索、加标注）后重跑，指标不降再上线。

这套流程和第 14 章 run_eval 完全同构，只是被测对象从代码系统换成了 Dify 应用。标注（Annotation）可以看成"人工把 judge 的低分样本修对"的落库动作。
</details>

延伸阅读

• 第 17 章：概念与选型 | 第 14 章：代码版对照
• Dify 官方文档：部署、模型供应商、知识库、工作流节点、API（以你部署版本的文档为准）
• 概念底层：第 05-06 章（RAG）、第 08-10 章（工具与编排）、第 12 章（生产清单）
• Java 生态对照：第 13 章