Dify 安装、使用方法详细全解

Dify 安装、使用方法详细全解

目录

1. 项目概述

1.1 Dify 是什么

Dify（Dify.AI）是一个开源的大语言模型（LLM）应用开发与运维平台，由 LangGenius, Inc. 开发。

核心定位：“Production-ready platform for agentic workflow development”（面向生产环境的智能体工作流开发平台）

解决的核心问题：

• 降低构建 LLM 应用的技术门槛——无需编写胶水代码即可将 AI 模型、工具、数据源快速整合
• 提供从原型到生产的一站式开发环境
• 提供直观的可视化画布界面，让非程序员也能构建复杂的 AI 应用

1.2 核心特性

Dify 提供六大核心功能模块：

1.3 适用场景

• RAG 聊天机器人 / 知识库问答系统
• 内容生成自动化
• 智能客服与支持系统
• 多步骤 AI 业务流程编排
• 数据洞察与分析
• 潜在客户生成与营销自动化
• 企业搜索与知识管理

1.4 开源情况

2. 安装部署

2.1 系统要求

2.2 Docker Compose 本地开发安装

前置依赖

# Ubuntu/Debian – 安装 Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# 安装 Docker Compose 插件 (V2)
sudo apt install docker-compose-plugin

# 验证版本
docker –version
docker compose version # 必须 ≥ 2.24.0

安装步骤

# 第 1 步：克隆仓库
git clone https://github.com/langgenius/dify.git
cd docker

# 第 2 步：复制环境变量文件
cp .env.example .env

# 第 3 步：编辑 .env 修改必要配置（SECRET_KEY、数据库密码等）
nano .env

# 第 4 步：启动服务
docker compose up -d

# 第 5 步：查看日志确认服务状态
docker compose logs -f

启动后访问

• 默认地址：http://localhost:80（Nginx 代理端口）
• 首次访问会引导创建管理员账户

核心服务容器清单

数据库与向量数据库选择

数据库选项（通过 DB_TYPE 选择）：

• postgres（默认）— PostgreSQL 15
• mysql — MySQL 8.0
• oceanbase — OceanBase 4.3.5（国产数据库）

向量数据库选项（通过 VECTOR_STORE 选择，17+ 种）：

• weaviate（默认）
• qdrant、milvus、pgvector、pgvecto-rs
• chroma、elasticsearch、opensearch
• redis、opengauss、myscale、matrixone 等

# .env 中设置
DB_TYPE=postgresql
VECTOR_STORE=weaviate

# 或使用 profiles 启动特定服务
docker compose –profile milvus –profile postgresql up -d

常用操作命令

# 停止服务
docker compose down

# 重启服务
docker compose restart

# 查看服务状态
docker compose ps

# 升级 Dify
cd /path/to/dify
git pull origin main
cd docker
docker compose pull # 拉取新镜像
docker compose up -d # 重启

# 环境变量同步工具（升级后使用）
chmod +x dify-env-sync.sh
./dify-env-sync.sh

SSL/TLS 配置（HTTPS）

# .env 中设置
CERTBOT_EMAIL=your@email.com
CERTBOT_DOMAIN=your-domain.com
NGINX_HTTPS_ENABLED=true

# 启动 certbot profile
docker compose –profile certbot up -d

2.3 关键环境变量配置

# ==================== 安全与密钥 ====================
SECRET_KEY=*** # ⚠️ 必须修改！
CODE_EXECUTION_API_KEY=*** # 沙箱 API 密钥
PLUGIN_DAEMON_KEY=*** # 插件守护进程密钥

# ==================== 数据库 ====================
DB_TYPE=postgresql
DB_USERNAME=postgres
DB_PASSWORD=*** # ⚠️ 必须修改！
DB_HOST=db_postgres
DB_PORT=5432
DB_DATABASE=dify

# ==================== Redis ====================
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=*** # ⚠️ 必须修改！
CELERY_BROKER_URL=redis://:password@redis:6379/1

# ==================== 向量数据库 ====================
VECTOR_STORE=weaviate # 17+ 种选择

# ==================== 存储 ====================
STORAGE_TYPE=opendal # opendal/s3/azure-blob/google-storage
OPENDAL_SCHEME=fs
OPENDAL_FS_ROOT=storage

