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)** — 最常用: ```bash 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 工作流构件清单 ```yaml # 一个典型 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 节点 → 信号: 业务逻辑已超出可视化优势