54. Dify 低代码 AI 应用平台¶

# 最低配置要求：
# CPU >= 2 核
# 内存 >= 4 GB
# 磁盘 >= 20 GB（Docker 镜像 + 数据）
# 操作系统：Linux / macOS / Windows (WSL2)

# Ubuntu 安装 Docker（已安装可跳过）
sudo apt update                          # 更新包索引
sudo apt install -y docker.io            # 安装 Docker
sudo apt install -y docker-compose-plugin # 安装 Docker Compose 插件（v2）
sudo systemctl start docker              # 启动 Docker 服务
sudo systemctl enable docker             # 设置开机自启
sudo usermod -aG docker $USER            # 把当前用户加入 docker 组，免 sudo
# 注意：加入 docker 组后需要重新登录才生效

# 第一步：克隆 Dify 仓库
git clone https://github.com/langgenius/dify.git  # 从 GitHub 克隆代码
cd dify/docker                                     # 进入 Docker 配置目录

# 第二步：创建环境配置文件
cp .env.example .env                               # 复制示例配置为正式配置
# 你可以编辑 .env 文件修改以下常用配置：
#   SECRET_KEY=你的密钥          # 安全密钥，生产环境必须修改
#   INIT_PASSWORD=你的初始密码    # 管理员初始密码
#   DB_PASSWORD=数据库密码        # PostgreSQL 密码，默认 difyai123456
#   DIFY_PORT=5001               # API 服务端口，默认 5001

# 第三步：启动所有服务
docker compose up -d                               # 后台启动所有容器
# 这个命令会拉取并启动以下服务：
#   - api：Dify 后端 API 服务（Python/Flask）
#   - worker：后台任务队列（Celery，处理文档索引等）
#   - web：前端界面（Next.js）
#   - db_postgres：PostgreSQL 数据库
#   - redis：Redis 缓存和消息队列
#   - weaviate / qdrant：向量数据库（用于 RAG）
#   - nginx：反向代理，统一入口

# 第四步：查看服务状态
docker compose ps                                  # 查看所有容器运行状态
docker compose logs -f api                         # 实时查看 API 日志（调试用）

# 第五步：访问 Dify
# 浏览器打开 http://localhost/install
# 首次访问会进入初始化页面，设置管理员邮箱和密码

# 更新 Dify 到最新版本
cd dify/docker                    # 进入 Docker 目录
git pull origin main              # 拉取最新代码
docker compose down               # 停止当前服务
docker compose pull               # 拉取最新镜像
docker compose up -d              # 重新启动

# 查看日志
docker compose logs -f            # 查看所有服务日志
docker compose logs -f worker     # 只看 worker 日志（文档索引相关）

# 数据备份
docker compose exec db_postgres pg_dump -U postgres dify > backup.sql  # 备份数据库

# 完全卸载（谨慎操作！会删除所有数据）
# docker compose down -v          # 停止并删除所有容器和数据卷

操作：浏览器打开 http://localhost
     → 输入管理员邮箱和密码登录
     → 进入"工作台"页面
界面位置：左上角 "工作台" 标签

操作：点击右上角头像 → "设置" → "模型供应商"
     → 选择一个模型供应商（如 OpenAI）
     → 输入 API Key → 点击 "保存"
注意：如果用本地 Ollama，见第 8 节单独说明
界面位置：设置 → 模型供应商

操作：左侧导航栏 → "知识库" → 点击 "创建知识库"
     → 输入知识库名称（如 "T2D文献库"）
     → 点击 "创建"

操作：进入刚创建的知识库 → 点击 "添加文件"
     → 可以上传 PDF/DOCX/TXT/Markdown 等文件
     → 选择分块策略：
       - "自动"（推荐，Dify 自动决定怎么切）
       - "自定义"（可设置分块大小，如 500 tokens，重叠 50 tokens）
     → 选择嵌入模型（Embedding Model）
     → 点击 "保存并处理"
     → 等待索引完成（状态变为绿色 "可用"）
耗时：取决于文档大小，通常几秒到几分钟

