1. 为什么推荐 Dify RAG从“大模型幻觉”聊起先说我踩过的一个坑。去年在做内部知识库问答时直接用 ChatGPT 一代的通用大模型接口把公司产品手册丢给它问“离职交接流程是什么”。它回答得一本正经每个步骤都有模有样但其中的审批人、系统名称全是错的。这就是典型的大模型幻觉Hallucination——模型不知道答案时会基于训练数据“编”一个看起来合理的答案。要解决这个问题业界常用的方案就是RAGRetrieval-Augmented Generation检索增强生成。它的思路很简单不让大模型凭空回答而是先从我们自己的知识库里检索出相关片段再把这些片段和用户问题一起交给大模型让它“看着资料回答”。这样答案有依据、可溯源准确率会明显提升。但 RAG 落地并不轻松。早期我尝试自己写用 Python 调 Embedding 接口、自己管理向量库、写检索逻辑、再拼 Prompt……整套流程涉及组件非常多文档切分策略、向量化模型、检索召回、重排序、Prompt 模板任何一个环节出问题效果都会打折扣。更麻烦的是普通业务同事根本没法用每次改知识文档都要找开发帮忙重新跑流程。后来我接触到了Dify。它是一个开源的大模型应用开发平台把 RAG 所需的功能做成了可视化操作上传文档、配置分段规则、选择 Embedding 模型、建立知识库索引、编排问答工作流都在同一个 Web 界面里完成。换句话说Dify 把 RAG 从“代码工程”降维成了“配置工程”让非技术背景的运营同学也能搭建自己的 AI 知识库问答系统。本文就是一期零基础的Dify RAG 入门实战目标是带大家从本地部署开始逐步搭建一个属于自己的企业级 AI 知识库与智能问答系统。你会掌握RAG 的核心原理和常见误区Dify 社区版的本地部署方法知识库创建、文档分段、索引配置的操作步骤基于知识库的应用编排方式工作流模式的进阶玩法生产环境落地时需要注意的工程细节无论你是后端开发、AI 应用开发新人还是只想给团队内部做个文档问答机器人这篇文章都值得收藏跟着做一遍。2. 核心概念先行RAG、知识库、Agent 与 Dify 的关系2.1 理解 RAG检索增强生成到底在做什么RAG 的核心过程可以拆成两个阶段、五个步骤离线索引阶段知识入库文档加载把 PDF、Word、Markdown、TXT 等格式的文档读入系统。文本分段把长文档切分成多个 chunk文本块比如按 500 字一段切分。向量化把每个文本块用 Embedding 模型转换成向量一组浮点数存入向量数据库。在线推理阶段问答检索4. 查询向量化用户提问时把问题也转换成向量。 5. 相似度检索在向量数据库中找出与问题向量最相似的几个文本块将它们拼入 Prompt让大模型基于这些文本块生成回答。整个过程可以用一张简单的 ASCII 图表示用户提问 │ ▼ 问题向量化 ──────► 向量数据库相似度检索 │ ▼ 返回 Top-K 相关文本片段 │ ▼ 将片段 用户问题 拼入 Prompt │ ▼ 大模型生成回答它和“微调Fine-tuning”的区别在于RAG 不需要重新训练模型只需要更新知识库内容而微调是改变模型本身的参数。两者可以互补但对于大多数企业内部知识库场景RAG 的性价比更高也更灵活。2.2 Dify 在 RAG 体系中承担什么角色Dify 不是一个单独的模型而是一个LLMOps 平台。它帮你把 RAG 流程中的各个环节封装成了可视化服务数据集Knowledge管理文档上传、分段、索引、检索测试。应用App支持聊天助手、Agent、文本生成、工作流等类型。模型管理集中配置 OpenAI、Azure OpenAI、国内大模型、自部署模型等各种模型 Provider。工作流Workflow通过画布拖拽节点编排复杂逻辑比如先检索、再重排、再判断是否需要追问等。所以Dify 和 RAG 的关系可以理解为RAG 是方法论Dify 是落地工具。2.3 Agentic RAG从“问答机器”到“主动思考”在最新的 RAG 演进中还有一个高频词叫Agentic RAG智能体检索增强生成。传统的 RAG 是“一次检索、一次生成”如果检索不到内容模型只能瞎编。Agentic RAG 则让系统具备“多轮决策”能力先尝试检索判断结果是否满足需求如果不够可以改写查询词、换一种检索策略如果某个问题不在知识库里再决定是调用外部工具还是直接说明不知道。Dify 的工作流和 Agent 功能正是实现 Agentic RAG 的很好载体。我们这篇文章先打好基础在后面的工作流环节会演示一个简化的“判断-反思-再回答”流程。3. 环境准备Docker 部署 Dify 社区版3.1 部署方案选型Dify 的部署方式主要有三种部署方式适用场景难度云服务Dify Cloud快速体验不关心运维低Docker Compose 自托管企业内部私有化、二次开发中Kubernetes Helm 部署生产集群、高可用高本教程推荐使用Docker Compose 方式部署社区版。它既能完整体验所有功能又能掌握部署细节后续上线生产也能平滑迁移。3.2 环境要求操作系统Linux / macOS / WindowsWindows 建议开启 WSL2Docker20.10 以上Docker Composev2 以上硬件建议最低 4 核 CPU、8GB 内存磁盘可用空间 50GB 以上主要是镜像和向量数据占用如果你机器配置偏低也可以只部署核心组件但建议完整安装避免后续因为缺少中间件出现奇怪问题。3.3 开始部署首先克隆 Dify 源码仓库并进入 docker 目录git clone https://github.com/langgenius/dify.git cd dify/docker复制环境变量模板cp .env.example .env然后启动容器docker compose up -d首次启动会拉取多个镜像包括 API 服务、Worker、PostgreSQL、Redis、Weaviate向量数据库等。等待时间取决于网络一般需要 5-15 分钟。查看容器状态docker compose ps当所有容器状态为running健康检查为 healthy时打开浏览器访问http://localhost默认端口是 80。如果 80 被占用可以在.env中修改EXPOSE_NGINX_PORT8080之类的配置。需要注意的是Dify 版本迭代很快不同版本的界面细节可能略有差异。本文以当前社区版常见界面为例重点是操作思路具体按钮名称可能在不同版本中略有变化。3.4 初始化管理员账号第一次访问会进入初始化页面需要设置管理员邮箱和密码。设置完成后用管理员账号登录控制台就能看到 Dify 的主界面。主界面左侧是功能区通常包含应用Studio知识库Knowledge工具工作流扩展模型供应商设置4. 配置模型供应商连接大模型与 Embedding 模型4.1 为什么要配两种模型在 Dify 中至少需要配置两类模型LLM大语言模型负责最终生成回答比如 GPT-4o、Claude、Qwen、DeepSeek 等。Embedding嵌入模型负责将文本转换成向量比如 OpenAI 的text-embedding-3-small、智源的bge-m3、Ollama 内置的nomic-embed-text等。两类模型缺一不可。没有 LLM 就无法问答没有 Embedding 就无法建知识库索引。4.2 以 DeepSeek 本地 Embedding 为例Dify 支持多种模型 Provider。这里以国内常用的DeepSeek为例打开“设置 → 模型供应商”。找到 DeepSeek点击“安装”或“添加模型”。填入 API Key选择模型名称如deepseek-chat保存。如果你希望 Embedding 也走国内模型也可以选智源、OpenAI、Ollama 等。其中的关键是API Key 要正确且网络能访问对应服务。如果你使用 Ollama 本地模型则需要先启动 Ollama 服务并拉取需要的模型ollama pull nomic-embed-text ollama pull qwen2.5:7b然后在 Dify 的 Ollama Provider 中填写 Ollama 服务地址例如http://host.docker.internal:11434和模型名。4.3 连接性验证配置完成后Dify 提供了一个测试入口。在模型供应商页面点击“测试”如果显示连接成功说明模型配置没有问题。否则需要检查API Key 是否有效是否有余额网络是否能连通目标服务如果是自部署模型容器网络是否能访问到模型服务地址5. RAG 原理拆解从文档上传到检索回答的完整链路5.1 文档加载与格式支持Dify 知识库支持多种文档格式包括 PDF、DOCX、Markdown、TXT、HTML 等。上传后 Dify 会调用内置的文档解析器把文件内容提取成纯文本再进行后续处理。这里有一个实际经验PDF 文件的文字层质量很重要。如果 PDF 是扫描件图片型 PDFDify 默认无法直接提取文字需要先经过 OCR 处理。建议尽量避免直接用扫描件测试知识库效果。5.2 分段Chunking策略分段是 RAG 中最影响效果的一环。Dify 提供了两种分段模式通用分段按固定长度切分可设置最大分段长度如 500 tokens以及分段重叠长度如 50 tokens。父子分段先切出较大的父级段落再从父级中细分出子级段落检索时命中子级段落但拿去喂给模型的是父级段落。这种方式适合需要上下文连贯性的文档。分段参数中比较重要的是参数含义经验值最大分段长度每个 chunk 的最大 token 数300-500分段重叠长度相邻 chunk 重叠的 token 数20-50分隔符切分时优先考虑的字符段落、句号、换行符为什么需要重叠因为如果一段文档正好在“句子的中间”被切开前后两个 chunk 都会丢失上下文。重叠可以让边界信息在相邻 chunk 中重复出现从而减少信息丢失。5.3 索引方式高质量模式 vs 经济模式Dify 提供两种索引方式高质量模式使用 Embedding 模型生成向量语义检索效果好但消耗 token。经济模式使用关键词索引不消耗 Embedding token但语义理解能力弱适合资源受限场景。实际项目中优先选择高质量模式。经济模式检索容易出“一字不差才能命中”的问题效果通常不够理想。5.4 检索设置召回策略与 Top-K在知识库关联到应用后可以设置检索策略。Dify 常见的有向量检索直接计算查询向量与文档向量的余弦相似度。全文检索基于关键词的倒排索引检索。混合检索Hybrid Search同时执行向量检索和全文检索并融合排序结果效果更好。Rerank 重排检索出的结果先用轻量模型重新打分排序把最相关结果排在前面。这个对回答质量提升非常明显。Top-K 表示召回几个文本片段一般设置为 3-5 比较合适。K 值太大会引入不相关内容太小则可能漏掉关键信息。6. 完整实战从零搭建企业知识库与智能问答系统6.1 第 1 步创建知识库在 Dify 左侧菜单点击“知识库”进入后选择“创建知识库”。填写知识库名称与描述然后上传文档。假设我们上传一份公司《员工手册》Markdown 文件内容包括入职流程、考勤规则、请假审批、报销制度等。6.2 第 2 步配置分段与索引上传完成后Dify 会进入文档设置页面。这里我们可以选择分段模式为“通用分段”设置最大分段长度为 500Tokens设置分段重叠长度为 50Tokens索引方式选择“高质量”选择 Embedding 模型并保存。保存后Dify 会开始索引构建。构建完成后知识点列表会显示每个分段的数量和状态。这里建议先点“召回测试”看一下效果。输入一个测试问题比如“新员工入职需要准备什么材料”观察检索到的文本片段是否确实包含答案。如果检索结果很偏说明分段策略需要调整。6.3 第 3 步创建聊天助手应用回到“应用”页面点击“创建应用”选择“聊天助手”。应用名称可设为“内部知识问答助手”。在应用编排界面需要做两件事在“上下文”中选择刚创建的知识库。在“提示词”中说明系统角色和回答要求。提示词参考你是公司的智能知识助手请基于提供的知识库内容回答用户问题。如果知识库中没有相关信息请明确回答知识库中暂无相关内容不要编造答案。回答时尽量引用知识库原文并在最后附上参考来源。保存后点击右上角“预览”就能在调试面板中和知识库进行对话了。6.4 第 4 步验证效果我们来做一个简单测试问题“如何申请年假”预期回答应该包含《员工手册》中关于年假申请流程的内容并且语气、结构自然。再问“公司楼下便利店几点关门”预期回答知识库中没有相关信息模型应拒绝回答或说明“知识库中暂无相关内容”而不是胡乱编造。如果第二个问题模型没有正确拒绝就说明 Prompt 中的“不要编造答案”约束还不够强可以考虑调整提示词或加入“置信度阈值”判断逻辑。6.5 第 5 步发布为 Web 应用或 API调试满意后点击“发布”。Dify 支持将应用发布为WebApp生成一个可分享的网页链接API 服务通过 REST API 调用嵌入网页生成 iframe 嵌入代码企业场景中通常是把 API 接入企业微信、钉钉、飞书或者自己公司内部的系统。这样团队成员就能通过常用聊天工具直接提问。7. 进阶实战用工作流编排一个更聪明的问答助手7.1 为什么需要工作流基础聊天助手是“拿到问题就去知识库检索然后生成回答”。但当用户问题不明确、需要多步判断时这种线性流程就不够用了。举例来说用户问“报销有什么规定”知识库里有多个文档都提到报销但侧重点不同用户先问 A再问 B但两个问题之间存在上下文关系某些问题需要调用外部工具比如查天气、查数据库才能回答。这时可以用 Dify 的工作流Workflow功能把流程编排成更丰富的结构。7.2 工作流节点设计以下是一个简化版 Agentic RAG 工作流开始 │ ▼ 问题理解LLM 节点判断是否需要知识库检索 │ ├── 需要检索 ──► 知识库检索节点 │ │ │ ▼ │ 判断检索结果置信度 │ │ │ ┌──────────┴──────────┐ │ ▼ ▼ │ 结果充足 结果不足 │ │ │ │ ▼ ▼ │ 生成最终回答 改写问题、再次检索 │ │ │ │ ▼ ▼ └── 不需要检索 ──► 直接回答 生成兜底话术在 Dify 工作流画布中我们可以拖出这些节点开始节点接收用户输入。LLM 节点第一个 LLM 节点负责分类意图输出 JSON。知识检索节点根据分类结果执行检索。条件分支节点判断检索到的分段数量或分数。代码节点可选对检索结果做后处理。LLM 生成节点生成最终回答。结束节点输出结果。7.3 工作流关键配置说明在“知识检索”节点中选择知识库并设置参数{ retrieval_mode: hybrid, top_k: 5, score_threshold: 0.5, rerank_enabled: true }在“条件分支”中判断检索结果数是否大于 0。如果检索到内容就进入回答分支如果没有检索到内容就进入兜底分支。这种编排的意义在于系统不再“无脑回答”而是先判断自己有没有能力回答再决定执行路径。这正是 Agentic RAG 的雏形。8. 常见问题与排查思路在实际使用 Dify RAG 的过程中下面这些问题出现频率非常高。我整理成一份排查表问题现象常见原因解决思路部署后页面打不开端口被占用或容器未完全启动检查docker compose ps各容器状态查看 nginx 容器日志配置模型后测试失败API Key 错误、网络不通、余额不足先用 curl 直接调用模型接口判断是 Provider 问题还是 Dify 配置问题知识库“召回测试”结果为空文档解析失败、分段不合理、Embedding 模型未配置检查文档是否包含可提取文字切换分段模式重新保存索引回答质量差答非所问Top-K 太小或太大、检索设定不合理、Prompt 不清晰调整 Top-K 至 3-5开启混合检索和 Rerank优化提示词模型拒绝回答但知识库有答案Prompt 约束过强或检索结果不包含关键内容调整提示词加入“请优先从知识库中寻找答案”优化分段策略上传文档后一直“索引中”文档过大、Embedding 接口过慢、任务队列阻塞将文档拆分成多个较小文件重新上传检查 Worker 容器日志在线预览正常但 API 调用报错API Key 权限问题、请求参数错误确认在 API 管理中创建了 API 密钥并对照官方 API 文档检查请求体修改知识库文档后问答结果不变索引未重新构建或缓存生效滞后编辑文档后点击“重新索引”按钮等待索引任务完成再测试多人同时使用速度很慢模型 QPS 限制、向量检索慢、容器资源配置不足配置模型限流策略升级服务器配置对高并发场景引入缓存排查问题时建议养成一个习惯先看容器日志再查模型连通性最后查知识库索引状态。# 查看 Dify API 容器日志 docker compose logs api --tail200 # 查看 Worker 容器日志文档索引任务相关 docker compose logs worker --tail200 # 查看容器资源占用 docker stats9. 最佳实践与工程化建议9.1 知识库内容治理RAG 的效果上限很大程度上由知识库内容质量决定。建议按照以下原则管理文档文档格式统一尽量使用 Markdown 或结构化文本避免扫描版 PDF。一段一个主题写文档时一个段落只表达一个核心意思方便 Dify 分段后保持语义完整。定期更新员工手册、流程文档会持续变化要建立文档更新机制每次更新后重新索引。删除无关内容知识库不是文件服务器不要把无关的图片、代码日志、临时记录传进去。9.2 检索优化清单当问答效果不理想时按以下顺序检查召回设置是否开启混合检索是否开启 RerankTop-K 是否合理分段设置分段长度是否合适是否需要开启父子分段Prompt 设置是否明确告诉模型“只基于知识库内容回答”模型选择是否用了较强的 LLM部分简单问题用大模型和用轻量模型都可以但复杂推理问题要选择更强的模型。知识库结构是否需要拆分成多个知识库并在工作流中做路由选择9.3 安全与权限企业知识库往往包含内部敏感信息。上线生产时需要重点考虑访问控制Dify 应用要配置访问密钥不要将 WebApp 链接直接公开。最小权限原则不同团队的知识库应互相隔离避免越权访问。Prompt 注入防护用户可能通过输入“忽略之前的指令”等方式试图绕过限制工作流中要加入输入校验或异常输入处理。日志审计记录所有问答请求和模型响应方便事后追溯。9.4 监控与成本控制设置模型调用限额避免某个用户刷爆 Token 配额。监控 Embedding token 消耗文档重新索引时会产生额外费用。定期清理长期不用的知识库和测试应用。在高并发场景下为模型接口配置限流。9.5 版本升级与备份Dify 社区版迭代快升级前要备份数据库。Dify 的 PostgreSQL 中存储了用户、知识库、应用配置等关键数据建议在升级前执行备份docker compose exec db pg_dump -U postgres dify dify_backup_$(date %Y%m%d).sql升级时先拉取新代码再重建容器git pull docker compose up -d升级后如遇异常可通过备份数据回滚。10. 总结与下一步学习建议本文从 RAG 的基础原理出发走了一遍 Dify 从零部署到知识库问答系统上线的完整流程。掌握了这些内容之后你已经能够理解 RAG 的索引与检索链路不再把 Dify 当作“黑盒”使用自己部署 Dify 社区版并完成模型配置创建高质量知识库合理配置分段和索引参数编排聊天助手和工作流实现带判断能力的问答系统遇到常见问题时有自己的排查思路。下一步可以沿着几个方向继续深入学习 Dify 中的Agent 节点让助手具备调用外部 API 的能力研究Agentic RAG在工作流中引入多轮反思与工具调用尝试接入企业微信、钉钉、飞书机器人让知识库助手真正进入日常办公对比不同向量数据库Weaviate、Qdrant、Milvus的检索性能如果对底层感兴趣可以读 Dify 源码中 knowledge 模块的检索实现理解 Rerank 的接入逻辑。技术学习最忌讳只看不练。建议你现在就部署一个 Dify 实例上传一份自己的技术笔记或项目文档实际体验一下“问它一个问题它看着你的资料回答”的完整过程。遇到问题不要慌对照本文第 8 节的排查表基本能覆盖大部分场景。如果这篇文章对你有帮助建议收藏备用。下一期可以继续聊聊如何把知识库问答接入企业微信机器人或者深入讲一讲 Rerank 模型的选型与调优。 Dify + RAG 实战：从零搭建企业知识库智能问答系统
1. 为什么推荐 Dify RAG从“大模型幻觉”聊起先说我踩过的一个坑。去年在做内部知识库问答时直接用 ChatGPT 一代的通用大模型接口把公司产品手册丢给它问“离职交接流程是什么”。它回答得一本正经每个步骤都有模有样但其中的审批人、系统名称全是错的。这就是典型的大模型幻觉Hallucination——模型不知道答案时会基于训练数据“编”一个看起来合理的答案。要解决这个问题业界常用的方案就是RAGRetrieval-Augmented Generation检索增强生成。它的思路很简单不让大模型凭空回答而是先从我们自己的知识库里检索出相关片段再把这些片段和用户问题一起交给大模型让它“看着资料回答”。这样答案有依据、可溯源准确率会明显提升。但 RAG 落地并不轻松。早期我尝试自己写用 Python 调 Embedding 接口、自己管理向量库、写检索逻辑、再拼 Prompt……整套流程涉及组件非常多文档切分策略、向量化模型、检索召回、重排序、Prompt 模板任何一个环节出问题效果都会打折扣。更麻烦的是普通业务同事根本没法用每次改知识文档都要找开发帮忙重新跑流程。后来我接触到了Dify。它是一个开源的大模型应用开发平台把 RAG 所需的功能做成了可视化操作上传文档、配置分段规则、选择 Embedding 模型、建立知识库索引、编排问答工作流都在同一个 Web 界面里完成。换句话说Dify 把 RAG 从“代码工程”降维成了“配置工程”让非技术背景的运营同学也能搭建自己的 AI 知识库问答系统。本文就是一期零基础的Dify RAG 入门实战目标是带大家从本地部署开始逐步搭建一个属于自己的企业级 AI 知识库与智能问答系统。你会掌握RAG 的核心原理和常见误区Dify 社区版的本地部署方法知识库创建、文档分段、索引配置的操作步骤基于知识库的应用编排方式工作流模式的进阶玩法生产环境落地时需要注意的工程细节无论你是后端开发、AI 应用开发新人还是只想给团队内部做个文档问答机器人这篇文章都值得收藏跟着做一遍。2. 核心概念先行RAG、知识库、Agent 与 Dify 的关系2.1 理解 RAG检索增强生成到底在做什么RAG 的核心过程可以拆成两个阶段、五个步骤离线索引阶段知识入库文档加载把 PDF、Word、Markdown、TXT 等格式的文档读入系统。文本分段把长文档切分成多个 chunk文本块比如按 500 字一段切分。向量化把每个文本块用 Embedding 模型转换成向量一组浮点数存入向量数据库。在线推理阶段问答检索4. 查询向量化用户提问时把问题也转换成向量。 5. 相似度检索在向量数据库中找出与问题向量最相似的几个文本块将它们拼入 Prompt让大模型基于这些文本块生成回答。整个过程可以用一张简单的 ASCII 图表示用户提问 │ ▼ 问题向量化 ──────► 向量数据库相似度检索 │ ▼ 返回 Top-K 相关文本片段 │ ▼ 将片段 用户问题 拼入 Prompt │ ▼ 大模型生成回答它和“微调Fine-tuning”的区别在于RAG 不需要重新训练模型只需要更新知识库内容而微调是改变模型本身的参数。两者可以互补但对于大多数企业内部知识库场景RAG 的性价比更高也更灵活。2.2 Dify 在 RAG 体系中承担什么角色Dify 不是一个单独的模型而是一个LLMOps 平台。它帮你把 RAG 流程中的各个环节封装成了可视化服务数据集Knowledge管理文档上传、分段、索引、检索测试。应用App支持聊天助手、Agent、文本生成、工作流等类型。模型管理集中配置 OpenAI、Azure OpenAI、国内大模型、自部署模型等各种模型 Provider。工作流Workflow通过画布拖拽节点编排复杂逻辑比如先检索、再重排、再判断是否需要追问等。所以Dify 和 RAG 的关系可以理解为RAG 是方法论Dify 是落地工具。2.3 Agentic RAG从“问答机器”到“主动思考”在最新的 RAG 演进中还有一个高频词叫Agentic RAG智能体检索增强生成。传统的 RAG 是“一次检索、一次生成”如果检索不到内容模型只能瞎编。Agentic RAG 则让系统具备“多轮决策”能力先尝试检索判断结果是否满足需求如果不够可以改写查询词、换一种检索策略如果某个问题不在知识库里再决定是调用外部工具还是直接说明不知道。Dify 的工作流和 Agent 功能正是实现 Agentic RAG 的很好载体。我们这篇文章先打好基础在后面的工作流环节会演示一个简化的“判断-反思-再回答”流程。3. 环境准备Docker 部署 Dify 社区版3.1 部署方案选型Dify 的部署方式主要有三种部署方式适用场景难度云服务Dify Cloud快速体验不关心运维低Docker Compose 自托管企业内部私有化、二次开发中Kubernetes Helm 部署生产集群、高可用高本教程推荐使用Docker Compose 方式部署社区版。它既能完整体验所有功能又能掌握部署细节后续上线生产也能平滑迁移。3.2 环境要求操作系统Linux / macOS / WindowsWindows 建议开启 WSL2Docker20.10 以上Docker Composev2 以上硬件建议最低 4 核 CPU、8GB 内存磁盘可用空间 50GB 以上主要是镜像和向量数据占用如果你机器配置偏低也可以只部署核心组件但建议完整安装避免后续因为缺少中间件出现奇怪问题。3.3 开始部署首先克隆 Dify 源码仓库并进入 docker 目录git clone https://github.com/langgenius/dify.git cd dify/docker复制环境变量模板cp .env.example .env然后启动容器docker compose up -d首次启动会拉取多个镜像包括 API 服务、Worker、PostgreSQL、Redis、Weaviate向量数据库等。等待时间取决于网络一般需要 5-15 分钟。查看容器状态docker compose ps当所有容器状态为running健康检查为 healthy时打开浏览器访问http://localhost默认端口是 80。如果 80 被占用可以在.env中修改EXPOSE_NGINX_PORT8080之类的配置。需要注意的是Dify 版本迭代很快不同版本的界面细节可能略有差异。本文以当前社区版常见界面为例重点是操作思路具体按钮名称可能在不同版本中略有变化。3.4 初始化管理员账号第一次访问会进入初始化页面需要设置管理员邮箱和密码。设置完成后用管理员账号登录控制台就能看到 Dify 的主界面。主界面左侧是功能区通常包含应用Studio知识库Knowledge工具工作流扩展模型供应商设置4. 配置模型供应商连接大模型与 Embedding 模型4.1 为什么要配两种模型在 Dify 中至少需要配置两类模型LLM大语言模型负责最终生成回答比如 GPT-4o、Claude、Qwen、DeepSeek 等。Embedding嵌入模型负责将文本转换成向量比如 OpenAI 的text-embedding-3-small、智源的bge-m3、Ollama 内置的nomic-embed-text等。两类模型缺一不可。没有 LLM 就无法问答没有 Embedding 就无法建知识库索引。4.2 以 DeepSeek 本地 Embedding 为例Dify 支持多种模型 Provider。这里以国内常用的DeepSeek为例打开“设置 → 模型供应商”。找到 DeepSeek点击“安装”或“添加模型”。填入 API Key选择模型名称如deepseek-chat保存。如果你希望 Embedding 也走国内模型也可以选智源、OpenAI、Ollama 等。其中的关键是API Key 要正确且网络能访问对应服务。如果你使用 Ollama 本地模型则需要先启动 Ollama 服务并拉取需要的模型ollama pull nomic-embed-text ollama pull qwen2.5:7b然后在 Dify 的 Ollama Provider 中填写 Ollama 服务地址例如http://host.docker.internal:11434和模型名。4.3 连接性验证配置完成后Dify 提供了一个测试入口。在模型供应商页面点击“测试”如果显示连接成功说明模型配置没有问题。否则需要检查API Key 是否有效是否有余额网络是否能连通目标服务如果是自部署模型容器网络是否能访问到模型服务地址5. RAG 原理拆解从文档上传到检索回答的完整链路5.1 文档加载与格式支持Dify 知识库支持多种文档格式包括 PDF、DOCX、Markdown、TXT、HTML 等。上传后 Dify 会调用内置的文档解析器把文件内容提取成纯文本再进行后续处理。这里有一个实际经验PDF 文件的文字层质量很重要。如果 PDF 是扫描件图片型 PDFDify 默认无法直接提取文字需要先经过 OCR 处理。建议尽量避免直接用扫描件测试知识库效果。5.2 分段Chunking策略分段是 RAG 中最影响效果的一环。Dify 提供了两种分段模式通用分段按固定长度切分可设置最大分段长度如 500 tokens以及分段重叠长度如 50 tokens。父子分段先切出较大的父级段落再从父级中细分出子级段落检索时命中子级段落但拿去喂给模型的是父级段落。这种方式适合需要上下文连贯性的文档。分段参数中比较重要的是参数含义经验值最大分段长度每个 chunk 的最大 token 数300-500分段重叠长度相邻 chunk 重叠的 token 数20-50分隔符切分时优先考虑的字符段落、句号、换行符为什么需要重叠因为如果一段文档正好在“句子的中间”被切开前后两个 chunk 都会丢失上下文。重叠可以让边界信息在相邻 chunk 中重复出现从而减少信息丢失。5.3 索引方式高质量模式 vs 经济模式Dify 提供两种索引方式高质量模式使用 Embedding 模型生成向量语义检索效果好但消耗 token。经济模式使用关键词索引不消耗 Embedding token但语义理解能力弱适合资源受限场景。实际项目中优先选择高质量模式。经济模式检索容易出“一字不差才能命中”的问题效果通常不够理想。5.4 检索设置召回策略与 Top-K在知识库关联到应用后可以设置检索策略。Dify 常见的有向量检索直接计算查询向量与文档向量的余弦相似度。全文检索基于关键词的倒排索引检索。混合检索Hybrid Search同时执行向量检索和全文检索并融合排序结果效果更好。Rerank 重排检索出的结果先用轻量模型重新打分排序把最相关结果排在前面。这个对回答质量提升非常明显。Top-K 表示召回几个文本片段一般设置为 3-5 比较合适。K 值太大会引入不相关内容太小则可能漏掉关键信息。6. 完整实战从零搭建企业知识库与智能问答系统6.1 第 1 步创建知识库在 Dify 左侧菜单点击“知识库”进入后选择“创建知识库”。填写知识库名称与描述然后上传文档。假设我们上传一份公司《员工手册》Markdown 文件内容包括入职流程、考勤规则、请假审批、报销制度等。6.2 第 2 步配置分段与索引上传完成后Dify 会进入文档设置页面。这里我们可以选择分段模式为“通用分段”设置最大分段长度为 500Tokens设置分段重叠长度为 50Tokens索引方式选择“高质量”选择 Embedding 模型并保存。保存后Dify 会开始索引构建。构建完成后知识点列表会显示每个分段的数量和状态。这里建议先点“召回测试”看一下效果。输入一个测试问题比如“新员工入职需要准备什么材料”观察检索到的文本片段是否确实包含答案。如果检索结果很偏说明分段策略需要调整。6.3 第 3 步创建聊天助手应用回到“应用”页面点击“创建应用”选择“聊天助手”。应用名称可设为“内部知识问答助手”。在应用编排界面需要做两件事在“上下文”中选择刚创建的知识库。在“提示词”中说明系统角色和回答要求。提示词参考你是公司的智能知识助手请基于提供的知识库内容回答用户问题。如果知识库中没有相关信息请明确回答知识库中暂无相关内容不要编造答案。回答时尽量引用知识库原文并在最后附上参考来源。保存后点击右上角“预览”就能在调试面板中和知识库进行对话了。6.4 第 4 步验证效果我们来做一个简单测试问题“如何申请年假”预期回答应该包含《员工手册》中关于年假申请流程的内容并且语气、结构自然。再问“公司楼下便利店几点关门”预期回答知识库中没有相关信息模型应拒绝回答或说明“知识库中暂无相关内容”而不是胡乱编造。如果第二个问题模型没有正确拒绝就说明 Prompt 中的“不要编造答案”约束还不够强可以考虑调整提示词或加入“置信度阈值”判断逻辑。6.5 第 5 步发布为 Web 应用或 API调试满意后点击“发布”。Dify 支持将应用发布为WebApp生成一个可分享的网页链接API 服务通过 REST API 调用嵌入网页生成 iframe 嵌入代码企业场景中通常是把 API 接入企业微信、钉钉、飞书或者自己公司内部的系统。这样团队成员就能通过常用聊天工具直接提问。7. 进阶实战用工作流编排一个更聪明的问答助手7.1 为什么需要工作流基础聊天助手是“拿到问题就去知识库检索然后生成回答”。但当用户问题不明确、需要多步判断时这种线性流程就不够用了。举例来说用户问“报销有什么规定”知识库里有多个文档都提到报销但侧重点不同用户先问 A再问 B但两个问题之间存在上下文关系某些问题需要调用外部工具比如查天气、查数据库才能回答。这时可以用 Dify 的工作流Workflow功能把流程编排成更丰富的结构。7.2 工作流节点设计以下是一个简化版 Agentic RAG 工作流开始 │ ▼ 问题理解LLM 节点判断是否需要知识库检索 │ ├── 需要检索 ──► 知识库检索节点 │ │ │ ▼ │ 判断检索结果置信度 │ │ │ ┌──────────┴──────────┐ │ ▼ ▼ │ 结果充足 结果不足 │ │ │ │ ▼ ▼ │ 生成最终回答 改写问题、再次检索 │ │ │ │ ▼ ▼ └── 不需要检索 ──► 直接回答 生成兜底话术在 Dify 工作流画布中我们可以拖出这些节点开始节点接收用户输入。LLM 节点第一个 LLM 节点负责分类意图输出 JSON。知识检索节点根据分类结果执行检索。条件分支节点判断检索到的分段数量或分数。代码节点可选对检索结果做后处理。LLM 生成节点生成最终回答。结束节点输出结果。7.3 工作流关键配置说明在“知识检索”节点中选择知识库并设置参数{ retrieval_mode: hybrid, top_k: 5, score_threshold: 0.5, rerank_enabled: true }在“条件分支”中判断检索结果数是否大于 0。如果检索到内容就进入回答分支如果没有检索到内容就进入兜底分支。这种编排的意义在于系统不再“无脑回答”而是先判断自己有没有能力回答再决定执行路径。这正是 Agentic RAG 的雏形。8. 常见问题与排查思路在实际使用 Dify RAG 的过程中下面这些问题出现频率非常高。我整理成一份排查表问题现象常见原因解决思路部署后页面打不开端口被占用或容器未完全启动检查docker compose ps各容器状态查看 nginx 容器日志配置模型后测试失败API Key 错误、网络不通、余额不足先用 curl 直接调用模型接口判断是 Provider 问题还是 Dify 配置问题知识库“召回测试”结果为空文档解析失败、分段不合理、Embedding 模型未配置检查文档是否包含可提取文字切换分段模式重新保存索引回答质量差答非所问Top-K 太小或太大、检索设定不合理、Prompt 不清晰调整 Top-K 至 3-5开启混合检索和 Rerank优化提示词模型拒绝回答但知识库有答案Prompt 约束过强或检索结果不包含关键内容调整提示词加入“请优先从知识库中寻找答案”优化分段策略上传文档后一直“索引中”文档过大、Embedding 接口过慢、任务队列阻塞将文档拆分成多个较小文件重新上传检查 Worker 容器日志在线预览正常但 API 调用报错API Key 权限问题、请求参数错误确认在 API 管理中创建了 API 密钥并对照官方 API 文档检查请求体修改知识库文档后问答结果不变索引未重新构建或缓存生效滞后编辑文档后点击“重新索引”按钮等待索引任务完成再测试多人同时使用速度很慢模型 QPS 限制、向量检索慢、容器资源配置不足配置模型限流策略升级服务器配置对高并发场景引入缓存排查问题时建议养成一个习惯先看容器日志再查模型连通性最后查知识库索引状态。# 查看 Dify API 容器日志 docker compose logs api --tail200 # 查看 Worker 容器日志文档索引任务相关 docker compose logs worker --tail200 # 查看容器资源占用 docker stats9. 最佳实践与工程化建议9.1 知识库内容治理RAG 的效果上限很大程度上由知识库内容质量决定。建议按照以下原则管理文档文档格式统一尽量使用 Markdown 或结构化文本避免扫描版 PDF。一段一个主题写文档时一个段落只表达一个核心意思方便 Dify 分段后保持语义完整。定期更新员工手册、流程文档会持续变化要建立文档更新机制每次更新后重新索引。删除无关内容知识库不是文件服务器不要把无关的图片、代码日志、临时记录传进去。9.2 检索优化清单当问答效果不理想时按以下顺序检查召回设置是否开启混合检索是否开启 RerankTop-K 是否合理分段设置分段长度是否合适是否需要开启父子分段Prompt 设置是否明确告诉模型“只基于知识库内容回答”模型选择是否用了较强的 LLM部分简单问题用大模型和用轻量模型都可以但复杂推理问题要选择更强的模型。知识库结构是否需要拆分成多个知识库并在工作流中做路由选择9.3 安全与权限企业知识库往往包含内部敏感信息。上线生产时需要重点考虑访问控制Dify 应用要配置访问密钥不要将 WebApp 链接直接公开。最小权限原则不同团队的知识库应互相隔离避免越权访问。Prompt 注入防护用户可能通过输入“忽略之前的指令”等方式试图绕过限制工作流中要加入输入校验或异常输入处理。日志审计记录所有问答请求和模型响应方便事后追溯。9.4 监控与成本控制设置模型调用限额避免某个用户刷爆 Token 配额。监控 Embedding token 消耗文档重新索引时会产生额外费用。定期清理长期不用的知识库和测试应用。在高并发场景下为模型接口配置限流。9.5 版本升级与备份Dify 社区版迭代快升级前要备份数据库。Dify 的 PostgreSQL 中存储了用户、知识库、应用配置等关键数据建议在升级前执行备份docker compose exec db pg_dump -U postgres dify dify_backup_$(date %Y%m%d).sql升级时先拉取新代码再重建容器git pull docker compose up -d升级后如遇异常可通过备份数据回滚。10. 总结与下一步学习建议本文从 RAG 的基础原理出发走了一遍 Dify 从零部署到知识库问答系统上线的完整流程。掌握了这些内容之后你已经能够理解 RAG 的索引与检索链路不再把 Dify 当作“黑盒”使用自己部署 Dify 社区版并完成模型配置创建高质量知识库合理配置分段和索引参数编排聊天助手和工作流实现带判断能力的问答系统遇到常见问题时有自己的排查思路。下一步可以沿着几个方向继续深入学习 Dify 中的Agent 节点让助手具备调用外部 API 的能力研究Agentic RAG在工作流中引入多轮反思与工具调用尝试接入企业微信、钉钉、飞书机器人让知识库助手真正进入日常办公对比不同向量数据库Weaviate、Qdrant、Milvus的检索性能如果对底层感兴趣可以读 Dify 源码中 knowledge 模块的检索实现理解 Rerank 的接入逻辑。技术学习最忌讳只看不练。建议你现在就部署一个 Dify 实例上传一份自己的技术笔记或项目文档实际体验一下“问它一个问题它看着你的资料回答”的完整过程。遇到问题不要慌对照本文第 8 节的排查表基本能覆盖大部分场景。如果这篇文章对你有帮助建议收藏备用。下一期可以继续聊聊如何把知识库问答接入企业微信机器人或者深入讲一讲 Rerank 模型的选型与调优。