对于刚接触 Dify 的开发者或业务人员来说，最大的障碍往往不是理解 AI 模型本身，而是如何快速上手一个功能强大的平台。Dify 作为一个集成了智能体工作流、RAG 知识库和多种模型支持的 AI 应用开发平台，其界面和功能模块相当丰富。如果一开始没有理清账号体系、核心界面和基本操作逻辑，后续无论是构建聊天机器人、设计复杂工作流还是管理知识库，都会感到无从下手。本文将从零开始，带你完成 Dify 的账号开通，并系统性地导览其核心界面与功能模块，让你在 30 分钟内建立起对 Dify 平台的清晰认知，为后续的深度开发打下坚实基础。

1. 理解 Dify：它是什么以及能解决什么问题

在开始操作之前，我们需要先明确 Dify 的定位和价值。这有助于我们理解后续看到的每一个功能模块背后的设计意图。

1.1 Dify 的核心定位：AI 应用开发与部署平台

Dify 是一个开源的 LLM（大语言模型）应用开发平台。它的核心目标是将 AI 应用的开发、调试、部署和运维流程标准化和可视化。你可以把它理解为一个“乐高积木”式的搭建工具，提供了各种预制好的 AI 能力模块（如对话、文本生成、知识库检索、代码执行等），允许开发者通过拖拽的方式，将这些模块组合成复杂的 AI 应用或工作流，而无需从零开始编写大量的胶水代码。

它主要解决以下几个痛点：

  1. 降低开发门槛 ：通过可视化工作流和丰富的预置节点，让非资深 AI 工程师也能构建功能复杂的 AI 应用。
  2. 统一管理 ：在一个平台内完成模型配置、知识库管理、应用构建、版本发布和监控观测，避免了工具链的碎片化。
  3. 快速集成与扩展 ：原生支持连接 OpenAI、 Anthropic、国内主流模型厂商以及本地部署的模型（如 Ollama），并通过插件（Plugins）和 MCP（Model Context Protocol）协议轻松集成外部工具和系统。

1.2 关键概念澄清：应用、工作流与智能体

在 Dify 的语境下，这几个概念有明确的区分：

  • 应用（Application） ：这是最终交付给用户使用的产物。一个应用可以是一个聊天机器人、一个文本生成工具，或者一个自动化的数据处理流程。应用是功能实现的载体。
  • 工作流（Workflow） ：这是构建应用的“蓝图”或“流水线”。在工作流编辑器中，你可以通过拖拽节点（如 LLM、知识库检索、条件判断、代码执行等）并连接它们，来定义应用的处理逻辑。一个应用通常由一个或多个工作流驱动。
  • 智能体（Agent） ：在 Dify 中，智能体特指那些具备自主决策和工具调用能力的 AI 实体。它通常由 LLM 作为“大脑”，并配置了一系列可用的工具（如搜索、计算、API 调用）。在工作流中，你可以插入一个“智能体”节点来赋予流程自主完成任务的能力。

简单来说，你 创建工作流来定义逻辑 ，然后 发布工作流来生成一个可用的应用 ，而 智能体是工作流中一种特殊且强大的节点类型 。

2. 开通与访问：三种主要方式及其选择

Dify 提供了多种使用方式，你可以根据自身的技术条件、数据安全要求和功能需求进行选择。

2.1 方式一：使用官方云服务（最快上手）

这是最快捷的方式，适合个人学习、快速原型验证或小型团队。

操作步骤：

  1. 访问 Dify 官方网站。
  2. 在首页点击 “Get Started” 或 “开始使用”，通常会引导你进行注册。
  3. 使用邮箱或第三方账号（如 GitHub）完成注册。
  4. 注册成功后，系统会自动为你创建一个工作空间（Workspace），并引导你进行初始设置，如配置第一个 AI 模型供应商（Model Provider）。

注意：使用云服务意味着你的应用数据（非知识库文件内容）会经过 Dify 的服务器。对于敏感数据，请谨慎评估或选择下面两种自托管方式。

初始设置关键一步：配置模型 登录后，平台很可能会提示你“未配置模型”或引导你添加模型。这是使用 Dify 所有 AI 功能的前提。

  • 入口 ：通常在左侧菜单栏找到 “模型供应商” 或 “设置” -> “模型供应商” 。
  • 操作 ：点击“添加模型供应商”，选择你拥有的模型 API 服务，例如 OpenAI、Azure OpenAI、智谱 AI、月之暗面等。
  • 填写信息 ：你需要填入对应服务商提供的 API Key 和 Base URL（如果需要）。例如，使用 OpenAI 时，就填入从 OpenAI 平台获取的 API Key。