操作：左侧导航栏 → "工作台" → 点击 "创建应用"
     → 选择 "聊天助手"（Chatbot）
     → 输入应用名称（如 "T2D文献问答助手"）
     → 点击 "创建"

操作：进入应用编排页面
     → 左侧面板 "上下文" 区域 → 点击 "添加" → 选择刚才的知识库
     → 在 "提示词" 区域编写 System Prompt，例如：

提示词示例：
-----------
你是一个2型糖尿病肠道菌群研究的专家助手。
请根据提供的文献内容回答用户的问题。
如果文献中没有相关信息，请明确告知用户。
回答要求：
1. 引用具体的文献段落
2. 使用中文回答
3. 用通俗易懂的语言解释专业术语
-----------

     → 右侧选择 LLM 模型（如 GPT-4 或 Claude）
     → 设置参数：Temperature 建议 0.3-0.5（更精确）

操作：右侧 "预览" 面板 → 输入测试问题
     → 例如："2型糖尿病患者肠道菌群有什么特点？"
     → 查看回答是否引用了知识库中的内容
     → 如果回答不理想，调整 Prompt 或分块策略

操作：点击右上角 "发布" 按钮
     → 发布后可获得：
       1. Web 应用链接（直接分享给别人使用）
       2. 嵌入代码（iframe 嵌入到你的网页）
       3. API 端点（集成到其他系统）

API 调用示例：

# 调用 Dify 对话 API
curl -X POST 'http://localhost/v1/chat-messages' \
  -H 'Authorization: Bearer your-api-key' \        # 替换为你的 API Key
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": {},
    "query": "2型糖尿病患者肠道中哪些菌群显著减少？",
    "response_mode": "blocking",
    "user": "test-user"
  }'

操作：工作台 → 创建应用 → 选择 "工作流"
     → 进入可视化画布编辑器

节点1: [开始] 
  ↓ 用户输入问题
节点2: [LLM - 问题分类器]
  → Prompt: "判断以下问题属于哪个类别：A.菌群组成 B.代谢通路 C.治疗方案 D.其他"
  ↓ 输出分类结果
节点3: [条件分支]
  → 如果分类=A → 走知识库检索分支
  → 如果分类=B → 走代谢数据库查询分支
  → 如果分类=D → 直接 LLM 回答
  ↓
节点4: [知识检索] → 从T2D文献库检索相关段落
  ↓
节点5: [LLM - 答案生成] → 基于检索结果生成回答
  ↓
节点6: [结束] → 返回最终答案给用户

# 确保 Ollama 已安装并运行
ollama serve                              # 启动 Ollama 服务（默认 11434 端口）
ollama pull llama3                        # 下载 Llama3 模型（约 4.7GB）
ollama pull nomic-embed-text              # 下载嵌入模型（用于 RAG 向量化）

# Ollama 默认只监听 127.0.0.1（本机）
# 如果 Dify 运行在 Docker 中，需要让 Ollama 监听所有地址

# 方法一：设置环境变量（Linux）
export OLLAMA_HOST=0.0.0.0:11434         # 让 Ollama 监听所有网络接口
ollama serve                              # 重启 Ollama

# 方法二：修改 systemd 配置（如果 Ollama 是系统服务）
sudo systemctl edit ollama                # 编辑服务配置
# 添加以下内容：
# [Service]
# Environment="OLLAMA_HOST=0.0.0.0:11434"
sudo systemctl restart ollama             # 重启服务

操作：设置 → 模型供应商 → 找到 "Ollama"
     → 点击添加
     → 填写配置：
       模型名称：llama3（和你 ollama pull 的名字一致）
       Base URL：http://host.docker.internal:11434
       （如果是 Linux Docker，用 http://172.17.0.1:11434）
     → 点击保存

嵌入模型同理：
     → 模型类型选 "Text Embedding"
     → 模型名称：nomic-embed-text
     → Base URL 同上