# ==================== 运行时 ====================
DEPLOY_ENV=PRODUCTION
LOG_LEVEL=INFO
DEBUG=false

2.4 生产环境部署方案

方案一：Kubernetes + Helm Chart

社区 Helm Chart（BorisPolonsky/dify-helm）：

# 添加仓库
helm repo add dify https://borispolonsky.github.io/dify-helm
helm repo update

# 基础安装
helm install dify dify/dify –namespace dify –create-namespace

# 使用自定义 values.yaml
helm install dify ./charts/dify –namespace dify –create-namespace -f custom-values.yaml

生产环境推荐配置：

api:
replicas: 3
resources:
requests: { cpu: 500m, memory: 1Gi }
limits: { cpu: 1000m, memory: 2Gi }
autoscaling:
enabled: true
minReplicas: 2
maxReplicas: 10

worker:
replicas: 2
resources:
requests: { cpu: 1000m, memory: 2Gi }
limits: { cpu: 2000m, memory: 4Gi }

方案二：AWS 部署

• AWS Marketplace — Dify Premium（官方云原生版本）
• Terraform + ECS Fargate：ECS + RDS Aurora PostgreSQL + ElastiCache Redis + S3
• 仓库：https://github.com/sonodar/dify-aws-terraform

方案三：GCP 部署

• Terraform + Cloud Run：Serverless + Cloud SQL PostgreSQL + Cloud Memorystore + Cloud Storage
• 仓库：https://github.com/DeNA/dify-google-cloud-terraform

方案四：Azure 部署

• AKS + Helm Chart：Azure Kubernetes Service
• 仓库：https://github.com/Ruiruiz30/Dify-helm-chart-AKS

部署方式对比

3. 使用方法

3.1 应用类型概览

Dify 支持四种主要应用类型：

3.2 Prompt Engineering / 提示词编排

创建 Chatbot 应用

变量系统

在提示词中输入 / > 新建变量（New Variable） 快速插入：

变量语法：{{variable_name}}

AI 辅助提示词生成

• 点击 Generate（生成） 按钮，让 LLM 帮助起草或优化提示词
• 在 Ideal Output（理想输出） 中添加示例以获得更精准结果
• 每次生成保存为一个版本，支持自由回滚

多模态支持

• Vision（视觉）：图片处理，支持高/低分辨率配置
• Audio（音频）：语音处理
• Document（文档）：文档处理

模型对比调试

• 选择 “多模型调试” 可同时运行最多 4 个模型进行输出对比
• 模型参数调节：Temperature（0-1）、Top P、Frequency Penalty、Presence Penalty
• 预设模式：Precise（精确）、Balanced（平衡）、Creative（创意）

应用工具箱（App Toolkit）

3.3 Agent 创建与配置

什么是 Agent

Agent 是聊天式应用，模型可以自主推理任务、决定下一步操作，并在需要时使用工具。

创建步骤

推理策略

内置工具（50+）

自定义工具创建

3.4 工作流（Workflow）编排

工作流 vs Chatflow

所有节点类型（26+ 种）

ROOT（入口节点）

EXECUTABLE（逻辑节点）

BRANCH（分支节点）

If-Else 比较运算符：

• 文本：包含/不包含、以…开头/结尾、等于/不等于
• 数值：等于/不等于、大于/小于、≥/≤
• 通用：为空/不为空
• 逻辑组合：AND（所有条件为真）/ OR（任一条件为真）

CONTAINER（容器节点）

Iteration vs Loop 对比：

Iteration 内置变量：

• items[object]：当前元素
• index[number]：当前索引（从 0 开始）

错误处理： Terminate（终止）/ Continue on Error（出错继续）/ Remove Failed Results（移除失败结果）

RESPONSE（输出节点）

UTILITY（工具节点）

并行执行

• 从同一节点分出多条路径可同时运行
• 并行分支在汇聚点后合并
• 注意：并行节点无法读取彼此的变量，但汇聚点后下游节点可读取所有来源

错误处理

重试配置： 最多 10 次自动重试，可配置重试间隔（最大 5000ms）

Human-in-the-Loop (HITL)

Dify 1.13.0 引入 Human Input 节点：

• 传递方式：Web 应用 / 邮件（发送链接到成员或外部邮箱）
• 表单内容：Markdown 格式、动态变量引用、输入字段
• 用户操作：预定义决策按钮，每个按钮路由到不同路径
• 超时策略：默认 3 天，超时后走超时分支

