这篇文章适合谁看？如果你正在搭建企业级知识库问答机器人、做自动化客服，或者想快速把大模型接入到自己的业务系统里，但又不想从底层代码写起，那么这篇教程就是为你准备的。读完这篇文章，你将能独立完成一个基于 Dify 的智能体应用：支持文件上传解析、RAG 语义检索、数据库持久化，并且能调用外部 HTTP 工具完成真实业务动作。我们全程用图形化界面操作，不写一行后端代码，只复制几个必要的 JSON 片段，保证你可以直接复现。

为什么选 Dify 而不是其他框架

当前 GitHub 热榜上 Agent 类项目非常多，比如字节跳动的 DeerFlow 偏重长周期任务自动执行，Composio 主打工具生态接入。但如果你需要的是一个开箱即用、自带可视化编排、能直接对接向量数据库和常见大模型 API 的企业级平台，Dify 是目前社区活跃度最高、文档最完善的选择。它目前有超过 15 万 Star，支持从对话流到 Agent 工作流的完整模式，尤其适合中文开发者。

我实测下来的核心优势有三个：第一，应用编排界面是拖拽式的，修改一个分支节点不需要重新部署；第二，内置了 RAG 管道，从文档分块、向量化到召回测试全部可视化；第三，发布了 API 后可以方便地接入到微信、飞书、网页客服等多种渠道。下面我们进入实操。

准备工作：你需要哪些东西

  • 一台能联网的服务器或者本地电脑，至少 4G 内存，推荐 8G（我用的是 Ubuntu 22.04 云服务器）。
  • Docker 和 Docker Compose，用于一键部署 Dify 社区版。
  • 一个可用的 LLM API Key，DeepSeek、通义千问、智谱或 OpenAI 兼容接口都可以，本教程用 DeepSeek 作为示例。
  • 一个 HTTP 请求测试工具，例如 Postman 或者直接使用 Dify 内置的调试节点。

如果你完全没有 Docker，先执行下面的命令安装（以 Ubuntu 为例）：

curl -fsSL https://get.docker.com | sh
sudo systemctl enable docker
sudo systemctl start docker
sudo curl -L "https://github.com/docker/compose/releases/download/v2.24.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

安装完成后验证一下：docker-compose --version 输出正常就继续。

第一步：部署 Dify 社区版

克隆 Dify 的官方仓库，并切换到稳定版本分支。我这里用 v1.5.0 版本，实测比较稳定。

git clone https://github.com/langgenius/dify.git
cd dify
git checkout 1.5.0
cd docker
cp .env.example .env

在 .env 文件里，你需要做两处修改：一是设置你自己的密钥，二是把暴露的端口改为不被占用的端口。默认 80 端口经常和已有 Nginx 冲突，所以我改成 8080：

# 在 .env 中修改
EXPOSE_NGINX_PORT=8080
SECRET_KEY=你的随机字符串（可以用 openssl rand -hex 32 生成）

然后启动服务：

sudo docker-compose up -d

第一次启动需要拉取镜像，大约需要 5 到 10 分钟，取决于网络。启动完成后访问 http://服务器IP:8080，设置管理员邮箱和密码即可进入控制台。这一步我留一个提示：如果无法访问，先执行 sudo docker ps 查看容器是否全部 running，尤其注意 api 和 worker 这两个容器。

第二步：接入 DeepSeek 大模型

进入 Dify 控制台以后，点击右上角头像进入“设置”，再选择“模型供应商”。在列表中找到 DeepSeek，填入你在 DeepSeek 开放平台申请的 API Key。Dify 会自动拉取模型列表，你只需要在“模型类型”里选择“LLM”，然后选中 deepseek-chat 作为默认模型。

如果你用的是 OpenAI 兼容接口，也可以选择“OpenAI-API-compatible”进行自定义配置，只要把 base URL 指向你的网关地址即可。这里要特别注意一个细节：更新模型 Key 后，一定要回到“模型供应商”页面点击“重新获取模型列表”，否则新增的模型不会出现在下拉框里。

第三步：创建知识库并上传文档

在顶部导航中找到“知识库”，点击“创建知识库”，输入名称“公司产品手册”，然后上传一个 PDF 或者 Markdown 文件。我这里用一份 200 页的产品说明书 PDF 做测试。上传完成后，Dify 会自动进入分段设置页面。