完成这一步，你就拥有了驱动 AI 应用的“引擎”。

2.2 方式二：使用 Docker 本地部署（推荐用于开发测试）

如果你想在本地或自己的服务器上完全控制 Dify，Docker 部署是最主流和推荐的方式。它隔离性好，一键启动，非常适合开发、测试和生产环境。

环境准备清单：

  • 操作系统 ：Linux (Ubuntu/CentOS), macOS, Windows 10/11 (需要 WSL2)。
  • Docker ：版本 20.10.0 或更高。
  • Docker Compose ：版本 v2.0.0 或更高。通常 Docker Desktop 已包含。
  • 硬件 ：建议至少 4GB 空闲内存，2核 CPU。如需运行本地模型（如 Ollama），需要更高配置。

部署步骤：

  1. 获取部署文件 ：在终端中，使用 git 克隆官方仓库或直接下载 docker-compose.yaml 文件。 
    git clone https://github.com/langgenius/dify.git
cd dify/docker
  2. 启动服务 ：在包含 docker-compose.yaml 的目录下执行命令。 
    docker-compose up -d
    这个命令会拉取 PostgreSQL、Redis、Dify-API、Dify-Web 等镜像并在后台启动。
  3. 访问服务 ：启动完成后，在浏览器中访问 http://localhost:3000 （默认前端端口）。你将看到初始化设置页面。
  4. 初始化设置 ：
    • 设置管理员账号和密码。
    • 配置数据库连接（通常使用默认的 Docker 内部连接即可）。
    • 完成初始化后，使用管理员账号登录。

关键配置文件与环境变量 对于生产部署，你需要关注 .env 文件或通过 docker-compose.yaml 设置环境变量。以下是一些关键配置：

环境变量 说明 默认值/示例
DB_PASSWORD 数据库密码 在 docker-compose.yaml 中定义
SECRET_KEY Django 加密密钥 必须修改，用于安全
CONSOLE_API_URL 后端 API 地址 http://localhost:5001
CONSOLE_WEB_URL 前端访问地址 http://localhost:3000
MODEL_PROVIDERS 启用的模型供应商 可在界面配置

2.3 方式三：源码部署（适用于深度定制）

如果你需要修改 Dify 的源代码，或进行深度二次开发，可以选择源码部署。这种方式最复杂，但灵活性最高。

基本流程：

  1. 克隆代码仓库。
  2. 分别设置后端（Python）和前端的开发环境。
  3. 安装依赖（PostgreSQL, Redis, Python 包, Node.js 包等）。
  4. 配置环境变量和数据库。
  5. 启动后端服务和前端服务。

由于步骤较多，通常建议初学者先使用 Docker 方式，待熟悉后再考虑源码部署。官方文档提供了详细的源码部署指南。

3. 核心界面导览：从登录到第一个应用

假设你已经通过上述某种方式成功登录到 Dify 控制台。接下来，我们将系统性地浏览整个界面。

3.1 全局布局与导航

Dify 的控制台通常采用左侧主导航栏，中间工作区的布局。

  • 顶部栏 ：显示当前工作空间名称、用户信息、通知、全局搜索和设置入口。
  • 左侧导航栏 ：这是功能的核心入口，通常包含以下主要模块：
    1. 仪表盘 ：概览应用访问量、Token 消耗、错误统计等。
    2. 应用 ：创建和管理所有 AI 应用的地方。
    3. 工作流 ：可视化构建和编辑应用逻辑的画布。
    4. 知识库 ：上传、处理和管理用于 RAG 的文档数据。
    5. 工具 ：管理可被智能体调用的插件和自定义工具。
    6. 模型供应商 ：配置和管理不同的 AI 模型 API。
    7. 日志与标注 ：查看应用运行日志，并对结果进行人工标注以优化模型。
    8. 成员 ：管理团队协作成员和权限（企业版功能更强）。
    9. 设置 ：系统级设置，如模型供应商、环境变量、邮件配置等。

3.2 核心功能模块详解

3.2.1 “应用”模块：你的产品列表

这是你所有 AI 应用的集合页面。你可以在这里：

  • 创建新应用 ：点击“创建新应用”，通常有两种初始类型选择：“对话型应用”或“文本生成型应用”。选择后，会进入该应用的配置页面。
  • 管理应用 ：对已有应用进行更名、复制、查看 API 访问方式、监控访问数据、调整高级设置（如对话开场白、敏感词过滤）等。
  • 访问应用 ：每个应用都有一个独立的访问链接或可嵌入的 Web 组件，你可以分享给最终用户。
3.2.2 “工作流”模块：构建逻辑的车间

