Agentsop Dify

Dify SOP — LLM Application Platform, Visual-First with Code Escape Hatches

> 框架定位: "An open-source platform for building agentic workflows" — visual workflow + RAG + agent + monitoring + deploy in one box, self-hostable. [docs.dify.ai/en/introduction], [github.com/langgenius/dify]

> "Dify is the only tool that gives you data ingestion, RAG, an API, and a polished, shareable web UI in one click." [learnwithparam.com/blog/batteries-included-rag-platforms-dify-ragflow-onyx]

---

1. 何时激活 (When to Activate)

1.1 直接信号 (Direct triggers)

• 用户说 "我需要个 LLM 应用 / 客服 bot / 知识库问答 / 文档处理流"，且希望几天内交付
• 用户说 "我们在用 Dify / 自己部署了 Dify / 想自己 host LLM 平台"
• 团队有非工程师参与编排逻辑（PM / 运营 / 业务方画 chatflow）
• 需要一站式：模型管理 + RAG + 工具调用 + 用户访问 + API + 监控 + 评估
• 需要多租户 / workspace 权限（典型 SaaS / 企业内多团队场景） [blog.elest.io/dify-vs-langflow-vs-flowise]

1.2 反向信号 (Skip Dify when)

• 高吞吐: 单 pod ~10 QPS 上限，每个 workflow 节点单独打 DB [memo.d.foundation/breakdown/dify]
• 实时低延迟: workflow 引擎开销 + 同步 DB 调用，sub-second 场景不适用
• 需要 pause-and-wait-for-user: 审批流 / 用户多步交互 → Dify workflow 不支持，issue #21455 已关 "not planned"
• 纯工程团队 + 已有 LangChain/LangGraph 投入: Dify 的可视化层成为负担而非杠杆
• 训练 / 微调 workflow: Dify 是 inference + orchestration，不碰训练
• 极致 RAG: 需要 KG-RAG、deep parsing、混合检索调优 → RAGFlow 更专 [sider.ai/blog/ai-tools/dify-vs-ragflow]
• AI 代码已经能写: 业内已有声音 "既然在 Dify 里也要写 Python，何不直接 Python？" [zhuanlan.zhihu.com/p/1947389040702781389]

1.3 心智门槛 (Mental check)

> Dify 的核心价值是 "把 LLM 应用工程的脚手架打平"——auth、API、UI、向量库、模型 provider、日志、版本——而不是替代 LLM 编排框架本身的表达力。

判断公式:

• 如果你的瓶颈是 "组装周边设施" → 用 Dify
• 如果你的瓶颈是 "逻辑表达力 / 状态管理 / 极致性能" → 用 LangGraph / 直接代码

---

2. 核心心智模型 (Mental Model)

2.1 五层架构 (The 5-layer stack)

[Studio]        ← Visual canvas (workflow / chatflow / agent / chatbot / text-gen)
   ↓ 编排
[Apps]          ← 5 种 app 类型，全部跑在统一 Graph Engine 上
   ↓ 依赖
[Knowledge]     ← RAG pipeline (ingest → chunk → embed → index → retrieve → rerank)
   ↓ + 调用
[Tools/Plugins] ← Marketplace: Models / Tools / Agent Strategies / Extensions / Bundles
   ↓ 观察
[Monitoring]    ← 内建 logs + 外接 LangSmith / Langfuse / Arize Phoenix / Opik

参考: [docs.dify.ai/en/introduction], [dify.ai/blog/dify-plugin-system-design-and-implementation]

2.2 五种 App 类型 — 选哪个？

| App Type | 触发模型 | 记忆 | 编排方式 | 典型场景 | |---|---|---|---|---| | Chatbot (legacy) | 多轮对话 | 内置 | 单 prompt + tools | 简单客服、FAQ bot | | Agent (legacy) | 多轮对话 | 内置 | ReAct / FC 自主决策 | 自治工具使用、多步推理 | | Text Generator (legacy) | 单次调用 | 无 | 单 prompt | 文案生成、翻译 | | Workflow | 单次调用 / 批处理 | 无 | 可视化 DAG | API 后端、批量任务、ETL | | Chatflow | 每轮对话触发整图 | 有 (conversation vars) | 可视化 DAG + 对话状态 | 复杂对话流、guided dialogue |