典型场景：

LLM 生成内容 → Human Input（审批/修改）→ [批准 → 发布] / [修改 → LLM 重新生成]

变量和数据传递

• 变量引用语法：{{#node_id.field_name#}} 或 {{variable_name}}
• 工作流变量：仅在一次执行中存活
• 会话变量：在整个聊天会话中持久化（Chatflow）

调试与发布

• 右侧预览面板实时测试
• 多模型调试（最多 4 个模型对比）
• 完整执行日志查看（节点链路 + 变量值）
• 发布选项：WebApp / API / Workflow as Tool / Mermaid 图表导出
• 版本控制：每次发布创建新版本，支持回滚

3.5 RAG（检索增强生成）

RAG 管线工作流程

文档上传 → 数据清洗 → 文本分块 → 向量化 → 索引存储
↓
用户查询 → 向量化 → 向量检索 + 关键词检索 → Rerank → 上下文注入 → LLM 生成回答

分块策略（Chunking）

关键参数：

• 最大 chunk 长度（通常 100~1000 tokens）
• 重叠令牌数（Overlap Tokens）
• 分隔符（Separators）

检索策略

重排序（Rerank）： 使用 Cross-Encoder 模型（如 Cohere Rerank、BGE Reranker）对候选 chunks 精细化打分排序。

Dify 官方博客表明，混合检索 + 语义重排序方案比 OpenAI Assistants API 的 RAG 效果高出 20%。

元数据过滤

• 为文档添加自定义元数据（作者、日期、分类等）
• 手动过滤：在检索节点设置元数据过滤规则
• LLM 自动过滤：LLM 分析用户查询，自动决定过滤哪些元数据

多模态 RAG（v1.11.0+）

• 多模态 Embedding：文本和图像同时向量化
• 自动图片提取：PDF/Markdown 中的图片自动提取并索引
• 跨模态搜索：文字查图、图片查文字
• 使用多模态 Embedding 的知识库标记为 Multimodal

3.6 数据集管理

创建数据集

三种方式：

支持的导入格式

导入方法

索引方式

注意：高质量模式不能降级为经济模式。

文档管理

• 状态流转：waiting → parsing → cleaning → splitting → indexing → completed（失败则为 error）
• 在线编辑：可修改、合并、拆分 chunk
• 批量操作：支持多文档删除
• 分段管理：每个文档分割为多个 segment，可单独启用/禁用/删除
• API 查询进度：GET /v1/datasets/{id}/documents/{doc_id}/indexing-status

数据集权限

3.7 API 集成

API 分类

Chat API

POST /v1/chat-messages — 创建聊天消息

curl -X POST https://api.dify.ai/v1/chat-messages -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{
"inputs": {},
"query": "你好，请介绍一下你的功能",
"response_mode": "streaming",
"user": "user-123456",
"conversation_id": "",
"files": []
}'

流式响应（SSE）：

event: message
data: {"event":"agent_message","answer":"你好…","conversation_id":"xxx"}

event: message_end
data: {"event":"message_end","metadata":{"usage":{"total_tokens":123}}}

其他端点：

• GET /v1/conversations — 获取会话列表
• GET /v1/messages — 获取消息列表
• DELETE /v1/conversations/{id} — 删除会话
• POST /v1/messages/{id}/feedback — 消息反馈

Workflow API

POST /v1/workflows/run — 运行工作流

curl -X POST https://api.dify.ai/v1/workflows/run -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{
"inputs": {"input_param_1": "value1"},
"response_mode": "streaming",
"user": "user-123456"
}'

流式事件： workflow_started → node_started → node_finished → workflow_finished

其他端点：

• GET /v1/workflows/{run_id}/results — 获取执行结果
• POST /v1/workflows/{run_id}/stop — 停止执行

Completion API

POST /v1/completion-messages — 创建完成消息

curl -X POST https://api.dify.ai/v1/completion-messages -H "Authorization: Bearer {API_KEY}" -d '{
"inputs": {"text": "请帮我写一段介绍"},
"response_mode": "streaming",
"user": "user-123456"
}'

Dataset API（知识库 API）

# 创建数据集
curl -X POST https://api.dify.ai/v1/datasets -H "Authorization: Bearer {DATASET_API_KEY}" -d '{"name":"我的知识库","indexing_technique":"high_quality",…}'

