Dify 实战教程：从零部署到构建 AI 应用全流程详解

Pretend455

340人浏览 · 2026-06-09 21:23:04

Pretend455 · 2026-06-09 21:23:04 发布

本文面向有一定开发基础的读者，涵盖 Dify 的核心概念、Docker 部署、知识库配置、Workflow 搭建，以及通过 API 接入自己系统的完整流程。

一、Dify 是什么？

Dify 是一个开源的 LLM 应用开发平台，定位是让开发者快速构建、部署、运营基于大语言模型的 AI 应用，而不需要从头搭建推理、向量检索、对话管理等基础设施。

核心能力

能力	说明
多模型支持	OpenAI、Claude、通义千问、文心一言、本地 Ollama 等
知识库 RAG	上传文档，自动向量化，支持语义检索
Workflow	可视化编排 AI 流程，支持分支、循环、代码节点
Agent	工具调用、多步推理
API 开放	每个应用自动生成 REST API，方便对接业务系统

和 LangChain、FastGPT 的区别

LangChain：代码框架，灵活但需要大量手写代码
FastGPT：偏向知识库问答场景，功能相对收敛
Dify：介于两者之间，可视化 + 可编程，适合团队协作和快速落地

二、Docker 部署（推荐方式）

环境要求

Docker 20.10+
Docker Compose 2.x+
内存建议 4GB 以上

部署步骤

1. 克隆仓库

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

2. 复制配置文件

cp .env.example .env

3. 修改关键配置

打开 .env 文件，必须修改以下内容：

# 必须替换，用于 JWT 签名和加密
SECRET_KEY=your-random-secret-key-here

# 生成方法：
# openssl rand -base64 42

其他常用配置：

# Token 过期时间
ACCESS_TOKEN_EXPIRE_MINUTES=60
REFRESH_TOKEN_EXPIRE_DAYS=30

# 如果需要外网访问，配置这些
CONSOLE_WEB_URL=http://你的服务器IP
SERVICE_API_URL=http://你的服务器IP

4. 启动服务

docker compose up -d

5. 验证部署

docker ps

正常情况下应该看到以下容器全部 Up：

docker-nginx-1          # 反向代理，监听 80/443
docker-api-1            # 后端 API
docker-web-1            # 前端
docker-worker-1         # 异步任务
docker-db-postgres-1    # 数据库（PostgreSQL）
docker-redis-1          # 缓存
docker-weaviate-1       # 向量数据库
docker-sandbox-1        # 代码执行沙箱
docker-plugin_daemon-1  # 插件服务

6. 访问控制台

浏览器打开：http://服务器IP

首次访问需要创建管理员账号。

三、配置模型

部署完成后，第一件事是配置 LLM 模型。

步骤

右上角头像 → 设置
左侧 模型供应商
选择对应厂商，填入 API Key

常用模型配置示例

OpenAI：

API Key: sk-xxxxxxxx
Base URL: https://api.openai.com/v1（或中转地址）

Ollama（本地模型）：

Base URL: http://host.docker.internal:11434

注意：Docker 内访问宿主机用 host.docker.internal 而不是 localhost

通义千问：

API Key: 阿里云控制台申请

四、知识库配置详解

知识库是 Dify 的核心功能之一，基于 RAG（检索增强生成）实现文档问答。

创建知识库

顶部导航 → 知识库
创建知识库 → 上传文档（支持 PDF、Word、TXT、Markdown 等）
配置分段规则

分段策略选择

通用分段

检索和召回用同一个块，适合大多数场景。

关键参数：

分段标识符：\n\n（以空行为分割点）
最大长度：1024 characters
重叠长度：50 characters（防止语义在段边界被截断）

父子分段（推荐用于长文档）

核心思路：子块负责检索（精准），父块负责召回（完整）

用户提问 → 向量匹配子块（小而精准）→ 返回对应父块给 LLM（大而完整）

适用场景：

文档有清晰的章节层级
问题需要综合多个小点来回答
文档篇幅较长（>5000 字）

检索设置

模式	说明	适用
向量检索	语义相似度匹配	通用问答
全文检索	关键词精确匹配	查找专有名词
混合检索	两者结合	推荐默认使用

五、创建应用

Dify 支持四种应用类型：

类型	说明
聊天助手	单轮或多轮对话，最简单
Agent	可调用工具，多步推理
Chatflow	可视化编排的对话流程
Workflow	批处理流程，无对话界面

以 Chatflow 为例

1. 新建 Chatflow

工作室 → 创建应用 → Chatflow

2. 基本节点构成

[开始] → [知识检索] → [LLM] → [回复]

3. 知识检索节点配置

选择已创建的知识库
检索模式：混合检索
Top K：3（返回最相关的3段）
Score 阈值：0.5（低于此相似度的结果不采用）

