如果你已经拿到了大模型 API却依然很难做出一个像样的 AI 应用这并不奇怪。过去半年里我和不少开发者交流时发现一个共性真正卡住大家的往往不是“模型能力不够”而是“从模型 API 到可用产品之间的工程链路太长”。你要处理对话上下文、管理 Prompt、设计工具调用、接入知识库、做日志和评测还要让业务人员也能参与调优。这一整套事情如果全部靠手写代码周期会拉得很长。这也是 Dify 最近在开发者社区里讨论度不断上升的核心原因。它不是一个模型也不是一个聊天页面而是一套开源的大模型应用开发平台。你可以把它理解成“LLM 应用开发的集成开发环境”把模型接入、Prompt 编排、知识库检索、Agent 工作流、应用发布和运营监控都放到了同一套可视化体系里。而社区版支持本地部署意味着你的数据链路、API Key 和业务逻辑都可以留在自己的服务器上。这篇文章会从零开始完整走一遍 Dify 的安装部署流程再从创建第一个智能体开始逐步做到带知识库的客服类 Agent。内容会覆盖环境准备、Docker Compose 部署、模型供应商配置、工作流搭建、知识库接入、常见排错和生产环境建议。你可以把它当作一份可以直接照着操作的实战笔记也可以收藏起来等实际部署时再做对照。1. 为什么要自己部署 Dify而不是直接用云平台版聊 Dify 的部署之前先想清楚一个前提现在很多大模型平台都提供“零代码应用搭建”云平台版 Dify 也能通过官方入口直接注册使用。那为什么还需要本地部署社区版答案是四个字数据可控。在企业或团队场景里模型应用往往要接内部知识库、客户资料、业务系统的真实数据。这些数据一旦通过云端平台流转就会引入数据合规、访问审计和供应商绑定问题。部分企业甚至有硬性要求所有数据处理必须发生在内网或自建服务器上不能进入第三方云端链路。这时开源社区版 Docker Compose 部署就成了最稳妥的起步方式。从部署成本看Dify 本身不是重组件它由 API 服务、Worker、Web 前端、PostgreSQL、Redis、Weaviate或 Qdrant等容器组成通过 Docker Compose 一键编排。一台 4 核 8G 的 Linux 服务器就能跑起来个人开发环境如果只是演示或单团队试用2 核 4G 也勉强可用但会更吃力。对于手头有 Windows 电脑、Mac 电脑的开发者Dify 同样支持 Docker Desktop 方式运行。从功能演进看Dify 社区版已经在往“可支撑团队协作”的方向走。比如前面提到的社区版 1.10 版本开始引入多租户能力这让一个自建实例可以被多个业务团队共享而不是每个人各搭一套。这也意味着“自己部署”不再是个人玩具而是逐渐成为企业内部 AI 应用平台的一种可选形态。需要提醒的是云平台版和社区版在功能更新节奏上不完全一致。如果你想第一时间体验某些 SaaS 功能可能还是要看官方版本说明。但对绝大多数想深入掌握 Dify、想定制内部工作流的开发者来说直接本地部署社区版是更合适的学习路径。2. Dify 能解决什么问题从模型 API 到智能体的最后一公里要理解 Dify 的价值最有用的方式是拆解一下没有 Dify 时做一个“带知识库的客服智能体”需要经历什么。假设你用的是 OpenAI 兼容接口目标是让用户先通过聊天窗口提问系统从内部文档里检索相关内容再交给大模型组织回答。传统做法大致是开发一个后端服务负责前端聊天消息转发。实现会话上下文管理包括会话 ID、消息历史存储和窗口截断。接入向量数据库完成知识库文档的切分、Embedding 和检索。编写 Prompt 模板把检索结果拼接到系统提示词中。对大模型返回结果做流式输出处理对接前端。部署到服务器处理日志、异常、版本更新。这套流程的每一步都不难但串起来非常消耗时间。尤其当业务方要求“换一个模型试试”“调整一下检索范围”“给这个知识库增加一段文档”时如果全在代码里硬编码改起来就更痛苦。Dify 做的事情是把这条链路上的大部分环节变成可视化配置。模型供应商在你的账号体系里统一管理知识库通过界面直接上传文件并自动分段Agent 编排可以拖拽节点Prompt 修改后立即生效不用改代码甚至整个应用可以一键发布成 WebApp 或 API 服务。这意味着什么意味着 LLM 应用开发从“面向代码的工程实现”变成“面向流程的组装与调优”。开发者的时间可以更多花在业务逻辑和效果评测上而不是反复写工具调用和上下文管理代码。当然Dify 不是万能的。如果你的应用需要完全自定义的前端交互、非标准协议接入、极高并发定制化架构或者需要深度修改模型调用底层逻辑那直接用代码框架比如 LangChain 或自研编排层依然更合适。Dify 更适合的场景是知识库问答、内部工具助手、业务流自动化、客服机器人、数据分析入口以及想快速验证 AI 产品原型的团队。3. Dify 安装部署前的环境准备开始部署前先把环境梳理清楚。这里不会指定死板的版本号以实际安装时的最新稳定版为准但通用思路是稳定的。3.1 服务器与操作系统推荐使用 Ubuntu 22.04 或 Debian 12 这类常用 Linux 发行版。CentOS 7 也可以跑但在 Docker 新版本兼容性上要额外注意。个人开发可以使用 Windows Docker Desktop 或 macOS Docker Desktop但生产环境建议使用 Linux 服务器。3.2 硬件估算决定服务器配置前先考虑一个关键因素你是否要跑本地 Embedding 模型或本地 LLM。如果只使用云端模型 API比如 DeepSeek、通义千问、OpenAI 兼容接口那么 Dify 本身对硬件要求并不高。4 核 CPU、8G 内存、40G 磁盘足够支撑个人和中小团队使用。如果你希望通过 Ollama 之类工具运行本地模型那么内存和显卡需求会明显上升。以常见的 7B 参数量化模型为例16G 内存勉强可跑32G 内存更稳妥想要流畅体验最好有独立显卡并启用 GPU 加速。3.3 必需软件Docker 与 Docker ComposeDify 官方推荐的部署方式就是 Docker Compose。因此服务器上必须安装 Docker 和 Docker Compose 插件。安装 Docker 后的基础检查命令如下docker --version docker compose version如果系统里还没有 Docker可以参考 Docker 官方文档执行安装。Ubuntu 上常见做法是sudo apt-get update sudo apt-get install -y ca-certificates curl sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc sudo chmod ar /etc/apt/keyrings/docker.asc echo \ deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \ $(. /etc/os-release echo $VERSION_CODENAME) stable | \ sudo tee /etc/apt/sources.list.d/docker.list /dev/null sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin sudo systemctl enable docker sudo systemctl start docker这里把 Docker Compose 作为 Docker 插件安装后续命令使用docker compose中间有空格而不是老式的docker-compose。3.4 端口规划Dify 默认占用以下端口端口用途80Nginx 入口提供 Web 访问443HTTPS 入口如果启用5432PostgreSQL 数据库6379Redis8000API 服务一般通过 Nginx 反向代理访问如果服务器上 80 端口已经被其他服务占用可以通过修改 docker-compose.yaml 中的端口映射来避开。比如把80:80改成8080:80之后通过http://服务器IP:8080访问。3.5 域名与 HTTPS生产环境建议提前准备好域名并为域名配置好 DNS 解析。Dify 的 Docker Compose 里提供了 Nginx 容器可以通过环境变量配置 HTTPS 证书。如果只是想本地测试直接用 IP 访问也可以但登录和 API 调用时部分浏览器会有安全提示。4. 使用 Docker Compose 部署 Dify 社区版这一节是全文的实操核心。我们按步骤完成 Dify 社区版的下载、配置、启动和访问。4.1 获取 Dify 源码与 docker 目录Dify 的部署文件在 GitHub 仓库中。使用 git 克隆项目然后进入 docker 目录git clone https://github.com/langgenius/dify.git cd dify/docker如果你在一个网络受限的环境中无法访问 GitHub也可以从官网或镜像站下载对应版本源码包解压后同样进入docker目录操作。4.2 配置环境变量 .envdocker 目录下有一个.env.example文件把它复制为.envcp .env.example .env.env文件里保存了 Dify 的关键环境变量包括数据库连接、Redis 连接、密钥等。初次部署时以下变量需要特别注意# 用于加密敏感信息的密钥必须自行生成 SECRET_KEYyour-secret-key-here # 数据库配置默认连接 docker-compose 内的 PostgreSQL DB_USERNAMEdify DB_PASSWORDdify DB_HOSTdb DB_PORT5432 DB_DATABASEdify # Redis 配置 REDIS_HOSTredis REDIS_PORT6379 REDIS_PASSWORD # 向量数据库类型可选 weaviate / qdrant / milvus 等 VECTOR_STOREweaviate如果使用默认配置Dify 会启动一个 Weaviate 容器作为向量数据库。你也可以改成 Qdrant只需在.env中调整VECTOR_STORE并为 docker-compose 里对应容器做配置。4.3 启动所有容器直接使用 compose 启动cd dify/docker docker compose up -d首次启动会拉取多个镜像时间取决于网络状况。等到命令执行完成查看容器状态docker compose ps如果一切正常你会看到类似api、worker、web、db、redis、weaviate、nginx等容器处于Up状态。启动完成后通过浏览器访问http://服务器IP首次访问会进入管理员账号设置页面。按照提示设置管理员邮箱和密码后就可以登录 Dify 控制台了。4.4 后续升级与版本更新Dify 社区版迭代比较快升级时可以按以下通用步骤操作cd dify/docker git pull origin main docker compose down docker compose pull docker compose up -d升级前务必备份数据库和向量数据库数据否则一旦出现数据迁移失败恢复会非常麻烦。这个建议后面会展开。5. 配置大模型供应商让智能体拥有“大脑”Dify 部署完成后第一件重要的事是接入大模型。没有模型后续所有编排都无法运行。5.1 打开模型供应商页面登录 Dify 控制台后点击右上角头像进入“设置”然后选择“模型供应商”。页面上会列出各种模型供应商类型。Dify 的模型供应商接入通常分为两类官方 SDK 支持的高阶供应商比如 OpenAI、Anthropic、Azure OpenAI、通义千问、DeepSeek 等直接填写 API Key 即可。OpenAI API Compatible 兼容服务适合接入各类开源模型网关、代理服务或其他兼容 OpenAI 接口的模型平台。5.2 接入 OpenAI 兼容接口以 DeepSeek 或开源模型网关为例在“模型供应商”页面找到“OpenAI-API-Compatible”或类似入口填写配置项说明API Key对应平台的 API KeyAPI Base URL平台提供的接口地址例如https://api.deepseek.com/v1Models需要使用的模型名称例如deepseek-chat填写完成后点击“保存”或“测试”Dify 会调用一次小规模请求来验证连通性。如果返回模型列表或测试成功说明配置正确。5.3 使用 Ollama 接入本地模型如果你希望完全离线运行可以安装 Ollama 并在本地拉取模型然后通过 Dify 的 Ollama 供应商接入。启动 Ollama 服务后需要在宿主机或容器网络中确保 Dify API 容器能访问到 Ollama 地址。如果是 Docker 部署通常填http://host.docker.internal:11434或宿主机实际 IP根据操作系统决定。Dify 里配置 Ollama 时需要填写 Base URL 和模型名称。Ollama 模型拉取示例ollama pull qwen2.5:7b ollama pull bge-m3其中bge-m3可用于知识库 Embeddingqwen2.5:7b可用于对话生成。5.4 API Key 安全原则Dify 平台里的模型供应商 API Key 本身是加密保存的但你在.env或初始化配置中使用的SECRET_KEY必须妥善保管。此外不要在不安全的日志或分享文档中粘贴真实 API Key。生产环境建议为 Dify 单独申请专用 Key并设置调用额度上限。6. 从零创建第一个智能体对话型应用编排模型接入完成后我们就可以在 Dify 中创建第一个智能体了。6.1 创建空白应用进入 Dify 控制台点击“创建空白应用”选择“聊天助手”类型。聊天助手是 Dify 中最基础的应用形态适合做客服、问答、对话机器人。创建时需要选择“编排方式”。Dify 提供了两种主要模式基础编排适合简单对话配置系统提示词、模型、对话开场白即可。工作流编排适合多步骤、有条件分支、需要调用工具或知识库的复杂场景。对于第一个智能体建议先用“基础编排”跑通流程。6.2 配置系统提示词系统提示词决定了 AI 的角色和行为。以客服助手为例你是一个耐心、专业的客服助手。你需要根据用户的问题提供准确、简洁的回答。如果遇到不确定的信息如实说明你不了解不要编造答案。这段提示词看起来简单但它是后续所有调优的基础。好的系统提示词应当明确角色、任务边界和回答风格。6.3 选择模型在应用编排页右侧选择你在第 5 节接入的模型。比如选择deepseek-chat或qwen-plus。可以设置模型参数如 Temperature 和 Max Tokens。初始阶段保持默认即可。6.4 添加对话开场白和下一步引导对话开场白是用户在聊天窗口看到的第一个内容。好的开场白可以降低用户上手成本你好我是小 D 助手。你可以向我提问业务相关的问题也可以让我帮你处理文档。在编排页面保存并发布后应用就会生成一个 WebApp 访问链接。打开链接就能在浏览器里和智能体对话了。6.5 查看日志与对话记录Dify 的“日志与标注”功能可以查看每次对话的输入输出、模型消耗 Token 数量。这一步非常关键因为很多问题只有在真实对话中才会暴露。养成每次修改 Prompt 后都去看日志的习惯对后续调优帮助极大。7. 搭建带知识库的客服智能体工作流 RAG单纯靠模型本身的通用知识无法回答企业内部问题。要让智能体“知道”你的产品手册、FAQ、内部制度必须接入知识库也就是 RAG检索增强生成。Dify 里这个能力可以通过“工作流编排”完整呈现。7.1 准备知识库文档知识库支持 txt、markdown、pdf、html、docx 等格式。建议先把资料整理成结构清晰的 Markdown 或 PDF 文件。文件越规整后续检索效果越好。7.2 创建知识库在控制台点击“知识库”创建新的知识库。上传文档后Dify 会执行分段和向量化流程。这里有两个重要配置配置说明分段模式自动分段还是自定义分段。自动分段适合常规文档结构化文档建议自定义分段按章节切分索引方式高质量模式调用 Embedding 模型和高性价比模式。高质量模式检索准确率更高Embedding 模型在知识库创建时选择。如果你使用云端模型可以选text-embedding-ada-002、bge-m3等如果是本地 Ollama就选bge-m3。7.3 创建工作流知识检索 模型回答回到“创建空白应用”这次选择“工作流”类型。工作流的本质是可视化定义流程节点。一个典型的知识库客服智能体包含开始节点接收用户输入。知识检索节点从指定知识库中检索相关内容。LLM 节点把用户问题和检索结果拼接成最终回答。结束节点输出回答。在知识检索节点中选择你要检索的知识库设置 TopK返回片段数量和 Score 阈值。Score 阈值用于过滤低相关度结果建议初始设为 0.5 左右后续根据实际效果调整。在 LLM 节点中使用“上下文”变量把检索结果注入系统提示词。示例基于以下参考资料回答用户问题。 参考资料 {{#context#}} 用户问题 {{#sys.query#}} 如果参考资料中没有相关信息请明确回答“资料库中暂无相关内容”。这里的{{#context#}}和{{#sys.query#}}是 Dify 工作流节点的变量引用语法不同版本可能略有差异以节点编辑面板中可选的变量名为准。7.4 发布为 WebApp工作流配置完成后点击“发布”。发布后应用会像聊天助手一样生成访问链接。你可以在链接里测试“你们的退货政策是什么”之类的业务问题并检查回答是否来自知识库。7.5 通过 API 调用智能体Dify 创建的每个应用都会在“API 访问”页面生成独立的 API 密钥和调用地址。你可以在自己的业务系统里通过 HTTP 调用该智能体。例如使用 Python 调用聊天助手 APIimport requests api_key app-xxxxxxxxxxxx url http://你的服务器IP/v1/chat-messages headers { Authorization: fBearer {api_key}, Content-Type: application/json } payload { inputs: {}, query: 你好我想咨询退货政策, response_mode: blocking, conversation_id: , user: demo-user } resp requests.post(url, headersheaders, jsonpayload) print(resp.json())API 密钥只应保存在服务端环境变量或配置中心中不要直接写死在代码仓库。8. 验证智能体效果与常见问题排查智能体不是“发布完就能交付”效果验证和问题排查才是真正花时间的环节。8.1 怎么判断智能体是否正常工作至少做三类测试通用对话测试验证模型基础回答是否正常。知识库问题测试提出一个答案明确在文档中的问题检查回答是否忠实于资料。边界问题测试提出一个知识库中不存在的问题观察智能体是否如实说明而不是强行编造。如果测试中回答质量不佳优先调整知识库分段的粒度、检索 Score 阈值和系统提示词。8.2 常见问题排查表问题现象可能原因排查方式解决方案首次访问页面无法打开容器未完全启动或端口被占用执行docker compose ps查看容器状态等待容器启动完成检查端口映射冲突模型供应商配置失败API Key 错误或接口地址不通在模型供应商页面点击测试核对 Key 和 Base URL查看服务器防火墙智能体回答不基于知识库知识检索节点未接入或 Score 阈值过高查看工作流节点输出日志调低 Score 阈值确认知识库已启用知识库文档上传后无法检索Embedding 模型未配置查看知识库处理状态为知识库指定可用的 Embedding 模型并重新处理升级后容器启动失败数据库迁移未执行或镜像缓存冲突查看 API 容器日志备份数据后执行docker compose pull再启动必要时清理旧镜像API 返回 401API Key 错误或未启用访问检查请求 Header 和 API 密钥在应用 API 访问页面重新生成密钥8.3 日志在哪里看Dify 主要容器的日志可以通过以下命令查看# 查看 API 服务日志 docker compose logs -f api # 查看 Worker 日志 docker compose logs -f worker # 查看 Nginx 日志 docker compose logs -f nginx遇到“页面能打开但对话报错”的情况第一优先看api容器日志遇到“知识库处理失败”查看worker容器日志。这条排查顺序能解决绝大多数问题。9. 生产环境的最佳实践与工程建议如果你只是在自己电脑上跑通流程前面内容已经足够。但当 Dify 要进入团队协作或企业环境有几个问题必须提前考虑。9.1 多租户与团队共享Dify 社区版从 1.10 开始逐步引入多租户能力这意味着一个实例可以承载多个团队或项目的隔离。多租户上线后管理员可以创建不同工作空间不同团队的数据、应用、知识库相互隔离。这个能力对“一个平台服务多个业务方”的场景非常关键也避免每个团队单独部署一套带来的资源浪费。使用多租户时要注意给每个租户明确资源配额和模型 Key 归属避免某个团队的大批量调用影响其他团队。9.2 数据备份与恢复在生产环境必须定期备份 PostgreSQL、向量数据库和 Dify 配置文件。最简单的方案是直接备份 Docker Volume 目录但更可靠的方式是使用数据库原生导出工具。备份 PostgreSQL 示例docker compose exec db pg_dump -U dify dify dify_backup_$(date %Y%m%d).sql向量数据库同样需要备份。以 Weaviate 为例它的数据存储在对应 volume 下可以使用文件备份或 Weaviate 的导出接口。建议设置定时任务每日备份一次。9.3 安全边界Dify 的管理员控制台、API 和知识库包含敏感数据。生产环境建议通过 Nginx 或云防火墙限制管理后台的访问来源 IP为 API 调用配置独立的密钥并通过网关层做限流。模型供应商的 API Key 不要在界面中随意复制传播。9.4 资源监控运行一段时间后要关注 CPU、内存、磁盘和 PostgreSQL 连接数。Dify 的 API 和 Worker 容器会随对话量变化产生压力。如果对话量大可以扩大 Worker 副本数方式是根据 docker compose 服务配置做横向扩展docker compose up -d --scale worker3但横向扩展前必须确认 Redis 和数据库能承受相应连接压力否则容易出现更严重的问题。9.5 提示词与调试规范建议团队内部统一管理 Prompt 版本。Dify 的编排页面天然适合在线调整但每次调整都应有记录。可以按以下格式维护提示词文档应用名称版本修改人修改内容关联知识库客服助手v1.2张三增加“拒绝编造答案”约束产品FAQ这样做的好处是当线上效果回退时可以快速定位是哪一次 Prompt 调整导致的。9.6 选择合适的部署方式如果你的团队已经使用了 KubernetesDify 也提供 Helm Chart 等部署方式。但对于绝大多数中小团队Docker Compose 已经足够稳定和简单没必要一开始就引入 Kubernetes 的复杂度。先用 Compose 跑通业务等规模发展到需要自动扩缩容和多节点高可用时再考虑迁移到 K8s。10. 总结与后续学习方向这篇文章真正想表达的观点是2026 年做 AI 应用比拼的不再是“谁调用了更强大模型”而是“谁能把模型能力更好地嵌入到业务流程中”。Dify 作为开源大模型应用平台把模型接入、知识库、工作流、Agent 编排和应用发布整合在一条链路里极大降低了 LLM 应用从想法到落地的时间成本。如果你想继续深入接下来的方向可以从这几条线展开深入学习工作流编排把工具调用、条件分支、HTTP 请求节点结合起来做出具备实际行动能力的 Agent。研究知识库检索效果优化包括分段策略、Embedding 模型选择、召回与重排。尝试把 Dify 应用通过 API 接入到企业微信、钉钉、飞书或自己的管理后台中。关注 Dify 社区版的多租户和权限模型变化为团队协作做好准备。最后提醒一句不要跳过备份和日志这两个习惯。真正的生产事故往往不是“功能不会用”而是“数据没备份”“日志不查”造成的。先从一台服务器跑通一个最小的 Dify 实例开始再慢慢往里加业务场景这是最稳妥的路。