# 创建文档（从文本）
curl -X POST https://api.dify.ai/v1/datasets/{id}/document/create-by-text -d '{"name":"示例文档","text":"文档内容…",…}'

# 创建文档（从文件）
curl -X POST https://api.dify.ai/v1/datasets/{id}/document/create-by-file -F "file=@document.pdf" -F 'data={"indexing_technique":"high_quality"}'

# 查询检索
curl -X POST https://api.dify.ai/v1/retrieval -d '{"query":"检索问题","retrieval_model":{"search_method":"hybrid_search","top_k":4,…}}'

HITL API

文件上传 API

POST /v1/files/upload

curl -X POST https://api.dify.ai/v1/files/upload -H "Authorization: Bearer {API_KEY}" -F "user=user-123456" -F "file=@image.png"

在消息中引用：

{
"files": [
{"type": "image", "transfer_method": "remote_url", "url": "https://example.com/image.png"},
{"type": "document", "transfer_method": "local_file", "upload_file_id": "xxx"}
]
}

音频 API

• POST /v1/audio-to-text — 语音转文字（STT）
• POST /v1/text-to-audio — 文字转语音（TTS）

SDK 可用性

Node.js SDK 示例：

const { ChatClient } = require('dify-client');
const chat = new ChatClient('api-key');
const result = await chat.createMessage({ query: 'Hello', user: 'user-123' }, (data) => {
console.log(data);
});

3.8 模型配置

支持的模型提供商

Dify 支持数十家模型提供商，涵盖以下类型：

模型类型支持：

• LLM — 大语言模型
• Text Embedding — 文本向量化
• Rerank — 重排序
• Speech-to-Text — 语音转文字
• Text-to-Speech — 文字转语音
• Moderation — 内容审核
• Speech-to-Text — STT

添加自定义模型

方式一：自定义提供商（Custom Provider）

在模型提供商页面 → 添加自定义提供商：

方式二：OpenAI 兼容端点

任何兼容 OpenAI API 的端点（如 vLLM、Ollama、本地部署的 Llama.cpp 等）均可直接接入。

方式三：插件系统

通过 Dify Marketplace 安装社区模型插件。

3.9 插件/扩展系统

架构

Dify 插件系统采用解耦架构，每个插件作为独立包运行：

• 独立开发、部署和维护
• 标准化的版本控制和安全管理
• 通过 Plugin Daemon 进行统一管理

插件类型

Dify Marketplace

• 网址：https://marketplace.dify.ai
• 社区插件库，包含自动审核机制
• 插件源码仓库：https://github.com/langgenius/dify-plugins

MCP 集成

Dify 支持 MCP（Model Context Protocol）标准，可接入 MCP 工具服务器。

3.10 团队协作与权限管理

工作区（Workspace）概念

Dify 的权限体系以 工作区（Workspace） 为中心。每个用户可属于多个工作区。

角色体系

邀请成员

3.11 日志与监控

内置分析

• 应用日志：查看每次对话/工作流执行的完整记录
• 性能指标：Token 消耗、响应时间、模型使用统计
• 标注功能：对 AI 回复进行标注，用于持续优化
• 版本对比：不同版本的应用使用效果对比

外部可观测性集成

Grafana 监控

通过 PostgreSQL 数据源接入 Grafana：

# Grafana 数据源配置
Host: <dify-postgres-host>
Port: 5432
Database: dify
User: <db-user>
SSL Mode: disable

日志级别配置

# .env 中设置
LOG_LEVEL=INFO # DEBUG / INFO / WARNING / ERROR

4. 生态系统与资源

4.1 官方资源

4.2 社区资源

4.3 教程与视频

4.4 第三方部署方案

5. 商业版 vs 开源版对比

5.1 三种部署模式

5.2 许可证限制

Dify Open Source License 基于 Apache 2.0，附加两项限制：

5.3 版本发布频率

• 平均 每 1-2 周发布一个新版本
• 发布频率极高，更新非常活跃

最近版本：

总结

Dify 是目前GitHub 上最受欢迎的开源 LLM 应用开发平台之一（14.4 万+ Star），核心优势包括：

推荐场景：需要快速构建 AI 应用、搭建企业知识库问答系统、编排复杂 AI 工作流的团队和个人开发者。