核心决策树:

有对话上下文需求？
├─ 是 ─→ Chatflow (复杂逻辑) 或 Chatbot/Agent (简单)
└─ 否 ─→ Workflow (复杂逻辑) 或 Text Generator (单 prompt)

需要 LLM 自主选择工具 / 多步推理？
├─ 是 ─→ Agent app  或  Workflow + Agent Node (推荐, 1.9+)
└─ 否 ─→ Workflow / Chatflow + 显式节点编排

参考: [docs.dify.ai/en/use-dify/getting-started/key-concepts], [hellodify.com/en/docs/workflow/workflow-chatflow-difference], [zediot.com/blog/dify-difference-between-agent-and-workflow]

> "Workflow behaves more like a script… each Workflow run is a completely fresh start. Chatflow… is a robot that can interact with users in a loop." [hellodify.com/en/docs/workflow/workflow-chatflow-difference]

2.3 Graph Engine = "graphon"

• 自研 DAG 执行引擎，所有 app 类型底层一套
• v1.9+ 重写为 queue-based scheduling: 任务统一入队、调度器管依赖与并行 [github.com/langgenius/dify/discussions/26138]
• 节点有标准签名：输入变量 → 处理 → 输出变量
• 支持：partial run、step debugging、stream-stitch across nodes、pause/terminate commands

2.4 节点目录 (Node taxonomy)

| 类别 | 节点 | 用途 | |---|---|---| | 基础 | Start, End, Answer | 入口 / 出口 | | LLM | LLM, Question Classifier, Parameter Extractor | 调模型 | | RAG | Knowledge Retrieval | 查知识库 | | 逻辑 | IF/ELSE, Iteration, Loop, Variable Assigner, Variable Aggregator | 控制流 | | 代码 | Code (Python/Node.js), Template (Jinja2) | 自定义逻辑 | | 外部 | HTTP Request, Tool, Agent Node | 调外部 / 子 agent | | 数据 | List Operator, Document Extractor | 处理结构化数据 |

> "Dify's canvas includes LLM calls, knowledge retrieval, conditionals, HTTP requests, code nodes (Python/Node), Jinja transforms, iterators/loops, and aggregators." [legacy-docs.dify.ai/guides/workflow/node]

2.5 Plugin 系统 (五元类型)

v1.0+ 引入插件系统，从 monolith → marketplace。 [dify.ai/blog/introducing-dify-plugins]

| 类型 | 用途 | 何时选它 | |---|---|---| | Models | 接入新模型 provider | 内置不支持的模型 | | Tools | 给 agent / workflow 加能力 | 需要复用的领域工具 (Slack, Notion, 自家 API) | | Agent Strategies | 自定义 reasoning loop | 想用 ToT / GoT / 自研推理 | | Extensions | 轻量 HTTP webhook | 简单 API 接入，不需打包 | | Bundles | 多插件打包 | 整套行业解决方案 |

决策: 一次性 = HTTP Request 节点；可复用 = Tool plugin；逻辑深 = Agent Strategy plugin。

2.6 Knowledge Base (RAG) 心智

RAG 流程: Ingest → Extract → Clean → Chunk → Embed → Index → Retrieve → Rerank → Augment [docs.dify.ai/en/guides/knowledge-base/readme]

三种构建方式:

1. Quick create — 上传即用，自动处理
2. Knowledge pipelines (v1.9+) — 可视化定义 ingest 流程，类似 workflow but for data
3. External integration — 接外部知识库 API (Pinecone / Weaviate / 自有 RAG 服务)

向量库支持: 13+ (Qdrant 默认推荐, Weaviate, Milvus, Pinecone, PGVector, TiDB, Chroma…) [deepwiki.com/langgenius/dify-docs/8.3-vector-database-configuration]

检索策略:

• N-to-1 Recall (需 reasoning model 选库)
• Multi-way Recall (并行检索 + Rerank model 合并)

