🚀 30+款热门AI模型一站整合,DeepSeek/GLM/Qwen 随心用,限时 5 折。 👉 点击领海量免费额度

这次我们来看一个关于 Dify 的实战教程项目。Dify 是一个开源的 LLM 应用开发平台,它最大的价值在于,让开发者能像搭积木一样,通过可视化工作流的方式,快速构建和部署基于大语言模型的 AI 应用,比如智能客服、内容生成、数据分析助手等。这个教程号称从零基础到精通,覆盖了从环境部署到实战项目的完整路径。

对于想快速上手 AI 应用开发,但又不想深陷于复杂代码和模型部署细节的开发者来说,Dify 提供了一个非常高效的解决方案。它的核心特点包括:提供直观的图形化工作流编排界面,支持多种主流模型 API(如 OpenAI、通义千问、DeepSeek 等)的接入,具备知识库管理、Agent 构建能力,并且可以一键部署为可访问的 Web 应用或 API 服务。

本文将带你系统性地了解 Dify,并基于教程思路,梳理出一套从环境准备到实战上手的可操作指南。我们会重点关注:Dify 的几种部署方式及其硬件门槛、核心概念(应用、工作流、知识库、Agent)的理解、如何从零构建一个可运行的工作流应用,以及最终如何将其发布为服务。无论你是想个人学习,还是为团队搭建内部 AI 工具,这篇文章都能提供清晰的路径。

1. 核心能力速览

在深入细节之前,我们先通过一个表格快速了解 Dify 平台的核心能力与特性,这有助于你判断它是否适合你的需求。

能力项 说明
项目类型 开源 LLM 应用开发与部署平台
核心价值 通过可视化工作流,低代码/无代码构建 AI 应用,降低开发门槛
部署方式 Docker Compose(推荐)、云服务直接部署、本地源码启动
硬件门槛 依赖所连接的模型服务。平台本身资源需求低,2核4G内存的服务器即可运行。GPU 非必需,除非本地部署大模型。
模型支持 支持接入 OpenAI GPT、Anthropic Claude、国内主流大模型(通义、文心、智谱、月之暗面等)的 API,也支持本地部署的 Ollama、vLLM 等开源模型。
核心功能 可视化工作流编排、对话型应用构建、知识库(RAG)管理、Agent(智能体)开发、模型性能评估、API 服务发布。
启动与访问 通过 Docker 启动后,提供 Web 管理界面(默认端口 80/3000)和 API 服务端点。
是否支持 API 。所有构建的应用均可自动生成并暴露 API,方便集成到其他系统。
是否支持批量任务 。通过工作流可以设计批处理逻辑,或通过 API 进行批量调用。
适合场景 快速原型验证、企业内部 AI 助手开发、基于文档的智能问答系统、多步骤复杂 AI 任务自动化。

2. 适用场景与使用边界

Dify 并非一个“大模型”,而是一个“应用工厂”。理解它能做什么、不能做什么,是高效利用它的前提。

它非常适合以下场景:

  1. 快速构建 AI 应用原型 :如果你有一个 AI 产品想法,想快速验证其可行性,用 Dify 拖拽工作流可能比写代码快得多。
  2. 开发企业内部工具 :如合同审核助手、周报生成器、代码评审机器人、内部知识库问答系统等。Dify 便于部署在内网,且能连接企业自有的模型 API 或知识库。
  3. 教育学习与演示 :对于想学习 LLM 应用架构(如 RAG、Agent)的学生或开发者,Dify 的可视化界面能直观展示数据流和组件交互。
  4. 为现有系统添加 AI 能力 :通过 Dify 构建好的应用 API,可以轻松嵌入到你的网站、APP 或后台管理中,无需重写 AI 逻辑。

