Dify 使用指南：从模型接入到生产级 AI 应用的完整路径
Dify 使用指南：从模型接入到生产级 AI 应用的完整路径
本文面向初中级 AI 应用开发者，以能力演进为主线，系统讲透 Dify 平台的核心概念与实操技巧。从"为什么要用 Dify"讲起，逐层深入到模型接入、Prompt 编排、RAG 知识库、Workflow、Agent、API 发布与生产运营。读完本文，你将具备独立构建生产级 AI 应用的完整能力。
一、为什么需要 Dify？
1.1 裸调 API 的痛苦
假设你要用大模型做一个"客服问答系统"。最原始的方式是：
import openai
response = openai.chat.completions.create(
model="gpt-4",
messages=[
{"role": "system", "content": "你是一个客服..."},
{"role": "user", "content": user_question}
]
)
看起来很简单。但当你真正要做成产品时，问题接踵而至：
| 痛点 | 具体表现 |
|---|---|
| Prompt 管理混乱 | 散落在代码各处，改一个词要重新部署 |
| 模型切换成本高 | 想从 GPT-4 换成 Claude？改代码、改参数、重新测试 |
| 没有 RAG 能力 | 用户问"你们的退款政策是什么"，模型根本不知道 |
| 无法可视化调试 | 出了问题只能看日志，无法直观看到每一步的输入输出 |
| 团队协作困难 | 产品经理想调 Prompt？对不起，得找开发改代码 |
| 缺乏运营能力 | 没有日志、没有标注、没有用户反馈闭环 |
1.2 Dify 的定位
Dify 是一个开源的 LLM 应用开发平台，它的核心价值是：
把"写代码调 API"变成"可视化拖拽编排"，把"单次调用"变成"可运营的产品"。
它在 AI 技术栈中的位置：
┌─────────────────────────────────────────────────┐
│ 你的业务系统 / 用户界面 │
├─────────────────────────────────────────────────┤
│ Dify（应用编排层） │
│ Prompt管理 │ RAG │ Workflow │ Agent │ API │
├─────────────────────────────────────────────────┤
│ 模型层（可切换） │
│ OpenAI │ Claude │ 通义千问 │ Llama │ 本地模型 │
├─────────────────────────────────────────────────┤
│ 基础设施 │
│ 向量数据库 │ 对象存储 │ 日志 │ 监控 │
└─────────────────────────────────────────────────┘
1.3 Dify 的四种应用类型
Dify 支持创建四种类型的应用，它们对应不同的复杂度层级：
| 类型 | 适用场景 | 复杂度 | 类比 |
|---|---|---|---|
| Chatbot | 对话式交互（客服、助手） | ★☆☆☆ | 一个"会说话的人" |
| Text Generator | 单次输入→单次输出（翻译、摘要） | ★☆☆☆ | 一个"函数调用" |
| Agent | 自主决策、调用工具完成复杂任务 | ★★★☆ | 一个"会做事的人" |
| Workflow | 多步骤、有分支的复杂流程 | ★★★★ | 一条"生产线" |
本文按照从简到繁的顺序，逐层讲透每一种类型及其背后的核心概念。
二、第一层：模型接入——Dify 的"地基"
2.1 模型供应商（Model Provider）
Dify 本身不是模型，它是一个调度层。你需要先接入至少一个模型供应商：
支持的供应商（部分）：
| 供应商 | 代表模型 | 接入方式 |
|---|---|---|
| OpenAI | GPT-4o、GPT-4o-mini | API Key |
| Anthropic | Claude 3.5 Sonnet | API Key |
| 通义千问 | Qwen-Max、Qwen-Plus | API Key |
| 智谱 AI | GLM-4 | API Key |
| 本地部署 | Llama 3、Qwen（Ollama/vLLM） | 本地地址 |
| Azure OpenAI | GPT-4（企业版） | Endpoint + Key |
| Hugging Face | 开源模型 | Inference API |
2.2 接入配置
在 Dify 后台 → 设置 → 模型供应商 中添加：
以通义千问为例：
1. 选择"通义千问"供应商
2. 填入 API Key（从阿里云百炼平台获取）
3. 选择可用模型：qwen-max、qwen-plus、qwen-turbo
4. 点击"保存"并测试连通性
2.3 模型选择策略
不同任务适合不同模型，Dify 允许你在同一个应用中按用途分配不同模型：
| 用途 | 推荐模型 | 原因 |
|---|---|---|
| 主对话（复杂推理） | GPT-4o / Claude 3.5 / Qwen-Max | 推理能力强 |
| 简单分类/提取 | GPT-4o-mini / Qwen-Turbo | 速度快、成本低 |
| Embedding（向量化） | text-embedding-3-small / bge-large | 专用于文本转向量 |
| Rerank（重排序） | bge-reranker / Cohere Rerank | 提升检索精度 |
2.4 关键参数理解
每个模型调用都有几个核心参数：
| 参数 | 含义 | 建议值 |
|---|---|---|
| Temperature | 输出随机性（0=确定，1=创造） | 客服/提取：0~0.3；创作：0.7~1.0 |
| Top-P | 核采样概率阈值 | 通常 0.9~1.0，与 Temperature 二选一调 |
| Max Tokens | 最大输出长度 | 根据场景设置，避免截断 |
| Presence Penalty | 重复惩罚 | 需要多样性时适当提高 |
| Frequency Penalty | 频率惩罚 | 减少重复用词 |
实践建议： - 先用默认参数跑通，再逐个微调 - Temperature 和 Top-P 不要同时大幅调整，选一个为主 - 生产环境中，Temperature 设低（0~0.3）保证输出稳定
三、第二层：Prompt 编排——从散乱到可视化
3.1 编排界面
Dify 的 Prompt 编排是可视化的。创建一个 Chatbot 应用后，你会看到：
┌─────────────────────────────────────────────────────┐
│ 应用编排 │
│ │
│ ┌─────────────────────────────────────────────┐ │
│ │ 模型选择：[qwen-max ▼] │ │
│ │ Temperature：[0.3 ━━━●━━━] │ │
│ └─────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────┐ │
│ │ 提示词（System Prompt）： │ │
│ │ │ │
│ │ 你是一位专业的{{domain}}顾问。 │ │
│ │ 请根据用户问题提供准确、有条理的回答。 │ │
│ │ 如果不确定，请明确告知用户。 │ │
│ │ │ │
│ └─────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────┐ │
│ │ 变量： │ │
│ │ {{domain}} → 用户输入 / 固定值 / 环境变量 │ │
│ └─────────────────────────────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────────────────┐ │
│ │ 调试预览 │ │ 日志 & 标注 │ │
│ └──────────────┘ └──────────────────────────┘ │
└─────────────────────────────────────────────────────┘
3.2 变量系统
Dify 的 Prompt 支持变量插值，这是它比裸写代码强大的地方之一：
变量类型：
| 类型 | 语法 | 说明 | 示例 |
|---|---|---|---|
| 用户输入变量 | {{query}} |
用户在对话框输入的内容 | 自动绑定 |
| 表单变量 | {{name}} |
应用启动前用户填写的字段 | 姓名、公司、偏好 |
| 环境变量 | {{env.API_VERSION}} |
全局配置，不随对话变化 | 版本号、域名 |
| 会话变量 | {{conversation.id}} |
当前会话的元信息 | 会话 ID、轮次 |
| 系统变量 | {{#sys.query#}} |
Workflow 中上游节点的输出 | 前一步的结果 |
实践示例：
# System Prompt（使用变量）
你是{{company_name}}的{{role}}，服务于{{department}}部门。
当前时间：{{current_time}}
用户等级：{{user_level}}
请根据用户等级调整回答深度：
- VIP用户：提供详细的技术细节和源码级解释
- 普通用户：提供简洁明了的操作指引
3.3 开场白与对话变量
Chatbot 类型应用还支持：
- 开场白（Opening Statement）：用户进入时自动显示的第一条消息
- 下一步问题建议（Suggested Questions）：AI 回答后自动推荐 3 个后续问题
- 对话变量（Conversation Variables）：在多轮对话中持久保存的状态值
3.4 调试与标注
Dify 提供实时调试面板：
- 在右侧"调试预览"中输入测试问题
- 查看完整的请求/响应（包括实际发送给模型的 Prompt）
- 对回答进行"点赞/点踩"标注
- 标注数据可用于后续的 Prompt 优化
实践建议： - Prompt 中使用变量而非硬编码，方便复用和 A/B 测试 - 利用"日志"功能查看真实用户的提问，发现 Prompt 的盲区 - 定期查看"点踩"记录，针对性优化
四、第三层：RAG 知识库——给 AI 装上"专业大脑"
4.1 为什么需要 RAG？
大模型有两个根本性缺陷： 1. 知识截止：训练数据有截止日期，不知道最新信息 2. 缺乏私有知识：不知道你公司的内部文档、产品手册、业务规则
RAG（Retrieval-Augmented Generation，检索增强生成） 的解决思路：
用户提问
│
▼
┌──────────────┐ ┌──────────────┐
│ 将问题向量化 │────►│ 在知识库中 │
│ (Embedding) │ │ 语义搜索 │
└──────────────┘ └──────┬───────┘
│
▼ 找到最相关的 3~5 段文档
┌──────────────┐
│ 将文档片段 │
│ 注入 Prompt │
└──────┬───────┘
│
▼
┌──────────────┐
│ LLM 基于 │
│ 文档回答问题 │
└──────────────┘
4.2 创建知识库
在 Dify 中：知识库 → 创建知识库 → 上传文档
支持的数据源：
| 来源 | 格式 | 说明 |
|---|---|---|
| 文件上传 | PDF、Word、Markdown、TXT、HTML、CSV | 最常用 |
| 网页抓取 | URL | 自动爬取网页内容 |
| Notion | 页面/数据库 | 需授权连接 |
| API 同步 | 自定义 | 通过 API 推送文档 |
4.3 分段策略（Chunking）
文档上传后需要切分为小段（Chunk），这是 RAG 质量的关键：
| 策略 | 适用场景 | 参数建议 |
|---|---|---|
| 自动分段 | 通用文档 | 500~1000 token/段，重叠 50~100 |
| 按段落分段 | 结构化文档（FAQ、手册） | 以空行/标题为分隔 |
| 按固定长度 | 代码、日志 | 根据上下文窗口调整 |
| 自定义分隔符 | 特殊格式 | 指定分隔正则 |
分段的核心原则： - 每段应该是一个语义完整的信息单元 - 太小 → 信息碎片化，检索到也不完整 - 太大 → 噪声多，稀释关键信息 - 重叠（Overlap）防止关键信息被切断
4.4 索引方式
| 索引模式 | 原理 | 适用场景 |
|---|---|---|
| 高质量（向量） | Embedding → 向量数据库 | 语义搜索，最常用 |
| 经济（关键词） | 倒排索引 | 精确匹配术语、编号 |
| 混合检索 | 向量 + 关键词 + Rerank | 生产环境推荐 |
4.5 检索配置
在应用中关联知识库后，可配置检索参数：
检索模式：混合检索（推荐）
Top-K：5（返回最相关的 5 段）
Score 阈值：0.5（过滤低相关性结果）
Rerank：开启（使用 bge-reranker 重排序）
4.6 提升 RAG 质量的实战技巧
| 技巧 | 说明 |
|---|---|
| 文档预处理 | 上传前清理格式、添加标题层级、去除页眉页脚 |
| FAQ 化 | 将长文档改写为 Q&A 格式，检索命中率大幅提升 |
| 元数据标注 | 给每段添加来源、日期、类别等元数据，支持过滤 |
| 多知识库分层 | 通用知识 + 专业知识分开，按问题类型路由 |
| 定期更新 | 设置自动同步，避免知识过期 |
| 召回测试 | 用真实问题测试检索结果，调整分段和 Top-K |
五、第四层：Workflow——从单步到多步编排
5.1 为什么需要 Workflow？
简单的 Chatbot 是"一问一答"。但真实业务往往是多步骤的：
用户提交简历
→ 提取关键信息（姓名、学历、技能）
→ 判断是否符合岗位要求
→ 如果符合：生成面试邀请
→ 如果不符合：生成婉拒信
→ 发送对应邮件
这种有分支、循环、多步处理的流程，需要 Workflow。
5.2 Workflow 的核心概念
| 概念 | 说明 |
|---|---|
| 节点（Node） | 流程中的一个处理步骤 |
| 连线（Edge） | 节点之间的执行顺序 |
| 变量传递 | 上游节点的输出作为下游节点的输入 |
| 分支（IF/ELSE） | 根据条件走不同路径 |
| 并行 | 多个节点同时执行 |
5.3 节点类型全解
Dify Workflow 提供丰富的节点类型：
| 节点 | 功能 | 典型用途 |
|---|---|---|
| 开始 | 定义输入变量 | 接收用户输入 |
| LLM | 调用大模型 | 生成、分析、提取 |
| 知识检索 | 从知识库搜索 | RAG 检索 |
| IF/ELSE | 条件分支 | 路由、判断 |
| 代码 | 执行 Python/JS | 数据转换、计算 |
| HTTP 请求 | 调用外部 API | 集成第三方服务 |
| 模板转换 | Jinja2 模板渲染 | 格式化输出 |
| 变量聚合 | 合并多个变量 | 汇总并行结果 |
| 迭代 | 对列表逐项处理 | 批量处理 |
| 参数提取 | 从文本中提取结构化数据 | 表单填充 |
| 问题分类 | 将问题路由到不同分支 | 意图识别 |
| 结束 | 定义最终输出 | 返回结果 |
5.4 一个完整的 Workflow 示例
场景：智能文档摘要 + 翻译流水线
┌──────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────┐
│ 开始 │───►│ LLM节点1 │───►│ 代码节点 │───►│ LLM节点2 │───►│ 结束 │
│ │ │ 生成摘要 │ │ 字数检查 │ │ 翻译英文 │ │ │
└──────┘ └──────────┘ └─────┬────┘ └──────────┘ └──────┘
│
│ 如果超过500字
▼
┌──────────┐
│ LLM节点3 │
│ 二次精简 │
└─────┬────┘
│
└──► 回到"翻译英文"
节点配置示例（LLM 节点）：
节点名称: 生成摘要
模型: qwen-max
Temperature: 0.2
System Prompt: |
你是一位专业的文档分析师。
请对以下文档生成结构化摘要，包含：
1. 核心主题（一句话）
2. 关键要点（3-5条）
3. 结论/建议
User Prompt: |
{{#start.document#}}
5.5 Workflow 中的变量引用
Dify 使用 {{#node_id.variable#}} 语法引用其他节点的输出：
{{#start.user_input#}} ← 开始节点的用户输入
{{#llm_1.text#}} ← LLM节点1的输出文本
{{#code_1.result#}} ← 代码节点1的返回值
{{#knowledge_1.result#}} ← 知识检索的结果
5.6 实践建议
- 先画流程图，再搭建节点：在纸上理清逻辑再动手
- 每个 LLM 节点只做一件事：不要在一个 Prompt 里又摘要又翻译又分类
- 善用代码节点做"胶水"：格式转换、数据清洗用代码比 LLM 更可靠
- 设置错误处理：HTTP 节点设置超时和重试，LLM 节点设置 fallback
- 利用迭代节点处理批量：比如对多条评论逐条分析
六、第五层：Agent——自主决策的执行体
6.1 Agent 与 Workflow 的区别
| 维度 | Workflow | Agent |
|---|---|---|
| 执行路径 | 预定义的固定流程 | AI 自主决定下一步 |
| 分支逻辑 | 开发者写 IF/ELSE | AI 根据情况自行判断 |
| 工具调用 | 在固定位置调用 | AI 决定何时调用哪个工具 |
| 适用场景 | 流程明确、步骤固定 | 流程不确定、需要灵活应变 |
| 可控性 | 高（路径可预测） | 较低（AI 自主决策） |
简单判断标准： - 如果你能画出完整的流程图 → 用 Workflow - 如果你只能说"目标是 X，具体怎么做让 AI 自己决定" → 用 Agent
6.2 Dify Agent 的推理模式
| 模式 | 原理 | 适用场景 |
|---|---|---|
| Function Calling | 模型原生支持工具调用（GPT-4、Claude） | 首选，最稳定 |
| ReAct | Thought→Action→Observation 循环 | 模型不支持 FC 时的替代 |
6.3 工具（Tools）配置
Agent 的能力来自它可以调用的工具：
内置工具：
| 工具 | 功能 |
|---|---|
| 网络搜索 | Google/Bing 搜索 |
| 网页抓取 | 获取指定 URL 内容 |
| 代码执行 | 运行 Python 代码 |
| 数学计算 | 精确数学运算 |
| 图片生成 | DALL-E / Stable Diffusion |
| 天气查询 | 获取天气信息 |
自定义工具（通过 OpenAPI Schema）：
你可以把任何 API 注册为 Agent 工具：
# 示例：注册一个内部订单查询 API
openapi: 3.0.0
info:
title: 订单系统
version: 1.0.0
paths:
/api/orders/{order_id}:
get:
summary: 查询订单详情
description: 根据订单号查询订单状态、金额、物流信息
parameters:
- name: order_id
in: path
required: true
schema:
type: string
responses:
'200':
description: 订单详情
Dify 会解析这个 Schema，让 Agent 在需要时自动调用。
6.4 Agent 的约束配置
| 配置项 | 说明 | 建议 |
|---|---|---|
| 最大迭代次数 | Agent 最多循环几轮 | 5~15（防止无限循环） |
| 可用工具列表 | 限定 Agent 能调用哪些工具 | 最小权限原则 |
| System Prompt | 约束 Agent 的行为边界 | 明确禁止事项 |
| 超时时间 | 单次执行最长时长 | 根据业务设置 |
6.5 Agent 的 Prompt 设计
Agent 的 System Prompt 比 Chatbot 更关键，因为它决定了 AI 的"决策风格"：
你是{{company}}的智能客服 Agent。
## 能力范围
- 查询订单状态（使用 order_query 工具）
- 查询物流信息（使用 logistics_track 工具）
- 解答常见问题（参考知识库）
## 行为规则
1. 先理解用户意图，再决定是否调用工具
2. 如果用户提供了订单号，直接查询；否则先询问
3. 不要编造订单信息，必须通过工具获取
4. 如果问题超出能力范围，引导用户联系人工客服
5. 每次回复控制在 200 字以内
## 禁止事项
- 不得透露系统内部信息
- 不得承诺退款或赔偿（需人工处理）
- 不得执行与客服无关的操作
七、第六层：发布与集成——从玩具到产品
7.1 发布渠道
Dify 应用编排完成后，有多种发布方式：
| 渠道 | 说明 | 适用场景 |
|---|---|---|
| Web App | Dify 自带的对话界面 | 快速体验、内部使用 |
| 嵌入网页 | iframe / JS SDK 嵌入现有网站 | 官网客服、帮助中心 |
| API | RESTful API 调用 | 集成到自有系统 |
| 微信小程序 | 通过 API 对接 | C 端用户 |
7.2 API 集成
每个 Dify 应用自动生成 API，核心接口：
# 对话型应用（Chatbot / Agent）
curl -X POST 'https://your-dify.com/v1/chat-messages' \
-H 'Authorization: Bearer app-xxxxx' \
-H 'Content-Type: application/json' \
-d '{
"inputs": {"user_name": "张三"},
"query": "我的订单到哪了？",
"response_mode": "streaming",
"conversation_id": "",
"user": "user-123"
}'
# 文本生成型应用
curl -X POST 'https://your-dify.com/v1/completion-messages' \
-H 'Authorization: Bearer app-xxxxx' \
-H 'Content-Type: application/json' \
-d '{
"inputs": {"text": "需要翻译的内容"},
"response_mode": "blocking",
"user": "user-123"
}'
# Workflow 型应用
curl -X POST 'https://your-dify.com/v1/workflows/run' \
-H 'Authorization: Bearer app-xxxxx' \
-H 'Content-Type: application/json' \
-d '{
"inputs": {"document": "..."},
"response_mode": "streaming",
"user": "user-123"
}'
7.3 关键 API 参数
| 参数 | 说明 |
|---|---|
response_mode |
streaming（流式，推荐）/ blocking（等待完整响应） |
conversation_id |
多轮对话标识，首次为空，后续传回 |
user |
终端用户标识，用于日志追踪和限流 |
inputs |
应用定义的表单变量 |
files |
上传的文件（图片、文档） |
7.4 前端集成示例（JavaScript SDK）
<!-- 在网页中嵌入 Dify 对话窗口 -->
<script>
window.difyChatbotConfig = {
token: 'app-xxxxx',
baseUrl: 'https://your-dify.com',
inputs: {
// 预设变量
user_level: 'VIP'
},
userProperties: {
user_id: 'user-123',
name: '张三'
}
}
</script>
<script
src="https://your-dify.com/embed.min.js"
id="app-id"
defer>
</script>
7.5 生产环境部署
Dify 支持 Docker Compose 私有化部署：
# 克隆仓库
git clone https://github.com/langgenius/dify.git
cd dify/docker
# 配置环境变量
cp .env.example .env
# 编辑 .env：设置密码、密钥、模型配置等
# 启动
docker compose up -d
核心服务组成：
| 服务 | 作用 |
|---|---|
| api | 后端 API 服务 |
| worker | 异步任务处理 |
| web | 前端界面 |
| db | PostgreSQL 数据库 |
| redis | 缓存 & 消息队列 |
| weaviate/qdrant | 向量数据库 |
| sandbox | 代码执行沙箱 |
| nginx | 反向代理 |
八、第七层：运营与优化——持续迭代
8.1 日志与监控
Dify 内置完整的运营面板：
| 功能 | 说明 |
|---|---|
| 对话日志 | 查看所有用户对话、每步耗时、token 消耗 |
| 标注管理 | 对回答进行"正确/错误"标注，积累优化数据 |
| 用户反馈 | 收集终端用户的点赞/点踩 |
| Token 统计 | 按应用、按模型统计消耗和成本 |
| 活跃用户 | DAU、对话轮次、平均会话长度 |
8.2 Prompt 优化闭环
收集日志 → 发现 bad case → 分析原因 → 调整 Prompt/知识库 → 验证 → 上线
↑ │
└──────────────────────────────────────────────────────────────┘
常见 bad case 及对策：
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
| 回答不相关 | 检索到的文档不对 | 优化分段策略、调整 Top-K |
| 回答有幻觉 | Prompt 约束不够 | 添加"如果不确定请说明"指令 |
| 回答太啰嗦 | 缺少格式约束 | 在 Prompt 中限定字数和格式 |
| 工具调用错误 | 工具描述不清晰 | 优化 API Schema 的 description |
| 多轮对话"失忆" | 上下文窗口溢出 | 开启对话摘要压缩 |
8.3 成本控制
| 策略 | 说明 |
|---|---|
| 模型分级 | 简单问题用便宜模型，复杂问题用强模型 |
| 缓存 | 相同问题命中缓存直接返回（Dify 支持） |
| 限制长度 | 设置 Max Tokens 避免输出过长 |
| 知识库精简 | 减少无关文档，降低检索噪声 |
| 对话轮次限制 | 防止用户无限对话消耗 token |
8.4 安全与合规
| 措施 | 说明 |
|---|---|
| API Key 管理 | 不同应用使用不同 Key，定期轮换 |
| 敏感词过滤 | Dify 支持配置 Moderation 策略 |
| 访问控制 | 通过 API Key + 用户标识实现权限隔离 |
| 数据隔离 | 私有化部署保证数据不出内网 |
| 审计日志 | 记录所有对话，满足合规要求 |
九、全景图：一次请求的完整旅程
让我们追踪一个用户请求在 Dify 中的完整生命周期：
用户在网页输入："帮我查一下订单 ORD-2024-001 的物流状态"
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Dify 平台 │
│ │
│ ① 接收请求：解析 inputs + query + user │
│ │ │
│ ▼ │
│ ② 路由判断：这是一个 Agent 类型应用 │
│ │ │
│ ▼ │
│ ③ Agent 推理循环（Function Calling 模式）： │
│ ┌───────────────────────────────────────────────┐ │
│ │ LLM 思考：用户想查物流，需要调用物流查询工具 │ │
│ │ 调用工具：logistics_track(order_id="ORD-...") │ │
│ │ 工具返回：{status:"运输中", city:"上海"} │ │
│ │ LLM 思考：信息足够，可以回答了 │ │
│ │ 生成回答：基于工具结果组织自然语言回复 │ │
│ └───────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ④ 后处理：敏感词检查 → 格式化 → 记录日志 │
│ │ │
│ ▼ │
│ ⑤ 返回响应（SSE 流式输出） │
│ │
└─────────────────────────────────────────────────────────────┘
│
▼
用户看到："您的订单 ORD-2024-001 目前正在运输中，
已到达上海转运中心，预计明天送达。"
十、最佳实践与避坑指南
10.1 应用设计原则
| 原则 | 说明 |
|---|---|
| 单一职责 | 一个应用只做一件事，别做"全能助手" |
| 最小知识 | 知识库只放相关文档，别把整个公司wiki都塞进去 |
| 渐进增强 | 先 Chatbot 跑通 → 加 RAG → 需要时升级 Workflow/Agent |
| 可观测 | 上线前确保日志、标注、监控都配好 |
| 优雅降级 | 模型超时/出错时有兜底回复，别让前端白屏 |
10.2 常见踩坑
| # | 坑 | 现象 | 解决方案 |
|---|---|---|---|
| 1 | 知识库分段太大 | 检索到整页内容，回答不精准 | 缩小分段至 300~500 token |
| 2 | Prompt 中变量未定义 | 运行时报错或输出 {{xxx}} 原文 |
检查变量名拼写，确认已在"变量"面板注册 |
| 3 | Agent 无限循环 | 反复调用同一个工具 | 设置最大迭代次数 + 在 Prompt 中明确终止条件 |
| 4 | 流式输出前端乱码 | SSE 解析错误 | 确保前端正确处理 data: 前缀和 [DONE] 标记 |
| 5 | 多轮对话上下文丢失 | 第三轮开始 AI "忘记"前面说的 | 检查 conversation_id 是否正确传递 |
| 6 | 知识库更新后不生效 | 新文档搜不到 | 确认文档状态为"已完成"，等待索引构建完毕 |
| 7 | 模型输出被截断 | 回答到一半突然停止 | 增大 Max Tokens 设置 |
| 8 | Workflow 变量引用错误 | 下游节点拿到空值 | 使用 {{#node_id.var#}} 格式，检查节点 ID |
| 9 | 并发请求超时 | 高峰期响应慢 | 增加 Worker 数量、配置队列、使用更快的模型 |
| 10 | Docker 部署后向量库连不上 | 知识库功能异常 | 检查 docker-compose 中 weaviate/qdrant 的网络配置 |
10.3 性能优化清单
□ 模型选择：简单任务用小模型（成本降 80%）
□ 缓存策略：高频问题启用语义缓存
□ 知识库：控制总量 < 10万段，定期清理过期文档
□ Prompt：精简 System Prompt，减少无效 token
□ 并发：Worker 数量 = CPU 核心数 × 2
□ 向量库：数据量大时从 Weaviate 迁移到 Qdrant/Milvus
□ 监控：设置 token 消耗告警阈值
十一、学习路径建议
阶段一：快速上手（1~3 天）
- 部署/注册 Dify，接入一个模型供应商
- 创建一个 Chatbot 应用，写好 System Prompt
- 用调试面板反复测试，理解变量系统
- 里程碑：能做一个"像模像样"的对话助手
阶段二：知识增强（1~2 周）
- 创建知识库，上传业务文档
- 理解分段策略，用真实问题测试检索效果
- 将知识库关联到应用，配置混合检索 + Rerank
- 里程碑：AI 能准确回答"只有内部文档才有"的问题
阶段三：流程编排（2~4 周）
- 学习 Workflow 的所有节点类型
- 搭建一个包含 LLM + 代码 + HTTP + 分支的完整流程
- 理解变量传递和错误处理
- 里程碑：能实现一个多步骤自动化流水线
阶段四：生产化（持续）
- API 集成到真实业务系统
- 配置日志、监控、告警
- 建立 Prompt 优化闭环
- 成本控制和性能调优
- 里程碑：应用稳定服务真实用户，有数据驱动的迭代机制
十二、写在最后
回顾 Dify 的能力演进路径：
模型接入（有大脑）
→ Prompt 编排（会说话）
→ RAG 知识库（有知识）
→ Workflow（能流程化）
→ Agent（会自主决策）
→ API 发布（能服务用户）
→ 运营优化（能持续进化）
每一层都在解决上一层解决不了的问题： - 光有模型，只能"闲聊" - 加了 Prompt 编排，能"按规矩说话" - 加了 RAG，能"基于事实说话" - 加了 Workflow，能"按流程做事" - 加了 Agent，能"自主判断做事" - 加了 API，能"服务真实用户" - 加了运营，能"越用越好"
Dify 的价值不在于它有多"智能"，而在于它把这些能力标准化、可视化、可运营化了。你不需要写一行代码就能搭建一个 80 分的 AI 应用——而剩下 20 分的打磨，才是你真正需要花心思的地方。
License:
CC BY 4.0