Dify 从部署到实战：RAG 知识库、工作流与 Agent 全解析

1. 先搞清楚 Dify 到底是个什么东西1.1 一句话说清 Dify 的定位Dify 是一个开源的 LLM 应用开发平台。你可以把它理解成一个“AI 应用的中控台”——它把大模型调用、提示词编排、知识库检索、工作流自动化、Agent 工具调用这些原本需要写大量代码才能串起来的东西全部做成了可视化界面。你不需要从零写一个后端服务去对接模型 API也不需要自己搭一套向量数据库来做检索Dify 把这些都封装好了你只需要在浏览器里拖拖拽拽、填填参数就能跑起来一个能用的 AI 应用。我最初接触 Dify 是因为手上有个需求给一个内部团队做一个能查文档、能回答问题的问答助手。如果纯手写大概需要做这几件事——接模型 API、做文本切分、接向量库、写检索逻辑、拼提示词、做对话管理、加个前端。这套东西写下来少说一周还不算调试。用 Dify 的话模型接入是现成的知识库上传文档就自动切分入库工作流拖几个节点就串起来了前端它自带一个可分享的对话页面。实际从部署到跑通我花了不到两个小时。所以 Dify 解决的核心问题是把 AI 应用的开发门槛从“会写代码”降到“会配置”。它适合几类人——想快速验证 AI 产品想法的开发者、需要给业务部门搭 AI 工具的技术人员、想学习 RAG 和 Agent 到底怎么跑起来的学生或转行者以及不想在基础设施上浪费时间的独立开发者。1.2 Dify 和 Coze、ComfyUI 这些到底有什么区别热词里出现了 coze 工作流、comyui 工作流说明很多人会把它们放在一起比较。我实际都用过说一下区别。Coze 是字节跳动的产品偏向 C 端和轻量级 Bot 搭建托管在云端上手极快但你对底层数据的控制力弱而且它更偏向“做一个聊天机器人”。ComfyUI 是 Stable Diffusion 生态里的节点式工作流工具核心是图像生成节点编排逻辑和 Dify 类似但领域完全不同。Dify 的定位在两者之间——它比 Coze 更“工程化”支持本地部署、支持接自己的模型、支持复杂的 RAG 流水线它比 ComfyUI 更“通用”不局限于图像而是面向所有 LLM 应用场景。关键差异在于部署形态。Dify 可以完全跑在你自己的服务器上数据不出内网这对有数据合规要求的团队来说是刚需。Coze 这类云端产品做不到这一点。而 Dify 的工作流引擎支持条件分支、循环、代码节点、HTTP 请求节点复杂度和灵活性比大多数同类产品高一个档次。1.3 Dify 能做的四类核心事情我把 Dify 的能力归纳成四块这也是它的四个主要功能模块。第一块是聊天助手。最基础的形态你配好模型和提示词就能得到一个对话机器人。可以挂知识库让它基于你的文档回答。第二块是知识库RAG。上传文档Dify 自动做切分、向量化、存储然后检索时用语义相似度找到相关片段喂给模型。这是 Dify 用得最多的功能也是热词里 rag、rag 知识库、ontology rag 反复出现的原因。第三块是工作流。用节点编排的方式定义一套处理逻辑比如“接收用户输入 → 判断意图 → 如果是查询就走知识库检索 → 如果是计算就调代码节点 → 最后汇总输出”。工作流是 Dify 最强大的部分也是简历筛选工作流、动画工作流这类具体应用的基础。第四块是Agent。让模型自己决定调用哪些工具、按什么顺序调用。比如你给它一个“查天气”的工具和一个“发邮件”的工具它会根据用户问题自己判断先查天气再发邮件。Agent 和 workflow 的区别在于workflow 的路径是你定死的Agent 的路径是模型自己规划的。2. 安装部署从 Docker 到跑起来2.1 为什么 Dify 官方推荐 Docker 部署Dify 的架构不是单一服务它由 API 服务、Worker 服务、Web 前端、PostgreSQL、Redis、向量数据库默认 Weaviate、Nginx 等多个组件构成。手动一个个装光是版本兼容就能折腾半天。Docker Compose 把这些组件的镜像、网络、依赖关系全部定义好了一条命令拉起全部服务。热词里 docker、docker desktop、docker 安装教程、windows 安装 docker 出现频率极高说明很多人卡在 Docker 这一关。我先把 Docker 是什么说清楚Docker 是一个容器化工具它把应用和它需要的运行环境打包成一个“镜像”运行起来就是一个“容器”。你可以把它想象成一个轻量级的虚拟机但比虚拟机轻得多启动只要几秒。Docker Desktop 是 Windows 和 macOS 上的图形化 Docker 客户端装它就等于装好了 Docker 环境。注意Windows 上装 Docker Desktop 需要开启 WSL2Windows Subsystem for Linux 2。如果你用的是 Windows 10 家庭版WSL2 是支持的但需要手动开启。开启方法是在“启用或关闭 Windows 功能”里勾选“适用于 Linux 的 Windows 子系统”和“虚拟机平台”然后重启。2.2 Windows 环境下从零安装 Dify 的完整步骤我以 Windows 11 Docker Desktop 为例把每一步都写清楚。第一步安装 Docker Desktop。去 Docker 官网下载 Docker Desktop for Windows 的安装包。安装过程中会提示是否启用 WSL2勾选。安装完成后重启电脑。重启后打开 Docker Desktop等左下角变成绿色表示 Docker 引擎已启动。第二步验证 Docker 是否正常。打开 PowerShell 或 CMD输入docker --version docker compose version如果两条命令都能输出版本号说明 Docker 和 Docker Compose 都装好了。如果docker compose报错可能是版本太老需要更新 Docker Desktop。第三步下载 Dify 源码。在你想存放项目的目录下打开终端执行git clone https://github.com/langgenius/dify.git cd dify/docker如果你没有 git也可以直接去 GitHub 下载 zip 包解压。进入dify/docker目录后你会看到一个.env.example文件。第四步配置环境变量。把.env.example复制一份改名为.envcp .env.example .env默认配置基本够用但有几个地方建议改一下。EXPOSE_NGINX_PORT默认是 80如果你本机 80 端口被占用了比如装了 IIS 或其他 Web 服务改成 8080 或其他空闲端口。SECRET_KEY建议改成一个随机字符串这是用来加密会话的。第五步启动服务。在dify/docker目录下执行docker compose up -d-d表示后台运行。第一次执行会下载所有镜像大概需要几分钟到十几分钟取决于网速。下载完成后容器会自动启动。第六步验证。执行docker compose ps查看容器状态应该看到 api、worker、web、db、redis、weaviate、nginx 等容器都是 running 状态。然后浏览器打开http://localhost:8080如果你改了端口就用改后的能看到 Dify 的初始化页面说明部署成功。2.3 CentOS 7 上安装 Dify 的注意事项热词里有 centos7 安装 dify说明不少人在服务器环境部署。CentOS 7 的坑比 Windows 多一些我列几个关键的。CentOS 7 默认的 Docker 版本比较老建议先卸载旧版本再装新版本。安装命令sudo yum remove docker docker-client docker-client-latest docker-common docker-latest docker-latest-logrotate docker-logrotate docker-engine sudo yum install -y yum-utils sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin sudo systemctl start docker sudo systemctl enable dockerCentOS 7 的内核版本是 3.10某些新版本的 Docker 对它支持不好。如果遇到容器启动失败检查一下内核版本必要时升级内核。另外 CentOS 7 的防火墙默认是 firewalldDocker 会自己管理 iptables 规则有时候会和 firewalld 冲突导致端口不通。如果部署后访问不了先试试systemctl stop firewalld排除防火墙因素。还有一个常见问题是 SELinux。CentOS 7 默认开启 SELinuxDocker 挂载卷时可能被拦截。临时关闭用setenforce 0永久关闭改/etc/selinux/config里的SELINUXdisabled然后重启。2.4 安装过程中最常见的报错和排查方法热词里有一个很具体的报错dify an error occurred during credentials validation。这个通常出现在你配置模型供应商的时候比如接 OpenAI 或某个兼容接口填了 API Key 但验证不通过。原因一般有三个Key 本身不对或过期、API 地址填错了比如多加了/v1或少加了、网络不通导致请求发不出去。排查方法是先用 curl 直接测一下那个 API 地址能不能通排除网络因素后再检查 Key。另一个热词是dify ssl错误。这个多半出现在你给 Dify 配了 HTTPS 域名之后或者调用外部 API 时证书验证失败。如果是自签名证书需要在环境变量里加SSL_VERIFYfalse仅限内网测试环境。如果是 Lets Encrypt 证书过期重新签发即可。dify unstructured api url is not configured for doc file processing这个报错说明你上传了 Dify 默认解析器处理不了的文档格式比如某些 PDF 或 Word需要在.env里配置 Unstructured API 的地址。Unstructured 是一个文档解析服务Dify 用它来处理复杂格式的文档。你可以自己部署一个 Unstructured 服务也可以用云端版本。3. 核心功能拆解RAG、工作流、Agent 怎么用3.1 RAG 知识库从上传文档到精准回答RAG 是 Retrieval-Augmented Generation 的缩写中文叫“检索增强生成”。说人话就是模型本身不知道你的私有数据你先把文档存到一个能快速检索的地方用户提问时先检索出相关片段再把片段和问题一起喂给模型模型基于这些片段来回答。Dify 的知识库流程是这样的上传文档 → 文本切分 → 向量化 → 存入向量数据库 → 用户提问时检索 → 重排序 → 拼入提示词 → 模型生成回答。文本切分是第一个关键点。Dify 默认按固定长度切分比如每 500 个字符一段段之间重叠 50 个字符。重叠是为了避免一个完整的句子被切断导致语义丢失。但固定长度切分对结构化文档不友好比如一份产品手册按 500 字切可能把“参数表”和“注意事项”混在一起。我的经验是对于 FAQ 类文档按段落切分效果最好对于技术文档按标题层级切分对于对话记录按轮次切分。Dify 支持自定义切分规则在知识库设置里可以调。向量化是把文本转成一串数字向量语义相近的文本向量距离近。Dify 默认用 OpenAI 的 embedding 模型如果你用的是本地模型可以在模型供应商里配。这里有个坑embedding 模型和生成模型可以是不同的。比如你可以用本地的 bge-large 做 embedding用 GPT-4 做生成。但要注意embedding 模型换了之后之前入库的向量全部要重新生成因为不同模型的向量空间不兼容。检索环节Dify 支持三种模式向量检索、全文检索、混合检索。向量检索擅长语义匹配比如用户问“怎么退款”文档里写的是“如何申请退货”向量检索能匹配上。全文检索擅长关键词精确匹配比如用户搜一个产品型号“XR-500”全文检索能精确找到。混合检索是两者结合实际用下来效果最稳。我一般建议开启混合检索 重排序Rerank重排序模型会对检索结果做二次打分把最相关的排到前面。实操心得知识库的召回效果不好八成不是模型的问题而是切分和文档质量的问题。我踩过的坑是上传了一堆扫描版 PDFDify 解析出来全是乱码检索自然一塌糊涂。后来换成文字版 PDF 或者先用 OCR 处理一遍效果立刻上来了。另外文档里如果有大量表格建议单独处理成 Markdown 表格再上传Dify 对表格的解析能力有限。3.2 工作流把 AI 能力串成自动化流水线工作流是 Dify 最值得花时间学的部分。它的逻辑是你定义一系列节点每个节点做一件事节点之间用连线表示数据流向。用户输入从起点进入经过各个节点处理最后从终点输出。Dify 工作流的节点类型包括LLM 节点调用模型、知识库检索节点、代码节点执行 Python 或 Node.js 代码、HTTP 请求节点调外部 API、条件分支节点if-else、循环节点、变量聚合节点、模板转换节点等。我拿热词里的“简历筛选工作流”举个例子说明怎么串起来。起点接收一份简历文本。第一个节点是 LLM 节点提示词写“从以下简历中提取姓名、学历、工作年限、技能标签以 JSON 格式输出”。第二个节点是代码节点解析 JSON判断学历是否满足“本科及以上”、工作年限是否满足“3 年以上”。第三个节点是条件分支如果满足条件走“进入面试”分支不满足走“淘汰”分支。第四个节点是 HTTP 请求节点把结果推送到 HR 系统或发邮件通知。最后终点输出筛选结果。这套流程跑下来一份简历的处理时间大概 3-5 秒一天筛几百份简历完全没问题。关键是提示词要写清楚让模型输出的 JSON 格式稳定。我试过用 GPT-3.5 做提取偶尔会输出多余的解释文字导致 JSON 解析失败换成 GPT-4 或者加一个“只输出 JSON不要任何其他文字”的强约束就稳了。工作流还有一个高级用法是嵌套。你可以把一个工作流发布成工具然后在另一个工作流里调用它。比如你把“简历筛选”做成一个工具然后在“招聘管理”工作流里调用它。这样可以把复杂逻辑拆成模块维护起来方便。3.3 Agent让模型自己决定怎么干活Agent 和工作流的区别我用一个类比说明。工作流像是一条生产线每个工位做什么、按什么顺序做都是你提前定好的。Agent 像是一个项目经理你告诉他目标他自己决定先做什么后做什么、需要用什么工具。Dify 的 Agent 支持 ReAct 和 Function Calling 两种策略。ReAct 是让模型输出“思考-行动-观察”的循环Function Calling 是让模型直接输出要调用的函数和参数。Function Calling 更稳定因为格式是结构化的ReAct 更灵活但有时候会陷入循环。Agent 的核心是工具。Dify 内置了一些工具比如 Google 搜索、DALL-E 画图、Wolfram Alpha 计算。你也可以自定义工具比如把一个工作流发布成工具或者接一个 HTTP API 作为工具。我实际用 Agent 做过一个“竞品调研助手”。给它配了三个工具一个搜索工具搜竞品新闻、一个网页抓取工具抓竞品官网内容、一个总结工具把抓到的内容总结成报告。然后我只需要说“帮我调研一下 XX 产品最近的动态”它会自己搜索、抓取、总结最后输出一份报告。整个过程不需要我干预。但 Agent 有个现实问题并发能力。热词里有“ai agent 怎么扛并发”这是个真问题。Agent 的执行链路比普通对话长得多一次请求可能触发多次模型调用和工具调用耗时可能是普通对话的 5-10 倍。如果并发量上来模型 API 的速率限制和响应延迟会成为瓶颈。我的做法是给 Agent 加缓存——对于相同或相似的请求直接返回缓存结果另外把 Agent 的执行超时设短一点避免一个请求卡死拖垮整个服务。4. 从零跑通一个 RAG 问答助手的完整实操4.1 准备工作模型接入和知识库创建先解决模型接入。Dify 支持两种模型来源一是内置的模型供应商OpenAI、Anthropic、Azure OpenAI、通义千问等二是兼容 OpenAI 接口的自定义模型比如 Ollama 本地模型、vLLM 部署的模型。如果你用 Ollama 跑本地模型在 Dify 的“设置 → 模型供应商”里选“OpenAI-API-compatible”API Base URL 填http://host.docker.internal:11434/v1Windows/Mac 上 Docker 访问宿主机的地址API Key 随便填一个非空值模型名称填你在 Ollama 里拉下来的模型名比如qwen2:7b。填完点保存如果没报错就说明接上了。注意host.docker.internal在 Linux 上默认不可用需要加--add-hosthost.docker.internal:host-gateway参数启动容器或者在 docker-compose.yml 里加extra_hosts配置。知识库创建很简单在 Dify 左侧菜单点“知识库 → 创建知识库”上传文档。支持的文件格式包括 TXT、Markdown、PDF、Word、CSV 等。上传后选切分方式一般选“自动切分”就行特殊文档选“自定义”。然后选 embedding 模型点“保存并处理”等处理完成。4.2 搭建对话应用并挂载知识库在“工作室”里创建一个“聊天助手”应用。进入编排页面你会看到左侧是提示词编辑区右侧是调试窗口。提示词里最关键的是上下文变量。Dify 会自动把知识库检索结果注入到{{context}}变量里。你的提示词可以这样写你是一个专业的客服助手。请根据以下参考资料回答用户问题。 如果参考资料中没有相关信息请如实告知用户你不知道不要编造。 参考资料 {{context}} 用户问题{{query}}然后在“上下文”设置里添加你刚创建的知识库。可以设置召回数量比如 3 条和相似度阈值比如 0.5低于这个分数的片段不返回。调试窗口里输入问题看回答是否准确。如果回答不对先看检索到的片段是不是对的。Dify 调试时会把检索到的片段展示出来如果片段本身就不相关说明是检索问题如果片段相关但回答不对说明是提示词问题。4.3 发布应用并接入实际业务调试满意后点右上角“发布”。Dify 提供几种接入方式一是直接分享链接任何人打开就能用二是嵌入到网站复制一段 iframe 代码贴到你的网页里三是通过 API 调用Dify 提供 RESTful API你可以用自己的前端去调。API 调用的方式是在“访问 API”页面生成一个 API Key然后调POST /v1/chat-messages接口传query、user、conversation_id等参数。返回是流式的适合做打字机效果。如果你要接入企业微信、飞书、钉钉这类平台Dify 本身不直接支持但你可以用它的 API 做中间层自己写一个适配器。我做过一个飞书机器人逻辑是飞书收到消息 → 调 Dify API → 拿到回答 → 返回给飞书。整个适配器不到 100 行代码。5. 踩坑记录与常见问题速查5.1 部署类问题问题现象可能原因解决方法容器启动后访问不了端口被占用或防火墙拦截检查.env里的端口配置检查防火墙规则docker compose up卡在拉镜像网络问题配置国内镜像加速器或手动拉取镜像数据库连接失败PostgreSQL 容器未就绪等几分钟再试或查看 db 容器日志上传文档后处理失败文档格式不支持或解析服务未配检查文件格式配置 Unstructured APISSL 证书错误证书过期或自签名未信任更新证书或临时关闭 SSL 验证5.2 使用类问题知识库检索不准怎么办先看切分是否合理再看 embedding 模型是否适合中文bge 系列对中文支持好最后看是否需要加 Rerank 模型。如果文档里有大量专有名词建议在提示词里加一个术语表。工作流执行超时怎么办Dify 默认的工作流超时是 300 秒可以在.env里调WORKFLOW_MAX_EXECUTION_TIME。但更根本的是优化工作流本身——减少不必要的 LLM 调用把能并行的节点改成并行执行。Agent 一直循环调用工具怎么办在 Agent 设置里限制最大迭代次数一般设 5-10 次就够了。另外检查工具描述是否清晰描述模糊会导致模型不知道该用哪个工具。模型输出格式不稳定怎么办用 Function Calling 代替纯文本输出或者在提示词里加 few-shot 示例给出期望的输出格式样例。5.3 性能优化经验Dify 默认的向量数据库是 Weaviate单机跑没问题但如果知识库文档超过 10 万条检索速度会明显下降。这时候可以换成 Milvus 或 QdrantDify 支持切换向量库后端改.env里的VECTOR_STORE配置即可。模型调用是最大的延迟来源。如果用的是云端 API网络延迟占大头如果用的是本地模型GPU 推理速度是关键。我的做法是对高频问题做缓存Dify 本身不支持缓存但可以在前面加一层 Redis 做查询缓存。还有一个容易被忽略的点是日志和监控。Dify 的日志默认输出到容器标准输出用docker compose logs -f api可以看。生产环境建议接一个日志收集系统方便排查问题。Dify 也支持接入 LangSmith 或 Langfuse 做调用链追踪在.env里配一下就行。6. 我对 Dify 的一些真实看法Dify 不是万能的。它适合快速搭建和验证但如果你要做深度定制——比如自定义检索算法、特殊的对话管理逻辑、极致的性能优化——那 Dify 的抽象层反而会成为束缚。我一般建议先用 Dify 跑通 MVP验证需求成立后如果遇到性能或定制化瓶颈再把核心逻辑抽出来自己实现。另外 Dify 的版本迭代很快升级时要注意数据库迁移。我踩过一次坑直接docker compose pull拉了新镜像重启结果数据库 schema 不兼容服务起不来。后来学乖了升级前先备份数据库再看 release notes 里有没有 breaking change。最后说一个实际体会Dify 最大的价值不是它某个功能特别强而是它把 RAG、工作流、Agent 这些概念变成了可以动手操作的东西。你看再多文章讲 RAG 原理不如自己传一份文档、调一次检索参数、看一次召回结果来得直观。对于想入门 AI 应用开发的人来说Dify 是一个很好的练手平台。