它的能力边界和注意事项:

  1. 不提供底层模型 :Dify 本身不包含大模型,你需要自行准备模型 API 密钥或部署本地模型服务。这是最主要的成本和技术决策点。
  2. 深度定制有限 :虽然工作流灵活,但对于需要极端定制化算法逻辑或复杂后端处理的场景,纯代码开发仍是更优选择。
  3. 性能依赖外部模型 :应用的响应速度、效果和质量,主要取决于你接入的模型 API 的性能和效果。
  4. 合规与版权 :使用 Dify 构建应用时,需确保接入的模型服务符合当地法规。如果应用涉及用户数据或敏感信息,务必做好数据隐私保护。构建知识库时,确保文档内容拥有合法版权或授权。

3. 环境准备与前置条件

开始部署 Dify 前,请确保你的环境满足以下基本要求。我们将以最常用的 Docker Compose 部署方式为例进行说明。

  1. 操作系统 :推荐 Linux(如 Ubuntu 20.04/22.04)或 macOS。Windows 10/11 也可通过 WSL2(Windows Subsystem for Linux)获得最佳体验。
  2. Docker 与 Docker Compose :这是必须的。请确保已安装最新稳定版本的 Docker Engine 和 Docker Compose Plugin。
    • 检查命令:
      docker --version
      docker compose version
      
  3. 硬件资源
    • CPU :2 核或以上。
    • 内存 :至少 4GB。如果计划同时运行本地模型(如通过 Ollama),则需要更多(建议 8GB+)。
    • 磁盘空间 :至少 10GB 可用空间,用于存放 Docker 镜像、数据库和知识库文档。
    • 网络 :能够访问 Docker Hub 和所需的模型 API 服务(如 OpenAI、国内大模型平台)。
  4. 模型 API 准备
    • 准备一个或多个大语言模型的 API Key。例如:
      • OpenAI: sk-...
      • 通义千问: 从阿里云灵积平台获取。
      • 智谱 AI: 从开放平台获取。
    • 如果打算使用 本地模型 ,需要提前在服务器上部署好相应的模型服务,如 Ollama(运行 ollama run qwen2.5:7b )或 vLLM,并确认其 API 端点(如 http://localhost:11434/v1 )。

4. 安装部署与启动方式

Dify 提供了多种部署方式,这里详细介绍最稳定、最主流的 Docker Compose 部署

4.1 一键部署(Docker Compose)

这是官方推荐的方式,它会拉起包括 Web 前端、后端 API、数据库(PostgreSQL)、缓存(Redis)在内的所有必需服务。

  1. 获取部署文件 : 在服务器上创建一个工作目录,并下载官方 docker-compose.yaml 和 环境变量文件。

    # 创建并进入目录
    mkdir dify && cd dify
    # 下载 docker-compose 文件
    wget https://github.com/langgenius/dify/blob/main/docker/docker-compose.yaml
    # 下载环境变量配置文件
    wget https://github.com/langgenius/dify/blob/main/docker/.env.example -O .env
    
  2. 配置环境变量 : 编辑 .env 文件,最关键的是配置数据库密码和外部访问地址。

    # 使用 vim 或 nano 编辑
    vim .env
    

    找到并修改以下关键配置(其他可暂时保持默认):

    # 设置一个安全的数据库密码
    POSTGRES_PASSWORD=difyai123456
    # 设置一个安全的 Redis 密码
    REDIS_PASSWORD=difyai123456
    # 指定 Dify 服务对外访问的地址,如果是本地测试,可以是 http://localhost
    # 如果是服务器部署,请替换为你的服务器 IP 或域名
    CONSOLE_API_URL=http://localhost:3000
    CONSOLE_WEB_URL=http://localhost:3000
    

    注意: CONSOLE_API_URL CONSOLE_WEB_URL 如果配置错误,可能导致前端无法连接到后端。

  3. 启动所有服务 : 在 dify 目录下,执行以下命令启动服务。

    docker compose up -d
    

    这个命令会在后台下载所有镜像并启动容器。首次执行可能需要几分钟,取决于网络速度。

  4. 查看服务状态 : 使用以下命令检查容器是否正常运行。

    docker compose ps
    

    你应该看到 dify-api dify-web postgres redis 等容器的状态均为 Up

4.2 访问 Web 管理界面

服务启动成功后,即可通过浏览器访问 Dify 的控制台。

  • 访问地址 http://你的服务器IP:3000 (如果你在本地部署,就是 http://localhost:3000 )。
  • 首次登录 :打开页面后,会进入初始化设置流程。你需要:
    1. 设置管理员账号和密码。
    2. 进入“模型供应商”配置页面,添加你的第一个模型。

4.3 配置模型供应商

这是让 Dify “活”起来的关键一步。在 Dify 控制台,点击左下角“设置” -> “模型供应商”。

  1. 添加供应商 :点击“添加模型供应商”,选择你已准备好 API Key 的平台,如“OpenAI”。
  2. 填写配置
    • 模型类型 :选择“文本生成”或“Embedding”(用于知识库)。
    • API Key :填入你的密钥。
    • API Base :一般使用默认值。如果是国内镜像或本地模型,需要修改为对应的 API 地址。
  3. 模型配置 :添加供应商后,需要进一步配置可用的模型。例如,在 OpenAI 供应商下,添加 gpt-4o-mini gpt-3.5-turbo 模型,并设置好上下文长度、单价(用于费用估算)等。

至此,Dify 平台的基础部署和配置就完成了。

5. 功能测试与效果验证

平台跑起来后,我们通过创建几个不同类型的应用来验证其核心功能。

5.1 创建第一个对话型应用(Chat App)

这是最简单的应用类型,类似于一个定制化的 ChatGPT。

  1. 创建应用 :在控制台点击“创建应用”,选择“对话型应用”,输入名称(如“我的第一个助手”)。
  2. 编排工作流
    • 进入应用编辑界面,默认就是一个简单的工作流: 开始 -> LLM -> 结束
    • 点击 LLM 节点,在右侧面板选择你刚才配置好的模型(如 gpt-4o-mini )。
    • 你可以在 提示词 区域编写系统指令,例如:“你是一个专业的编程助手,用中文回答。”
  3. 测试对话
    • 点击右上角“预览”按钮,在右侧聊天窗口输入问题,如“用 Python 写一个快速排序函数”。
    • 查看模型是否根据你的系统指令正确响应。
  4. 验证成功 :模型能理解系统指令并生成符合要求的回答,且响应速度正常。

5.2 构建一个知识库问答应用(RAG)

这是 Dify 的强项,用于构建基于自有文档的智能问答系统。

  1. 创建知识库
    • 在控制台左侧菜单进入“知识库”,点击“创建知识库”,命名为“产品手册”。
    • 进入该知识库,点击“上传文件”,上传你的 PDF、Word 或 TXT 文档(如一份产品说明书)。
    • Dify 会自动进行文本提取、分块和向量化(Embedding)处理。 确保你已配置了 Embedding 模型 (在模型供应商处添加,如 text-embedding-3-small )。
  2. 创建应用并接入知识库
    • 新建一个“对话型应用”或“工作流型应用”。
    • 在工作流编辑器中,从左侧组件库拖入 知识库检索 节点,放置在 开始 LLM 节点之间。
    • 连接线: 开始 -> 知识库检索 -> LLM
    • 配置 知识库检索 节点:选择刚才创建的“产品手册”知识库。
    • 配置 LLM 节点:在提示词中,可以加入 {{#context#}} 变量来引用检索到的文档内容。例如:“请根据以下文档内容回答问题:\n{{#context#}}\n\n问题:{{query}}”。
  3. 测试效果
    • 预览应用,提问一个文档中明确记载的问题,如“产品A的最大支持用户数是多少?”
    • 观察 LLM 的回答是否准确引用了文档内容。
  4. 验证成功 :应用能正确从上传的文档中检索到相关信息,并基于这些信息生成答案,而不是仅凭模型自身知识“瞎编”。

5.3 设计一个工作流型应用(复杂任务)

工作流允许你将多个步骤串联起来,实现复杂的 AI 任务。

示例:文章摘要生成与情感分析流水线

  1. 设计工作流 :目标是输入一篇文章URL,先抓取内容,然后生成摘要,最后分析摘要的情感倾向。
  2. 拖放组件
    • 开始 (输入:文章URL)
    • HTTP 请求 节点(用于抓取URL内容)
    • 文本处理 节点(可选,用于清洗HTML标签)
    • LLM 节点 A(提示词:“请为以下长文生成一个简洁的摘要:{{input}}”)
    • LLM 节点 B(提示词:“请判断以下文本的情感倾向(积极/消极/中性):{{上一步的摘要}}”)
    • 结束 (输出:摘要和情感倾向)
  3. 连接与配置
    • 按顺序连接所有节点。
    • 配置 HTTP 请求 节点的 URL 为变量 {{input}}
    • HTTP 请求 的输出,通过变量映射,传递给 LLM 节点 A 作为输入。
    • LLM 节点 A 的输出,作为 LLM 节点 B 的输入。
  4. 测试与验证
    • 在预览界面输入一个新闻文章链接。
    • 观察工作流是否按步骤执行:抓取 -> 生成摘要 -> 分析情感。
    • 最终输出应包含结构化的结果(摘要文本和情感标签)。

6. 接口 API 与批量任务

构建好的应用,除了在 Web 界面使用,更重要的是能通过 API 集成到其他系统中。

6.1 获取应用 API

  1. 在 Dify 应用编辑界面,点击右上角的“发布”。
  2. 选择“API 访问”选项卡。
  3. 这里你会看到:
    • API 密钥 :用于身份验证。
    • API 端点 :应用的调用地址。
    • 代码示例 :Dify 提供了 curl 、Python、JavaScript 等语言的调用示例。

6.2 调用 API 示例

假设你发布了一个对话应用,以下是使用 Python requests 库调用的示例:

import requests
import json

# 配置参数
api_key = "app-你的应用API密钥"
endpoint = "https://api.dify.ai/v1/chat-messages"  # 示例端点,请以实际为准

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

payload = {
    "inputs": {},  # 工作流所需的输入变量,如果应用有定义的话
    "query": "你好,请介绍一下你自己。",  # 用户输入的问题
    "response_mode": "streaming",  # 或 "blocking"
    "conversation_id": "",  # 可选,用于多轮对话
    "user": "test_user_001"  # 用户标识
}

response = requests.post(endpoint, headers=headers, json=payload, stream=True)

if response.status_code == 200:
    if payload['response_mode'] == 'streaming':
        # 处理流式响应
        for line in response.iter_lines():
            if line:
                decoded_line = line.decode('utf-8')
                if decoded_line.startswith('data: '):
                    data = json.loads(decoded_line[6:])
                    # 处理返回的数据,例如打印内容
                    if 'answer' in data:
                        print(data['answer'], end='', flush=True)
    else:
        # 处理阻塞式响应
        result = response.json()
        print(result.get('answer'))
else:
    print(f"请求失败,状态码:{response.status_code}")
    print(response.text)

6.3 实现批量任务

Dify 本身不提供内置的批量任务队列管理界面,但你可以通过以下方式实现:

  1. 脚本批量调用 :编写一个 Python 脚本,读取一个任务列表(如 CSV 文件),循环调用上述 API,并将结果保存。
  2. 工作流内循环(高级) :对于复杂的批量处理逻辑,可以在工作流中使用“循环”节点(如果版本支持)或通过“代码”节点编写自定义逻辑来处理列表数据。
  3. 外部任务队列集成 :将 Dify API 封装成一个 Worker,接入像 Celery + Redis/RabbitMQ 这样的分布式任务队列中,实现高并发的批量处理。

批量调用注意事项

  • 注意 API 的速率限制(取决于你的模型供应商和 Dify 服务配置)。
  • 为每个任务设置合理的超时时间。
  • 做好错误处理和重试机制,记录失败的任务以便后续重试。

7. 资源占用与性能观察

Dify 平台本身的资源消耗并不高,性能瓶颈主要出现在其调用的外部模型 API 或本地模型服务上。

  1. 平台服务资源占用

    • 使用 docker stats 命令可以查看各个容器的实时资源使用情况。
    docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}"
    
    • 正常情况下, dify-api dify-web 容器内存占用在 200MB-500MB 左右,CPU 使用率很低。数据库和 Redis 会占用一部分内存。
    • 主要磁盘空间占用 :知识库上传的原始文件和处理后的向量数据会存储在持久化卷中,需定期清理无用文件。
  2. 性能影响因素

    • 模型 API 延迟 :这是最大的影响因素。海外 API 受网络影响大,可考虑使用国内节点或本地模型。
    • 知识库检索速度 :知识库文档数量巨大时,检索可能变慢。优化分块策略和索引设置可以改善。
    • 工作流复杂度 :一个工作流中节点越多,尤其是串行的 HTTP 请求或 LLM 调用越多,整体耗时越长。
    • 并发请求 :高并发调用 API 时,需关注 Dify 后端和数据库的性能,必要时调整 Docker 容器的资源限制或进行水平扩展。
  3. 优化建议

    • 对于知识库应用,使用高效的 Embedding 模型(如 text-embedding-3-small )并优化文本分块大小和重叠度。
    • 对于复杂工作流,考虑将可以并行的任务拆分。
    • 如果使用本地模型,确保服务器有足够的 GPU 内存(针对大模型)或 CPU 算力。

8. 常见问题与排查方法

在部署和使用过程中,你可能会遇到以下问题。这里提供通用的排查思路。

问题现象 可能原因 排查方式 解决方案
访问 localhost:3000 失败 1. 服务未启动成功。
2. 端口被占用。
3. 防火墙/安全组限制。
1. docker compose ps 检查容器状态。
2. netstat -tlnp | grep :3000 查看端口占用。
3. 检查服务器防火墙规则。
1. 查看日志 docker compose logs dify-web
2. 修改 .env 中的 CONSOLE_WEB_PORT 并重启。
3. 开放对应端口。
前端能打开,但登录或操作时报错/卡住 1. 前端配置的后端地址错误。
2. 数据库连接失败。
3. Redis 连接失败。
1. 检查浏览器开发者工具(F12)控制台网络请求报错。
2. 检查 dify-api 容器日志: docker compose logs dify-api
1. 确认 .env CONSOLE_API_URL 配置正确,且前端能访问此地址。
2. 检查数据库容器是否正常运行,密码是否正确。
模型调用失败,提示“Invalid API Key”或“Connection Error” 1. API Key 填写错误或过期。
2. 网络无法访问模型供应商。
3. 本地模型服务未启动。
1. 在模型供应商配置页面重新检查 API Key。
2. 在服务器上尝试 curl 模型供应商的测试端点。
3. 检查本地模型服务(如 Ollama)状态。
1. 重新生成并填写正确的 API Key。
2. 配置网络代理或使用国内镜像地址。
3. 启动本地模型服务并确认 API 端口。
知识库文件处理失败 1. 未配置 Embedding 模型。
2. 文件格式不支持或已损坏。
3. 文件过大或内容编码问题。
1. 检查知识库设置中 Embedding 模型是否已选。
2. 查看知识库处理详情页面的错误信息。
1. 在“模型供应商”中配置一个 Embedding 模型并关联到知识库。
2. 尝试将文件转换为 TXT 或 PDF 格式重新上传。
3. 拆分大文件为多个小文件上传。
工作流执行到某节点卡住或报错 1. 节点配置错误(如变量名不对)。
2. 外部服务(如 HTTP 请求的 URL)不可用。
3. 代码节点语法错误。
1. 在应用预览界面,开启“工作流运行详情”查看每一步的输入输出。
2. 单独测试该节点所需的外部服务。
1. 仔细检查节点配置,确保输入变量与上游节点输出变量名匹配。
2. 确保外部服务可达且返回预期格式的数据。
3. 调试代码节点的逻辑。
API 调用返回 401 或 403 错误 1. API 密钥错误。
2. 应用未发布或 API 访问未启用。
3. 请求的端点或方法错误。
1. 检查请求头中的 Authorization Bearer Token 是否正确。
2. 登录 Dify 控制台,确认该应用已“发布”且“API 访问”处于开启状态。
1. 使用正确的应用 API 密钥。
2. 发布应用并开启 API 访问。
3. 对照 Dify 控制台提供的 API 文档检查请求 URL 和格式。

9. 最佳实践与使用建议

为了更稳定、高效地使用 Dify,遵循一些最佳实践至关重要。

  1. 环境隔离 :始终使用 Docker Compose 部署,这能保证依赖环境的一致性,避免污染宿主机。定期备份 docker-compose.yaml .env 文件。
  2. 配置管理 :将敏感的 API Key 和密码放在 .env 文件中,并确保该文件不被提交到代码仓库。使用不同的 .env 文件区分开发、测试和生产环境。
  3. 版本控制 :Dify 更新较快,在升级前,务必在测试环境验证新版本。关注官方发布的升级说明和破坏性变更。
  4. 应用设计
    • 提示词工程 :精心设计系统提示词和用户提示词模板,这是影响应用效果最直接的因素。善用变量( {{variable}} )使工作流动态化。
    • 工作流模块化 :将常用的功能(如文本清洗、特定格式解析)构建成可复用的“工作流模板”,方便在不同应用中快速导入。
    • 测试与评估 :利用 Dify 的“日志与标注”功能,对生产应用的对话进行抽样检查,评估效果并持续优化提示词。
  5. 知识库优化
    • 文档预处理 :上传前尽量清理文档格式,复杂的 PDF 或扫描件可能识别效果差。
    • 分块策略 :根据文档类型调整文本分块大小和重叠度。技术文档可能适合较小的块,而连贯性强的文章可能需要较大的块。
    • 混合检索 :在知识库设置中,可以尝试结合“向量检索”和“全文检索”,以提高召回率。
  6. 安全与合规
    • API 访问控制 :妥善保管应用 API 密钥,在 Nginx 等反向代理后配置访问限制和速率限制。
    • 内容审核 :对于面向公众的应用,考虑在工作流最后加入内容安全审核节点(可调用相关审核 API),过滤不当输出。
    • 数据隐私 :如果处理用户隐私数据,确保你的模型供应商符合数据合规要求,或使用本地部署的私有模型。

10. 总结与下一步

Dify 通过将 LLM 应用开发中的常见模式(对话、检索、工作流)产品化,极大地加速了从想法到可运行服务的进程。它的核心优势在于 可视化 集成化 ,让你能专注于业务逻辑而非底层设施。

对于初学者,最应该优先验证的是: 能否在 30 分钟内,从零部署好 Dify,并成功连接一个模型 API,创建一个能简单对话的应用。 这是验证整个链路是否通畅的关键。

最容易踩的坑通常集中在 初始环境配置 (网络、端口、模型 API 连接)和 工作流变量传递 上。严格按照日志提示进行排查,大部分问题都能解决。

完成基础入门后,可以深入探索以下方向:

  1. Agent 开发 :尝试使用 Dify 的“工具”功能,让 LLM 能够调用外部 API(如天气查询、数据库操作)或执行代码。
  2. 模型微调与评估 :探索 Dify 的模型微调功能(如果支持你使用的模型),并使用其内置的评估数据集对应用效果进行量化评估。
  3. 生产部署 :研究如何将 Dify 部署到云服务器,配置域名、HTTPS,并设置监控和告警,使其成为一个稳定的生产服务。
  4. 复杂业务流 :将 Dify 工作流与你现有的业务系统(通过 API)深度集成,实现业务流程的智能化改造。

这个平台就像一套强大的乐高积木,能拼装出什么,很大程度上取决于你对业务的理解和对 LLM 能力的想象力。建议从解决一个实际的小问题开始,逐步构建你的第一个 AI 应用。

🚀 30+款热门AI模型一站整合,DeepSeek/GLM/Qwen 随心用,限时 5 折。 👉 点击领海量免费额度

Logo

Agent 垂直技术社区,欢迎活跃、内容共建。

更多推荐