分段参数我建议这样设置：

参数推荐值说明 分块长度500对于中文文档，500 字左右召回效果最好 分块重叠50避免中间关键信息被切断 检索模式向量检索配合 Embedding 模型使用 Embedding 模型text-embedding-ada-002 或 BAAI/bge-m3Dify 内置了多种选择，配好 Key 即可

点击“保存并处理”，等待几秒钟，Dify 会显示分段数量。你可以在“召回测试”选项卡里输入一个问题，例如“产品的保修期是多久”，来验证是否召回正确。这一步非常关键，如果返回结果不相关，请调整分块重叠值到 80 或者更换 Embedding 模型。

第四步：搭建工作流

现在进入重头戏，创建 Agent 工作流。点击“创建应用”，选择“Agent 工作流”，命名为“智能客服助手”。你会看到一个画布，左侧是节点库，右侧是预览和调试区。我们要实现的功能是：用户提问 → 在知识库检索 → 把检索结果拼入提示词 → 调用大模型 → 如果用户需要查询订单状态，则调用 HTTP 工具请求外部 API → 返回最终答案。

4.1 添加知识检索节点

从节点库中拖入一个“知识检索”节点，在节点配置里选择刚才创建的“公司产品手册”。设置检索参数：top_k 设为 3，score_threshold 设为 0.5。这意味着只取相似度分数高于 0.5 的前 3 个分段。

4.2 设置提示词节点

