Dify 开源 LLM 应用开发平台：从安装到实战指南

2.4 服务架构

┌─────────────────────────────────────────────────────┐
│ Dify │
├─────────────┬─────────────┬─────────────┬───────────┤
│ Web UI      │ API Server  │ Worker      │ Database  │
│ (Next.js)   │ (Flask)     │ (Celery)    │ (PostgreSQL)│
├─────────────┼─────────────┼─────────────┼───────────┤
│ Redis       │ Weaviate    │ Sandbox     │ Nginx     │
│ (Cache)     │ (Vector DB) │ (Code Exec) │ (Proxy)   │
└─────────────┴─────────────┴─────────────┴───────────┘

2.5 常见问题

Q: 启动失败怎么办？

# 查看日志
docker compose logs -f
# 重启服务
docker compose down && docker compose up -d

Q: 如何重置管理员密码？

docker compose exec api flask reset-password [email protected]

3. API 配置与集成

3.1 获取 API Key

1. 登录 Dify 控制台
2. 进入「设置」→「API 访问」
3. 点击「创建密钥」
4. 复制并妥善保存 API Key

3.2 API 调用示例

Python SDK

from dify import DifyClient
client = DifyClient(api_key="your-api-key")
# 发送对话请求
response = client.chat_messages(inputs={"query": "你好"}, user="user-123")
print(response.json())

cURL 示例

curl -X POST https://your-dify-instance.com/v1/chat-messages \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{ "inputs": { "query": "你好" }, "user": "user-123" }'

3.3 API 限流与配额

4. 自定义工具开发

4.1 为什么需要自定义工具？

Dify 内置工具可能无法满足所有需求。当需要：

• 访问企业内部 API
• 调用第三方服务
• 执行特定业务逻辑

这时就需要开发自定义工具。

4.2 本地 API 公网穿透

由于 Dify 云端服务无法直接访问本地 API，需要使用穿透工具。

安装 localtunnel

npm install -g localtunnel

启动穿透服务

lt --port 8081

输出示例：

your url is: https://random-name-123.local.lt

安全加固

# 添加基本认证
lt --port 8081 --basic_auth username:password

4.3 工具配置步骤

1. 在 Dify 中添加工具
   • 进入「工具」→「自定义工具」
   • 填写 API URL（使用穿透后的地址）
   • 配置请求方法和参数
   • 设置鉴权方式（如需要）
2. 测试工具
   • 使用「测试」功能验证连接
   • 检查响应格式是否符合预期

创建 API 端点

from flask import Flask, request, jsonify
app = Flask(__name__)

@app.route('/api/custom-tool', methods=['POST'])
def custom_tool():
    data = request.json
    # 处理逻辑
    return jsonify({"result": "success"})

if __name__ == '__main__':
    app.run(port=8081)

4.4 鉴权配置

Dify 支持多种鉴权方式：

5. 工作流类型详解

5.1 Workflow（工作流）

特点：

• 面向任务处理
• 批量执行
• 无状态或弱状态
• 适合数据处理、内容生成等场景

典型流程：

输入 → 预处理 → LLM 处理 → 后处理 → 输出

适用场景：

• 文章摘要生成
• 数据清洗与转换
• 批量内容创作
• 报告自动生成

5.2 Chatflow（对话流）

特点：

• 面向对话交互
• 保持上下文状态
• 支持多轮对话
• 适合客服、助手等场景

典型流程：

用户输入 → 意图识别 → 知识库检索 → LLM 生成 → 回复用户 ↓ 多轮记忆

适用场景：

• 智能客服
• 个人助手
• 咨询问答
• 情感陪伴

5.3 Workflow vs Chatflow 对比

5.4 选择建议

• 选择 Workflow：当你需要处理一批数据、生成固定格式内容、或执行自动化任务时
• 选择 Chatflow：当你需要与用户进行自然对话、保持上下文、或提供个性化服务时

6. 知识库管理

6.1 知识库的作用

知识库是 Dify 的 RAG（检索增强生成）核心，通过向量化存储私有数据，让 AI 能够：

• 回答基于企业内部文档的问题
• 提供准确的产品信息
• 避免大模型的幻觉问题

6.2 创建知识库流程

步骤 1：选择数据源

支持的数据源类型：

步骤 2：文本分段与清洗

分段策略：

清洗选项：

• 去除 HTML 标签
• 去除特殊字符
• 标准化空白字符
• 去除页眉页脚

步骤 3：向量化处理

Dify 使用嵌入模型将文本转换为向量：

文本 → [嵌入模型] → 向量 → [向量数据库] → 可检索

支持的嵌入模型：

