第14章 Dify入门：开源可私有化部署的智能体平台搭建

Dify入门：开源可私有化部署的智能体平台搭建

Dify是一款开源的LLM应用开发平台，也是目前最受欢迎的开源智能体平台之一。与Coze不同，Dify支持私有化部署——你可以把它安装在自己的服务器上，数据完全在自己的控制范围内。这对于对数据安全有要求的企业（如制造业、金融、政府）来说，是非常重要的特性。

本章将带你从零开始，学习Dify的安装部署、基本配置和第一个智能体应用的搭建。

一、Dify平台概览

1.1 Dify的核心功能

1.2 Dify的应用类型

Dify支持多种应用类型，适合不同的场景：

• 聊天助手（Chatbot）：最基础的对话型应用，适合客服、问答、助手等场景
• Agent：具备工具调用能力的自主智能体，可以自主规划和执行复杂任务
• 工作流（Workflow）：可视化编排的多步骤流程应用，适合标准化、复杂的业务流程
• 文本生成（Text Generator）：根据输入生成文本的应用，适合文案生成、报告生成、翻译等场景
• Chatflow：聊天+工作流的混合模式，在对话中嵌入工作流节点

1.3 Dify vs Coze

二、Dify的安装部署

2.1 部署方式选择

Dify支持多种部署方式：

初学者建议：先用Dify Cloud（https://cloud.dify.ai）免费体验，熟悉功能后再用Docker Compose私有化部署。本章主要介绍Docker Compose部署方式。

2.2 Docker Compose部署步骤

前置要求：

• 服务器配置：至少2核4G内存（推荐4核8G以上），40G以上磁盘空间
• 操作系统：Linux（Ubuntu/CentOS）、macOS、Windows（WSL2）
• 已安装Docker和Docker Compose
• 有公网IP或域名（需要访问大模型API）

部署步骤：

# 第一步：克隆Dify代码库
git clone https://github.com/langgenius/dify.git
cd dify/docker

# 第二步：复制环境变量配置文件
cp .env.example .env

# 第三步：编辑配置文件（可选，修改端口、密钥等）
vim .env
# 主要配置项：
# - EXPOSE_NGINX_PORT=80 （Web访问端口）
# - EXPOSE_NGINX_SSL_PORT=443 （SSL端口）
# - SECRET_KEY= （加密密钥，自动生成，也可以手动设置）

# 第四步：启动服务
docker compose up -d

# 第五步：查看服务状态
docker compose ps
# 确认所有服务状态都是running（约10个服务：nginx、api、worker、web、db、redis、weaviate等）

# 第六步：访问Dify
# 在浏览器中打开 http://你的服务器IP 或 http://localhost
# 首次访问会引导你创建管理员账号

常见问题排查：

• 服务启动失败：用docker compose logs查看日志，常见原因是端口被占用、内存不足、镜像拉取失败
• 无法访问大模型API：检查服务器网络是否能访问模型API（如OpenAI需要海外网络），在"模型供应商"中正确配置API Key
• 知识库上传失败：检查磁盘空间、文件大小限制、向量数据库（Weaviate）服务状态
• 页面加载慢：检查服务器配置，建议至少4核8G；检查网络带宽

2.3 初始配置

部署完成后，首次登录需要进行以下配置：

1. 创建管理员账号：设置邮箱和密码，这是系统的超级管理员
2. 配置模型供应商：进入"设置"→"模型供应商"，添加你要用的大模型。支持OpenAI、Anthropic、Azure OpenAI、百度文心、阿里通义、腾讯混元、智谱AI、DeepSeek、月之暗面等，也可以自定义OpenAI兼容的接口（如本地部署的Ollama、vLLM）
3. 设置默认模型：配置好模型后，设置默认的推理模型、Embedding模型、Rerank模型
4. 配置系统参数：在设置中可以配置文件上传大小限制、知识库分段默认参数、邮件通知等

三、实战：在Dify上搭建"制造业知识库问答助手"

部署和配置完成后，让我们通过一个实战案例，学习如何在Dify上搭建第一个智能体应用。我们要做的是一个"制造业知识库问答助手"——上传企业的设备手册、工艺规范、安全规程等文档，员工可以用自然语言提问，智能体基于知识库给出准确回答。

第一步：创建知识库

1. 在Dify工作台，点击左侧"知识库"→"创建知识库"
2. 填写知识库名称："制造业知识库"，描述："包含设备手册、工艺规范、安全规程等企业技术文档"
3. 选择检索设置：
   • 检索方式：混合检索（推荐）
   • Embedding模型：选择你配置的Embedding模型（如text-embedding-3-small）
   • 召回数量：5
   • 相似度阈值：0.5
   • Rerank模型：如果配置了Rerank模型，开启它，效果更好
4. 点击"创建"，知识库就创建好了

第二步：上传文档

1. 进入刚创建的知识库，点击"上传文档"
2. 选择要上传的文档（支持PDF、Word、Excel、PPT、txt、markdown、HTML等格式，也可以上传网页链接）
3. 设置分段策略：
   • 自动分段：Dify自动按语义分段，适合大多数文档
   • 自定义分段：可以设置分段标识符（如按标题分段）、分段大小、重叠长度

   建议：技术文档（如设备手册）用自定义分段，按标题分段，分段大小设为500，重叠50；普通文档用自动分段即可。