再拖入一个“LLM”节点，在系统提示词中引用知识检索的输出。Dify 使用 {{#node_id#}} 这种语法来引用上游节点输出。例如：

你是公司的客服助手。请根据以下资料回答问题，如果资料中没有相关内容，请回答“对不起，我需要查阅更多资料”。
上下文：
{{#knowledge_retrieval_1#}}

用户问题：{{#sys.query#}}

注意，这里的 knowledge_retrieval_1 是知识检索节点的实际 ID，你可以在知识检索节点的右上角“复制 ID”获得。不要写成固定的字符串，否则渲染不出来。

4.3 添加工具节点

为了让工作流具备“查询订单”的能力，我们添加一个“HTTP 请求”节点。假设你的内部系统提供了一个订单查询接口：https://api.example.com/order?order_no=ABC123。在节点类型里选择 GET，URL 参数引用用户输入中的订单号。Dify 支持把上一个分支的条件输出作为参数传递，我们这里直接引用系统变量 sys.query 里的参数即可。

实际生产中你可能需要鉴权，那就选择 Header 方式，把 API Key 填写到请求头里。我测试时用一个免费的 Mock 接口，返回 JSON 数据。这样我们就能在下一步把它解析出来。

4.4 条件分支和结果解析

拖入一个“条件分支”节点，配置规则：如果 LLM 节点的输出文本包含“订单号”字样，就走“查询订单”分支，调用 HTTP 请求节点；否则直接输出 LLM 的答案。最后再拖入一个“直接回复”节点，把所有分支的结果汇总成一个字符串返回给用户。这里要提醒新手：Dify 的字符串拼接不能直接用加号，要用“模板”类型的节点，或者用“代码”节点里写 Python 完成拼接。

第五步：调试与测试

点击画布右上角的“运行”按钮，在右侧调试输入框中输入“你好，请问你们产品的保修期是多久？”，然后点击运行。你会看到数据流逐步走完知识检索和 LLM 节点，最终输出答案。我实测的延迟大约为 1.8 秒，其中检索只占了 0.2 秒。

接着测试工具调用：输入“我的订单号是 308291，帮我查一下物流状态”。此时条件分支判断命中，进入 HTTP 请求节点，从 Mock 接口返回了物流数据。整个流程跑通以后，点击右上角“发布”按钮，生成 API。

发布后你会得到一系列 API 地址，例如https://你的域名/v1/chat-messages。利用 Dify 的 API 密钥，你可以把它接入到任何前端应用中。下面是一个使用 Python 调用该接口的最小示例：

import requests

url = "http://你的服务器IP:8080/v1/chat-messages"
headers = {
    "Authorization": "Bearer app-你的API密钥",
    "Content-Type": "application/json"
}
data = {
    "inputs": {},
    "query": "我的订单号是 308291",
    "response_mode": "blocking",
    "user": "test-user-123"
}
r = requests.post(url, json=data, headers=headers)
print(r.json()["answer"])

我实际跑通后，API 返回速度在 2 秒左右，完全满足客服场景。注意：如果你是本地服务器，需要把 URL 的 IP 替换成你的服务器公网 IP，并确保防火墙放行 8080 端口。

容易被忽略的细节与陷阱

在整个实践过程中，我踩了几个坑，这里集中列出来，你们可以避开：

  • Embedding 模型和 LLM 模型不要选同一个供应商下的同一个模型。有些供应商的 Embedding 模型输出维度不兼容 Dify 的向量库索引，可能导致召回结果为空。建议用独立 Embedding 服务。
  • 知识库文档更新后，召回测试结果不会立刻更新。你必须手动点击文档右侧的“重新处理”按钮，让系统重新切分和向量化。否则旧向量还在索引里，回答内容还是老的。
  • LLM 节点引用知识检索输出时，必须确认节点 ID 是动态的。如果你复制了一个已经删除的节点 ID，调试时会直接报错找不到变量。
  • HTTP 请求节点默认超时是 60 秒，如果你的下游接口响应慢，请调大超时时间。否则工作流会直接失败。
  • Dify 1.5 及以上版本新增了“会话变量”功能，但新手不要一开始就上会话变量，否则容易把变量作用域搞混。第一版应用先用系统变量和节点输出来实现，足够覆盖大部分场景。
  • 发布 API 时，如果服务器在反向代理后面，要设置“允许 CORS 跨域”，否则你在前端网页里直接 fetch 会被浏览器拦截。

完整工作流总结

我们现在从头梳理一遍整体流程：

1. 安装 Docker 环境并部署 Dify 社区版
2. 接入 DeepSeek 或任意大模型 API
3. 创建知识库，上传文档，配置分块参数
4. 创建 Agent 工作流，依次搭建：
   开始节点 → 知识检索节点 → LLM 节点 → 条件分支节点 → HTTP 请求节点 → 直接回复节点
5. 调试运行，测试知识问答和工具调用
6. 发布为 API，并通过外部程序调用

这套流程不仅仅适用于客服机器人。你可以把知识检索节点替换成数据库查询节点，把 HTTP 请求节点替换成邮件发送工具，就可以构建一个自动化工单助手。核心思想就是：用知识库承载静态信息，用工具节点连接动态业务系统，用 LLM 节点做最终的自然语言生成。

实测数据与性能表现

为了让数据说话，我做了三组对比测试：

测试场景平均耗时成功率说明 纯知识库问答1.5 秒98%500 分块、3 个召回片段 知识库 + 工具调用2.3 秒94%HTTP mock 接口 300ms 响应 多轮连续对话2.8 秒92%加入历史消息上下文

从数据上看，Dify 的额外开销主要在节点间数据传递和 LLM 推理本身。如果你需要把单次响应压到 1 秒以内，建议使用流式输出模式，让用户感知更快。另外，HTTP 请求如果频繁调用，建议在 Dify 里配置缓存节点，避免每次命中都去请求第三方。

结论与推荐

如果你正在为项目选型，我的建议是：Dify 非常适合中小团队快速搭建业务型 Agent 应用，尤其是知识库问答、内容审核、客服助手这类场景。你不需要掌握 prompt 工程的复杂技巧，Dify 的编排界面已经帮你把常见范式封装好了。当你的业务增长到需要精细管控每个节点时，Dify 也支持通过 API 回调外部代码，不会限制开发者自由。

相比之下，DeerFlow 更适合需要自主规划长任务的研究类场景，Composio 更适合纯工具链集成，而 Dify 则在“应用开发平台”这个定位上做到了平衡。因此我的最终推荐是：默认选择 Dify 作为你的 Agent 应用底座，如果后续遇到性能瓶颈，再把具体节点替换成自研微服务。

最后，不要光看不练，建议你立刻部署一个实例，把今天教的步骤走一遍。如果你在过程中遇到端口冲突、向量库连接失败等问题，欢迎在评论区留言，我会针对高频问题补充一篇排错指南。