• OpenAI text-embedding-ada-002
• 本地部署的 BGE/M3E
• 其他兼容模型

步骤 4：完成索引

等待向量化完成后，知识库即可用于检索。

6.3 检索配置

6.4 最佳实践

1. 文档质量优先：确保源文档清晰、准确、无歧义
2. 合理分段：避免过长或过短的分段
3. 定期更新：及时同步最新的企业知识
4. 权限控制：敏感信息需要访问控制

7. 实战案例：跨境电商客服

7.1 场景描述

构建一个跨境电商智能客服系统，能够：

• 自动识别用户意图
• 处理常见问候和礼貌用语
• 转接人工服务
• 基于知识库回答专业问题

7.2 系统架构

用户输入
↓
[意图识别节点]
├─→ 打招呼 → 固定回复
├─→ 感谢语 → 礼貌回复
├─→ 告别语 → 告别回复
├─→ 人工服务 → 转接链接
└─→ 其他问题 → RAG 检索 → LLM 生成

7.3 意图识别代码实现

import random
import re

def main(query: str) -> dict:
    """
    基于固定短语匹配的跨境电商问答处理器
    Args: query: 用户输入的问题
    Returns: Dict: 包含回复类型、回复内容等信息的字典
    """
    # 去除首尾空格
    query = query.strip()
    # 打招呼相关的固定短语
    greeting_phrases = {
        # 基本问候
        "你好", "您好", "hi", "hello", "嗨", "哈喽", "哈罗", "早上好", "下午好", "晚上好", "上午好", "中午好", "晚安", "早", "午安", "good morning", "good afternoon", "good evening",
        # 询问身份
        "你是谁", "你是什么", "你叫什么", "你的名字", "介绍一下自己", "自我介绍", "你是什么东西", "你是哪个", "你是啥",
        # 询问状态
        "你好吗", "怎么样", "还好吗", "你还好吗", "最近怎么样", "你在吗", "在不在", "还在吗", "在线吗", "你在线吗",
        # 询问能力
        "你能干什么", "你会做什么", "你能做什么", "你的功能", "你有什么用", "你的作用", "你的职责", "你的用途", "你能帮我什么", "你可以做什么", "你会什么", "你懂什么", "能力介绍", "功能介绍", "你的能力", "你有什么功能",
        # 开始对话
        "开始", "开始咨询", "开始对话", "开始聊天", "我想咨询", "我有问题", "我想问问题", "我想了解", "咨询一下",
        # 测试类
        "测试", "试试", "试一试", "test", "testing", "试试看", "测试一下", "看看", "检查一下"
    }
    # 固定回复
    greeting_response = "你好，很高兴为您服务！我是您的跨境电商学习小助手，专业为您答疑解惑。"
    # 礼貌用语
    thank_phrases = {"谢谢", "感谢", "多谢", "谢了", "thanks", "thank you", "thx", "3q", "3x", "谢谢你", "感谢你", "多谢了", "非常感谢", "十分感谢", "万分感谢", "太感谢了"}
    goodbye_phrases = {"再见", "拜拜", "bye", "byebye", "goodbye", "88", "走了", "告辞", "先走了", "下次见", "回头见", "有空再聊", "改天聊", "see you", "拜", "溜了", "闪了", "slip away"}
    polite_responses = {
        "thank": ["不用客气，随时为您服务！", "很高兴能帮助到您！", "这是我应该做的，有问题随时找我哦！", "客气了，有什么问题尽管问！", "不客气，祝您跨境电商生意兴隆！"],
        "goodbye": ["再见！期待下次为您服务！", "祝您生活愉快，有问题随时来找我！", "再见！祝您跨境电商生意兴隆！", "拜拜！有问题随时回来咨询！", "再见！祝您学习愉快！"]
    }
    # 人工服务相关短语
    human_service_phrases = {
        # 直接要求人工服务
        "人工服务", "人工客服", "人工坐席", "人工咨询", "人工帮助", "人工支持", "人工答疑", "人工解答", "人工回复", "人工对话",
        # 转接相关
        "转人工", "找人工", "要人工", "转接人工", "转接客服", "切换人工", "接入人工", "联系人工", "答疑入口",
        # 真人服务
        "真人服务", "真人客服", "真人咨询", "真人对话", "真人帮助", "活人", "真人", "人类", "人工", "真的人",
        # 客服相关
        "客服", "在线客服", "联系客服", "找客服", "客服电话", "客服微信", "客服 qq", "官方客服",
        # 老师/导师
        "联系老师", "找老师", "咨询老师", "请教老师", "老师帮忙", "专业老师", "课程老师", "指导老师",
        # 专业服务
        "专人服务", "专人客服", "专业咨询", "专业服务", "专家咨询", "顾问咨询", "一对一服务", "专属服务",
        # 投诉和问题
        "投诉", "举报", "反馈问题", "意见反馈", "服务投诉", "质量问题", "服务问题", "系统问题",
        # 售后相关
        "退款", "退货", "售后", "售后服务", "退换货", "申请退款", "退费", "取消订单", "订单问题",
        # 不满意
        "不满意", "有问题", "出问题", "不行", "太差了", "服务差", "回答不对", "答非所问", "听不懂", "不准确"
    }
    human_service_response = "同学，点击 https://www.123.com 可进入人工答疑"

    def normalize_text(text: str) -> str:
        """标准化文本：去除标点符号，转换为小写"""
        cleaned = re.sub(r'[^\w\u4e00-\u9fff]', '', text.lower().strip())
        return cleaned

    def exact_match_check(query_text: str, phrase_set) -> bool:
        """精确匹配检查"""
        normalized_query = normalize_text(query_text)
        for phrase in phrase_set:
            normalized_phrase = normalize_text(phrase)
            if normalized_phrase == normalized_query:
                return True
        return False

    def contains_match_check(query_text: str, phrase_set) -> bool:
        """包含匹配检查（用于短查询中包含关键短语的情况）"""
        normalized_query = normalize_text(query_text)
        # 只有当查询很短时才使用包含匹配（避免误匹配）
        if len(normalized_query) <= 10:
            for phrase in phrase_set:
                normalized_phrase = normalize_text(phrase)
                if normalized_phrase in normalized_query or normalized_query in normalized_phrase:
                    return True
        return False

    # 处理输入
    query = query.strip()
    if not query:
        return {"type": "error", "response": "请输入您的问题。", "need_rag": False, "original_query": query}
    print(f"处理查询：'{query}'")
    print(f"标准化后：'{normalize_text(query)}'")

    # 1. 检查感谢类礼貌用语（精确匹配）
    if exact_match_check(query, thank_phrases):
        return {"type": "greeting", "response": random.choice(polite_responses["thank"]), "need_rag": False, "original_query": query}

    # 2. 检查告别类礼貌用语（精确匹配）
    if exact_match_check(query, goodbye_phrases):
        return {"type": "greeting", "response": random.choice(polite_responses["goodbye"]), "need_rag": False, "original_query": query}

    # 3. 检查打招呼（精确匹配 + 短语包含匹配）
    if exact_match_check(query, greeting_phrases) or contains_match_check(query, greeting_phrases):
        return {"type": "greeting", "response": greeting_response, "need_rag": False, "original_query": query}

    # 4. 检查人工服务请求（精确匹配 + 短语包含匹配）
    if exact_match_check(query, human_service_phrases) or contains_match_check(query, human_service_phrases):
        return {"type": "human_service", "response": human_service_response, "need_rag": False, "original_query": query}

    # 5. 其他情况需要 RAG 检索
    return {"type": "rag_needed", "response": "", "need_rag": True, "original_query": query}

