1. 为什么 Dify 被越来越多团队当成 AI 应用底座过去一年里大模型应用落地的方式发生了很明显的变化。早期很多团队是直接调 OpenAI 或国产大模型的 API把 key 写在代码里prompt 靠程序拼接文档检索自己写向量库逻辑流程编排全靠代码堆。但这种做法在真正做产品时会遇到几个绕不开的问题模型切换成本高、提示词反复改要重新发版、知识库和对话逻辑耦合太深、给非技术同事演示时全靠开发人员操作。Dify 这类 LLMOps 平台解决的就是这些问题。Dify 是一个开源的大模型应用开发平台核心定位是让开发者用可视化方式编排 Agent、工作流和 RAG 知识库应用同时保留 API 接入能力。它不是一个简单的聊天框封装而是把模型管理、提示词管理、知识库、工具调用、日志观测、数据集标注这些环节统一到一个平台里。你可以把它理解为面向 LLM 应用的“后端低代码平台”复杂逻辑用工作流画出来模型统一接入知识库可视化管理最终通过 API 或网页嵌入对外提供服务。这篇文章会围绕一个相对完整的实战链路展开用 Docker 完成 Dify 私有化部署接入本地或云端大模型搭建一个基于 RAG 的知识库创建一个带有工具调用能力的 Agent示例场景选择三角洲游戏攻略问答 Agent最后把应用嵌入到网页里。对于正在做 AI 应用选型、或者想在企业内部搭建私有化大模型平台的团队来说这套流程可以作为直接参考的落地路径。2. 环境准备与 Docker 部署2.1 部署前需要确认的环境在开始之前先明确一下整套环境需要什么。Dify 本身是前后端分离的项目后端使用 Python Flask 框架前端是 Next.js数据库使用 PostgreSQL缓存使用 Redis向量存储可选 Weaviate 或 Qdrant。官方提供了一键部署的 docker-compose 文件所以对使用者的要求并不高只要 Docker 环境正常即可。组件说明Docker Engine20.10 以上版本建议使用 Docker Desktop 4.x 或 Linux 上的 Docker CEDocker Compose2.x 版本docker compose 子命令操作系统Linux、macOS、WindowsWindows 推荐 WSL2 后端内存至少 8GB推荐 16GB知识库索引和模型 API 调用有一定内存开销磁盘空间预留 20GB 以上镜像和向量数据会占用不少空间如果你是 Windows 用户需要注意 Docker Desktop 启动时比较常见的virtualization support not detected问题。这个报错通常是因为 BIOS 中没有开启虚拟化或者 WSL2 没有正确安装。最简单的处理方式是在任务管理器的“性能”页签查看虚拟化是否已启用如果未启用进入 BIOS 开启 Intel VT-x 或 AMD-V同时确保控制面板里“适用于 Linux 的 Windows 子系统”功能已被勾选。2.2 获取 Dify 源码与 docker-compose 文件Dify 官方推荐的方式是克隆 GitHub 仓库然后使用其中的 docker 目录启动服务。操作如下git clone https://github.com/langgenius/dify.git cd dify/docker进入dify/docker目录后可以看到.env.example文件。首次部署需要复制一份环境变量文件cp .env.example .env这里需要说明一下.env文件里包含了很多服务初始化变量比如 PostgreSQL 密码、Redis 密码、向量数据库类型等。官方给的默认值可以直接用但如果要在多环境部署建议把密码改成强密码。Dify 的 compose 文件会读取.env中定义的变量来生成容器配置直接修改docker-compose.yaml里的值反而可能造成不一致这一点要格外注意。2.3 启动 Dify 服务环境变量文件准备好之后执行启动命令docker compose up -d第一次启动需要拉取多个镜像包括api、web、postgres、redis、weaviate或qdrant等。镜像体积比较大建议保持网络稳定。启动完成后可以查看容器状态docker compose ps正常情况下你会看到api、web、db、redis、weaviate等容器处于 running 状态。Dify 的前端服务默认监听 3000 端口。打开浏览器访问http://localhost:3000如果出现初始化管理员账号的页面说明服务已经正常启动。在首次访问时系统会要求设置管理员邮箱和密码这一步完成之后进入主界面。这里特别提醒一点Dify 的web容器对外暴露的是 3000 端口但实际项目中可能和已有服务冲突。如果 3000 端口被占用可以在.env中修改EXPOSE_NGINX_PORT变量然后重新执行docker compose up -d前端入口也会随之改变。2.4 升级与迁移注意事项热词里出现了dify迁移和dify安装教程的需求这里稍微扩展一句。Dify 的版本迭代速度很快升级时一般执行下面的操作git pull origin main cd docker docker compose down docker compose up -d但要注意docker compose down 会删除容器如果后端数据存储在 Docker Volume 中数据不会丢失。如果迁移到另一台服务器需要把 Docker Volume 目录一起备份尤其是 PostgreSQL 和向量数据库的卷目录。这个操作属于有风险的生产级变更建议先在一台测试机上演练一遍确认数据完整再动生产环境。3. 大模型接入本地模型与云端 API 的选择Dify 本身不提供模型算力它只是模型的管理和调用网关。所以部署完 Dify 之后第一步要做的就是接入模型。在“设置 - 模型供应商”页面里可以看到 OpenAI、Azure OpenAI、Anthropic、通义千问、文心一言、智谱、Ollama 等多家供应商。不同供应商的接入方式略有差异但大方向一致配置 API Key、模型名称、模型类型。3.1 接入云端大模型 API以 OpenAI 为例进入模型供应商页面找到 OpenAI填入 API Key 和对应的 Base URL。如果使用的是国内云的兼容接口Base URL 可以改成对应的网关地址。这里不涉及任何特殊网络操作只需要填官方控制台提供的合法密钥即可。填写完成后点击“保存”Dify 会调用一次凭据校验接口。如果出现an error occurred during credentials validation报错常见原因有三个可能原因排查方向API Key 不正确去模型服务商控制台重新生成 Key 并确认没有额外空格Base URL 配置错误检查是否填写了完整的 v1 接口地址服务商网关拦截查看服务商控制台的调用日志确认是否拒绝了来源 IP对于国内用户更省心的方式可能是接智谱 GLM、通义千问这类国产模型它们在控制台申请 API Key 之后即可使用而且很多新用户都有免费额度。需要提醒的是不同模型在工具调用、函数调用的支持力度上不同Agent 类型的应用尽量选择支持工具调用的大模型否则 Dify 需要依赖提示词方式模拟工具调用在复杂场景下稳定性会差一些。3.2 接入本地大模型Ollama如果企业内部对数据安全要求较高或者不想按 token 付费可以部署本地大模型和 Dify 配合使用。Ollama 是目前最简单的本地模型运行时之一。在服务器上安装 Ollama 后先拉取模型ollama pull qwen2.5:7b然后启动模型服务ollama serveOllama 默认监听 11434 端口。回到 Dify 的模型供应商页面找到 Ollama按照下面的方式配置配置项填写内容Base URLhttp://宿主机IP:11434模型类型对话模型 / Embedding 模型模型名称qwen2.5:7b如果你是用 Docker Compose 启动的 Dify宿主机 IP 不能写localhost因为容器内部访问localhost指向的是容器本身。在 Linux 上可以填http://172.17.0.1:11434或宿主机局域网 IP在 macOS 上填http://host.docker.internal:11434。Docker Desktop 会自动把host.docker.internal解析到宿主机这是很多新手第一次接入本地模型最常见的坑。3.3 免费大模型 API 和企业私有化的取舍热词里反复出现“免费大模型api”和“企业大模型私有化部署”这里结合选型给大家一个相对务实的判断标准个人学习和原型验证阶段优先用云端免费额度或低价格模型比如智谱、通义、百炼的试用额度省时省力。企业内部知识库场景如果数据不敏感可以先用云端 API 快速验证产品价值如果数据敏感就必须考虑私有化模型Ollama Qwen、vLLM Qwen 都是可行的方向。混合策略也是常见做法对话模型用云端Embedding 模型用本地。因为 Embedding 模型参数规模小本地跑起来压力不大而对话场景对模型质量更敏感。4. RAG 知识库从原理到完整配置4.1 RAG 到底是什么为什么要用知识库RAG 的全称是 Retrieval-Augmented Generation检索增强生成。通俗解释是当用户问一个问题时系统不直接让大模型硬答而是先从知识库里检索相关文档片段把检索到的内容作为上下文和问题一起交给大模型让大模型基于给定材料生成回答。这种做法的价值很明显。大模型的训练数据有时间截断对于企业内部文档、产品说明书、特定领域的实时内容模型根本没见过。直接问模型要么编造答案要么回答“我不知道”。引入知识库之后模型变成了一个“带着材料回答问题的人”准确率会大幅提升。在 Dify 中创建一个知识库非常简单。进入“知识库”页面点击“创建知识库”上传文档系统会进行文本清洗、分段、向量化三步处理。最终文档会被拆成多个文本块每个块通过 Embedding 模型转换成向量存入向量数据库。用户提问时系统将问题转换成向量在向量库中执行相似度检索找出最相关的若干文本块。4.2 RAG 知识库与 KG 知识库的区别搜索材料里出现了kg知识库、rag知识库和结构知识库区分以及应用场景这里值得展开讲一下。RAG 知识库存储的是非结构化文本块适合处理文档、手册、聊天记录这类内容它的优点是搭建速度快不需要定义实体关系缺点是只做向量检索时对复杂逻辑推理支持有限。KGKnowledge Graph知识图谱知识库则是把知识建模成实体和关系比如“《三角洲行动》的护甲分为 A、B 两级”这里“护甲”和“等级”就是实体它们之间的关系是“分为”。KG 适合处理强关联、多跳查询场景但对文本抽取质量要求很高建模成本也大。Dify 目前主要还是以 RAG 路线为主对于大多数文档问答场景RAG 正确的分段策略已经够用。如果未来遇到知识图谱需求可以考虑引入专门的图数据库再通过 API 集成到 Dify 工作流中。优先把 RAG 用明白再去碰 KG这个顺序对大多数团队更合理。4.3 决定 RAG 效果的分段策略很多同学把知识库效果不好归咎于“模型不行”但实际影响最大的是分段Chunking策略。以游戏攻略类文档为例分段过大比如把整篇攻略塞进一个 chunk检索出来的内容太宽泛大模型抓不住重点回答就会啰嗦、偏题。分段过小比如把一句“护甲值减少50%”单独成段上下文不完整模型无法理解这句话是哪个模式下的规则。合理分段按章节或小节拆分每段控制在 200 到 500 字左右尽量保证一段包含一个完整知识点。Dify 创建知识库时可以在“分段设置”里调整分段标识和最大长度。对于政务法规类文档可以按条款编号分段对于游戏攻略类文档按 Markdown 标题分段就很合适。同时开启“父子分段”或增加重叠字符数能让检索结果在片段完整性和回答性能之间取得平衡。4.4 实操上传与检索测试为了演示我们在 Dify 中创建一个名为“三角洲行动攻略库”的知识库导入一篇游戏指南分段方式选择自动分段的增强模式索引方式选高质量用 Embedding 模型。上传完成后进入“召回测试”页面输入类似“三角洲行动的护甲机制是什么”查看召回结果。这里要留意一个常见误区召回测试看到的结果是“检索到什么”不是“最终回答什么”。如果召回结果里已经出现了正确片段但最终回答不对问题出在提示词编排如果召回结果里压根没有相关内容问题出在分段或 Embedding 模型。这个排查思路可以帮你快速定位问题。5. 三角洲游戏 Agent工具调用与工作流编排5.1 Agent 基本概念与架构选择热词中出现多次agent、agent架构、ai agent。通俗地说Agent就是让大模型不只是“聊天”而是能自主决策观察用户输入拆解任务调用工具观察结果再决定下一步动作的智能体。在 Dify 中创建一个 Agent 应用有两种主要方式方式适用场景特点Chatflow 工作流流程固定、步骤确定可视化编排调试方便适合生产交付Agent 节点方式需要模型自主决定工具调用灵活但结果存在一定不确定性三角洲游戏 Agent 更适合使用 Chatflow 工作流。整个流程可以这样设计用户输入问题 → 知识库检索 → 游戏百科工具查询 → 大模型总结回答。这样的设计既借助了 RAG 知识库补充攻略知识又利用外部工具查询实时数据同时用大模型作为最终的“主持人”组织答案。5.2 工作流节点设计创建一个 Chatflow 应用命名为“三角洲行动战术助手”。在画布上依次添加以下节点开始节点接收用户输入。知识检索节点关联“三角洲行动攻略库”设置 topK 为 4相似度阈值 0.5。工具节点接入一个自定义 HTTP 工具用于查询游戏弹药数据或地图信息。Dify 支持 OpenAPI schema 方式导入工具也支持直接填写 URL 和参数映射。大模型节点选用前面接入的对话模型将知识库检索结果和工具返回结果拼接进系统提示词让模型基于材料作答。结束节点输出最终答案。下面给一个工具接入的示例配置假设我们需要一个根据武器名称返回弹匣容量的 HTTP APIopenapi: 3.0.0 info: title: Game Weapon API version: 1.0.0 servers: - url: https://your-game-api.example.com paths: /weapon/{name}: get: operationId: getWeaponInfo parameters: - name: name in: path required: true schema: type: string responses: 200: description: success将这个 schema 导入 Dify 的工具列表Dify 会自动解析出工具入参。实际请求的地址需要根据你的后端服务修改这里的 URL 仅为示例。5.3 提示词设计示例在 Agent 或 Chatflow 的大模型节点中提示词直接决定回答质量。下面是三角洲游戏助手系统提示词的一个参考模板你是“三角洲行动战术助手”负责回答关于《三角洲行动》游戏机制、装备、地图、玩法的问题。 回答规则 1. 优先参考知识库检索结果和工具查询结果不要编造数据。 2. 如果知识库中没有相关内容明确告知用户当前资料暂未覆盖。 3. 回答时给出数据来源帮助用户判断可信度。 4. 保持简洁先给出结论再解释原因。这段提示词里最关键的规则是第一条。很多 Agent 应用最后效果“一本正经胡说八道”往往就是提示词里没有强约束模型必须基于检索内容回答。5.4 调试与日志观测Dify 的 Chatflow 画布上有一个“运行”按钮可以在调试面板中单步执行。启动一次运行后能看到知识检索节点命中了哪些文本块、工具节点返回了什么内容、大模型节点最终生成了什么结果。这在排查 RAG 和 Agent 问题时非常有用。生产运行之后在“日志”页面可以看到每次会话的完整过程。如果某次回答离预期很远先看日志里是否检索到了相关片段再看提示词变量是否被正确注入。日志是整个链路中最容易被忽略但价值最高的部分。6. 网页嵌入与发布6.1 网页嵌入的原理Dify 创建的每一个应用都可以发布为可嵌入的 Web App。这个功能对实际项目非常实用不需要单独写一个前端聊天页面只需要在现有网站里嵌入一段 iframe 代码对话界面就能直接工作。在应用管理页的“发布”标签中选择“嵌入 iframe”Dify 会生成一段类似下面的代码iframe srchttp://localhost:3000/chat/your-app-token stylewidth: 100%; height: 700px; border: none; /iframe把这段代码放到你自己的网页 HTML 中比如活动页、产品官网、内部管理后台都可以。Dify 的 Web App 支持流式回答用户交互体验和原生页面差别不大。6.2 鉴权与访问控制默认情况下iframe 嵌入的连接是公开的谁拿到 URL 都能访问。如果只希望特定用户使用有两个方向用 Web App 的 API 接口代替 iframe在后端调用 Dify API把应用令牌放到服务端不在前端暴露。Dify 提供 API 访问令牌机制通过Authorization: Bearer app-token调用/chat-messages接口。这是生产环境更推荐的做法。下面是一个 Python 调用 Dify 对话接口的示例import requests url http://localhost:3000/v1/chat-messages headers { Authorization: Bearer app-xxxxxxxxx, Content-Type: application/json } payload { inputs: {}, query: 三角洲行动中哪把冲锋枪最适合近距离作战, response_mode: blocking, user: user-123, conversation_id: } resp requests.post(url, headersheaders, jsonpayload) print(resp.json())这个示例说明的是接入思路iframe 适合快速演示API 方式适合集成到正式系统。使用 API 时需要妥善保存应用令牌不要把令牌硬编码在前端页面中。7. 常见问题与排查清单7.1 高频报错汇总问题现象常见原因解决思路docker compose up 后 web 页面打不开端口冲突或 web 容器未正常启动执行 docker compose ps 检查容器状态查看 web 日志模型供应商保存时报 credentials validation 错误API Key 错误或 Base URL 不可达逐字检查密钥确认 Base URL 是否包含完整路径接入 Ollama 后提示连接失败容器内访问宿主机地址写错Linux 使用 http://172.17.0.1:11434macOS 使用 host.docker.internal知识库召回结果为空Embedding 模型未生效或向量库未写入检查知识库的索引状态重新执行索引Agent 不调用工具模型不支持工具调用或工具描述不清晰更换支持 function calling 的模型优化工具描述回答内容偏离知识库分段粒度过大或提示词约束不足调整分段策略增强提示词中对知识库来源的约束dify ssl 错误HTTPS 反代证书配置失败检查 Nginx 证书路径与 Dify 的环境变量配置7.2 排查清单遇到 Dify 异常时不建议直接重装。按下面的顺序排查会更高效看容器状态docker compose ps确认异常容器的名字。看容器日志docker compose logs container-name找到关键报错行。看模型配置确认供应商页面是否能通过凭据校验。看知识库状态确认文档分块和索引是否完成。看应用日志定位失败节点发生在检索、工具还是模型生成环节。8. 最佳实践与工程建议8.1 配置管理建议Dify 的.env文件在集群化部署中应当纳入配置管理不要直接塞进代码仓库。内部部署可以把敏感变量放到密钥管理系统中启动时动态注入。涉及docker compose down和配置变更时先在一台测试机完整验证再操作生产环境。8.2 知识库更新机制知识库不是“上传一次就不管了”。文档更新后要重新执行索引。对于高频更新内容可以考虑把文档放进对象存储用脚本自动触发 Dify 的文档更新接口。但在动手之前建议先确认你使用版本的 Dify 知识库 API 是否可用各版本接口有一定差异。8.3 成本与性能优化大模型 API 调用成本是生产环境的主要风险之一。可以从四个方向控制设置模型节点的最大 token 上限避免长文本上下文消耗过多。合理设置知识库检索 topK不需要一次性塞入太多片段。在路由层做简单缓存相同的问题直接命中缓存答案。对 Agent 工具调用增加超时限制避免某个工具故障导致整条链路变慢。8.4 Agent 安全边界热词里出现了agent安全这里必须强调一句。如果需要给 Agent 接入执行类工具比如修改数据库、发送邮件、调用支付接口务必遵循最小权限原则。工具节点应该只暴露必要的动作不能把整个系统的写接口直接交给模型调用。同时记录 Agent 每一次工具调用的输入输出日志便于审计和回溯。9. 总结与进一步学习方向这篇文章从 Docker 部署 Dify 开始走完了大模型接入、RAG 知识库构建、三角洲游戏 Agent 工作流编排、网页嵌入和 API 接入的完整链路。掌握了这些内容你已经具备在企业内部搭建一套可用的大模型问答应用的基础能力。接下来可以继续深入的方向包括Dify 的插件机制与自定义工具开发、用 Dify 的 API 与 Spring Boot 后端整合、基于 Weaviate 或 Qdrant 的向量检索调优、使用 vLLM 部署更大参数的私有化模型。每一步都值得做一次独立实验光是“把知识库效果调好”这一个主题就能展开非常多细节。希望这篇文章能帮你把环境搭起来、把第一个应用跑通然后带着真实的问题继续往前走。