这是 Dify 最强大的功能所在。点击进入后，你可以看到所有已创建的工作流列表。点击一个工作流或创建新工作流，会打开 可视化编辑器 。

编辑器界面构成：

  • 左侧节点面板 ：分类列出了所有可用的节点，如：
    • 开始节点 ：工作流的唯一入口。
    • LLM 节点 ：调用配置好的大模型。
    • 知识库检索节点 ：从已建知识库中查找相关信息。
    • 代码执行节点 ：运行 Python 代码。
    • 条件判断节点 ：实现 if-else 逻辑。
    • 智能体节点 ：封装了工具调用能力的智能体。
    • HTTP 请求节点 ：调用外部 API。
    • 变量分配/文本处理 等工具节点。
  • 中间画布 ：拖拽节点到此，并用连线连接它们，构建处理流程。连线代表了数据的流向。
  • 右侧属性面板 ：当选中画布上的某个节点时，这里会显示该节点的详细配置项。例如，选中一个 LLM 节点，你可以在这里选择具体的模型、设置温度（Temperature）、最大生成长度等参数。
  • 底部运行/调试面板 ：你可以输入测试数据，点击“运行”来调试当前工作流，并实时查看每个节点的输入输出，这对排查问题至关重要。
3.2.3 “知识库”模块：为 AI 注入专属知识

RAG 是让 AI 应用“更懂你”的关键。在这里，你可以：

  • 创建知识库 ：为其命名并选择嵌入模型（用于将文本转换为向量）。
  • 上传文档 ：支持 TXT、PDF、Word、PPT、Excel、Markdown 等多种格式。Dify 会自动进行文本提取、分割和向量化处理。
  • 处理状态 ：上传后，文档会进入“处理中”、“已索引”或“错误”状态。你可以在知识库详情页管理文档，进行重新索引或删除。
  • 检索测试 ：在知识库详情页，提供一个输入框，让你测试针对某个问题，知识库能检索出哪些相关片段，以评估效果。
3.2.4 “模型供应商”模块：连接 AI 大脑

这里是配置所有可用模型的地方。Dify 支持“一站接入，多处使用”。

  • 添加供应商 ：点击“添加模型供应商”，从列表中选择（如 OpenAI、Azure、通义千问、DeepSeek 等）。
  • 配置凭证 ：填入该供应商所需的 API Key、Base URL 等信息。
  • 模型管理 ：配置成功后，该供应商下的可用模型（如 gpt-4o, claude-3-5-sonnet, qwen-max）会自动或手动同步过来。你可以在创建工作流时，在 LLM 节点的配置中选用这些模型。

3.3 创建一个极简对话应用：全流程走查

让我们通过创建一个最简单的“对话助手”来串联上述模块。

  1. 进入“应用”模块 ，点击“创建新应用”，选择“对话型应用”。
  2. 基础配置 ：
    • 输入应用名称，如“我的第一个助手”。
    • 在“模型”配置区域，从下拉列表中选择一个你已经配置好的模型供应商和具体模型（例如，OpenAI 的 gpt-3.5-turbo）。
    • 可以简单设置一下“对话开场白”。
  3. 立即创建 ：点击创建，你会被带到这个应用的“提示词编排”页面。这里其实是一个简化版的工作流，包含系统提示词和用户输入变量。
  4. 预览与测试 ：在页面右侧，有一个“预览”窗口。你可以直接在这里输入问题，与你的 AI 助手对话，测试效果。
  5. 发布 ：测试满意后，点击右上角的“发布”按钮。发布后，这个应用就正式上线了。
  6. 访问应用 ：发布后，在应用概览页，你可以找到“访问地址”，点击即可在一个独立的网页中使用这个助手。你也可以复制“嵌入代码”，将其集成到自己的网站中。

至此，你已经完成了从零到一创建一个可用的 AI 应用。虽然简单，但流程是完整的。

4. 关键配置与常见问题排查

成功登录和创建应用只是第一步，要让应用稳定可靠地运行，还需要理解一些关键配置和知道如何排查常见问题。

4.1 模型配置的注意事项

模型是应用的核心，配置不当会导致应用无法工作或效果不佳。

配置项 作用与说明 常见问题
API Key 调用模型服务的凭证。 错误： LLM 提供者的密钥未设置 。检查密钥是否填写正确，是否有余额或权限。
Base URL 模型 API 的端点地址。 使用第三方代理或本地模型时，必须修改此项。例如 Ollama 通常是 http://localhost:11434/v1 。
模型列表 选择该供应商下可用的具体模型。 如果列表为空，可能是网络问题无法拉取，或需要手动填写模型名称。
配额与限流 设置每个应用的调用频率限制。 防止意外消耗过多 Token，尤其在使用付费模型时。