7.4 工作流配置

1. 开始节点：接收用户输入
2. 代码节点：运行意图识别代码
3. 条件分支：
   • type == "greeting" → 直接回复
   • type == "human_service" → 返回人工链接
   • type == "rag_needed" → 知识库检索 → LLM 生成
4. 结束节点：输出最终回复

7.5 优化建议

1. 添加意图识别模型：使用分类模型替代规则匹配
2. 多语言支持：扩展短语库支持更多语言
3. 情感分析：识别用户情绪，调整回复策略
4. 会话记忆：记录用户历史问题，提供个性化服务

8. 实战案例：Text2SQL 数据库查询

8.1 场景描述

构建一个自然语言查询学生成绩的系统，用户可以用中文提问，系统自动生成 SQL 并执行。

8.2 数据库设计

CREATE TABLE student_grades (
    id INT PRIMARY KEY AUTO_INCREMENT,
    student_id VARCHAR(20) NOT NULL,
    student_name VARCHAR(50) NOT NULL,
    class_name VARCHAR(20),
    subject VARCHAR(30),
    score DECIMAL(5,2),
    exam_date DATE,
    semester VARCHAR(20),
    grade INT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

8.3 LLM 提示词设计

## 角色
你是一个专业的 SQL 查询生成器，负责根据用户查询创建标准的 MySQL 数据库 SQL 语句。

## 任务
根据以下问题，生成一个格式清晰、结构明确的 JSON 数组，其中每个元素是一条合法且性能优化的 MySQL 查询语句。

### 表信息
表名：student_grades（学生成绩信息表）

### 字段说明
- id: 主键
- student_id: 学号
- student_name: 学生姓名
- class_name: 班级
- subject: 科目
- score: 分数
- exam_date: 考试日期
- semester: 学期
- grade: 年级
- created_at: 记录创建时间
- updated_at: 记录更新时间

### 输出要求
1. 根据用户的问题，生成最多 10 条直接关联问题的 SQL 查询语句。
2. 每条 SQL 应从不同分析角度（如按科目、班级、学期、年级等维度）切入，确保覆盖多维统计需求。
3. 所有 SQL 必须语法正确、可执行，并注重性能优化（如避免 SELECT *，合理使用索引字段等）。
4. 若问题涉及多维统计（例如"各班各科平均分"），请为每个统计维度单独生成子查询。
5. 对于全量数据查询，必须按 semester（学期）进行聚合或排序。
6. 最终输出必须是纯 JSON 数组格式，以 ```json 开头，以 ``` 结尾，不包含任何额外解释或文本，其中每个元素必须是对象，且仅包含一个字段：`"sql"`（字符串类型），格式示例：

```json
[
  { "sql": "SELECT ...;" },
  { "sql": "SELECT ...;" }
]

请严格按照上述格式和要求生成响应。

#### 8.4 示例查询

**用户输入**：「查询三年级一班的数学平均分」

**生成的 SQL**：

```json
[
  {"sql": "SELECT AVG(score) as avg_score FROM student_grades WHERE grade = 3 AND class_name = '一班' AND subject = '数学';"},
  {"sql": "SELECT class_name, subject, AVG(score) as avg_score FROM student_grades WHERE grade = 3 AND subject = '数学' GROUP BY class_name, subject;"},
  {"sql": "SELECT semester, AVG(score) as avg_score FROM student_grades WHERE grade = 3 AND class_name = '一班' AND subject = '数学' GROUP BY semester ORDER BY semester;"}
]

8.5 安全考虑

1. 只读权限：数据库用户仅授予 SELECT 权限
2. 查询限制：限制返回行数（如 LIMIT 1000）
3. 超时控制：设置查询超时时间（如 30 秒）
4. 审计日志：记录所有生成的 SQL 用于审计

8.6 工作流配置

1. 开始节点：接收用户自然语言问题
2. LLM 节点：使用提示词生成 SQL
3. 代码节点：解析 JSON，提取 SQL 语句
4. 数据库工具：执行 SQL 查询
5. LLM 节点：将查询结果转换为自然语言回复
6. 结束节点：输出最终回复

9. 网页集成方案

9.1 嵌入式聊天窗口

Dify 提供嵌入式脚本，可直接集成到网页中：

<!-- 在 </body> 前添加 -->
<script>
  window.difyChatbotConfig = {
    token: 'your-app-token',
    baseUrl: 'https://your-dify-instance.com'
  }
</script>
<script src="https://your-dify-instance.com/embed.min.js" id="your-app-token" defer></script>

9.2 自定义样式

.dify-chatbot-container {
  position: fixed;
  bottom: 20px;
  right: 20px;
  z-index: 9999;
}
.dify-chatbot-bubble {
  max-width: 400px;
  border-radius: 12px;
  box-shadow: 0 4px 12px rgba(0,0,0,0.15);
}

9.3 自定义事件监听

document.addEventListener('dify-chatbot-ready', function() {
  console.log('聊天机器人已就绪');
});
document.addEventListener('dify-chatbot-message', function(e) {
  console.log('收到消息：', e.detail);
});

9.4 React/Vue 组件集成

// React 示例
import { useEffect } from 'react';

function DifyChatbot() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://your-dify-instance.com/embed.min.js';
    script.id = 'your-app-token';
    script.defer = true;
    document.body.appendChild(script);
    return () => {
      document.body.removeChild(script);
    };
  }, []);
  return <div />;
}

10. 总结与建议

10.1 核心优势

10.2 适用场景推荐

强烈推荐：

• 企业知识库问答
• 智能客服系统
• 内部工具自动化

可以考虑：

• 个人 AI 助手
• 内容生成工具
• 数据分析助手

需要评估：

• 高并发场景（需企业版）
• 复杂业务逻辑（可能需要自定义开发）
• 严格合规要求（需私有化部署）

10.3 学习路线

1. 入门：完成本地部署，熟悉界面
2. 基础：创建第一个工作流和知识库
3. 进阶：开发自定义工具，集成外部 API
4. 高级：优化性能，生产环境部署

10.4 资源链接

• 官方网站：https://dify.ai
• GitHub 仓库：https://github.com/langgenius/dify
• 文档中心：https://docs.dify.ai