4. 点击"保存并处理"，Dify开始解析文档、分段、向量化（这个过程可能需要几分钟，取决于文档大小和数量）
5. 处理完成后，可以在文档列表中查看每个文档的分段数、状态
6. 点击文档可以查看分段详情，检查分段是否合理，也可以手动编辑或禁用某些分段

文档上传建议：

• 先上传2-3份典型文档测试效果，确认分段和检索效果满意后再批量上传
• 文档质量很重要——清晰、结构化、内容完整的文档效果好；扫描件、模糊图片、内容混乱的文档效果差
• 定期更新知识库，添加新文档，更新过时内容

第三步：创建应用

1. 回到工作台，点击"创建应用"→选择"聊天助手"
2. 填写应用信息：
   • 名称：制造业知识库问答助手
   • 描述：基于企业技术文档的智能问答助手，帮助员工快速查询设备操作、工艺规范、安全规程等信息
   • 图标：选择合适的图标
3. 点击"创建"，进入应用配置页面

第四步：配置提示词

在"提示词编排"区域，编写系统提示词：

你是一位制造业企业的知识管理专家，熟悉设备操作、工艺规范、安全规程等技术文档。
你的任务是基于企业知识库中的文档，准确回答员工的问题。

## 工作规则
1. 必须基于知识库中的文档内容回答，不要使用文档以外的知识
2. 如果知识库中没有相关信息，明确说"根据现有知识库无法回答这个问题，建议咨询技术部门或查阅相关手册"，不要编造
3. 回答要准确、专业、有条理，引用文档中的具体内容
4. 涉及安全操作时，必须强调安全注意事项和操作规程
5. 如果问题不清晰，先向用户询问更多信息，不要盲目回答
6. 回答末尾标注信息来源（文档名称和章节）

## 回答格式
## 答案
（基于知识库的回答，分点列出）

## 信息来源
- 《文档名称》- 章节名称

## 补充建议
（如果有，给出进一步的建议或指引）

第五步：关联知识库

1. 在应用配置页面，找到"上下文"区域，点击"添加"→选择"知识库"
2. 选择我们刚才创建的"制造业知识库"
3. 配置检索参数（可以用知识库的默认设置，也可以单独配置）
4. 确认关联后，知识库就会出现在上下文列表中

重要：在提示词中要明确告诉大模型"基于上下文（知识库）回答"。Dify会自动把检索到的知识库内容插入到提示词的{{context}}变量中。

第六步：配置模型和参数

• 模型：选择能力较强的模型（如GPT-4o、Claude 3.5、DeepSeek-V3等），知识库问答对模型理解能力要求较高
• 温度（Temperature）：设为0.1-0.3，知识库问答需要准确性，低温度更稳定
• 最大回复长度：根据需要设置，一般1024-2048足够
• Top P：默认0.7即可
• 频率惩罚/存在惩罚：默认0即可

第七步：添加工具（可选）

如果需要，可以给应用添加工具，扩展能力：

• 网页搜索：当知识库中没有答案时，可以搜索网络补充
• 代码执行：需要做计算或数据处理时使用
• 自定义API工具：对接企业内部系统（如设备管理系统、工单系统）

注意：工具不是越多越好，只添加真正需要的。对于纯知识库问答，可能不需要任何工具。

第八步：调试和测试

在右侧的"预览和调试"窗口中，测试应用的效果：

1. 基础测试：问一个知���库中有明确答案的问题，检查回答是否准确、是否标注来源
2. 检索测试：点击对话中的"引用"图标，查看检索到了哪些文档片段，是否相关
3. 边界测试：问一个知识库中没有的问题，检查是否如实说明"无法回答"，而不是编造
4. 安全测试：问涉及危险操作的问题，检查是否强调安全注意事项
5. 多轮测试：进行多轮对话，检查上下文理解是否正确

调试技巧：

• 如果回答不准确，先检查检索结果是否相关——检索不到是知识库问题，检索到但回答没用是提示词问题
• 如果检索不到相关内容，检查文档分段是否合理、检索参数是否正确、文档是否处理成功
• 如果回答格式不对，在提示词中加强格式约束，或给出示例
• 每次只改一个地方（提示词/检索参数/模型），观察效果变化

第九步：发布应用

测试满意后，点击右上角"发布"按钮：

• 发布为Web应用：Dify会生成一个独立的网页链接，可以分享给员工使用
• 嵌入网站：生成嵌入代码，可以把聊天助手嵌入到企业官网或内部系统中
• API访问：生成API密钥，可以通过API调用应用，集成到其他系统中
• 发布到应用目录：在Dify内部的应用目录中发布，团队成员可以直接使用

初学者建议：先发布为Web应用，生成链接测试使用。确认没问题后再考虑嵌入或API集成。

第十步：监控和持续优化

发布后，在"日志与监控"中查看应用的使用情况：

