手把手教你部署Dify，5分钟搞定AI应用

一、学习目标

1. 掌握 Dify 开发平台核心概念与能力
2. 学会 Dify 两种本地化部署方式及日常使用
3. 完成 4 个实战案例：LLM 联网搜索、古诗词 WorkFlow、智能客服 ChatFlow、智能文档分析助手（MinerU+Dify）
4. 掌握 Agent API 应用方法（Coze、Dify）

二、Dify 开发平台

2.1 平台定义

Dify 是开源的 LLM 应用开发平台，提供 Agent 构建、AI workflow 编排、RAG 检索、模型管理等能力，可快速构建生成式 AI 原生应用，比 LangChain 更易上手。

2.2 五种应用类型

应用类型	核心能力	适用场景
聊天助手	基于 LLM 实现对话式交互	基础智能问答、日常对话助手
文本生成应用	专注文本生成类任务	故事撰写、文本分类、翻译等
Agent	任务分解、推理思考、工具调用	复杂任务处理、多工具协同
对话流（Chatflow）	多轮对话、记忆功能、动态编排	智能客服、AI 助教、引导式机器人
工作流（Workflow）	自动化、批处理、单向生成	无实时交互的数据处理、内容生成、系统集成

三、Dify 部署

本地化部署有 Docker Compose（推荐） 和源代码部署两种方式。

3.1 部署前提

1. 安装 Docker 和 Docker Compose：https://www.docker.com（选择对应系统 Docker Desktop）
2. 安装 Git：用于克隆 Dify 代码仓库
3. 核心工具：
   • Docker：开源容器引擎，打包应用及依赖，保证跨环境一致
   • Docker Compose：通过 YAML 配置多容器服务，单命令启动

3.2 Docker Compose 部署步骤

Step1：克隆代码仓库

git clone https://github.com/langgenius/dify.git

Step2：进入 Docker 目录并配置环境变量

cd dify/docker
cp .env.example .env

关键配置项：

• APP_URL：Dify 访问地址（本地为 http://localhost 或服务器 IP）
• 数据库配置：默认使用 Docker 内置数据库，外部数据库需单独配置
• 模型供应商 API Keys：OpenAI、Anthropic、Qwen 等（必填，否则无法调用模型）

Step3：启动服务

docker compose up -d

• -d：后台运行

Step4：访问并初始化

1. 访问 http://你的IP地址/install，设置管理员账户
2. 初始化完成后，访问 http://你的IP地址 进入主页面

3.3 后续管理

1. 更新 Dify（在 dify/docker 目录下）：

git pull
docker compose pull
docker compose up -d

2. 重启服务：

docker compose up -d

3.4 使用入口

1. 本地部署：http://部署服务器IP:端口/signin（需先初始化管理员）
2. 官方云服务：https://cloud.dify.ai/apps（开箱即用，支持付费套餐）

四、Chatflow 与 Workflow 核心区别

4.1 对话流（Chatflow）

1. 核心特性：对话式交互、上下文记忆、动态响应、流式输出、用户交互增强（开场白、问题建议等）
2. 专属节点：Answer 节点（中间步骤流式输出文本）
3. 适用场景：智能客服、语义搜索、AI 助教、多轮引导式对话

4.2 工作流（Workflow）

1. 核心特性：自动化批处理、单轮执行、无实时交互、复杂流程编排
2. 适用场景：数据处理分析、批量内容生成、系统集成、无交互工具链

五、实战案例

5.1 案例 1：LLM 联网搜索

目标：用户输入问题 → AI 提取关键字 → Tavily 搜索 → 结果总结

前期准备

1. 申请 Tavily Search API Key：https://tavily.com/
2. 在 Dify 中安装 Tavily 工具（市场插件：langgenius/tavily）
3. 对 TavilySearch 工具进行 API Key 授权

工作流搭建

1. 开始节点：设置 input 变量，接收搜索主题
2. LLM 节点：提取关键字（系统提示词：提取关键字，空格隔开；用户提示词：关联 input）
3. TavilySearch 节点：执行搜索（查询变量关联 LLM 节点 text 输出）
4. LLM2 节点：总结搜索结果（系统提示词：总结整理搜索内容；用户提示词：关联 TavilySearch 输出）
5. 结束节点：设置 output 变量，关联 LLM2 的 text 输出

实战成果

以 “黄金价格和哪些因素有关” 为例，输出包含影响因素（实际利率、地缘政治、通胀、央行购金等）、历史趋势、未来预测的结构化报告。

打卡要求

1. 掌握 TavilySearch 插件安装与授权
2. 掌握大模型在 “关键字提取” 和 “结果总结” 中的用法

5.2 案例 2：古诗词 WorkFlow

目标：输入古诗 → AI 描绘画面 → 翻译英文提示词 → 调用绘图工具生成图像