---

3. SOP 工作流 (Standard Operating Procedure)

Phase 0: 选定 App 类型 (5 分钟决策)

1. 问：对话还是一次性任务？ → Chatflow 系 vs Workflow 系
2. 问：逻辑能写死，还是要 LLM 自主决策？ → 显式 workflow vs Agent (app or node)
3. 问：会不会跟 PM/业务方共编？ → 是 → 优先 visual app；否 → 考虑直接代码
4. 问：是 MVP 还是会长期演进？ → 长期 → 强烈建议 Workflow/Chatflow（legacy 三件套不推荐）

> 官方建议: "Workflow/Chatflow are recommended for most use cases. Use the legacy basic types (Chatbot/Agent/Text Generator) only if preferring simplified interfaces over advanced features." [docs.dify.ai/en/use-dify/getting-started/key-concepts]

Phase 1: 部署 (Deploy) — 30 分钟

Cloud (推荐起步):

• Sandbox (Free): 200 credits / 10 apps / 5MB storage
• Professional ($59/mo): 5k credits / 50 apps / 5GB
• Team ($159/mo): 10k credits / 20GB / SSO
• Enterprise: 自定义 [architjn.com/blog/dify-cloud-pricing-plans-free-tier-when-to-self-host]

Self-host (Docker Compose) — 最常用:

git clone https://github.com/langgenius/dify
cd dify/docker
cp .env.example .env
docker compose up -d

• 最低: 2 vCPU / 4GB RAM
• 生产建议: 2 vCPU / 4GB / 40GB SSD + 反向代理 (Caddy/Nginx) + HTTPS
• 切勿直接暴露内部端口到公网 [docs.dify.ai/en/self-host/quick-start/docker-compose]

关键环境变量:

• VECTOR_STORE — 选 Qdrant / Weaviate / Milvus / Pinecone…
• PLUGIN_DAEMON_TIMEOUT=300 — 插件超时
• WORKFLOW_MAX_EXECUTION_TIME / HTTP_REQUEST_MAX_READ_TIMEOUT — 长链路必调

Phase 2: Prompt + 单节点 (Prompt Studio) — 1 小时

1. 先在 Prompt IDE 调通单个 LLM 调用——别上来就堆 workflow
2. 在 Prompt IDE 多模型对比 (GPT-4 / Claude / 自有模型)
3. 把变量 {{var}} 抽出来——后续会成为 workflow 输入

Phase 3: 接知识库 (Knowledge) — 半天

1. 上传文档 → 选 High-Quality (embed + vector) 或 Economical (BM25, 省钱)
2. 调 chunk size / overlap (默认 500/50 起手，长文档调到 1000+)
3. 跑 Retrieval Testing——用真实问题模拟，看召回的 chunks
4. 调 retrieval mode: Semantic / Full-text / Hybrid (推荐)
5. 接 Rerank 模型（jina-rerank, cohere-rerank, BGE-rerank）
6. 文档量大 / 多类型时 → 用 Knowledge Pipeline 自定义 ingest

> "Dify provides a comprehensive RAG pipeline handling the full lifecycle from raw file upload through extraction, cleaning, segmentation, embedding, indexing, retrieval, and reranking." [pyshine.com/2026/04/20/Dify-Open-Source-LLM-App-Development-Platform]

Phase 4: 接工具 (Tools) — 半天

• 内置 50+ 工具: Google Search, DALL·E, WolframAlpha, Stable Diffusion… [github.com/langgenius/dify]
• 自家 API → 优先用 HTTP Request 节点 (零代码)
• 复用 / 团队共享 → 写成 Tool plugin
• 复杂业务逻辑 → Code 节点 (Python/Node.js, sandboxed)

Phase 5: 编 workflow (Build) — 1-3 天

构建顺序 (反直觉但重要):

1. 先线性跑通——LLM → Knowledge → LLM → End
2. 加 IF/ELSE 分支——只在真正需要分流时
3. 加 Iteration——批量处理列表
4. 加 Agent Node (1.9+)——当确实需要 LLM 自主选工具时
5. 再加 Code 节点——填补无法表达的逻辑

