最近在尝试将AI能力集成到业务系统时发现从零构建一个智能应用涉及模型调用、提示工程、知识库管理等多个复杂环节开发周期长且门槛较高。Dify作为一款开源的LLM应用开发平台极大地简化了这一过程。本文将为你提供一份从零开始的Dify实战指南涵盖本地部署、核心概念解析、工作流搭建到企业级项目复现的全流程。无论你是想快速验证AI想法的新手还是寻求高效落地的开发者都能从中获得可直接复用的代码与配置。1. Dify 核心概念与价值在深入实操之前我们有必要理解Dify是什么以及它能解决什么问题。1.1 Dify 是什么Dify 是一个开源的 LLM大语言模型应用开发平台。它的核心目标是让开发者能够像“组装乐高”一样通过可视化编排的方式快速构建和部署基于大语言模型的 AI 应用而无需深入底层复杂的模型训练和接口调试。你可以把它理解为一个“AI应用工厂”。它提供了统一的界面来管理提示词Prompt、连接多种大模型如 GPT、Claude、国产模型、处理文件上传、构建知识库以及编排复杂的工作流。最终你可以将构建好的应用通过 API 或网页界面直接发布使用。1.2 为什么选择 Dify对于开发者和企业而言Dify 带来了几个显著的价值降低开发门槛无需从零编写复杂的模型调用、上下文管理、流式输出等代码通过可视化配置即可完成。提升开发效率将 AI 应用的核心组件模型、提示词、知识库、工作流模块化支持快速迭代和复用。统一管理能力在一个平台内管理多个模型供应商的密钥、监控应用的使用情况和成本。支持企业级需求提供知识库增强RAG、工作流编排、多模型路由等高级功能满足复杂业务场景。开源与可定制基于 Apache 2.0 协议开源支持私有化部署保障数据安全并能根据业务需求进行二次开发。1.3 核心功能模块Dify 主要包含以下功能模块理解它们有助于后续的实操应用Apps你构建的 AI 应用的载体分为“对话型”和“文本生成型”。提示词编排Prompt Engineering通过可视化界面调试和优化与大模型对话的指令和上下文。知识库Knowledge Base支持上传文本、PDF、Word 等文件通过向量化处理为模型提供外部知识来源实现基于文档的问答。工作流Workflow一个强大的可视化编排工具可以将模型调用、代码执行、条件判断、API 调用等多个节点连接起来构建复杂的自动化 AI 流程。模型供应商Model Providers集中配置 OpenAI、Anthropic、智谱AI、月之暗面等国内外主流模型的 API 密钥和端点。2. 环境准备与部署安装我们将以最常用的本地部署方式开始。部署是后续所有实践的基础。2.1 系统与环境要求操作系统本文以Linux (Ubuntu 20.04/22.04 LTS)为例这也是生产环境推荐的选择。Windows 和 macOS 也支持但通过 Docker 部署流程基本一致。Docker 与 Docker Compose这是部署 Dify 最简单的方式。请确保你的系统已安装Docker Engine 20.10.0 或更高版本Docker Compose 2.0.0 或更高版本硬件资源CPU至少 2 核。内存至少 4 GB。如果计划使用本地向量数据库或运行多个应用建议 8 GB 或以上。磁盘至少 20 GB 可用空间用于存放 Docker 镜像、数据库和上传的文件。网络能够访问 Docker Hub 和所需的模型 API如 OpenAI、国内模型平台。如果完全离线部署需要提前准备模型镜像。2.2 通过 Docker Compose 一键部署这是官方推荐且最快捷的部署方式。步骤 1下载部署配置文件打开终端创建一个目录并进入然后下载官方提供的docker-compose.yaml文件。# 创建并进入工作目录 mkdir dify cd dify # 下载 docker-compose 配置文件 curl -o docker-compose.yaml https://raw.githubusercontent.com/langgenius/dify/main/docker/docker-compose.yaml # 下载环境变量配置文件 curl -o .env https://raw.githubusercontent.com/langgenius/dify/main/docker/.env.example步骤 2配置环境变量编辑.env文件这是配置 Dify 的关键。你需要重点关注以下几个变量# 使用你喜欢的编辑器如 vim 或 nano vim .env# 设置一个安全的密钥用于加密会话等 SECRET_KEYyour_very_strong_secret_key_here_change_me # 指定 Dify 对外的访问地址本地测试可以设为服务器IP或localhost APP_URLhttp://localhost:3000 # 数据库配置通常使用默认即可 DB_PASSWORDdifyai123456 # 向量数据库配置默认为 Qdrant本地运行无需更改 VECTOR_STOREqdrant QDRANT_URLhttp://qdrant:6333 # 模型供应商配置以 OpenAI 为例你需要有自己的 API Key OPENAI_API_KEYsk-your-openai-api-key-here # 如果你想使用 Azure OpenAI则配置如下 # AZURE_OPENAI_API_KEYyour-azure-key # AZURE_OPENAI_ENDPOINTyour-azure-endpoint # AZURE_OPENAI_DEPLOYMENT_NAMEyour-deployment-name步骤 3启动 Dify 服务在dify目录下运行以下命令启动所有服务。sudo docker compose up -d这个命令会拉取 PostgreSQL、Redis、Qdrant向量数据库和 Dify 自身的镜像并以后台模式运行。首次启动可能需要几分钟时间下载镜像。步骤 4验证部署等待片刻后你可以通过以下命令查看容器状态sudo docker compose ps如果所有服务状态都是Up则部署成功。现在你可以在浏览器中访问http://你的服务器IP:3000如果在本机则是http://localhost:3000。首次访问会进入初始化页面设置管理员账号和密码之后即可登录到 Dify 控制台。2.3 常见部署问题排查问题现象可能原因解决方案访问localhost:3000连接被拒绝1. 容器尚未启动完成。2. 端口被占用。3. 防火墙规则限制。1. 等待片刻运行docker compose logs dify-api查看日志。2. 运行docker compose ps确认端口映射或修改docker-compose.yaml中的端口号如“3001:3000”。3. 检查服务器防火墙是否放行了3000端口。启动时提示SECRET_KEY相关错误.env文件中的SECRET_KEY未设置或太简单。确保.env文件中SECRET_KEY已设置为一个复杂的随机字符串。登录后无法加载应用或创建失败数据库连接问题或后端服务未完全就绪。1. 检查 PostgreSQL 容器日志docker compose logs db。2. 重启服务docker compose down docker compose up -d。上传文件到知识库失败存储卷权限问题或网络超时。1. 检查 Docker 卷的权限确保 Dify 容器有写入权限。2. 对于大文件尝试分批次上传。3. Dify 控制台核心功能初探成功登录后你会看到 Dify 的控制台界面。我们来快速熟悉一下核心区域。3.1 仪表盘与工作区首页仪表盘展示了应用数量、对话消息统计等信息。左侧是主导航栏应用创建和管理你的 AI 应用。工作流进入可视化工作流编排界面。知识库管理所有上传的文档和文本数据。工具管理自定义的 API 工具供工作流调用。日志与标注查看应用运行日志并对对话结果进行人工标注以优化模型。设置配置模型供应商、团队成员、权限等。3.2 创建你的第一个对话应用让我们通过一个简单的“智能客服助手”来上手。创建应用点击“应用” - “创建新应用”选择“对话型应用”输入名称“智能客服助手”。配置提示词进入应用后在“提示词编排”页面系统已经提供了一个默认的对话开场白。你可以在“系统提示词”区域输入角色设定例如你是一个专业的电商客服助手态度友好、耐心。请用中文回答用户关于订单、物流、退换货的问题。如果遇到无法回答的问题请引导用户联系人工客服。选择模型在右侧的“模型”区域选择你已配置的模型例如gpt-3.5-turbo。你可以在这里调整温度Temperature、最大生成长度等参数。预览与调试点击右上角的“预览”按钮在弹出的聊天窗口中尝试问一些问题如“我的订单到哪里了”。观察模型的回复是否符合预期。你可以随时修改提示词并重新测试。发布应用调试满意后点击“发布”。发布后你可以获得该应用的访问方式Web 访问地址一个独立的网页链接可以分享给他人使用。API 端点用于集成到你的其他系统或前端界面。至此你已经完成了第一个无需代码的 AI 应用搭建。但这只是开始Dify 更强大的能力在于知识库和工作流。4. 构建企业级知识库RAG应用单纯依赖模型的内置知识无法回答特定领域问题。知识库RAG功能通过检索增强生成让模型能够“阅读”你的私有文档并给出答案。4.1 创建与配置知识库新建知识库导航到“知识库” - “创建知识库”命名为“产品手册”。选择分词模型这是将文本转化为向量的关键。对于中文推荐选择text-embedding-3-small或BAAI/bge-small-zh-v1.5。前者是 OpenAI 的嵌入模型后者是开源模型。确保你拥有对应模型的 API 权限或在本地部署了该模型。上传文档支持文本、PDF、Word、Excel、PPT、Markdown 等格式。上传一份你的产品说明书 PDF。索引模式选择“高性能”或“高精度”。高性能模式检索快高精度模式召回结果更相关。初次创建选择“高性能”即可。上传后Dify 会在后台自动进行文本提取、分块Chunking、向量化并存储到 Qdrant 数据库中。你可以在知识库详情页看到处理状态。4.2 在应用中接入知识库回到刚才的“智能客服助手”应用编辑页面。在“提示词编排”页面的“上下文”区域勾选“知识库”。在下方关联步骤 4.1 中创建的“产品手册”知识库。你可以配置检索参数如“相似度阈值”控制检索相关度、“检索条数”等。现在你的客服助手不仅拥有通用对话能力还能基于你上传的产品手册回答具体问题。例如用户问“XX产品如何充电”模型会先从知识库中检索相关段落再结合这些信息生成回答。4.3 知识库优化技巧文档预处理上传前尽量保证文档格式清晰。对于扫描版 PDF最好先进行 OCR 文字识别。分块策略Dify 有默认分块规则但如果效果不佳可以尝试在“知识库设置”中调整“分段处理规则”如重叠Overlap大小让相邻文本块有一定交叉避免信息割裂。多知识库路由可以创建多个知识库如“内部规章”、“常见问题”并在工作流中根据问题类型动态选择检索哪个知识库实现更精细的控制。定期更新与清理文档更新后记得在知识库中重新执行“索引重建”以更新向量数据。清理不再使用的文档以节省资源。5. 可视化工作流Workflow高级编排工作流是 Dify 的“杀手锏”它允许你将复杂的 AI 逻辑图形化。我们以一个“智能工单分类与处理”为例。场景用户提交一段文本工单系统需要1. 判断工单类型技术问题、账单问题、投诉建议2. 根据类型提取关键信息3. 若是技术问题则从知识库检索解决方案4. 生成回复草稿。5.1 创建工作流导航到“工作流”点击“创建”。从左侧的节点库中将需要的节点拖拽到画布上。5.2 节点配置与连接我们将构建以下流程开始 - 工单文本输入 - LLM分类节点 - 条件判断节点 - (分支1:技术问题 - 知识库检索 - LLM生成回复) - (分支2:其他问题 - LLM直接回复) - 结束核心节点详解开始节点配置一个“文本”类型的输入变量命名为ticket_text。LLM 节点用于分类模型选择gpt-3.5-turbo。提示词请将以下用户工单分类为 [技术问题 账单问题 投诉建议] 中的一种。 工单内容{{ticket_text}} 只输出分类结果不要输出其他任何文字。输出变量命名为ticket_type。条件判断节点If-Else条件设置ticket_type等于技术问题。根据条件真假连接不同的下游分支。知识库检索节点在“技术问题”分支关联之前创建的“产品手册”知识库。查询文本{{ticket_text}}。输出变量命名为search_results。LLM 节点生成回复提示词在技术问题分支你是一名技术支持工程师。根据以下用户工单和知识库检索结果生成一份专业、清晰的回复。 用户工单{{ticket_text}} 知识库信息{{search_results}}提示词在其他问题分支你是一名客服专员。根据以下用户工单生成一份友好、得体的回复。 用户工单{{ticket_text}} 工单类型{{ticket_type}}输出变量命名为reply_draft。结束节点将reply_draft作为工作流的最终输出。5.3 调试与运行点击右上角的“运行”按钮在侧边栏的输入框中输入一段测试工单文本例如“我的设备无法连接Wi-Fi指示灯一直闪烁。” 点击运行你可以看到执行线沿着“技术问题”分支流转并最终输出结合了知识库信息的回复草稿。通过这个工作流我们实现了一个包含逻辑判断、知识检索和内容生成的自动化流程。你可以在此基础上继续扩展例如添加“发送邮件”节点需配置API工具将回复自动发送给客服人员。6. 模型管理与成本控制在企业环境中灵活使用多模型并控制成本至关重要。6.1 配置多个模型供应商在“设置” - “模型供应商”中你可以添加多个提供商。主流云厂商OpenAI, Azure OpenAI, Anthropic Claude, Google Gemini。国内模型智谱AIChatGLM、月之暗面Kimi、百度文心一言、阿里通义千问、讯飞星火等。开源模型通过 OpenAI 兼容的 API如 Ollama, vLLM, LocalAI接入本地部署的 Llama、Qwen 等模型。配置示例Ollama 本地模型在服务器上使用 Ollama 运行一个模型ollama run qwen:7b。在 Dify 中添加模型供应商选择“其他 OpenAI 兼容服务”。填写名称如Local-OllamaAPI 基址为http://localhost:11434/v1Ollama 默认地址API Key 可留空。保存后即可在应用或工作流的模型选择列表中看到本地模型。6.2 负载均衡与故障转移在“模型负载均衡”设置中你可以为同一模型如gpt-3.5-turbo配置多个 API Key可能来自不同账号或地区。Dify 会自动在它们之间进行负载均衡并在某个 Key 达到速率限制或失效时自动切换到其他可用的 Key提高服务的稳定性和可用性。6.3 使用量监控与成本估算在“日志与标注” - “使用统计”中可以查看所有应用、所有模型在不同时间段的 Token 消耗情况。结合模型供应商的定价你可以大致估算出 API 调用成本。这对于预算管理和优化提示词减少不必要的 Token 消耗非常有帮助。7. API 集成与前端部署构建好的应用最终需要集成到业务系统中。7.1 调用应用 API每个已发布的应用都提供了标准的 API。在应用发布页面找到“API 访问”部分。你会看到API Endpoint和API Key。使用任何 HTTP 客户端如 curl, Postman或代码即可调用。示例使用 cURL 调用对话应用curl -X POST \ https://api.dify.ai/v1/chat-messages \ -H Authorization: Bearer YOUR_APP_API_KEY \ -H Content-Type: application/json \ -d { inputs: {}, query: 你好请介绍一下你自己。, response_mode: streaming, # 或 blocking conversation_id: , user: user-123 }示例在 Python 项目中集成import requests def ask_dify_app(question, api_key, app_endpoint): url f{app_endpoint}/chat-messages headers { Authorization: fBearer {api_key}, Content-Type: application/json } data { inputs: {}, query: question, response_mode: blocking, user: test_user_id } response requests.post(url, jsondata, headersheaders) return response.json() # 使用 answer ask_dify_app(今天天气怎么样, your-app-api-key, https://api.dify.ai/v1) print(answer[answer])7.2 嵌入聊天窗口到自有网站Dify 为每个应用生成了可嵌入的 JavaScript 代码片段。在应用发布页面找到“站点嵌入”部分。复制提供的script标签代码。将其粘贴到你网站 HTML 的body标签结束前。页面上会自动出现一个可拖动的聊天悬浮按钮用户点击即可与你的 AI 应用交互。这种方式无需后端开发即可快速为网站添加智能客服或助手功能。8. 生产环境最佳实践与安全建议将 Dify 用于实际业务时需要考虑以下方面数据安全与隐私私有化部署对于敏感数据务必采用本文所述的本地部署方案确保数据不出域。网络隔离将 Dify 部署在内网环境通过反向代理如 Nginx提供对外 HTTPS 访问。API 密钥管理不要在代码或配置文件中硬编码 API Key。使用环境变量或专业的密钥管理服务。Dify 自身的模型密钥也应定期轮换。高可用与备份数据库持久化确保 Docker 卷正确映射到宿主机持久化目录避免容器重启数据丢失。定期备份 PostgreSQL 和 Qdrant 数据。多实例部署对于高并发场景可以考虑部署多个 Dify 后端实例并通过负载均衡器分发请求。监控与告警监控服务器资源CPU、内存、磁盘、Docker 容器状态以及 Dify 应用的关键接口健康度。性能优化向量数据库调优对于大规模知识库数十万条以上考虑使用性能更好的向量数据库如 Weaviate, Milvus并单独部署在.env中修改VECTOR_STORE配置。缓存策略利用 Redis 缓存频繁访问的提示词模板或中间结果。Dify 内部已使用 Redis 进行会话缓存。提示词优化精简系统提示词和上下文避免携带过多无关历史消息以节省 Token 消耗并提升响应速度。应用迭代与管理版本控制Dify 应用配置本身缺乏 Git 式的版本管理。重要的提示词和工作流配置建议在平台外使用文本文件进行备份和版本控制。权限分级在团队设置中为不同成员分配“所有者”、“管理员”、“编辑者”、“只读者”等角色实现权限隔离。A/B 测试对于关键应用可以克隆创建不同版本如使用不同提示词或模型通过分析日志和人工标注来对比效果持续迭代优化。从本地部署、创建第一个对话机器人到构建结合私有知识库的 RAG 应用再到使用可视化工作流编排复杂业务逻辑Dify 提供了一条从原型到生产的快速路径。它并未取代深度开发而是将开发者从重复的底层整合工作中解放出来更专注于业务逻辑和 AI 能力的设计。建议你按照本文步骤亲手操作一遍遇到问题多查阅官方文档和社区。接下来可以尝试将公司内部的流程手册、产品文档导入知识库或者用工作流自动化一个具体的审批或分析任务在实践中不断深化理解。