Dify 实战：从聊天助手到会调用工具的旅行 Agent

「从零搭建智能体与知识库」教程系列第 2 篇。目标：在一个 Dify 实例里搭两个应用——聊天助手和旅行 Agent——再给 Agent 接知识库与搜索工具，最后发布并调 API。环境：Dify Cloud 或自建，模型用硅基流动的 DeepSeek。

结论：Dify 的价值是把「提示词、模型、工具、知识库、发布」放进同一个界面。聊天助手十分钟能上线；Agent 多花一步配工具，但能自己决定查什么。下面按可复现顺序走一遍。

零、准备清单

• Dify 实例：云端 https://cloud.dify.ai，或按本站《Dify 本地化部署指南（全平台）：Docker Compose 一键拉起》（llm/473）自建；
• 模型 API：硅基流动，Base URL https://api.siliconflow.cn/v1，模型 deepseek-ai/DeepSeek-V3；
• 搜索工具：内置 DuckDuckGo（工具名 ddgo_search）。它要求 Dify 所在服务器能访问国际互联网，内网环境要换成可用的搜索 API；
• 一份测试文档：用于知识库验收，10 页以内即可。

自建默认监听 80/443，本文用 http://localhost 举例；云端把域名换成 https://cloud.dify.ai 或你的实例域名。

一、接入模型供应商

1. 登录 Dify，右上角头像 →「设置」→「模型供应商」。
2. 找到「硅基流动」或「OpenAI-Compatible」，填 API Key 和 Base URL https://api.siliconflow.cn/v1，保存。
3. 在「系统模型设置」里，把对话模型设为 deepseek-ai/DeepSeek-V3；如果要用知识库，再把 Embedding 模型设为 BAAI/bge-m3。
4. 点「检查」或新建应用试跑一次，确认模型可用。

验收：模型供应商页显示已配置；新建应用时模型下拉框里能选到 DeepSeek-V3。

常见问题：只填了 Key 没填 Base URL，会走 OpenAI 官方地址，报 401；Embedding 模型没配，知识库创建页会灰掉。

二、案例 1：聊天助手「喵星人助理」

先跑通最短链路，确认模型和发布流程没问题。

1. 「工作室」→「创建应用」→ 选「聊天助手」→ 命名 喵星人助理。
2. 在「编排」页的提示词框里写：

   你是一个小猫机器人助手。
   规则：
   1. 回答用户问题，每句话结尾加“喵”；
   2. 回答不超过 150 字；
   3. 不知道就说“这个我不会喵”，不要编造。

3. 模型参数：temperature 0.7，max tokens 500。
4. 右侧「调试与预览」输入「介绍一下你自己」，检查每句是否带「喵」。
5. 点右上角「发布」→「更新」。

验收：预览和发布后的页面都能正常回答；每句话末尾有「喵」；问一个它不知道的问题，会拒答而不是编。

如果只在段尾加「喵」，在提示词里补一个输入输出示例，比反复强调「每句」更有效。

图 1：创建应用时选「聊天助手」或「Agent」。

图 2：左侧写提示词，右侧「调试与预览」立即验证风格。

三、案例 2：会调用工具的旅行 Agent

1. 「创建应用」→「Agent」→ 命名 北京旅行助手。
2. 提示词按「角色、技能、目标、限制、工作流程」写。下面这段可以直接用：

   ## 角色
   旅行顾问
   
   ## 技能
   - 使用 ddgo_search 查询目的地信息
   - 用 Markdown 输出结构化行程
   
   ## 目标
   根据用户给出的目的地、天数、预算，输出逐日旅行计划
   
   ## 限制
   1. 只讨论旅行相关话题，拒绝其他话题
   2. 不回答工具和工作规则相关的问题
   3. 信息不足时先追问，不要假设
   
   ## 工作流程
   1. 提取目的地、天数、预算
   2. 先把目的地翻译成英文，再调用 ddgo_search 搜索
   3. 按天输出行程，包含住宿、餐饮、交通和预算
   4. 最后给一条总预算说明