反模式: 一上来就画 30+ 节点的复杂图。先线性跑通，再分支。

Phase 6: 测试 + 发布 (Test & Publish) — 1 天

1. Step debugging——每个节点单步执行
2. Test run——从任意节点开始跑 (1.9+ 支持)
3. Annotation Reply (chat apps)——把好回答标注下来，下次直接返回 (省 token + 提质) [dify.ai/blog/boosting-chatbot-quality-cutting-costs-with-dify-annotation-replies]
4. Version control——发布版本带 release notes，可回滚 [legacy-docs.dify.ai/guides/management/version-control]
5. 导出 DSL (YAML)——纳入 git 版本管理 [github.com/langgenius/dify-docs/blob/main/en/guides/workflow/export_import.md]
6. 发布为 Web App / API endpoint / MCP Server

Phase 7: 接观测 (Monitor) — 半天

1. 内建 logs：每次调用的 input/output/token/latency
2. 外接 LLMOps:

• LangSmith — LangChain 全家桶用户 [docs.dify.ai/guides/monitoring/integrate-external-ops-tools]
• Langfuse — 开源自托管首选 [langfuse.com/integrations/no-code/dify]
• Arize Phoenix — 评测优先 [dify.ai/blog/dify-arize-how-to-evaluate-monitor-and-improve-agents]
• Opik — 性能最快 [comet.com Opik]

1. 跟踪 7 类 trace: Workflows / Messages / Moderation / Suggested Questions / Dataset Retrieval / Tools / Generated Names

Phase 8: 迭代 (Iterate) — 持续

1. 看监控里的 bad cases → 标注 → annotation reply 或返工 prompt
2. 收集 traces → 在 Phoenix/Langfuse 建 eval dataset → 对比 prompt 变体
3. 复杂 workflow 出现性能问题 → 拆 sub-workflow / 改 queue model / 接外部服务

---

4. 操作模型 (Operation Model)

4.1 工作流构件清单

# 一个典型 Dify workflow 的 building blocks
inputs:           # Start 节点变量 (text / number / file / select)
nodes:
  - llm:                    # 调模型
      model: gpt-4-turbo
      prompt: "..."
      memory: false         # workflow 永远是 false
  - knowledge_retrieval:    # 查知识库
      datasets: [kb_id_1, kb_id_2]
      mode: hybrid
      rerank: bge-rerank
  - if_else:                # 分支
      conditions: [...]
  - iteration:              # 批处理列表
      iterator: {{node.output}}
      sub_workflow: [...]
  - code:                   # Python/Node
      code: "def main(x): return ..."
  - http_request:           # 调外部
      method: POST
      url: "..."
  - agent:                  # 自主决策子节点 (1.9+)
      strategy: react / function_calling / custom
      tools: [...]
      max_iterations: 5
outputs:          # End / Answer 节点

4.2 变量系统

• User Input — Start 节点定义
• Node Output — {{node_id.var}} 跨节点引用
• Environment Variables — secrets, API keys
• Conversation Variables (Chatflow only) — 跨轮持久化 [docs.dify.ai/en/use-dify/getting-started/key-concepts]
• System Variables — sys.user_id, sys.conversation_id 等

4.3 发布形态

1. Web App — 一键得 hosted chat UI
2. API — REST endpoint + API key
3. Embed — iframe / web SDK
4. MCP Server (新) — 暴露给外部 agent 调用
5. Tool — 作为另一个 Dify app 的工具

4.4 多租户 / Workspace

• 同一 Dify 实例支持多 workspace
• 每 workspace 独立的 models / API keys / members / apps
• RBAC: Owner / Admin / Editor / Normal [blog.elest.io/dify-vs-langflow-vs-flowise]
• ⚠️ 已知限制: model provider key 是 workspace 级，无法 per-app 区分 [github.com/langgenius/dify/issues/32167]

4.5 DSL (YAML) 工作流

