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 类型 — 选哪个？

核心决策树:

有对话上下文需求？
├─ 是 ─→ 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)

"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]

决策: 一次性 = 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]
3. 跟踪 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]
• 分支嵌套深，看不清数据流
• 改一处怕碰别处

决策树:

节点数 < 20 且分支扁平
   → 留在 Dify, 优化命名 + 加 Note
节点数 20-40, 有可复用子流程
   → 拆 sub-workflow (打包成 Tool 给主流程调用)
节点数 > 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 已不合适" 的信号。