Dify 全流程实战指南：从部署到 API 集成

Dify (Do It For You) 是一个开源的 LLM 应用开发平台。它最大的特点是“开箱即用”，将复杂的 AI 模型调用、提示词编排、知识库管理和 API 发布整合在一个可视化的界面中。无论你是开发者还是业务人员，都能快速上手。

本教程将带你从零开始，完成 Dify 的本地部署、应用创建以及 API 集成。

第一部分：安装与部署

Dify 提供了多种部署方式，最推荐且最稳定的方式是使用 Docker Compose。这种方式将所有依赖（如 PostgreSQL, Redis, Weaviate 等）都容器化，避免了繁琐的环境配置。

1. 系统要求

在开始之前，请确保你的服务器或本地机器满足以下最低配置：

CPU: >= 2 Core
内存: >= 4 GiB (建议 8 GiB 以上以获得更流畅的体验)
软件: 已安装 Docker Desktop (Mac/Windows) 或 Docker Engine + Docker Compose (Linux)

2. 下载源码

首先，我们需要获取 Dify 的最新源代码。打开终端（Terminal）或命令行工具，执行以下命令：

# 克隆 Dify 仓库
git clone https://github.com/langgenius/dify.git

# 进入 docker 部署目录
cd dify/docker

3. 配置环境变量

在启动之前，建议检查一下环境配置文件。Dify 提供了一个示例文件 .env.example。

# 复制配置文件
cp .env.example .env

关键配置说明：
通常情况下，默认配置即可满足本地测试需求。但如果你计划在生产环境部署，或者前后端分离部署在不同域名下，需要修改 .env 文件中的以下变量：

COOKIE_DOMAIN: 设置为你的顶级域名（例如 example.com），以确保认证 Cookie 能跨子域共享。
NEXT_PUBLIC_COOKIE_DOMAIN: 设置为 1，启用前端的跨子域名 Cookie 支持。

4. 一键启动

一切准备就绪后，使用 Docker Compose 启动服务：

# 后台启动所有容器
docker compose up -d

启动过程可能需要几分钟，Docker 会自动拉取所需的镜像（包括 API 服务、Web 前端、数据库、向量数据库等）。

5. 验证安装

当终端显示所有容器状态为 Up 或 healthy 时，说明部署成功。
打开浏览器访问 http://localhost (如果你是在远程服务器部署，请访问服务器的 IP 地址)。你将看到 Dify 的初始化页面，按照指引设置管理员账号密码即可登录。

️ 第二部分：核心功能与使用

1. 配置模型供应商

Dify 本身是一个编排平台，它需要连接大模型（如 OpenAI, Azure, 通义千问等）才能工作。

点击左侧菜单栏的 “设置” (Settings) -> **“模型供应商” (Model Provider)**。
选择你喜欢的模型，例如 OpenAI。
输入你的 API Key。如果是在国内环境，也可以选择配置国产大模型或使用兼容 OpenAI 格式的第三方中转接口。
点击“保存并测试”，确保连接正常。

2. 创建空白应用

回到 “工作室” (Studio) 主页。
点击 **“创建空白应用”**。
选择 “聊天助手” 类型（这是最常用的对话型应用）。
填写应用名称（如“全能翻译官”）和描述，点击“创建”。

3. 编排提示词与逻辑

进入应用的编排页面，这里是 Dify 的核心。

提示词 (Prompt): 在右侧的“人设与回复逻辑”框中，输入以下内容：

你是一个专业的翻译助手。无论用户输入什么语言，你都将其翻译成中文。如果用户输入的是中文，则翻译成英文。请直接输出翻译结果，不要解释。
模型参数: 在右侧面板下方，选择刚才配置的模型（如 GPT-4 或 DeepSeek），并将温度（Temperature）设置为 0，以保证翻译的准确性。
开场白: 可以设置一句默认的欢迎语，例如：“你好！请输入你想翻译的内容。”

4. 调试与预览

在页面右下角的预览窗口中，输入一段文字（例如 "Hello Dify"），点击发送。你应该能立刻看到 AI 返回的中文翻译。这证明你的应用逻辑已经跑通了。

第三部分：对外提供 API

应用在 Dify 平台上跑通只是第一步，真正的价值在于将其集成到你自己的网站、APP 或业务系统中。Dify 提供了强大的后端即服务（BaaS）能力。

1. 获取 API 密钥

在应用详情页，点击右上角的 “访问 API” 按钮。
在弹出的窗口中，你可以看到自动生成的 API 文档和代码示例。
找到 “API 密钥” 区域，点击生成或直接复制现有的密钥（以 app- 开头）。注意：请妥善保管此密钥，不要在前端代码中直接暴露。

2. API 调用详解

Dify 的 API 遵循 RESTful 风格。对于聊天助手，我们主要使用 chat-messages 接口。

请求示例 (cURL):
这是一个向你的应用发送消息的标准请求：

curl --location --request POST 'https://api.dify.ai/v1/chat-messages' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "inputs": {},
    "query": "Hello World",
    "response_mode": "streaming",
    "user": "user-123"
}'

关键参数说明：

Authorization: 填入你在 Dify 控制台复制的 API Key。
query: 用户的提问内容。
response_mode: 推荐使用 streaming（流式输出），这样用户体验更好，像打字机一样逐字显示；也可以设为 blocking 等待完整回复。
user: 终端用户的唯一标识（用于区分不同用户的会话）。
conversation_id: （可选）如果是多轮对话，需要把上一次返回的 conversation_id 传回来，以保持上下文记忆。

3. 生产环境集成最佳实践

在实际开发中，为了安全和稳定，请遵循以下步骤：

后端代理: 永远不要在你的前端网页（HTML/JS）或移动端 App 代码中直接写死 API Key。你应该在自己的后端服务器（Node.js, Python, Java 等）上封装一个接口，由你的后端去请求 Dify API。
环境变量: 将 Dify 的 API Key 存储在你服务器的环境变量中。
错误处理: 处理网络超时或 Dify 服务不可用的情况（如 HTTP 429 频率限制）。
网关代理: 如果你是自托管 Dify，可以通过 Nginx 反向代理 Dify 的 API 服务，将其暴露在你的内网或公网域名下，方便内部系统集成。

通过以上步骤，你就完成了一个完整的 AI 应用闭环：从本地搭建平台，到可视化编排业务逻辑，最后通过标准 API 赋能外部系统。

Dify 全流程实战指南：从部署到 API 集成