• 对话日志：查看每一次对话的用户问题、AI回答、检索结果、用户反馈
• 用户反馈：查看用户的点赞/点踩，重点关注点踩的对话，分析原因并优化
• 性能统计：查看调用次数、平均响应时间、成功率等指标
• 知识库命中率：查看有多少对话命中了知识库，命中率低说明知识库需要补充或优化

持续优化是一个长期过程——定期查看日志，发现问题，优化提示词、知识库、检索参数，不断提升回答质量。

四、Dify使用技巧

4.1 提升RAG效果的技巧

• 文档质量优先：RAG效果的上限由文档质量决定。花时间整理高质量、结构化的文档，比调参数更有效。
• 启用Rerank：如果有Rerank模型（如Cohere Rerank、Jina Reranker），一定要开启。Rerank能显著提升检索精度。
• 混合检索：同时使用向量检索和全文检索（BM25），兼顾语义理解和精确匹配。
• 查询改写：在Dify中可以开启"查询改写"功能，用大模型把用户问题改写成更适合检索的查询。
• 元数据过滤：给文档添加元数据（如设备类型、文档类型、部门），在检索时可以基于元数据过滤，提高准确性。

4.2 提示词优化技巧

• 明确约束：在提示词中明确"必须基于上下文回答，不要编造，上下文没有就说明"。这是防止幻觉的关键。
• 标注来源：要求回答中标注信息来源，提升可信度，也方便验证。
• 角色具体：角色定义要具体（"有10年经验的制造业知识管理专家"比"知识助手"好）。
• 格式固定：用模板约束输出格式，确保回答结构一致。
• 异常处理：明确各种异常情况的处理方式（信息不足、问题不清晰、涉及危险操作等）。

4.3 成本优化技巧

• 选择合适的模型：简单任务用小模型（如GPT-3.5、DeepSeek-V2），复杂任务用大模型。不要所有任务都用最贵的模型。
• 控制上下文长度：检索结果不要太多（3-5条足够），减少传入大模型的token数。
• 优化提示词：提示词要精简，去掉不必要的内容。
• 缓存重复查询：对于常见问题，可以缓存回答，避免重复调用大模型。
• 监控用量：定期查看模型调用量和费用，发现异常及时调整。

下一章，我们将深入学习Dify的进阶功能——Agent模式、工作流编排、工具开发、API集成、多租户管理等，构建更复杂的企业级智能体应用。

📝 本章练习（5题）

答案与解析请在 互动学习看板 中作答查看。

📚 AI智能体实战训练营 课程目录（33 章）

1. 第1章 什么是AI智能体：从聊天机器人到自主决策系统
2. 第2章 智能体的四大核心能力：感知·思考·行动·记忆
3. 第3章 范式转移：智能体与传统软件的本质区别
4. 第4章 2025年主流智能体平台全景对比与选型
5. 第5章 智能体应用场景地图：从个人效率到企业级落地
6. 第6章 编排思维：如何把大模型变成可执行的业务流程
7. 第7章 Prompt工程实战：写出让智能体精准执行的指令
8. 第8章 工作流编排入门：节点、连线、条件分支与循环
9. 第9章 知识库RAG实战：让智能体拥有你的专业数据
10. 第10章 工具调用实战：搜索·计算·API·数据库全掌握
11. 第11章 多智能体协作：角色分工、任务分发与结果汇总
12. 第12章 Coze/扣子入门：30分钟搭建你的第一个智能体
13. 第13章 Coze进阶：插件开发、工作流深度编排与知识库优化
14. 第14章 Dify入门：开源可私有化部署的智能体平台搭建
15. 第15章 Dify进阶：RAG管道优化、Agent模式与工作流编排
16. 第16章 LangChain入门：用代码构建可定制的智能体应用
17. 第17章 LangChain实战：自定义Agent、工具链与记忆系统
18. 第18章 Agent Harness与新一代框架：2025年智能体开发趋势
19. 第19章 平台选型决策树：不同业务场景下的最优平台选择
20. 第20章 任务拆解方法论：把复杂问题变成智能体可执行的步骤
21. 第21章 提示词编排艺术：System·User·Function的三层协同
22. 第22章 记忆系统设计：短期记忆、长期记忆与向量数据库选型
23. 第23章 错误处理与容错：智能体执行失败时的兜底策略
24. 第24章 评估与优化体系：如何量化衡量智能体的效果并持续改进
25. 第25章 安全与合规：智能体应用的数据安全、隐私保护与风险防控
26. 第26章 实战项目一：企业知识库智能问答助手（全流程实操）
27. 第27章 实战项目二：制造业设备故障诊断智能体
28. 第28章 实战项目三：供应链采购智能分析与比价助手
29. 第29章 实战项目四：多智能体协同的项目管理办公室（PMO）
30. 第30章 实战项目五：智能体与MES/ERP系统的深度集成
31. 第31章 智能体落地路线图：从POC验证到规模化应用的完整路径
32. 第32章 AI智能体工程师/产品经理的能力模型与成长路径
33. 第33章 作品集打造与面试准备：如何拿到AI智能体岗位Offer