场景：上传 50 篇 T2D 肠道菌群相关论文 PDF，搭建文献问答助手
价值：快速定位文献中的关键信息，不用逐篇阅读
示例问题：
  - "Akkermansia muciniphila 在 T2D 中的作用？"
  - "有哪些研究使用了 16S rRNA 测序？"
  - "二甲双胍对肠道菌群的影响有哪些文献支持？"
实现：创建 RAG 知识库应用（见第 5 节教程）

场景：输入实验数据摘要，自动生成结构化分析报告
价值：节省写报告的时间，保持格式统一
工作流设计：
  用户输入实验参数 → LLM 生成报告大纲 → 知识库检索参考文献 
  → LLM 填充各章节 → 代码节点格式化 → 输出 Markdown 报告

场景：描述研究目的，AI 推荐实验方案、工具选择、参数设置
价值：帮助新手快速确定实验路线
示例对话：
  用户："我想比较 T2D 患者和健康人的肠道菌群差异，样本量 30 vs 30"
  AI："建议使用以下分析流程：
      1. 质控：fastp → KneadData（去宿主）
      2. 物种注释：MetaPhlAn4 或 Kraken2+Bracken
      3. 功能注释：HUMAnN3
      4. 差异分析：LEfSe + MaAsLin2
      5. 可视化：R ggplot2
      样本量建议：宏基因组推荐每组 ≥30，统计检验力足够..."

场景：把 QIIME2/MetaPhlAn/HUMAnN 等工具的官方文档导入知识库
价值：随时问 AI 工具的参数用法、报错解决方案

错误信息：Error starting userland proxy: listen tcp4 0.0.0.0:80: bind: address already in use
原因：80 端口被其他程序占用（如 Apache/Nginx）
解决：
  # 方法一：停掉占用 80 端口的程序
  sudo lsof -i :80                        # 查看谁占了 80 端口
  sudo systemctl stop nginx               # 停掉 nginx（举例）

  # 方法二：修改 Dify 端口
  # 编辑 docker-compose.yaml 中 nginx 服务的端口映射
  # 把 "80:80" 改为 "8080:80"
  # 然后访问 http://localhost:8080

错误信息：Embedding model not found / Provider not configured
原因：没有配置嵌入模型（Embedding Model），RAG 需要它把文本转向量
解决：
  设置 → 模型供应商 → 确保添加了支持 Embedding 的模型
  推荐：OpenAI text-embedding-3-small 或本地 nomic-embed-text

错误信息：Connection refused / Cannot connect to Ollama
原因：Dify Docker 容器无法访问宿主机的 Ollama 服务
解决：
  # 1. 确保 Ollama 监听 0.0.0.0 而不是 127.0.0.1
  export OLLAMA_HOST=0.0.0.0:11434

  # 2. 使用正确的地址
  #    Docker Desktop: http://host.docker.internal:11434
  #    Linux Docker:   http://172.17.0.1:11434

  # 3. 验证连通性
  docker exec -it dify-api-1 curl http://172.17.0.1:11434/api/tags

错误信息：{"code": "unauthorized", "message": "Invalid API key"}
原因：API Key 不正确或过期
解决：
  应用概览页 → 左侧 "API 访问" → 重新生成 API Key
  注意区分 "App API Key"（应用级别）和 "Dataset API Key"（知识库级别）

错误信息：File too large / Request entity too large
原因：默认文件大小限制（通常 15MB）
解决：
  # 修改 .env 文件中的上传限制
  UPLOAD_FILE_SIZE_LIMIT=50              # 单位 MB，改大一些
  UPLOAD_FILE_BATCH_LIMIT=10             # 批量上传数量限制

  # 重启服务
  docker compose restart api worker

错误信息：worker 容器状态显示 Restarting / OOMKilled
原因：服务器内存不足，索引大文档时内存溢出
解决：
  # 1. 确保服务器至少 4GB 内存（推荐 8GB+）
  free -h                                # 查看内存使用

  # 2. 减少 Celery Worker 数量
  # 编辑 .env：
  CELERY_WORKER_AMOUNT=2                 # 从默认 4 减少到 2

  # 3. 重启
  docker compose restart worker