4.2 工作流调试与日志查看

当工作流运行出错或结果不符合预期时，调试功能是你的主要工具。

  1. 使用调试面板 ：在工作流编辑器的底部，输入测试数据后运行。观察每个节点的“输入”和“输出”。如果某个节点报错（显示红色），错误信息会直接显示在该节点上。
  2. 查看应用日志 ：在左侧导航栏进入“日志与标注”。这里记录了所有对该应用的调用记录。
    • 你可以看到每次对话的完整请求和响应。
    • 可以筛选状态（成功/失败）、时间、所用模型等。
    • 对于失败的请求，点击进入详情，可以查看具体的错误堆栈信息，这对于排查 Internal Server Error 这类问题至关重要。
  3. 查看系统日志 ：对于 Docker 部署，如果 Web 界面无法访问或出现严重错误，需要查看容器日志。 
    # 查看所有 Dify 相关容器的日志
docker-compose logs -f
# 查看特定容器的日志，如后端 API 服务
docker-compose logs -f api

4.3 常见启动与访问问题排查

以下是一些在部署和初次使用 Dify 时的高频问题：

问题现象 可能原因 检查与解决步骤
访问 localhost:3000 无法打开页面 1. Docker 服务未成功启动。
2. 端口被占用。
3. Windows 未正确安装 WSL2。		 1. 运行 docker-compose ps 检查容器状态。
2. 运行 netstat -ano | findstr :3000 查看端口占用，修改 docker-compose.yaml 中的端口映射。
3. 确保 WSL2 已安装并启用。
页面打开后提示“无法连接到后端服务” 1. 后端 API 服务 ( api 容器) 启动失败。
2. 前端配置的后端地址错误。		 1. 检查 api 容器日志： docker-compose logs api 。
2. 检查前端环境变量 CONSOLE_API_URL 是否指向了正确的后端地址和端口（默认 http://localhost:5001 ）。
上传文件到知识库失败 1. 文件格式不支持或损坏。
2. 文件大小超限。
3. 向量数据库连接异常。		 1. 确认文件格式在支持列表中。
2. 查看页面错误提示或容器日志。
3. 检查 weaviate 或 qdrant 等向量数据库容器是否正常运行。
工作流运行时报 Internal Server Error 1. 节点配置错误（如 API Key 无效）。
2. 代码执行节点有语法错误。
3. 依赖服务（如数据库）连接超时。		 1. 首先查看应用日志详情 ，获取具体错误信息。
2. 检查工作流中各节点的配置，特别是需要填写密钥或 URL 的节点。
3. 检查相关外部服务的网络连通性。

5. 从入门到实践：下一步行动建议

完成界面导览和基础应用创建后，你可以沿着以下路径深化对 Dify 的掌握：

  1. 探索复杂工作流 ：尝试构建一个包含“知识库检索 -> 条件判断 -> LLM 生成”的流程。例如，创建一个客服助手，先检索知识库，如果找到答案就直接回复，如果没找到再让 LLM 生成。
  2. 集成外部工具 ：在“工具”模块探索或添加一个插件（如天气查询、数据库查询），然后在工作流中使用“智能体”节点，配置其可以调用该工具，体验智能体自动完成复杂任务的能力。
  3. 优化知识库效果 ：上传一份你熟悉的文档（如产品手册），测试其检索效果。尝试调整知识库的“分段处理方式”，观察不同设置对检索结果的影响。
  4. 学习版本管理与发布 ：在应用配置中，尝试修改提示词并保存为新版本，然后对比不同版本的应用效果。理解“开发版”和“生产版”的差异。
  5. 关注生产部署 ：如果你计划用于真实业务，需要深入研究 Docker 部署中的持久化存储、备份、域名配置、HTTPS 启用以及性能监控等生产级课题。

Dify 的强大在于它将复杂的 AI 工程能力封装成了可视化的组件。作为初学者，最重要的是先跑通端到端的流程，建立对平台模块和数据处理流向的直观感受。当遇到问题时，善用调试面板、应用日志和容器日志，大部分问题都能找到线索。从创建一个简单的对话应用开始，逐步增加工作流的复杂度，你会逐渐发现，构建一个功能丰富的 AI 应用，并没有想象中那么困难。

Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

一个 API 入口调用多个大模型：AiiOnly客户端 + CC Switch 打通 Codex AI编程流程

avatar AI编程社区
cover

VSCode Claude Code + MiMo 中转免登录完整配置教程（解决原生登录弹窗 + 模型报错）

avatar AI编程社区
cover

从零开始做一个属于自己的 Skill（保姆级教程）

avatar AI编程社区