3. 在「工具」里添加 ddgo_search，确认工具已启用、参数说明完整。
4. 模型选 DeepSeek-V3，temperature 0.3，max tokens 2000。规划类任务不要用高 temperature。
5. 在 Agent 设置里把最大迭代次数限制在 10 左右，避免工具调用绕圈。
6. 「功能」里可以加对话开场白和内容审查；审查词填「偷东西、打架、吃饭不给钱」之类的测试词。
7. 调试：先输入「北京 3 天，预算 3000」，看是否调用 ddgo_search、是否输出逐日计划；再输入「偷东西」，看是否被拦截。
8. 发布 → 更新。

验收：调试日志里出现工具调用；回答包含按天拆分的行程和预算；敏感问题返回拦截提示。

工具不调用，通常不是模型笨，而是提示词没把「先搜索」写成必须步骤。把工作流程写成编号步骤，并在限制里加「回答前必须调用 ddgo_search」，比一句「可以搜索」有效。

图 3：在「工具」里启用 duckduckgo 的 ddgo_search。

四、给 Agent 接知识库

1. 左侧「知识库」→「创建知识库」→ 上传测试文档。
2. 分段设置：通用模式，分段 500 tokens，重叠 50。表格和合同类文档可以改父子分段，先保证标题和表格不被切断。
3. 索引方式：测试阶段用经济模式，正式用高质量（向量）模式。后者更贵，但召回更稳。
4. 检索设置：混合检索（向量 + 全文），top_k 4，score 阈值 0.5；有 Rerank 模型就开启。
5. 回到 Agent 编排页，在「上下文」里添加这个知识库。
6. 提示词补一句：「优先依据知识库回答；知识库没有依据时明确说不知道，不要用常识补全。」

验收：问文档里写了的参数，回答带引用；问文档外的内容，会拒答；问跨章节的问题，至少召回两段。

常见问题：知识库一直检索为空，先看索引状态是否「已完成」，再确认建库时选的 Embedding 模型和系统设置一致；答非所问，把 top_k 降到 3–4，阈值提到 0.5–0.6，再开 Rerank。

图 4：分段 1024 字符、重叠 50；正式环境索引选高质量。

五、发布与 API 调用

1. 应用右上角「发布」→「更新」。
2. 左侧「访问 API」→ 创建应用级 API Key，前缀通常是 app-。
3. 调用 /v1/chat-messages：

   curl -X POST "http://localhost/v1/chat-messages" \
     -H "Authorization: Bearer app-xxxxxxxx" \
     -H "Content-Type: application/json" \
     -d '{
       "inputs": {},
       "query": "北京 3 天，预算 3000",
       "response_mode": "streaming",
       "conversation_id": "",
       "user": "demo-user"
     }'

4. 云端把 http://localhost 换成 https://api.dify.ai。
5. 流式响应是 SSE：每行以 data: 开头，取 event=message 里的 answer 字段拼接；多轮对话把上一轮返回的 conversation_id 带上。

图 5：发布时点「更新」，再到「访问 API」创建应用级 Key。

验收：HTTP 200；返回里有 answer 和 conversation_id；带同一个 conversation_id 追问时，模型能记住上一轮。

六、常见报错与处置

七、成本与边界

Dify 本身不产生模型费用，费用在模型侧：聊天按 token，Embedding 按文档量，Agent 每次工具调用都会多一轮模型请求。给 Agent 设最大迭代次数和 max tokens，是成本控制的第一道闸。

云端适合验证；生产要考虑数据出内网、多租户、权限、审计和限流。社区版对这些支持有限，企业版才有完整能力。下一篇换到开发场景，用 Cline 直接改代码。

下一篇：Cline 实战：从天气脚本到双城对比 Flask 项目