绘图工具准备

Dify 不提供绘图工具，需集成外部工具：

1. 官方工具：DALL-E（Dify 第一方工具）
2. 开源模型：Stable Diffusion、Flux（通过 SiliconFlow 调用）
3. 关键操作：申请 SiliconCloud API Key，在 Dify 工具页授权

工作流搭建

1. 开始节点：设置 input 变量，接收古诗词
2. LLM 节点（qwen-turbo）：描绘画面（提示词：请描绘一幅画面）
3. LLM2 节点（qwen-turbo）：翻译英文（提示词：翻译成英文，前面加 acient china）
4. Flux 节点（SiliconFlow）：生成图像（提示词关联 LLM2 输出，尺寸 1024x1024）
5. 结束节点：关联 Flux 输出（text、files、json）

实战示例

输入 “离离原上草”→ 生成中文画面描述 → 翻译为带 acient china 的英文提示词 → Flux 生成草原图像。

打卡要求

搭建文生图工作流，包含图片描述、翻译、text2image 三个核心节点。

5.3 案例 3：智能客服 ChatFlow

目标：多分类智能客服，实现营销咨询自动解答、投诉精准响应、其他问题友好回复。

客服分类配置

1. 营销专员：配置证券知识库，解答产品、交易规则等高频问题
2. 投诉专员：配置用户行为数据、用户标签，提取关键信息并解答
3. 其他问题：固定回复 “抱歉，这些问题我无法回答”

ChatFlow 搭建

Step1：问题分类器节点（qwen-turbo-latest/Qwen3）

3 个分类：营销咨询（证券知识）、投诉处理（产品使用不成功）、其他问题

Step2：营销咨询分支

1. 知识检索节点：配置证券知识库（需先创建上传文件），查询变量关联 sys.query，检索设置：高质量・向量检索
2. LLM 节点（qwen-turbo-latest）：基于知识库回答，不知则说不知，避免提及上下文来源
3. 直接回复节点：返回 LLM 回答

Step3：投诉处理分支

1. LLM 节点：提取关键信息（user_id、event_time 日期格式、event_type 固定枚举，无信息设为 null）
2. 知识检索节点：检索用户数据（上传 user_behavior_event.xlsx、user_tag.xlsx），混合检索（语义+关键词），适当扩大 TopK
3. LLM 节点（qwen-turbo-latest）：共情解答（定位专业投诉顾问，共情安抚、核查信息、筛选匹配 user_id 数据、≤200 字）
4. 直接回复节点：返回回答

Step4：其他问题分支

直接回复节点，固定输出 “抱歉，这些问题我无法回答”

知识库配置要点

1. 文件上传：支持 TXT、PDF、DOCX、XLSX，单文件≤15MB
2. 分段设置：结构不佳文本预设强分隔符；最大长度匹配模型窗口，重叠度建议 10-20%
3. 索引模式：“高质量” 适合专业内容，切换需重索引（成本高）
4. 检索配置：
   • Embedding 模型：text-embedding-v1（更换需重新向量化）
   • Rerank 模型：gte-rerank（提升相关性，增加延迟和成本）
   • TopK：3，Score 阈值：0.5（需按模型调优）
   • 检索方式：混合检索（向量+全文）为推荐

实战示例

1. 营销问题：“什么是竞价盘？”→ 证券知识库返回专业解答
2. 投诉问题：“我的用户 id:7501690985227960354，我在 5 月 4 日登录了软件，但是没有成功”→ 提取信息 → 检索行为数据 → 给出失败原因和解决方案

打卡要求

1. 使用 ChatFlow 实现意图识别（3 类分类）
2. 完成证券知识库、用户行为/标签数据表准备与配置
3. 实现营销自动解答和投诉精准响应

5.4 案例 4：智能文档分析助手（MinerU+Dify）

目标：上传科研论文 PDF → MinerU 解析 → LLM 基于解析内容回答问题

核心工具

MinerU：专业文档解析工具，可提取 PDF 中的图表、公式、多栏排版，通过 API 封装为 Dify 插件。

工作流搭建

Step1：设置输入变量

1. uploaded_pdf：单文件类型，支持 PDF，显示名 “请上传 PDF 文件”
2. user_question：文本类型，最大 100 字，显示名 “请输入您的问题”（必填）

Step2：MinerU 插件节点

• Base URL：https://mineru.net
• Token：从 https://mineru.net/apiManage/token 获取
• 功能：解析 uploaded_pdf，输出 text 内容

Step3：LLM 节点（qwen-turbo）

• 系统提示词：作为论文助手，基于解析全文回答问题
• 用户提示词：关联 user_question
• 上下文：关联 MinerU 节点 text 输出

Step4：结束节点

设置 output 变量，关联 LLM 节点 text 输出

实战示例

