Dify 2026最新版部署与智能体开发实战指南

先看结论Dify 是目前开源社区里把“智能体开发”这件事做得比较完整的平台之一。它不是一个单纯的模型网页壳而是把模型管理、知识库、工作流、智能体编排、应用发布和 API 管理整合到同一个 Web 界面的 LLMOps 平台。如果你正在关注本地部署、知识库流水线、智能体搭建或者想用一套可视化工具替代多个零散脚本这篇可以直接收藏。这次我们会按“核心能力 → 环境准备 → Docker Compose 部署 → 模型接入 → 搭建第一个智能体 → 接口调用 → 性能观察 → 排错 → 最佳实践”的顺序走一遍。标题里的“2026最新版”指的是当前时间下最新的社区稳定版部署方式和使用逻辑在近期版本中保持了较好的一致性但具体菜单名称和版本号请以你实际部署的为准。Dify 最值得关注的地方是它把“模型接入”和“应用发布”做成了平台级能力。你不需要自己写前端聊天框也不需要维护多套模型调用代码直接在界面里创建应用、接模型、挂知识库、配置工作流然后就能拿到一个可对外提供服务的 API。这对团队协作、企业知识库问答、客服智能体和流程自动化场景都很有价值。1. Dify 核心能力速览先把关键规格列出来方便快速判断这个平台适不适合你的场景。能力项说明项目类型开源 LLM 应用开发平台 / 智能体编排平台开源情况Dify 社区版开放源代码可在 GitHub 获取主要功能智能体搭建、工作流编排、知识库/RAG、模型管理、应用发布、API 管理、日志监控推荐部署方式Docker Compose 官方推荐也支持源码运行硬件门槛官方建议 CPU 2 核、内存 4GB 起步实际带知识库和在线应用推荐 4 核 8GB 或更高支持平台Linux、macOS、Windows通过 Docker Desktop 或 WSL 2启动方式docker compose up -d默认通过 80/443 端口访问 Web 界面是否支持 API支持应用发布后可生成独立 API 凭证提供对话和工作流接口是否支持批量任务支持通过 API 批量调用或在工作流中分批处理本地模型支持支持 Ollama、Xinference 等本地推理服务也支持 OpenAI-API-compatible 供应商适合场景企业知识库问答、客服智能体、流程自动化、模型应用原型验证、教学演示这里需要说明一点Dify 是一个平台不是单个模型所以“显存占用”主要取决于你接入的模型。如果只跑 Dify 平台本身主要消耗的是 CPU 和内存如果接入本地大模型显存占用要看模型规格比如 7B 模型和 70B 模型差距非常大建议以本机实际测试为准。2. 适用场景与使用边界2.1 适合谁用Dify 适合的人群比纯代码开发工具要宽很多。第一类是后端或全栈工程师。他们可以用 Dify 快速搭建带知识库的问答应用通过 API 集成到现有业务系统省去自己写 RAG 全链路的时间。第二类是算法工程师。他们在 Dify 里可以统一管理多个模型供应商对比不同模型的效果快速验证 prompt 设计和工作流逻辑。第三类是产品经理和业务运营。Dify 的可视化编排界面让他们不写代码也能搭建智能体比如配置一个客服机器人、销售助手、文档问答工具。第四类是企业内部 IT 团队。Dify 支持 Docker Compose 部署可以部署在内网让敏感业务数据不出内网同时通过 API 对业务方统一暴露能力。2.2 不适合什么场景Dify 不适合极致性能要求的场景。如果业务需要超高并发、毫秒级响应Dify 默认架构需要额外做性能压测、横向扩展和缓存优化不能直接认为开箱即满足生产高并发。Dify 也不适合深度自定义模型推理逻辑的场景。如果要做模型微调、自定义采样器、完整的训练 pipeline这类工作应该在模型训练框架里完成Dify 更偏向应用编排层。2.3 使用边界与合规提醒使用 Dify 时有几个边界必须注意。模型 API Key 属于敏感凭证不要提交到公开仓库不要在前端页面中暴露。自建知识库时上传的文档必须是合法获取且有使用授权的材料包含版权内容或个人信息的文件要先做合规审查。如果构建的智能体涉及人脸、声音、个人信息处理必须事先获得明确授权并限制访问范围。接口服务默认暴露在网络上时要配置访问控制、鉴权和流量限制防止被恶意调用。3. Dify 本地部署环境准备3.1 操作系统与依赖Dify 官方推荐的部署方式是 Docker Compose所以环境准备的核心是装好 Docker。适合的操作系统包括Ubuntu / Debian / CentOS 等 Linux 服务器。macOS通过 Docker Desktop 运行。Windows通过 Docker Desktop 或 WSL 2 运行。安装依赖前先检查环境# 检查 Docker 是否安装 docker --version # 检查 Docker Compose 插件 docker compose version # 检查系统内存和磁盘 free -h df -h如果命令执行后提示命令不存在需要先安装 Docker 和 Compose 插件。不同操作系统的安装方式不同建议参考 Docker 官方安装文档。3.2 硬件资源预估Dify 平台本身由多个服务组成包括 API 服务、Worker、Web 前端、PostgreSQL、Redis、Weaviate 或 Qdrant 向量数据库等。这些容器全部启动后对内存有持续占用。从通用部署经验看最低配置2 核 CPU、4GB 内存。只做界面演示、不接大数据量知识库时可用。推荐配置4 核 CPU、8GB 内存。适合日常开发测试、知识库问答、多个应用并行调试。生产配置8 核 CPU、16GB 内存以上。适合多用户使用、大量文档检索、在线 API 服务。磁盘方面Docker 镜像本身需要数 GB 空间PostgreSQL 和向量数据库的数据会随着知识库增长建议预留至少 20GB 可用空间。如果还要下载本地大模型需要额外预留模型文件空间。3.3 端口规划Dify 默认通过 80 端口提供 Web 服务443 端口用于 HTTPS。如果服务器上已经有 Nginx 或其他 Web 服务占用 80 端口部署时会冲突。建议部署前先确认端口占用情况# 检查 80 端口是否被占用 sudo lsof -i :80如果端口被占用需要在 docker-compose 配置中修改端口映射例如把 Web 端口改为 8080。4. Dify 安装部署与首次启动4.1 获取 Dify 源码与配置Dify 部署推荐通过官方 GitHub 仓库获取 docker 目录下的编排文件。以下流程是通用模板具体命令以官方 README 为准# 克隆 Dify 仓库 git clone https://github.com/langgenius/dify.git # 进入 docker 编排目录 cd dify/docker # 复制环境变量模板 cp .env.example .env此时会生成一个.env文件里面保存了数据库密码、密钥、服务端口等配置。默认配置可以启动但生产环境建议修改默认密码和密钥。4.2 Docker Compose 启动在dify/docker目录下执行# 拉取镜像并后台启动 docker compose up -d第一次执行会拉取多个 Docker 镜像包括 API、Worker、Web、PostgreSQL、Redis、向量数据库等耗时取决于网络状况和镜像大小。启动完成后查看容器状态docker compose ps如果所有服务的状态都是running说明启动成功。如果某个容器反复重启需要查看对应服务的日志# 查看指定服务日志例如 api docker compose logs -f api4.3 修改默认端口如果 80 端口被占用可以修改docker compose.yaml中的端口映射。典型的映射配置如下services: nginx: ports: - 8080:80修改后重新加载配置docker compose up -d之后通过http://服务器IP:8080访问 Dify Web 界面。4.4 首次访问与管理员初始化浏览器打开 Dify 地址后第一次访问会进入管理员初始化页面。需要设置管理员邮箱和密码这个账号是平台超级管理员后续可以在“设置”中创建成员账号。初始化完成后进入主界面此时还没有接入任何模型。下一步就是配置模型供应商。5. Dify 模型接入Ollama 本地模型与云端 APIDify 本身不提供模型推理能力它通过“模型供应商”方式对接各种模型服务。常见接入方式有两种云端模型 API 和本地模型服务。5.1 接入云端模型 API在 Dify 右上角点击头像进入“设置 → 模型供应商”可以看到 OpenAI、Azure OpenAI、Anthropic、DeepSeek、通义千问等供应商选项。以 OpenAI-API-compatible 供应商为例通常需要填写API Key。Base URL。模型名称。配置完成后点击“测试”按钮Dify 会发送一个测试请求返回成功就说明模型接入可用。这里要提醒一点API Key 属于敏感信息建议用环境变量或 Dify 的密钥管理能力保存不要硬编码到业务代码中。5.2 接入 Ollama 本地模型如果想在本地运行模型推荐接入 Ollama。Ollama 是一个本地推理服务可以把模型跑在自己的机器或服务器上数据不出内网。先安装并启动 Ollama然后拉取一个模型作为示例# 拉取模型具体模型名以 Ollama 仓库为准 ollama pull qwen2.5:7b # 保持 Ollama 服务运行 ollama serve在 Dify 的“模型供应商”页面选择 Ollama填写API 地址如果 Ollama 和 Dify 在同一台机器可以填http://host.docker.internal:11434因为 Dify 本身跑在 Docker 容器中不能直接用localhost访问宿主机。模型名称填写刚才拉取的模型名例如qwen2.5:7b。上下文长度根据模型规格填写。填写完成后测试连接。这里最容易遇到的问题就是 Ollama 地址错误Dify 容器内访问宿主机不能写localhost需要写host.docker.internal或宿主机局域网 IP。5.3 模型接入后的验证无论接入云端模型还是本地模型都要先在模型供应商页面完成“测试”。测试成功后创建应用时才能选择到该模型。模型接入是后面所有智能体功能的地基。如果模型测试失败后面的应用创建、对话调试都会失败。6. 从零搭建第一个 Dify 智能体6.1 创建智能体应用在 Dify 主界面点击“创建空白应用”选择应用类型。智能体相关的主要类型有聊天助手适合多轮对话可以选择是否使用 Agent 能力。Agent适合需要调用工具、自主规划步骤的场景。工作流适合固定流程编排比如先检索知识库再调用模型。文本生成适合单次文本生成任务。选择“Agent”类型设置应用名称和描述选择已接入的模型即可进入编排界面。Agent 编排界面通常包含系统提示词。模型选择。工具配置。知识库挂载。对话调试区。6.2 为智能体添加知识库知识库是 Dify 很核心的功能。点击“知识库 → 创建知识库”上传文档Dify 会进行分段和清洗然后写入向量数据库。创建知识库的通用步骤创建知识库填写名称和描述。上传文档支持常见的文本、PDF、Markdown 等格式。设置分段规则决定文档如何切分。选择索引方式Dify 会调用嵌入模型生成向量。完成数据处理进入可用状态。知识库创建成功后在 Agent 应用的“知识库”区域添加该知识库智能体就能基于文档内容回答问题。这里需要注意嵌入模型的选择。接入 Ollama 本地模型时可以同时接入一个嵌入模型比如nomic-embed-text或bge-m3具体名称以 Ollama 仓库为准。如果知识库检索结果为空优先检查嵌入模型是否正常、文档分段是否合理。6.3 配置工具与提示词Agent 的威力在于工具调用。Dify 内置了一些工具比如网页搜索、计算器、天气查询等也可以接入自定义工具。在工具配置区域添加工具后Agent 会在对话中根据用户问题决定是否调用工具。系统提示词可以约束 Agent 的角色和行为例如你是一个企业知识库问答助手。 请根据知识库内容回答用户问题。 如果知识库中没有相关信息明确告知用户“未找到相关内容”不要编造答案。 回答时使用简洁、专业的中文。配置完成后在右侧调试区输入测试问题观察 Agent 的回复、工具调用记录和知识库引用情况。6.4 工作流模式的智能体如果业务逻辑是固定流程推荐使用工作流模式。工作流把智能体能力拆成节点节点之间按顺序连接。典型最小工作流开始节点接收用户输入。知识库检索节点根据用户问题从知识库检索相关文档。LLM 节点把检索结果和用户问题一起发送给模型生成回答。结束节点输出最终回答。工作流的优势是可调试、可复用。每个节点都可以单独配置参数运行后可以查看每个节点的输入输出定位问题时比黑盒 Agent 更直观。6.5 发布应用编排完成后点击“发布”按钮。发布后应用可以在 Web 界面直接访问也可以在“API 访问”页面获取 API 凭证供外部系统调用。7. Dify 接口 API 调用与批量任务扩展Dify 应用发布后对外提供标准的 HTTP API。这意味着你可以把智能体能力集成到自己的业务系统中或者写脚本批量处理任务。7.1 获取 API 凭证在应用的“API 访问”页面可以找到API 端点地址。API 密钥通常以app-开头。调用示例。不同应用类型的 API 端点不同。聊天助手类应用一般调用对话接口工作流应用调用工作流执行接口。具体端点地址以应用页面展示为准。7.2 聊天助手接口调用示例以下是一个通用的 Python 调用模板适用于 Dify 聊天助手类应用import requests url http://your-dify-host/v1/chat-messages headers { Authorization: Bearer app-xxxxxxxxxxxx, Content-Type: application/json } payload { inputs: {}, query: 请根据知识库介绍产品功能, response_mode: blocking, user: test-user, conversation_id: } response requests.post(url, jsonpayload, timeout120) if response.status_code 200: data response.json() print(data.get(answer, )) else: print(f请求失败: {response.status_code}) print(response.text)其中response_mode有两种常见取值blocking表示等待完整回答一次性返回streaming表示流式返回。生产环境通常建议流式模式提升用户感知速度。7.3 工作流接口调用示例工作流应用接口调用方式略有不同通用模板如下import requests url http://your-dify-host/v1/workflows/run headers { Authorization: Bearer app-xxxxxxxxxxxx, Content-Type: application/json } payload { inputs: { query: 需要处理的文本内容 }, response_mode: blocking, user: test-user } response requests.post(url, jsonpayload, timeout180) print(response.json())工作流接口返回值中会包含每个节点的输出便于在外部系统中提取结果。7.4 批量任务设计Dify 支持通过 API 批量调用智能体。批量任务的关键是要做好任务记录、失败重试和结果落库。一个通用的批量处理逻辑import time import requests def call_dify(query): url http://your-dify-host/v1/chat-messages headers { Authorization: Bearer app-xxxxxxxxxxxx, Content-Type: application/json } payload { inputs: {}, query: query, response_mode: blocking, user: batch-task } response requests.post(url, jsonpayload, timeout120) response.raise_for_status() return response.json() tasks [ 问题 1, 问题 2, 问题 3 ] results [] for i, task in enumerate(tasks): try: result call_dify(task) results.append({task: task, status: success, result: result.get(answer, )}) except Exception as e: results.append({task: task, status: failed, error: str(e)}) print(f任务 {i} 失败: {e}) time.sleep(0.5) print(results)批量任务建议注意几点控制并发数避免瞬间打满 API 配额。每批任务记录开始时间和结束时间。失败任务写入错误日志后续统一重试。处理结果落到文件或数据库方便复核。8. 资源占用与性能观察8.1 查看容器资源占用Dify 部署后可以用docker stats实时观察资源消耗docker stats该命令会输出每个容器的 CPU、内存、网络和磁盘占用情况。重点关注api、worker、db、redis和sandbox这几个服务的资源占用。如果 Dify 容器内存持续走高可能原因包括知识库文档处理占用内存、并发对话请求过多、模型供应商重试频繁。解决办法是重启对应服务或调整 docker-compose 中的资源限制。8.2 本地模型与平台资源的关系Dify 平台本身不消费显存显存消耗来自外部模型推理服务。如果接入的是 Ollama 等本地模型显存占用取决于模型参数量。上下文长度。并发请求数。量化方式。比如 7B 级别模型在量化后通常需要数 GB 显存未量化版本更高70B 级别模型需要数十 GB 显存。具体占用要以模型详情和本机测试为准建议先使用小模型验证全流程再决定是否升级到更大模型。8.3 降低资源占用的方向如果服务器资源有限可以从几个方向优化知识库文档不要一次上传过大文件分段上传。不使用的应用设置停止状态减少 Worker 空闲负载。降低模型供应商的并发重试。使用小参数模型完成基础流程验证。定期清理 Docker 未使用镜像和容器日志。8.4 端口冲突与进程残留如果修改端口后仍然无法访问检查是否有旧容器占用端口# 查看端口监听情况 sudo lsof -i :80 # 重启 Dify 服务 docker compose down docker compose up -d不要只 kill 进程Dify 有多个容器协作最稳妥的方式是用docker compose down完整停止再重新启动。9. Dify 常见问题与排查方法问题现象可能原因排查方式解决方案启动后页面打不开端口被占用或服务未启动检查docker compose ps和端口监听修改端口映射重启服务首次初始化失败数据库连接失败或环境变量配置错误查看db和api容器日志检查.env中数据库配置重建容器访问返回 502Nginx 或 API 服务未就绪查看nginx和api日志等待服务初始化完成检查资源是否充足模型供应商测试失败API Key 错误或网络不通检查密钥和供应商地址更换正确密钥确认网络可达Ollama 连接失败Docker 容器内无法访问宿主机 localhost查看 Ollama 日志和 Dify 模型配置改为host.docker.internal或宿主机 IP知识库检索结果为空嵌入模型异常或文档分段不合理查看知识库处理状态重新创建知识库更换嵌入模型创建应用后对话无响应模型未正确接入在模型供应商页执行测试修复模型接入后再创建应用接口调用返回 401API Key 错误或未发布检查请求头 Authorization重新复制应用中 API 密钥批量任务卡住并发过高或接口超时查看 api 容器日志降低并发增加超时时间10. Dify 最佳实践与使用建议10.1 先用最小配置跑通全流程第一次部署时不要一上来就配置复杂工作流。建议按以下顺序验证接入一个模型供应商完成模型测试。创建一个最简单的聊天助手应用。发布应用通过 API 调用一次。确认 Web 界面、API、数据库三个环节全部正常。这样一旦出现问题排查范围很小。10.2 数据和配置分目录管理Dify 的 Docker 部署会创建多个数据目录。建议在项目目录外单独备份.env文件包含密钥和数据库密码。PostgreSQL 数据卷。向量数据库数据卷。知识库上传的原始文档。定期备份这些数据可以避免容器重建导致数据丢失。10.3 API 服务的安全加固Dify 提供了 API 访问能力但暴露到公网时要做好安全措施API 密钥只分发给必要人员。通过反向代理配置 HTTPS。在反代层限制访问 IP。设置请求频率限制和超时时间。避免在日志中打印完整 API 密钥。10.4 知识库的内容治理知识库是 RAG 应用的核心。上传文档前先做敏感信息检查移除不必要的人个信息和版权内容。文档分段参数会影响检索效果建议用一小批测试文档验证后再批量上传。10.5 批量任务的工程化用 Dify API 做批量任务时不要只写一个for循环丢到生产环境。更稳妥的做法是将待处理任务写入数据库或消息队列。增加任务状态字段例如pending、processing、success、failed。失败任务自动重试重试次数超过阈值后告警。结果单独存储支持按批次溯源。11. 总结与下一步Dify 最值得先跑通的功能是模型接入 → 创建智能体 → API 调用。这三个环节打通后你就拥有了一个可以持续扩展的智能体应用底座。最容易踩的坑有三个一是 80 端口冲突导致页面打不开二是 Ollama 在 Docker 容器内访问宿主机时地址写错三是模型 API Key 泄漏到代码仓库。把这三点处理好部署体验会顺畅很多。下一步可以继续扩展的方向包括工作流自动化、多租户配置、知识库检索效果调优、接入自己的业务系统、通过 API 与其他开源工具联动。建议先部署一个测试环境把最小智能体跑通再根据业务需求逐步增加能力。