4. LLM 节点配置

System Prompt 示例：

你是一个专业的客服助手。
请根据以下检索到的知识库内容回答用户问题：

{{#context#}}

如果知识库中没有相关信息，请如实告知用户，不要编造答案。

5. 发布应用

右上角发布 → 选择发布方式：

嵌入网站（iframe / 脚本）
独立页面
API 调用

六、API 接入

每个 Dify 应用都会自动生成 REST API，方便接入自己的业务系统。

获取 API Key

进入对应应用
左侧菜单 → 访问 API
右上角 API Key → 创建密钥

Chatflow API 调用示例

发送消息（流式响应）：

import requests
import json

url = "http://你的服务器IP/v1/chat-messages"
headers = {
    "Authorization": "Bearer app-xxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
}

payload = {
    "inputs": {},
    "query": "你好，请问如何申请退款？",
    "response_mode": "streaming",  # 流式输出
    "conversation_id": "",          # 首次为空，后续传上一次的 id
    "user": "user-001"
}

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

for line in response.iter_lines():
    if line:
        line = line.decode('utf-8')
        if line.startswith('data: '):
            data = json.loads(line[6:])
            if data.get('event') == 'message':
                print(data.get('answer', ''), end='', flush=True)

非流式响应：

payload["response_mode"] = "blocking"
response = requests.post(url, headers=headers, json=payload)
result = response.json()
print(result['answer'])

Workflow API 调用示例

url = "http://你的服务器IP/v1/workflows/run"
headers = {
    "Authorization": "Bearer app-xxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
}

payload = {
    "inputs": {
        "customer_name": "张三",
        "issue_type": "退款"
    },
    "response_mode": "blocking",
    "user": "user-001"
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()
print(result['data']['outputs'])

常用 API 接口汇总

接口	方法	说明
`/v1/chat-messages`	POST	发送对话消息
`/v1/conversations`	GET	获取会话列表
`/v1/conversations/:id/messages`	GET	获取历史消息
`/v1/workflows/run`	POST	执行工作流
`/v1/files/upload`	POST	上传文件

七、Workflow 进阶：常用节点

代码节点

支持 Python / JavaScript，可以做数据处理：

def main(inputs: dict) -> dict:
    name = inputs.get("name", "")
    score = inputs.get("score", 0)
    
    level = "优秀" if score >= 90 else "良好" if score >= 70 else "待提升"
    
    return {
        "result": f"{name} 的评级为：{level}（{score}分）"
    }

HTTP 请求节点

直接在工作流中调用外部 API：

方法：POST
URL：https://api.example.com/notify
Header：Authorization: Bearer {{token}}
Body：{"user_id": "{{user_id}}", "message": "{{message}}"}

条件分支节点

根据变量值走不同流程：

IF score >= 90 → 发送优秀通知
ELSE IF score >= 60 → 发送合格通知  
ELSE → 发送预警通知

迭代节点

对列表中的每个元素执行相同操作，类似 for 循环。

八、常见问题排查

容器启动失败

# 查看具体报错
docker logs docker-api-1

# 重启单个服务
docker compose restart api

知识库检索效果差

检查分段是否合理，避免一段内容过于杂乱
调低 Score 阈值（如从 0.5 降到 0.3）
尝试换用混合检索模式
检查 Embedding 模型是否支持中文

API 返回 401

{"code": "unauthorized", "message": "Unauthorized."}

→ 检查 Authorization Header 格式：Bearer app-你的key，注意 Bearer 后有空格

模型调用失败

# 查看 API 日志
docker logs docker-api-1 --tail 100

常见原因：API Key 错误、网络无法访问模型服务商、余额不足

九、生产环境建议

事项	建议
SECRET_KEY	必须替换默认值，使用 `openssl rand -base64 42` 生成
HTTPS	配置 SSL 证书，避免明文传输 API Key
数据备份	定期备份 PostgreSQL 数据和上传的文件
资源监控	向量数据库（Weaviate）比较吃内存，建议监控
版本升级	升级前对比 `.env.example` 的变更，备份数据库

十、总结

Dify 的核心价值在于把 LLM 应用的通用基础设施都帮你搭好了，开发者只需要专注在业务逻辑本身：

你负责：业务流程设计 + Prompt 调优 + API 接入
Dify 负责：模型调度 + 向量检索 + 对话管理 + 流式输出 + 插件生态

对于有一定开发基础的团队，Dify 可以极大缩短从想法到上线的周期。结合 Workflow 的可视化编排能力，非技术成员也能参与 AI 应用的迭代，降低了协作门槛。

参考资料

Dify 官方文档：Introduction - Dify Docs

GitHub 仓库：GitHub - langgenius/dify: Production-ready platform for agentic workflow development. · GitHub

Dify Marketplace（插件）：Dify Marketplace