上传 INTERNVIDEO2.5.pdf，提问 “论文的实验结果怎么样？”→ MinerU 解析 → LLM 输出结构化总结（含模型性能、基准提升、视觉能力增强等）。

打卡要求

1. 掌握 MinerU 插件配置（Base URL、token 获取）
2. 实现 “PDF 解析 → 上下文 → LLM 回答” 完整工作流

六、Agent API 应用（Coze + Dify）

6.1 Coze API（基于 cozepy）

cozepy 是 Coze 官方 Python SDK，支持同步/异步、流式输出、分页查询。

前期准备

1. 获取 API Token：https://www.coze.cn/open/oauth/pats（设置权限和过期时间）
2. 获取智能体 ID：从智能体详情页 URL 提取（如 7507272032905199655）

代码实现

1. 初始化客户端

import os
from cozepy import Coze, TokenAuth, COZE_CN_BASE_URL

coze_api_token = "your_api_token_here"
coze_bot_id = "your_bot_id_here"

coze = Coze(auth=TokenAuth(token=coze_api_token), base_url=COZE_CN_BASE_URL)

2. 普通聊天（非流式）

from cozepy import ChatStatus

chat_poll = coze.chat.create_and_poll(
    bot_id="your_bot_id",
    user_id="user_123",
    additional_messages=[Message.build_user_question_text("你好")]
)

if chat_poll.chat.status == ChatStatus.COMPLETED:
    for message in chat_poll.messages:
        if message.role == "assistant" and message.content:
            print(f"智能体回复: {message.content}")

3. 流式聊天（推荐）

from cozepy import Message, ChatEventType, MessageContentType

for event in coze.chat.stream(
    bot_id="your_bot_id",
    user_id="user_123",
    additional_messages=[Message.build_user_question_text("你好，请介绍一下你自己")]
):
    if event.event == ChatEventType.CONVERSATION_MESSAGE_DELTA:
        if hasattr(event.message, 'content') and event.message.content:
            if event.message.content.type == MessageContentType.TEXT:
                print(event.message.content.text, end="", flush=True)

实战案例：古诗词绘画 Coze API

1. 在 config.py 配置 TOKEN、BOT_ID、BASE_URL
2. 实现流式接收，支持模式切换（流式/普通）、退出、查看智能体信息
3. 输入 “离离原上草”，获取画面描述 + 英文翻译 + 生成图像

打卡要求

1. 掌握 cozepy 安装与使用
2. 完成核心步骤：获取 Token → 获取智能体 ID → 初始化客户端 → 调用聊天接口（普通/流式）

6.2 Dify API

Dify 为不同应用类型提供专属 API 端点，通过 API Key 验证。

基础准备

1. 获取 API Key：进入应用 → 访问 API → 右上角 “创建密钥”（避免前端明文引用）
2. API Base URL：每个应用的专属基础地址
3. 目录结构

├── dify_agent_client.py      # 核心客户端类（封装API调用）
├── dify_workflow_example.py  # 工作流调用示例
├── requirements.txt          # 依赖包
└── README.md                 # 使用说明

核心客户端类（DifyAgentClient）

class DifyAgentClient:
    def __init__(self, base_url: str, api_key: str):
        self.base_url = base_url.rstrip('/')
        self.api_key = api_key
        self.headers = {
            'Authorization': f'Bearer {api_key}',
            'Content-Type': 'application/json',
            'Accept': 'application/json'
        }

三大 API 端点

端点类型	接口地址	核心特性	适用应用类型
聊天应用	/chat-messages	多轮对话（conversation_id）、流式/阻塞	聊天助手、Chatflow
完成应用	/completion-messages	单次任务、无对话状态	文本生成应用
工作流应用	/workflows/run	需先发布、inputs 传参、复杂逻辑	Workflow

智能应用类型检测

按聊天 → 完成 → 工作流顺序尝试调用，根据错误码判断类型，实现容错：

def chat_completion(self, user_input: str, app_type: str = "auto"):
    if app_type == "auto":
        # 尝试聊天端点
        result = self._try_chat_endpoint(...)
        if "not_chat_app" in result.get("message", ""):
            # 尝试完成端点
            result = self._try_completion_endpoint(...)
            if "app_unavailable" in result.get("message", ""):
                # 尝试工作流端点
                return self._try_workflow_endpoint(...)

工作流调用示例

def simple_workflow_example():
    BASE_URL = "你的Dify URL"
    API_KEY = "你的API KEY"

    client = DifyAgentClient(BASE_URL, API_KEY)

    # 调用LLM联网搜索工作流
    user_input = "黄金价格和哪些因素有关"
    result = client.run_workflow(inputs={"input": user_input}, user_id="demo_user")
    print(result)

打卡要求

1. 掌握三大 API 端点调用方式和适用场景
2. 实现 Dify 应用类型智能检测