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

本文面向有一定开发基础的读者，涵盖 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