• 导出: Studio → 应用菜单 → Export DSL
• 导入: 跨实例迁移、git 版本管理、CI/CD
• 限制: Knowledge base 数据本身不打包到 DSL (v1.8.1 时仍未支持) [github.com/langgenius/dify/issues/25999]

---

5. 困境决策案例 (Dilemma Cases)

Case 1: "Workflow 变得不可维护——拆子工作流还是改写代码？"

症状:

• Workflow 画到 30+ 节点，canvas 拖动卡顿 (issue #28245) [github.com/langgenius/dify/issues/28245]
• 分支嵌套深，看不清数据流
• 改一处怕碰别处

决策树:

节点数  40 或 大量 Code 节点
   → 信号: 业务逻辑已超出可视化优势
   → 把核心逻辑改写为 Python 服务, Dify 只做编排前端 + RAG

实操:

• Workflow app 可以被打包为另一个 workflow/chatflow 的 Tool — 这是 Dify 提供的模块化路径 [hellodify.com/en/docs/workflow/workflow-chatflow-difference]
• 复杂业务逻辑 → 用 HTTP Request 节点调外部微服务，Dify 退化为 orchestrator

反模式: 在 Code 节点里写 200 行 Python——这是 "Dify 已不合适" 的信号。

Case 2: "可视化已到天花板——继续 Dify 还是切 LangGraph / 直接代码？"

症状:

• 需要 pause-and-wait-for-user（审批、用户多步选择）— Dify 不支持，issue #21455 closed "not planned"
• 需要复杂状态机 / 循环 / 中断恢复 / time-travel
• 需要 sub-second 延迟
• 节点级 DB 查询拖累吞吐 [memo.d.foundation/breakdown/dify]

判断公式: | 信号 | 留 Dify | 切代码 | |---|---|---| | 团队非 100% 工程师 | ✅ | ❌ | | 需要快速 UI / API / 认证 | ✅ | ❌ (得自己搭) | | pause-and-wait | ❌ | ✅ (LangGraph 原生) | | QPS > 10 / pod | ❌ | ✅ | | 复杂状态 + 回滚 | ❌ | ✅ | | RAG + 简单编排 | ✅ | — |

混合方案 (推荐): Dify 做前端 / RAG / 用户管理 / 监控；核心 agent 逻辑跑在 LangGraph 服务后端，Dify HTTP Request 节点调用。

> "Dify wins when you're building an LLM-powered SaaS, an internal product with multiple teams… Langflow is for teams that need power now and will need more later." [blog.elest.io/dify-vs-langflow-vs-flowise]

Case 3: "Self-host 还是 Cloud——什么时候值得自己运维？"

症状:

• 团队在评估 Dify Cloud Pro ($59) vs 自部署 Docker

决策矩阵 [architjn.com/blog/dify-cloud-pricing-plans-free-tier-when-to-self-host]:

| 条件 | 选 Cloud | 选 Self-host | |---|---|---| | 团队 ≤ 3 人, 用量小 | ✅ ($59-159/mo 比养 DevOps 便宜) | ❌ | | 合规 / 数据驻留 (金融、医疗) | ❌ | ✅ | | 用量大 (millions of API calls) | ❌ (订阅成本超过 infra) | ✅ | | Air-gapped / 内网部署 | ❌ | ✅ | | 自定义 vector store / 模型 | 部分支持 | ✅ 完全控制 | | 不想管 backup / scaling | ✅ | ❌ |

实操要点:

• 自部署不是"docker compose up"完事——需要反向代理 + HTTPS + 备份 + 监控 + 升级策略
• 生产 self-host 用 Kubernetes + Helm + 外部 PostgreSQL/Redis/Vector DB（不要用容器内置的）
• ⚠️ Community / Premium / Enterprise 用同一 Docker image，差异在环境变量 [github.com/langgenius/dify/discussions/32254]

Case 4: "Dify 知识库 vs 独立向量库 (Pinecone / Weaviate 自管)——边界在哪？"

症状:

• 团队有现存 Pinecone 索引 / 多个产品共享 RAG / 想精细控制 chunking 和 embedding pipeline

决策: | 场景 | 用 Dify 内建 Knowledge | 用 External Knowledge | |---|---|---| | 单个 app 单个数据集 | ✅ 一键搞定 | ❌ over-kill | | 多 app 共享同一份 KB | ✅ Dify KB 可被多 app 引用 | — | | 极致 chunking / 实验性 retrieval | ❌ Dify 抽象有限 | ✅ | | 已有自建 RAG 服务 | ❌ | ✅ Dify HTTP/External KB 接入 | | 数据量 > 100M chunks | ❌ Dify 有 memory leak 风险 [memo.d.foundation/breakdown/dify] | ✅ | | 需要 KG-RAG / hybrid + late interaction | ❌ | ✅ 或换 RAGFlow |

混合: Dify Knowledge 管常规文档；External Knowledge API 接你的自有 RAG 服务做长尾。

Case 5: "用 Agent app vs Workflow + Agent Node vs 显式 Workflow——分歧何在？"

症状: 同一个需求，三种实现方式纠结。

决策原则 [zediot.com/blog/dify-difference-between-agent-and-workflow], [dify.ai/blog/dify-agent-node-introduction-when-workflows-learn-autonomous-reasoning]:

任务路径可预测、调试性优先
  → 显式 Workflow (写死分支)

任务路径不可预测、需 LLM 选工具
  → Workflow + Agent Node (1.9+)
     [推荐!! 比纯 Agent app 更可控, 既享受自主性又有 workflow 外壳]

纯对话 + 工具调用、不需要复杂编排
  → Agent app (legacy)

混合: 主流程显式, 局部不确定路径
  → Workflow 主图 + 不确定段塞 Agent Node

> "The best systems combine both — workflows as orchestrators that delegate reasoning tasks to agents. This hybrid model provides both predictability and intelligence." [zediot.com/blog/dify-difference-between-agent-and-workflow]

反模式:

• Agent app 包打天下——失去 workflow 的可观察性
• 用 Workflow 强行表达完全不可预测的任务——逻辑膨胀

---

6. 反模式与边界 (Anti-patterns & Boundaries)

6.1 常见反模式

| 反模式 | 症状 | 修法 | |---|---|---| | 30+ 节点单图 | 卡顿 + 难调 [issue #28245] | 拆 sub-workflow / Tool | | Code 节点写业务核心 | Code 节点 200+ 行 Python | 抽到外部微服务, Dify 用 HTTP 调用 | | 不上 Knowledge Pipeline | 文档质量飘忽 | 用 1.9+ 的 pipeline 自定义 ingest | | 没接 LLMOps | 上线后看不见 bad case | 接 Langfuse / Phoenix | | DSL 不入 git | 改飞了无法回滚 | 导出 DSL → git, 用 dify-dsl-exporter 批量化 [github.com/linhai0872/dify-dsl-exporter] | | legacy Chatbot/Agent app 长期演进 | 无法表达分支 / 后期被迫迁移 | 直接上 Chatflow / Workflow | | workspace 共用 API key | 不同 app 计费混乱 | 已知限制, 暂用多 workspace 规避 | | 不做 retrieval testing | RAG 召回质量差还不自知 | 上传后立刻用真实 query 在 Retrieval Testing 里跑 | | stream 长任务 > 120s 不调超时 | Agent node 突然断开 [issue #27053] | 调 WORKFLOW_MAX_EXECUTION_TIME + 反代超时 |

6.2 性能边界 (硬约束)

• ~10 QPS / pod (1 CPU 2GB)——超过需水平扩 worker + queue depth 调优 [memo.d.foundation/breakdown/dify]
• 每节点单独 DB query——长 workflow 累积延迟
• 120s streaming——agent node 默认 timeout (可调但反代也要调) [github.com/langgenius/dify/discussions/27053]
• plugin daemon 300s——PLUGIN_DAEMON_TIMEOUT
• Cloud 配额硬上限——超额无法 reindex, 只能删数据 [discussions/32013]

6.3 不要用 Dify

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: agentsope
• Source: agentsope/SkillAlchemy
• License: MIT

Install and usage instructions live in the source repository linked above.