MKC — Dify Japan 内容体系

全体構成

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#0033FF', 'primaryTextColor': '#FFFFFF', 'primaryBorderColor': '#0026CC', 'lineColor': '#0033FF', 'secondaryColor': '#F8F9FB', 'tertiaryColor': '#E5EAFF', 'fontFamily': '-apple-system, BlinkMacSystemFont, sans-serif'}}}%%
flowchart TD
    YOU(["你来写"])

    YOU --> L1
    YOU --> L2
    YOU --> L3
    YOU --> L4

    subgraph L1["第1层 · 公开渠道 Public"]
        A1["技术文章 / 博客"] --> A2["X · LinkedIn"]
        A2 --> A3["品牌曝光 · 技术影响力"]
    end

    subgraph L2["第2层 · Dify协会 Members Only"]
        B1["深度 Use Case / 踩坑记录"] --> B2["协会专属发布"]
        B2 --> B3["社区粘性 · 生态培育"]
    end

    subgraph L3["第3层 · 合作伙伴培训 Partners"]
        C1["部署文档 Docker / Helm"] --> C3["合作伙伴独立交付"]
        C2["App搭建课程 · 业务场景"] --> C3
    end

    subgraph L4["第4层 · 原厂技术支持 Premium"]
        D1["架构建议 · 咨询文档"] --> D2["深度技术咨询 1on1"]
        D2 --> D3["高客单价 · 品牌护城河"]
    end

    style L1 fill:#E5EAFF,stroke:#0033FF,color:#000000
    style L2 fill:#E5EAFF,stroke:#0033FF,color:#000000
    style L3 fill:#E5EAFF,stroke:#0033FF,color:#000000
    style L4 fill:#E5EAFF,stroke:#0033FF,color:#000000

4层 × 具体写什么

第1层 · 公开渠道 Public

1-1 Dify 产品认知类

Dify 是什么：一个让企业不依赖单一 AI 厂商、自主掌控 AI 应用的平台
Dify Cloud vs Dify Enterprise 的区别：SaaS 试用 vs on-premise 私有部署
Dify 支持哪些 LLM：OpenAI、Claude、Gemini、本地模型（Ollama）等接入方式
Dify 的核心概念解释：Chatbot / Agent / Workflow / Knowledge Base 各是什么、适合什么场景
Dify 工作流（Workflow）和 n8n / Zapier 的本质区别

1-2 场景案例类

用 Dify 搭一个企业内部的 FAQ 机器人：从知识库上传到对话测试的完整流程
用 Dify + 知识库做合同审查助手：如何处理 PDF 文档、设定检索参数
用 Dify Workflow 自动化日报生成：多节点串联、变量传递、输出格式控制
用 Dify Agent 调用外部工具：以天气查询为例，演示工具定义到调用的全链路
日本企业常见 AI 需求场景盘点：客服、文档处理、社内知识检索、报告生成

1-3 技术观察类

MCP（Model Context Protocol）是什么：为什么它让 AI 工具调用变得标准化
RAG 的核心问题：为什么知识库检索结果不准，从 chunk 策略到 embedding 模型选型
提示词工程的误区：日本企业最常见的 3 种写法错误
AI Agent 的局限性：哪些任务不适合交给 Agent 做
on-premise 部署 AI 应用的必要性：数据主权、合规、网络隔离的实际考量

第2层 · Dify协会 Members Only

2-1 深度 Use Case（含配置细节）

制造业设备故障排查机器人：知识库分层结构设计 + 检索参数调优记录
法务合同比对 Workflow：迭代节点处理多文件、人类在环审核节点的触发条件设定
社内稟議（审批）自动草稿生成：结构化输出格式设计 + 提示词版本对比
多语言客服 Agent：工具调用链设计、fallback 策略、对话记忆管理
HR 入职文件处理流水线：PDF 解析 → 信息提取 → 表单填写的完整节点配置

2-2 踩坑记录与解法

知识库检索结果不相关：Top-K、Score 阈值、Rerank 模型三者如何联动调整
Workflow 节点超时频繁：LLM 节点超时参数、重试机制、异步处理的配置方式
同一问题每次回答不一致：Temperature 参数与提示词结构对输出稳定性的影响
大文件（100MB+ PDF）上传失败：分块上传、预处理脚本、存储配置的实际解法
Agent 工具调用陷入死循环：最大迭代次数设定 + 退出条件提示词的设计逻辑

2-3 Dify Enterprise 部署最佳实践（深度版）

生产环境 vs 测试环境的配置差异：资源规格、日志级别、备份策略对比
Helm Chart 部署的 values.yaml 关键参数逐项解说：哪些必改、哪些保持默认
多租户权限设计：企业内不同部门如何隔离数据、共享模型配置
License 管理实务：License 有效期监控、续期流程、多实例场景下的分配策略
升级版本时的注意事项：数据迁移、API 兼容性、回滚预案

第3层 · 合作伙伴培训 Partners

3-1 部署技术培训内容

Docker Compose 部署全流程：docker-compose.yaml 各服务的作用与依赖关系
Helm Chart 部署全流程：Kubernetes 环境要求、namespace 规划、持久化存储配置
License 激活与验证：Key 格式说明、激活接口、激活失败的排查步骤
基础运维操作手册：服务重启顺序、日志位置、常见报错代码对照表
SSO 集成配置：SAML / OIDC 协议选择、IdP 配置参数、用户权限映射规则

3-2 App 搭建培训内容

知识库三种构建方式的适用场景：配置方式 / 流水线 / Web 平台导入各自的边界
提示词设计规范：角色设定、输出格式约束、Few-shot 示例的标准写法
Workflow 节点类型与组合模式：顺序执行、条件分支、迭代、人类在环的典型搭配
Agent 工具定义规范：工具描述字段如何写才能让 LLM 准确调用
API 集成对接指南：发布后的 API Endpoint 结构、鉴权方式、请求/响应格式说明

3-3 合作伙伴交付检查清单内容

部署验收标准：哪些服务必须健康、哪些接口必须通、License 状态确认项
基础功能验证项目：知识库上传 → 检索 → 对话的端到端测试用例
客户移交文档模板：环境信息记录表、管理员账号交接单、运维联系方式
常见客户问题 Q&A 库：合作伙伴在交付现场最常遇到的 20 个问题与标准回答
升级与续费提醒机制：版本更新通知渠道、License 到期前的客户沟通话术

第4层 · 原厂技术支持 Premium

4-1 产品设计理念内容

为什么 Dify 选择 on-premise 而非纯 SaaS：数据主权、企业合规、日本市场特殊性
Dify 的 Provider 抽象层设计：为什么能同时接入几十种 LLM 而不耦合
Knowledge Base 的检索架构：向量检索 + 全文检索 + Rerank 三层为什么缺一不可
Workflow 的节点设计哲学：为什么要有「人类在环」节点，边界在哪里
Dify 的多租户模型：Workspace 隔离的粒度、权限继承关系、设计取舍

4-2 架构建议内容

企业 AI 应用的分层架构：基础设施层 / 平台层 / 应用层 / 用户层各自的职责划分
模型选型建议框架：按任务类型（生成/检索/分类/多模态）推荐不同模型组合
知识库规模化设计：文档量超过 10 万时的分库策略、索引维护、检索性能保障
高可用部署架构：多副本、负载均衡、数据库主从、灾备方案的参考配置
AI 应用的安全边界设计：输入过滤、输出审查、工具调用权限控制的完整方案

4-3 AI 治理咨询内容

企业 AI 落地路线图模板：试点阶段 → 规模化阶段 → 自主运营阶段的里程碑定义
AI 投资回报评估框架：如何量化 AI 应用在效率提升、成本节约上的实际价值
企业 AI 委员会设置建议：谁负责 AI 战略、谁负责技术、谁负责合规的职责划分
数据治理与 AI 合规：日本个人信息保护法（改正個人情報保護法）对 AI 应用的约束点
组织能力建设路径：内部 AI 人才培养计划 vs 依赖合作伙伴的边界与过渡策略

Dify 是什么：为企业构建、掌控并持续演进 AI 应用的平台

在 LangGenius，我们将 Dify 定义为一个面向企业与团队的 AI 应用开发平台。

它不是单一模型的聊天界面，也不是某一家模型厂商的附属工具。Dify 的核心价值在于：帮助企业以自己的业务逻辑、数据资产和治理要求为中心，构建、部署和迭代 AI 应用。

为什么企业需要 Dify

很多团队第一次接触生成式 AI，往往从单点对话开始：

用一个模型做问答
用一个网页做内容生成
用一个 prompt 解决一个局部问题

这类方式适合探索，但很难沉淀为真正可复用、可管理的业务能力。企业一旦进入实际应用阶段，就会很快遇到几个问题：

不想被单一模型厂商绑定
模型能力、价格、上下文长度、合规要求都在变化，企业需要保留切换模型与组合模型的自由。
需要把 AI 接入自己的业务系统与知识资产
真实业务不只是一轮对话，而是知识检索、流程控制、外部工具调用、结果审计的组合。
需要可运营、可治理、可迭代
AI 应用不是一次性交付，而是要持续优化 prompt、数据、工作流和用户体验。

Dify 正是为这些需求而设计。

Dify 不是“问 AI”，而是“做 AI 应用”

如果说通用聊天产品解决的是“与模型交互”，那么 Dify 解决的是“如何把模型变成可交付的应用”。

借助 Dify，团队可以围绕实际业务快速构建：

面向员工或客户的 Chatbot
基于企业知识库的问答系统
多步骤的 Workflow 自动化
可调用工具的 Agent
以 API 或 Web 应用形式交付的 AI 服务

这意味着，企业不必从模型 API、检索链路、流程编排、发布接口、日志观测这些底层环节从零搭建，而是可以在统一平台中完成设计与交付。

Dify 的平台价值

从平台视角看，Dify 提供的是一套把 AI 从“能力”转化为“系统”的方法。

1. 模型解耦

Dify 支持多模型接入，企业可以按任务类型自由选择模型，而不是把所有场景押注在同一家供应商上。

2. 数据可结合

企业可以把文档、FAQ、知识条目、网页内容等组织为知识库，构建更接近真实业务语境的 AI 应用。

3. 流程可编排

很多业务场景并不是“一个问题、一个回答”，而是多步骤判断、检索、生成、调用与回传。Dify 让这类流程以可视化方式落地。

4. 交付可产品化

应用完成后，可以通过 Web、API、嵌入等方式对外提供能力，真正进入团队与业务流程。

5. 运营可持续

AI 应用需要持续迭代。Dify 让团队能够围绕 prompt、知识库、流程与日志，不断提升效果，而不是每次重新开发。

Dify 适合哪些企业场景

Dify 适合那些已经意识到：AI 不应该只是一个聊天窗口，而应该成为组织能力的一部分的团队。

典型场景包括：

企业内部知识问答
客服与售前辅助
内容分析与摘要生成
表单、工单、文档类流程自动化
多模型协作的业务工作流
对数据治理与部署方式有明确要求的组织

我们如何看待 Dify 的角色

Dify 并不是要替企业决定该用哪一个模型，也不是要求企业改变自己的业务逻辑去适配某种 AI 工具。

相反，我们希望 Dify 成为企业自己的 AI 应用底座：

模型可以替换
数据可以掌控
工作流可以定义
交付方式可以选择
应用可以持续演进

Dify 的意义，不只是让团队更快接入 AI，而是让企业在 AI 时代保有自主权。

结语

从 LangGenius 的角度，Dify 的核心不是“又一个 AI 产品”，而是一个帮助企业构建 AI 应用体系的平台。

如果你的目标是让 AI 真正服务于业务，而不是停留在零散试用阶段，那么 Dify 提供的是一条更长期、也更可控的路径：

不依赖单一厂商，围绕企业自己的数据、流程与场景，构建属于自己的 AI 应用。

Dify Cloud vs Dify Enterprise：从快速试用到私有化落地

企业采用 AI 应用平台，通常会经历两个阶段：

先快速验证价值
再进入稳定、可治理、可规模化的部署

从这个视角看，Dify Cloud 与 Dify Enterprise 面向的是不同阶段、不同要求的组织需求。

一句话理解

Dify Cloud：适合快速开始、低门槛试用、尽快上线第一个 AI 应用
Dify Enterprise：适合对数据控制、部署环境、治理能力和组织协作有更高要求的企业级落地

Dify Cloud：更快开始

Dify Cloud 是托管式体验路径，重点在于让团队尽快把应用做出来、跑起来、验证起来。

它通常更适合以下情况：

团队想先做 PoC 或试点
需要快速体验产品能力
没有准备自建基础设施
当前阶段以验证场景为主，而不是先做复杂治理

对于许多团队来说，AI 项目的阻力不在创意，而在起步成本。Dify Cloud 的意义就是把这一步变得足够轻：

注册即可开始
可直接配置模型与应用
更适合从单点场景切入
有助于业务团队先看到结果，再决定扩大投入

Dify Enterprise：更强控制力

当企业从“试试 AI”走向“把 AI 纳入正式业务系统”，需求会发生变化。

此时，组织通常更关心：

数据应存放在哪里
是否需要私有部署或内网部署
是否要满足更严格的安全与合规要求
是否要对访问、日志、审计、组织协作进行更细粒度管理
是否希望将 AI 能力沉淀为长期基础设施

这时，Dify Enterprise 更适合作为企业级部署形态。

它强调的不是“更容易上手”，而是“更适合正式运行”。

该如何选择

选择 Dify Enterprise，如果你更关注：

私有化部署
数据与环境控制
企业安全与治理
中长期平台化建设
在组织内部规模化推广 AI 应用

不是二选一，而是两个阶段

我们并不把 Dify Cloud 与 Dify Enterprise 视为彼此对立的产品，而更愿意把它们看作企业 AI 落地中的两个自然阶段。

很多团队会先从 Cloud 开始：

快速试用
找到合适场景
验证业务效果
形成内部共识
再进入 Enterprise 部署

这种路径的优势在于，企业不需要在一开始就为所有问题做重投入，而是可以在明确价值后，再把部署、治理和组织化能力逐步补齐。

从 LangGenius 的视角看部署选择

我们始终认为，企业采用 AI 平台，不应只看“能不能做出来”，还要看“能不能长期掌控”。

因此，部署方式本身就是产品能力的一部分。

对希望尽快验证业务机会的团队，Cloud 更合适
对需要把 AI 纳入核心业务体系的企业，Enterprise 更合适

无论哪种路径，目标都一致：

让企业在自己的边界内，建立真正可用、可控、可持续演进的 AI 应用能力。

常见判断标准

如果你正在评估两者，可以优先问以下几个问题：

现在是在做试点，还是准备正式落地？
数据是否允许托管在公有云环境？
是否存在内网、私有云或本地部署要求？
是否需要更严格的权限、日志、审计与组织管理？
未来是否计划在多个团队、多个场景中推广使用？

如果前两个问题更重要，Cloud 往往是更高效的起点；如果后几个问题已经成为硬性条件，Enterprise 会更匹配。

结语

Dify Cloud 和 Dify Enterprise 的区别，不只是“一个在线、一个私有”。

本质上，它们分别对应企业 AI 采用的两种重点：

Cloud 解决的是“如何快速开始”
Enterprise 解决的是“如何稳健落地”

从 LangGenius 的角度，我们希望企业既能低门槛进入 AI 应用时代，也能在需要时拥有足够强的部署与治理能力。Dify 的产品设计，正是围绕这两件事展开。

Dify 支持哪些 LLM：在同一平台接入 OpenAI、Claude、Gemini 与本地模型

Dify 的一个核心设计原则，是不把企业的 AI 应用绑定在单一模型供应商上。

因此，Dify 从一开始就不是围绕“某一个模型最好”来构建，而是围绕“企业如何根据任务类型、成本目标和部署要求，自由选择模型”来设计。

Dify 支持的模型类型

在 Dify 中，团队通常可以接入以下几类模型：

OpenAI：适合通用生成、总结、分类、对话等场景
Anthropic Claude：适合长文本理解、复杂推理、企业写作等任务
Google Gemini：适合多模态与 Google 生态相关能力扩展
本地模型 / 开源模型：可通过 Ollama 等方式接入，用于更强的数据控制或特定成本策略
其他兼容接口的模型服务与推理后端

这意味着，企业可以在一个统一平台中使用不同模型，而不需要为每种模型单独重建应用层。

为什么多模型能力重要

企业真实使用 AI 时，几乎不会只有一种需求。

例如：

FAQ 分类任务更关注成本与速度
知识问答更关注检索质量与稳定输出
长文总结更关注上下文处理能力
复杂推理更关注模型智能水平
某些数据场景则要求模型运行在本地环境

如果平台只能绑定单一模型，企业很快会遇到限制。Dify 提供的不是“替你选模型”，而是“让你保留选模型的权利”。

在 Dify 中如何理解模型接入

从应用层看，模型接入不是单独存在的技术动作，而是和以下能力一起发生：

Prompt 编排
Workflow 流程控制
Knowledge 检索增强
Agent 工具调用
API / Web 应用发布

也就是说，Dify 的价值并不只是“能接 Claude 或 Gemini”，而是让这些模型在统一的应用框架里真正参与业务流程。

OpenAI、Claude、Gemini 各适合什么场景

虽然不同模型会持续演进，但从平台实践角度，企业通常会这样理解：

Claude

更适合对长文本、复杂理解和表达质量要求更高的场景：

长文总结
政策、制度、合同类文本分析
需要稳定书面表达的企业内容生成

本地模型 / Ollama

更适合对部署环境和数据边界有明确要求的组织，例如：

需要在本地或私有环境运行
对外部依赖有严格限制
希望在特定任务上优化成本结构

为什么本地模型接入很关键

对于企业来说，“是否支持本地模型”并不是一个附加选项，而常常是架构决策的一部分。

通过 Ollama 等方式接入本地模型，意味着企业可以：

在更可控的环境中运行推理
根据自身资源选择开源模型
在某些任务上降低外部 API 依赖
为私有化部署提供更完整的闭环

Dify 支持这条路径，是因为我们认为企业采用 AI，不应只有 SaaS 模式这一种答案。

多模型不只是备选，而是策略

企业成熟使用 AI 平台时，常见做法并不是“选一个最强模型”，而是建立模型策略：

低成本模型负责高频、标准化任务
高质量模型处理关键节点
私有模型覆盖敏感数据场景
不同工作流按目标切换不同推理后端

Dify 为这种策略提供统一承载层。

换句话说，Dify 不是在比较谁更聪明，而是在帮助企业把不同模型能力组织成真正可执行的应用体系。

我们如何看待模型生态

从 LangGenius 的视角，模型生态一定是持续变化的：

新模型会出现
价格会变化
能力边界会移动
企业需求也会不断调整

因此，一个企业级 AI 平台最重要的能力之一，就是对模型变化保持开放。

这也是为什么 Dify 会把模型接入能力设计为平台底座，而不是某个附属功能。

结语

Dify 支持 OpenAI、Claude、Gemini、本地模型等多种接入方式，其意义不在于“支持得多”，而在于：

让企业可以在统一平台中，按场景选择模型、按要求控制架构、按业务持续优化应用。

对 LangGenius 来说，真正重要的不是企业最终用了哪个模型，而是企业是否拥有了长期掌控 AI 应用演进方向的能力。

Dify 的核心概念：Chatbot、Agent、Workflow、Knowledge Base 分别适合什么场景

Dify 是一个统一的 AI 应用平台，但不同业务需求并不对应同一种构建方式。

在 LangGenius，我们通常用四个核心概念帮助团队理解 Dify：

Chatbot
Agent
Workflow
Knowledge Base

它们不是彼此替代的关系，而是面向不同问题的能力组合。

1. Chatbot：适合面向用户的对话入口

Chatbot 是最容易理解、也最常见的 AI 应用形态。它适合以对话方式与用户交互的场景。

例如：

员工自助问答
客户支持助手
产品使用咨询
基础信息收集与回复

如果你的目标是“让用户可以直接问问题，并得到自然语言回答”，Chatbot 往往是最合适的入口。

Chatbot 更适合什么场景

问答为主
流程相对简单
用户希望通过聊天完成操作
重点在体验与响应，而不是复杂流程控制

2. Agent：适合让 AI 主动调用工具完成任务

当应用不只是“回答问题”，而是需要 AI 根据目标自主选择工具、执行步骤、整合结果时，就进入了 Agent 的范畴。

例如：

搜索资料后生成结论
调用外部接口完成任务
在多个工具间协同处理复杂问题
根据目标动态决定下一步动作

Agent 的特点

强调任务完成而非单轮回答
可以结合工具调用
更适合开放式、多步骤问题
适合构建更具自主性的 AI 应用

Agent 更适合什么场景

任务路径不完全固定
需要工具调用
需要 AI 根据上下文决定策略
用户交付的是目标，不是明确步骤

3. Workflow：适合需要明确控制的业务流程

很多企业场景并不适合完全交给 Agent 自主决策，而是更需要可预测、可复用、可治理的执行路径。这类场景更适合 Workflow。

例如：

输入内容后先分类，再检索，再生成，再审核
读取表单后进行多步判断与分支处理
接收文本后做摘要、翻译、格式化与回传
将知识检索、模型生成、条件分支串成固定链路

Workflow 更适合什么场景

步骤明确
需要条件分支
需要稳定输出
需要可观测、可调试、可复用

如果说 Agent 更像“让 AI 自己想办法完成目标”，那么 Workflow 更像“由团队定义好过程，让 AI 在过程内执行”。

4. Knowledge Base：适合让 AI 回答基于企业知识的问题

Knowledge Base 是 Dify 中构建知识型应用的基础。它的作用不是替代模型，而是让模型在回答问题时可以结合企业自己的资料。

常见知识来源包括：

PDF
文档与手册
FAQ
网页内容
产品资料
内部制度与说明文档

Knowledge Base 的特点

为回答提供业务语境
降低模型脱离事实自由发挥的风险
支持知识问答、检索增强、内部助手等场景
是许多 Chatbot 与 Workflow 的关键基础设施

Knowledge Base 更适合什么场景

需要基于已有资料回答问题
企业有大量文档资产
需要提升回答的依据性与稳定性
想构建“懂自己业务”的 AI

四者之间的关系

理解 Dify 的关键，不是把这四个概念分开记忆，而是理解它们如何组合。

一个常见的应用结构可能是：

用 Chatbot 作为前端入口
用 Knowledge Base 提供检索支持
用 Workflow 组织回答逻辑
在需要时加入 Agent 调用工具

也就是说，Dify 不是只提供“一个聊天机器人”，而是提供了构建不同层次 AI 应用的通用框架。

该如何选择

你可以这样判断：

如果你的核心问题是：

“我需要一个清晰、稳定、可控制的处理流程。”
优先考虑 Workflow。

如果你的核心问题是：

“我想让 AI 基于我的资料来回答。”
优先建设 Knowledge Base。

从 LangGenius 的视角

我们希望企业理解：AI 应用不只有一种形态。

有些问题需要一个好用的对话入口，有些问题需要一个可控的流程引擎，有些问题需要一个真正懂业务语境的知识层，有些问题则需要自主调用工具的执行能力。

Dify 的产品设计，正是为了让这些能力不再分散在多个系统里，而是在同一平台中协同工作。

结语

Chatbot、Agent、Workflow、Knowledge Base 不是抽象术语，而是企业在构建 AI 应用时最常遇到的四类能力需求。

Chatbot 解决对话入口
Agent 解决任务执行
Workflow 解决流程编排
Knowledge Base 解决业务知识接入

当团队把这四个概念理解清楚，就更容易判断：自己的场景到底需要什么、应该从哪里开始，以及如何逐步把单点 AI 能力扩展成完整的企业应用。

Dify Workflow vs n8n / Zapier：AI 应用编排与系统自动化是两类不同的问题

当团队开始做自动化时，经常会同时看到几类工具：Dify、n8n、Zapier。

它们表面上都能“连流程、做自动化”，但如果只把它们看作同一类产品，就会错过最关键的判断标准。

从 LangGenius 的视角看，三者最本质的区别不是界面形式，而是它们围绕什么来设计自动化系统。

一句话概括

n8n / Zapier 的中心是：连接系统、搬运数据、触发动作
Dify Workflow 的中心是：围绕 LLM 构建可控的 AI 应用流程

这就是两类产品的分水岭。

n8n / Zapier 更像“系统之间的自动化管道”

n8n 和 Zapier 非常擅长把不同 SaaS、数据库、表单、通知系统连接起来。

典型流程是：

某个事件发生
触发自动化
把数据发往另一个系统
根据条件继续分支处理

例如：

表单提交后写入表格并通知 Slack
邮件到达后同步到 CRM
定时拉取数据并生成报表

在这种场景下，自动化的核心是：

事件触发
应用集成
数据流转
条件分支

这类工具非常强，也非常重要。

Dify Workflow 更像“AI 处理流程的编排层”

Dify Workflow 当然也可以接入外部系统，但它的设计出发点不同。

它重点解决的是：

如何把 LLM 放进业务流程里
如何把知识检索、模型推理、条件判断、工具调用组织成一个 AI 应用
如何让输出既有生成能力，又具备业务可控性

典型流程更像：

接收用户输入
检索知识库
选择模型或工具
进行推理与生成
根据结果分支处理
返回可交付结果或继续执行后续任务

也就是说，Dify Workflow 不是简单把 A 系统连到 B 系统，而是把AI 理解、AI 决策、AI 生成纳入一个可设计、可复用的应用流程中。

本质区别一：自动化对象不同

Dify Workflow 自动化的是：

AI 应用中的推理、检索、生成与控制逻辑

如果你的问题是： “我想把几个 SaaS 工具串起来。”
n8n / Zapier 往往更直接。

如果你的问题是： “我想把知识、模型、判断逻辑和输出过程组织成一个 AI 应用。”
Dify Workflow 更匹配。

本质区别二：核心能力不同

Dify Workflow 的强项

LLM 节点编排
Knowledge / RAG 结合
Prompt 与推理链路设计
AI 输出控制与应用交付

两类能力都重要，但面向的问题不同。

本质区别三：交付结果不同

n8n / Zapier 的结果通常是：

某个流程被自动执行了
某些系统之间不再需要手工同步
某个通知、更新或写入动作自动完成

Dify Workflow 的结果通常是：

一个可直接使用的 AI 应用
一个带知识能力的问答系统
一个可发布为 API 或 Web 的业务智能流程
一个把模型能力真正产品化的应用层

所以，Dify Workflow 更接近“AI 应用开发”，而不是传统意义上的“系统胶水”。

Dify 是否会替代 n8n / Zapier？

不会。

在很多企业架构里，它们更常见的关系是互补，而不是替代。

一个很自然的组合方式是：

用 n8n / Zapier 负责触发器、系统连接和外部流程搬运
用 Dify Workflow 负责 AI 推理、知识检索、生成与决策

例如：

表单提交后由 n8n 触发，再调用 Dify 完成文本分析与回复生成
外部系统采集数据后交给 Dify 进行总结、归类和问答处理
Dify 输出结果后，再由 n8n 写回 CRM、消息系统或数据库

从这个角度看，n8n / Zapier 更像“手脚”，Dify 更像“带业务语境的 AI 大脑”。

企业该如何选择

更适合优先考虑 n8n / Zapier 的情况

自动化重点在 SaaS 集成
业务规则清晰，AI 不是核心
主要诉求是触发、搬运、同步、通知

更适合优先考虑 Dify Workflow 的情况

业务核心在 LLM 能力
需要知识库检索与生成结合
需要围绕 AI 输出设计流程
目标是做成正式 AI 应用，而非单纯连线自动化

从 LangGenius 的视角

我们并不把 Dify Workflow 定义为传统自动化工具的替代品。

Dify Workflow 的价值在于，它把原本分散的 AI 能力——模型、知识、Prompt、工具、流程——统一到一个面向应用的框架中。这使得团队不只是“用了 AI”，而是真正把 AI 变成了系统的一部分。

这也是 Dify 和 n8n / Zapier 的根本不同：

Dify Workflow 的目标不是让系统彼此连接，而是让 AI 真正进入业务流程。

结语

如果把自动化理解成“让流程自己跑起来”，那么 n8n / Zapier 做得很好；但如果你要解决的是“让 AI 在业务中稳定、可控地工作”，Dify Workflow 才是更接近问题本身的答案。

因此，Dify Workflow 和 n8n / Zapier 的本质区别不是谁更强，而是谁在解决不同层级的问题：

前者更偏 AI 应用编排
后者更偏 系统自动化集成

当团队把这一点看清楚，工具选择就会简单很多。

用 Dify 搭建企业内部 FAQ 机器人：从知识库上传到对话测试的完整流程

在企业导入 AI 应用的过程中，内部 FAQ 机器人通常是最容易验证价值、也最适合率先落地的场景之一。

原因很明确：组织内部存在大量高频、重复、规则相对清晰的问题，例如报销标准、请假流程、出差规范、信息安全要求、合同流程、IT 支持入口等。这些问题本身并不复杂，但会持续占用人事、行政、财务、法务与 IT 团队的响应时间。

借助 Dify，企业可以将制度文档、流程说明与常见问答组织为知识库，并通过可视化方式构建一个可测试、可迭代、可上线的 FAQ 机器人。

本文将围绕一个完整落地流程展开说明：从资料准备、知识库上传，到问答流程设计、对话测试与后续优化，帮助团队快速完成第一版内部 FAQ 机器人的搭建。

一、为什么企业通常从 FAQ 机器人开始

与更复杂的 Agent 或跨系统自动化相比，FAQ 机器人具备三个明显优势：

业务边界清晰
回答范围通常围绕制度、流程与内部文档展开，适合标准化建设。
上线门槛较低
在第一阶段，团队通常不需要引入复杂工具调用，就可以通过知识库检索与回答生成完成基本能力。
效果容易验证
只要准备一批真实问题，就能够快速评估命中率、回答质量与用户接受度。

因此，对于多数企业而言，FAQ 机器人是进入 AI 应用建设最稳妥的起点之一。

二、第一步：准备知识资料

FAQ 机器人的效果，很大程度上取决于知识资料的组织方式。

建议优先准备以下内容：

员工手册
就业规则或公司制度
报销与出差规范
信息安全与合规手册
IT 支持文档
常见流程说明
既有 FAQ 表格或客服话术

资料整理建议

在上传知识库前，建议先完成一轮基础清理：

删除明显重复内容
尽量避免一个文件覆盖过多主题
让每份资料尽量聚焦于一个清晰问题域
使用明确标题，例如“出差报销标准”“请假审批流程”“VPN 申请说明”

这一步的目标，是让后续检索更稳定，减少无关上下文对回答结果的干扰。

三、第二步：在 Dify 中建立知识库

在 Dify 中，FAQ 机器人的知识层通常由 Knowledge 提供。

一个常见做法是：

按主题建立知识库或文档分组
上传 PDF、Word、Markdown、网页内容等资料
由系统完成切分与向量化
在后续问答流程中调用检索结果

四、第三步：设计 FAQ 机器人的问答流程

一个基础但可用的 FAQ 机器人，通常可以按照如下逻辑构建：

用户提问
→ 问题分类
→ 知识库检索
→ 基于检索结果生成回答
→ 输出答案

在 Dify Workflow 中，这一流程通常对应以下节点：

Start / Input：接收员工问题
LLM 节点：对问题进行主题分类
Condition 节点：判断应使用哪类知识范围
Knowledge Retrieval：检索对应知识库
LLM Answer：结合上下文生成回答
Answer：输出最终结果

为什么建议增加“问题分类”步骤

在小规模知识库中，问题可以直接进入检索。但一旦资料规模增长，直接全库检索会明显降低稳定性。

加入分类层后，系统可以先判断用户问题属于哪一类，再只在相关知识中检索。例如：

“出差补贴标准是多少？” → 财务 / 出差管理
“副业是否允许？” → 人事制度
“忘记 VPN 密码怎么办？” → IT 支持

与全量盲检索相比，这种做法更适合正式企业场景。

五、第四步：设置关键提示词

在 FAQ 机器人中，最关键的提示词通常有两类：分类提示词与回答提示词。

1. 分类提示词

用于判断问题所属范围，例如：

你是企业内部问题分类助手。
请判断以下问题属于哪一类：
- 人事制度
- 财务报销
- 出差管理
- 信息安全
- IT 支持
- 其他

问题：{{user_query}}

2. 回答提示词

用于约束输出边界，避免模型超范围推断，例如：

你是企业内部 FAQ 助手。
请严格基于提供的参考内容回答问题。
要求：
- 不要凭空补充制度中没有的信息
- 如果资料不足，明确说明“当前资料中未找到明确依据”
- 优先使用简洁、可执行的表达
- 如有必要，标注文档或制度来源

员工问题：{{user_query}}
参考内容：{{context}}

在内部 FAQ 场景中，重点不是让回答“像聊天”，而是让回答具备明确依据、表达稳定、可直接执行。

六、第五步：进行第一轮对话测试

知识库准备完成、流程搭建完成后，建议先进行一轮结构化测试，而不是直接上线。

建议至少准备三类问题：

3. 边界问题

公司没有写清楚的情况怎么办？
这个制度和实际执行不一致怎么办？
你能替我审批吗？

通过这三类测试，可以快速识别：

检索是否命中正确资料
回答是否存在超范围推断
用户表达方式变化后，系统是否仍然稳定

七、第六步：根据测试结果优化

在 FAQ 机器人建设中，最常见的问题并不只是“模型不够强”，而往往来自以下几个方面。

1. 知识库过于混杂

如果一个知识库覆盖过多主题，检索结果会明显变得不稳定。

优化方式：按主题重组资料，缩小单次检索范围。

2. 分类过于粗糙

所有问题都走同一条路径，系统很难对复杂业务问题做出稳定分流。

优化方式：增加分类维度，再决定调用哪类知识。

3. 回答风格过于泛化

如果提示词约束不够明确，模型容易输出流畅但依据不足的答案。

优化方式：在回答提示词中强调“仅依据资料回答、禁止猜测、优先引用来源”。

4. 用户不知道如何提问

完全开放式输入会让部分用户不知道应如何发问。

优化方式：增加问题示例或预设按钮，例如“报销类”“请假类”“出差类”“设备支持类”。

八、FAQ 机器人上线后的增强方向

当第一版 FAQ 机器人验证通过后，可以逐步增加以下能力：

3. 无法回答时转人工

对于制度未覆盖、需要个案判断或权限审批的问题，应引导用户联系对应部门，而不是让模型继续推断。

九、推荐的企业落地方式

在实际项目中，我们通常不建议企业第一阶段就覆盖“全公司、全制度、全问题域”。

更有效的方式通常是：

先选择一个部门试点，例如 HR 或行政
先覆盖 20 到 50 个高频问题
通过真实使用收集反馈
在验证效果后，再扩展到更多制度与部门

这种方式更容易控制范围，也更容易在组织内部形成正向反馈。

结语

借助 Dify 构建企业内部 FAQ 机器人，并不需要从复杂 Agent 开始。对于多数组织来说，更关键的是先把三件事情做好：

知识资料组织清楚
问答流程设计清楚
测试与优化路径清楚

一个真正可用的 FAQ 机器人，至少应满足以下要求：

能找到正确资料
能基于资料稳定回答
在资料不足时不进行无依据推断

当团队先把这类基础能力做扎实后，FAQ 机器人不仅可以帮助企业减少大量重复沟通成本，也可以成为后续知识检索、流程自动化与 Agent 应用建设的重要入口。

用 Dify + 知识库构建合同审查助手：如何处理 PDF 文档、设定检索参数

在企业场景中，合同审查并不意味着让 AI 替代法务，而更适合作为合同预审、条款识别与风险提示的第一层能力。

这类场景非常适合通过 Dify 的 Knowledge 与 Workflow 进行落地。因为合同审查的基础工作，通常可以被拆解为以下几个步骤：

读取合同文本
从模板、制度与规则中检索依据
输出结构化的风险提示与修改建议

其中最关键的两个问题通常不是“模型够不够强”，而是：

PDF 文档应该如何处理
检索参数应该如何设置，才能让结果更稳定

本文将围绕这两个问题展开，说明如何用 Dify + 知识库构建一个具备实用价值的合同审查助手。

一、先明确：合同审查助手适合承担什么角色

在企业实践中，合同审查助手更适合作为“预审工具”，而不是最终决策主体。

它更适合承担的任务包括：

提取合同基本信息，例如主体、金额、期限、付款条件
定位重点条款，例如违约责任、保密、知识产权、自动续约
对照企业标准模板或法务规则进行初步比对
输出风险提示清单
生成给业务或法务使用的修改建议草稿

而以下内容，通常仍应保留给人工判断：

重大交易结构判断
跨境合规问题
行业监管细则解释
超出企业既有规则体系的复杂争议

因此，一个成熟的合同审查助手，其目标并不是“替代法务”，而是优先完成标准化、重复性强、可规则化的第一轮审查工作。

二、第一步：准备两类资料

合同审查助手通常至少需要两类输入资料。

2. 审查依据资料

例如：

企业标准合同模板
法务审查清单
风险条款规则表
合同审批制度
常见问题说明
历史修订规范

在实际项目中，很多团队会优先上传合同本身，却忽略了“审查依据”的组织，结果系统只能给出泛化总结，而无法生成真正有价值的审查结论。

三、第二步：处理 PDF 文档

在合同场景中，PDF 是最常见、也最容易影响检索质量的文件格式之一。

常见问题

扫描版 PDF 无法直接提取文本
需要 OCR 才能进入后续流程。
排版复杂
页眉页脚、表格、签章与页码容易干扰切分效果。
多份模板混在同一文件中
会直接影响后续检索结果的稳定性。
重复条款过多
会在排序阶段挤占有效内容。

四、第三步：把知识层拆清楚

在合同审查场景中，我们不建议将所有资料直接堆入一个统一知识库，而更建议按角色拆分。

知识库 C：补充制度与合规资料

印章管理制度
付款审批制度
数据合规要求
行业特殊约束

这样做的价值在于：系统后续可以根据合同类型，选择更合适的知识范围，而不是在所有资料中进行无差别检索。

五、第四步：设计合同审查 Workflow

一个可落地的合同审查基础流程，通常可以设计为：

上传合同
→ 提取合同文本
→ 判断合同类型
→ 检索对应模板与审查规则
→ 抽取关键条款
→ 生成风险清单与建议
→ 输出结构化审查结果

在 Dify 中，通常可以拆分为以下节点：

Input：输入合同文本或上传处理后文本
LLM 节点：识别合同类型
Knowledge Retrieval：检索模板与规则
LLM 节点：抽取关键条款
LLM 节点：基于规则输出风险分析
Answer / JSON 输出：输出结构化审查结果

六、第五步：正确理解检索参数

在合同审查助手中，检索质量决定输出质量。

如果系统没有检索到正确条款、模板或规则，那么后面的生成步骤越完整，偏差反而可能越大。

因此，在构建阶段，建议重点关注以下几个参数思路。

1. Top K 不宜过小，也不能盲目过大

Top K 表示系统一次检索返回多少条相关片段。

过小：容易遗漏关键依据
过大：容易引入过多噪音，影响模型聚焦

在合同场景中，条款定位类问题可以适当偏小，而综合审查类问题通常需要更多上下文支撑。因此，Top K 不应固定为单一值，而应根据问题类型进行调试。

2. 不要把“无效化”当作长期策略

在一些 RAG 实践中，团队会把重复或不想继续使用的片段设为无效，以为这样就不会影响结果。

但在很多情况下，重复片段仍可能对排序过程产生影响，导致真正有效的内容被挤出前列。相比依赖无效化，更稳妥的做法是：

上传前就清理重复条款
删除过时版本
不把清洗任务留到检索之后

3. Chunk 应符合合同结构，而不是仅按字数切分

合同并不是普通文章。如果切分过碎，条款上下文会断裂；如果切分过长，检索聚焦度又会下降。

更合理的思路通常是：

按条款或小节切分
保留条款标题
尽量让一个 chunk 表达一个完整规则

例如“付款方式”与“违约责任”不应落入同一大块，也不应将一个完整条款人为切成多个断裂片段。

4. 对模糊问题先做改写

在合同审查中，常见问题往往较为模糊，例如：

“这个条款有没有风险？”
“这里需要改吗？”
“这份合同是否合规？”

这类问题直接进入检索，效果通常不理想。更推荐的方式，是先通过一个前置 LLM 节点，把问题改写为更明确的检索请求，例如：

“请检查付款条款是否与公司模板一致”
“请定位合同中关于自动续约与违约责任的内容”

这种方式可以显著提升相关性。

七、第六步：提示词必须强调“依据”与“边界”

合同审查场景最大的风险之一，是模型在资料不足时仍然输出听起来合理、但缺乏依据的判断。

因此，在回答提示词中，建议明确约束以下原则：

你是合同审查助手。
请严格基于提供的合同内容和审查规则进行分析。
要求：
- 不要编造不存在的条款
- 不要把推测当作结论
- 对每个风险点说明依据
- 如果资料不足，请明确指出需要人工复核
- 输出尽量结构化

如果企业希望进一步增强可读性，也可以增加风险分级，例如：

高风险
中风险
低风险
信息不足

八、第七步：建立小规模测试集

在正式上线前，我们建议先从一个单一合同品类开始测试，例如：

NDA
标准采购合同
劳务服务合同

然后准备 10 到 20 份测试样本，覆盖以下情况：

标准模板版本
经人工修改的版本
明显存在风险条款的版本
信息不完整或 OCR 质量较差的版本

评估时重点关注：

合同类型识别是否正确
关键条款能否稳定抽取
风险提示是否有依据
结果是否适合业务或法务直接阅读

九、推荐的落地方式

在企业内部推动这类项目时，我们通常不建议第一阶段就将其命名为“AI 合同审查系统”。

更容易被业务与法务接受的表述通常是：

合同预审助手
合同信息提取助手
条款风险提示助手
合同模板比对助手

这种表达方式更符合当前 AI 的实际能力边界，也有助于在组织内部建立合理预期。

结语

借助 Dify + 知识库构建合同审查助手，真正决定效果的并不只是模型，而是三个基础环节是否做扎实：

PDF 文档是否被清洗为高质量文本
审查依据是否被组织成清晰知识层
检索参数与切分策略是否围绕合同结构完成调优

当这三件事被处理好后，Dify 就能够很好地承接一个实用的合同预审流程：先提取信息，再定位条款，再基于规则输出风险提示，最后将复杂判断交还给人工复核。

这也是当前企业最容易真正用起来的一种方式：不是让 AI 直接替代法务，而是先让 AI 成为法务前的一层高效筛查能力。

用 Dify Workflow 自动化日报生成：多节点串联、变量传递与输出格式控制

日报、周报、资讯摘要与项目进展汇总，是企业内部最典型的高频文本生成任务之一。

这类任务具备几个共同特征：

输入来源较多
格式相对稳定
内容需要持续更新
重复劳动成本较高

因此，它们非常适合通过 Dify Workflow 来进行自动化建设。因为这类场景既需要多步骤处理，也需要对结果格式进行明确控制，不适合只依赖单一提示词一次生成完成。

本文将以“自动化日报生成”为例，重点说明三个关键问题：

多节点如何设计与串联
变量如何在节点之间稳定传递
输出格式如何做到可控、可复用

一、为什么日报生成更适合 Workflow

很多团队第一次尝试生成日报，通常会直接向模型发出类似请求：

“请根据今天的数据写一份日报。”

这种方式当然可以生成结果，但在正式业务环境中，通常会很快暴露出以下问题：

输入信息过于混杂
模型难以稳定理解来源不同、结构不同的上下文。
输出格式不稳定
有时像日报，有时像新闻摘要，有时又变成普通说明文。
难以调试与优化
当结果不理想时，很难判断问题究竟出在信息采集、重点提炼还是最终排版。

而 Workflow 的优势，正是在于它可以把“写日报”拆解为一条可设计、可测试、可演进的流程。

二、日报生成通常会接收哪些输入

日报并不一定来自单一数据源。常见输入包括：

Web 搜索结果
抓取的新闻正文
内部业务系统数据
销售或客服日报表
项目进展记录
群聊与会议纪要摘要

如果是资讯类日报，输入通常会更接近：

关键词
时间范围
搜索结果链接
页面正文

如果是内部业务类日报，则更可能包括：

当日新增客户数
工单处理量
项目状态变化
异常事件清单
管理层重点关注事项

无论来源如何，核心目标都一致：先把零散信息整理为可处理内容，再进入摘要与生成流程。

三、一个可落地的 Workflow 结构

以“自动收集行业资讯并生成日报”为例，一条典型流程通常如下：

开始
→ 输入主题或日期
→ 搜索新闻
→ 抽取网页正文
→ 汇总原始内容
→ 提炼重点信息
→ 生成日报正文
→ 按模板格式化输出

在 Dify 中，这通常可拆为以下节点：

Start / Input：输入日报主题、日期、关键词
工具节点或插件节点：执行搜索
内容抽取节点：抓取正文
LLM 节点 A：筛选重点信息
LLM 节点 B：整理为日报提纲
LLM 节点 C：按模板生成正式日报
Answer：输出 Markdown 或固定格式文本

四、多节点串联的原则：一个节点只做一件事

在 Workflow 设计中，最常见的问题是一个节点承担过多职责。

例如同时负责：

搜索
筛选
摘要
排版

这类设计在初期看起来省事，但会明显增加调试难度，也不利于后续复用。

更推荐的方式是让每个节点职责单一且清晰：

节点 5：格式化输出

仅负责按固定模板输出，不再重新理解业务内容。

当节点职责足够清楚时，无论是替换模型、优化提示词，还是增加审批与分发步骤，都会更容易管理。

五、变量传递如何设计更清楚

日报类应用中，变量传递直接决定流程是否可控。因为前一节点的输出，通常正是后一节点的输入。

一个典型变量链可能包括：

topic：日报主题
date_range：时间范围
search_results：搜索结果
raw_content：正文抽取结果
key_points：重点摘要
report_outline：日报提纲
final_report：最终日报正文

变量设计建议

1. 变量名必须有语义

避免使用 text1、result2 一类命名。变量越清楚，后续越容易维护。

3. 后续节点只读取必要变量

如果日报生成节点只需要 key_points 与 date_range，就不应再把全部原始正文一并传入。

4. 提纲与正文应分离

report_outline 与 final_report 最好分别保留。这样可以快速判断问题出在提纲设计还是正文表达。

六、输出格式控制的关键方法

日报场景的重点，不只是“生成内容”，而是“稳定输出企业需要的格式”。

很多团队习惯只写一句：

“请按日报格式输出。”

在实际项目中，这通常远远不够。

更有效的方式

在提示词中直接给出清晰模板，例如：

请按以下格式输出：

# {{date}} 日报

## 一、今日重点
- 重点 1
- 重点 2
- 重点 3

## 二、详细摘要
### 1. 主题一
内容

### 2. 主题二
内容

## 三、风险与关注事项
- 项 1
- 项 2

## 四、建议动作
- 动作 1
- 动作 2

如果日报还需要发送到下游系统，输出格式甚至可以进一步结构化为：

Markdown
JSON
HTML 片段
固定字段格式

这样生成结果不仅可读，还能直接被知识库、邮件系统、企业 IM 或内容管理系统消费。

七、一个更实用的节点设计示例

下面给出一个更贴近企业实际的 Workflow 结构。

八、如何避免“语言流畅但信息空泛”

在日报生成场景中，一个典型问题是内容读起来很顺，但信息量不足。

解决这一问题，通常可以从三方面入手。

3. 对写作节点设置明确风格边界

例如：

不写空洞开场
不使用夸张修饰
优先写结论，再写背景
控制每个重点的字数范围

通过这种分层方式，可以让日报更接近正式业务文档，而不是泛化摘要。

九、日报 Workflow 为什么适合持续扩展

一旦日报流程跑通，通常可以很快扩展到更多应用类型，例如：

周报
月报
竞品监控报告
舆情摘要
销售晨报
客服异常日报
项目进展播报

从本质上看，这些场景共享同一条基础链路：

采集 → 清洗 → 提炼 → 生成 → 格式化输出

因此，日报生成不仅是一个单独应用，也经常是企业后续自动化报告体系的起点。

结语

借助 Dify Workflow 自动化日报生成，真正的价值并不只是“让 AI 写一段话”，而是将原本依赖人工汇总、人工整理、人工排版的流程，重构为一条可复用、可调试、可持续优化的工作流。

在这个过程中，最关键的三个点始终是：

多节点串联：保证流程清晰
变量传递：保证上下文稳定
输出格式控制：保证结果可发布、可复用

当这三点被设计清楚后，日报应用就不再只是一个演示案例，而会成为企业内部非常实用的一类自动化能力。

用 Dify Agent 调用外部工具：以天气查询为例，演示工具定义到调用的完整链路

在很多企业场景中，用户真正需要的并不只是“与 AI 对话”，而是“让 AI 基于外部能力完成一项动作”。

这正是 Agent 价值开始体现的地方。

与普通问答应用不同，Agent 的重点不只是生成一句回答，而是围绕任务完成展开完整链路：

理解用户意图
判断是否需要调用工具
选择正确工具
组装调用参数
接收工具返回结果
基于结果生成最终回复

为了更容易说明这条链路，天气查询是一个非常典型的例子。它足够简单，同时又完整覆盖了 Agent 调用外部工具时最核心的能力结构。

一、什么是“工具调用”

所谓工具调用，可以理解为：模型在判断自身无法可靠回答某个问题时，通过外部能力获取信息，再将结果组织为最终输出。

以天气查询为例，一条典型流程如下：

用户：今天东京天气怎么样？
→ Agent 判断：这是一个需要实时信息的问题
→ 调用天气 API
→ 获取温度、天气状态、风力、降水概率
→ 生成最终回答

这意味着，关键点不在于模型“是否知道天气”，而在于模型“是否知道什么时候必须去查天气”。

二、Dify Agent 中常见的两种策略

在 Dify 的 Agent 场景中，工具调用通常会围绕两类方式展开：

ReAct：模型通过“思考 → 行动 → 观察”的方式逐步决定下一步
Function Calling：模型直接输出工具名称与参数，以结构化方式发起调用

Function Calling 更适合的情况

任务结构明确
工具调用路径稳定
对响应速度与参数准确性要求更高
输出格式要求结构化

对于天气查询这类任务，Function Calling 往往更直接；而对于“结合天气、交通与日程安排给出出行建议”这类更开放任务，ReAct 的灵活性会更高。

三、为什么天气查询是一个典型 Agent 场景

天气查询具备一个标准 Agent 场景的全部特征：

问题依赖实时数据
需要调用外部 API
参数结构清晰，例如城市与日期
返回结果结构化，例如温度、天气状态、降水概率
最终结果需要自然语言表达，而不是原始 JSON

因此，天气查询并不只是一个简单示例，而是理解 Agent 工具调用全链路最适合的入门案例之一。

四、第一步：定义工具能力

在 Dify Agent 中，工具本质上是一种可被模型调用的外部能力。

以天气查询为例，定义一个工具时，至少需要明确以下三项内容。

1. 工具名称

例如：

get_weather
query_weather

名称应尽量清晰，便于模型理解用途。

2. 工具描述

例如：

用于查询指定城市在指定日期的天气情况
返回天气状态、温度、湿度、风力与降水概率

描述质量会直接影响模型是否能正确判断使用场景，因此不应写得过于泛化。

3. 输入参数

天气查询最常见的参数包括：

city：城市名
date：日期
unit：温度单位（可选）

在企业场景中，参数定义越清晰，调用稳定性通常越高。

七、第四步：处理不完整输入

真实用户的输入并不会总是完整。例如：

“今天适合出门吗？”
“东京天气呢？”
“明天大阪会下雨吗？”

在这类情况下，Agent 需要具备两种基础能力。

2. 主动追问缺失参数

如果用户只说“天气怎么样”，却没有说明城市，就应优先追问：

“请问你想查询哪个城市的天气？”

这一能力非常关键，因为它直接决定 Agent 是否表现得像一个可用系统，而不只是一个偶尔能成功调用工具的演示原型。

八、第五步：把结构化结果转化为可用回答

工具返回的是结构化数据，但用户真正需要的是可执行、可理解的结论。

例如，当用户问：

“明天东京适合带伞吗？”

Agent 不应机械复述原始 JSON，而更适合输出类似结果：

明天东京多云转小雨，最高 21℃，降水概率 60%，建议携带雨具出门。

进一步还可以生成更场景化的表达：

如果明天有户外安排，建议准备轻便雨伞，以应对短时降雨。

这也是 Agent 与普通 API 调用的核心差异：工具负责取数，模型负责解释与表达。

九、为什么天气查询通常更适合 Function Calling

天气查询之所以特别适合 Function Calling，是因为它符合以下特点：

调用目标明确
参数结构稳定
返回值结构明确
不需要长链路推理

相比 ReAct，它通常有三个明显优势：

响应更快
减少不必要的思考文本生成。
参数更稳
更容易输出符合要求的结构化调用参数。
成本更低
可以减少额外 token 消耗。

因此，如果 Agent 的任务主要是“查天气、查库存、查订单、查价格”一类标准动作，Function Calling 通常会是更适合的第一选择。

十、从天气查询扩展到企业场景

天气查询只是一个教学案例，但它背后对应的，其实是一整类企业场景：

查库存
查工单状态
查订单进度
查客户信息
查会议室预订情况
查报销审批状态

这些问题与天气查询有一个共同点：

它们都不是让模型凭空生成答案，而是让模型先调用数据能力，再组织结果。

一旦天气查询这条链路被搭建清楚，企业通常就可以把同样的模式迁移到更多内部业务系统中。

十一、推荐的设计原则

在 Agent 工具调用设计中，一个非常实用的原则是：

让工具尽量结构化，让模型尽量少猜测。

具体来说，应尽量做到：

工具描述清晰
参数定义清晰
返回字段清晰
对实时信息场景明确要求“必须调用工具”
对缺失参数场景明确要求“先追问再调用”

这类基础设计，往往比单纯更换模型更能提升系统可靠性。

结语

以天气查询为例，Dify Agent 调用外部工具的完整链路可以被清晰地拆解为：

定义工具
接入 API
约束调用时机
处理参数补全
将结果组织为用户可理解的回答

这条链路的本质，不是让模型成为一个什么都知道的万能体，而是让模型在合适的时候调用外部能力。

对于企业而言，这种能力往往比“更会聊天”更重要。因为在真实业务中，更常见的需求不是“写一段更漂亮的话”，而是：

帮我查、帮我拿、帮我判断，并把结果整理成我可以直接使用的输出。

而这正是 Dify Agent 与工具调用最值得关注的价值所在。

日本企业常见 AI 需求场景盘点：客服、文档处理、社内知识检索与报告生成

如果从企业真实落地路径来看，多数组织在导入 AI 时，并不会一开始就以“通用 Agent 平台”作为目标。

更常见的情况是，企业首先看到的是一系列具体、重复、可衡量的问题：

客服与内部咨询压力过高
文档很多，但查找效率低
报告与摘要工作耗时过长
流程中仍然存在大量手工录入与人工判断

也正因为如此，企业对于 Dify 这类平台的需求，通常并不是抽象的“我要上 AI”，而是更具体地落在一个问题上：

能否优先解决那些高频、标准化、容易验证价值的业务环节。

本文将围绕五类最常见的企业需求，说明在日本企业语境中，哪些场景最容易出现，也最适合通过 Dify 这类平台切入。

一、客服与问答支持

客服与问答支持，是企业最容易量化 ROI 的 AI 场景之一。

常见问题

用户反复提出同类问题
客服团队被大量低复杂度咨询占满
夜间与非工作时段难以即时响应
不同人员的回答口径不一致

为什么这一场景常被优先建设

因为这一类场景通常具备以下特征：

重复度高
频率高
价值容易衡量
上线后效果容易被感知

一旦常见咨询被自动化处理，人工团队就可以将更多精力集中到复杂问题与高价值沟通上。

二、文档处理与知识提取

企业一旦真正开始建设 AI 应用，很快就会发现：组织里最常见的问题，并不是缺少模型，而是知识明明存在于文档中，却无法高效使用。

典型应用

合同信息提取
发票、请款单、申请表识别
长文摘要生成
文档分类与整理
条款比对与风险初筛

为什么这一场景需求普遍

一方面，企业内部通常积累了大量规范化文档；另一方面，正因为文档量大，人工查找、阅读与整理的成本也会显著增加。

因此，文档处理类 AI 应用，往往是组织在进入 AI 实践阶段后非常自然的一类需求。

三、社内知识检索

在很多企业中，知识检索往往是从试点进入正式运营阶段后最值得建设的能力之一。

前期组织可能会先建设聊天机器人，但很快会遇到一个更根本的问题：

组织内部的知识，是否能够被自然语言高效调用。

常见痛点

信息分散在 Drive、Wiki、文件夹、聊天记录与内部系统中
新员工无法快速找到制度、模板与历史资料
老员工通过经验回答问题，知识高度依赖个人
同一问题在多个部门中被重复询问

为什么这一能力非常关键

社内知识检索并不一定是最具展示性的 AI 应用，但通常是最容易真正嵌入业务流程的一类能力。

因为它解决的是组织协作中的基础问题：信息明明存在，但无法被及时、准确地调用。

对于文档规范程度较高、部门协作密集的企业而言，这一能力尤其重要。

四、报告生成与摘要自动化

在企业实际工作中，报告类文本仍然占据大量时间：

日报
周报
月报
会议纪要
市场调研摘要
竞品监测简报

常见问题

原始资料多，整理耗时
格式固定，但每次都需要重复编写
信息容易遗漏，风格不统一
管理层更需要结论，而不是原始材料

为什么这一场景适合 AI

报告类任务本质上往往是：

高结构化
低差异化
高重复性
可拆解为固定流程

因此，它天然适合通过 Workflow 进行自动化建设。企业不一定要求 AI 直接生成终稿，但通常非常期待它先形成一版可用初稿。

五、部门型效率工具

除了相对通用的场景之外，企业通常还会逐步进入更细分的部门型 AI 应用阶段。

例如

IT 与情报系统部门

内部支持机器人
操作手册问答
权限申请流程助手

这类场景的建设路径通常是：先从全公司都能理解的应用切入，再逐步深入到各部门的具体业务流程中。

六、企业在评估 AI 平台时通常会关心什么

除了“能做什么”，企业在评估 AI 平台时，通常还会特别关注以下问题：

5. 是否可以从单点场景扩展到平台化能力

这也是 Dify 这类平台受到广泛关注的重要原因之一：它既可以从简单问答切入，也可以逐步扩展到 Workflow、Agent 与多模型接入。

七、为什么这些场景适合 Dify

从以上需求可以看出，企业真正需要的通常不是一个单独模型，而是一层能够将 模型、知识、流程与工具调用 组织起来的应用层。

这正是 Dify 适合承接这类需求的原因。因为它能够用统一平台的方式，覆盖多种场景：

Chatbot：适合客服与 FAQ
Knowledge：适合制度、文档与知识检索
Workflow：适合报告生成、前置处理与信息汇总
Agent：适合查数据、调工具、执行动作

因此，对于企业而言，Dify 的意义并不只是“一个 AI 工具”，而更接近于一个可从试点逐步发展到正式能力建设的平台层。

八、更现实的导入顺序

如果观察企业的真实导入路径，通常更常见的顺序是：

先做 FAQ 或知识检索
再做文档处理与摘要
再做 Workflow 自动化
最后逐步扩展到 Agent 与跨系统调用

这是因为在第一阶段，企业最重视的通常是：

风险低
价值清晰
试点快速
业务部门能够参与

从这个角度看，客服、文档处理、社内知识检索与报告生成之所以成为高频需求，并不是偶然，而是因为它们正好位于企业 AI 落地最容易成功的起点上。

结语

从企业实践来看，高频需求并不一定是最具想象力的通用 Agent 叙事，而往往是那些最贴近日常业务的问题：

客服与问答支持
文档处理与信息提取
社内知识检索
报告生成与摘要自动化
部门型效率工具

这些场景之所以重要，是因为它们既有明确业务价值，也更容易形成可验证、可扩展的落地路径。

对多数企业而言，更有效的策略通常不是一开始就追求“全能 AI”，而是先把高频、重复、可标准化的任务做好，再逐步由点及面扩展。

而这，也正是 Dify 这类平台最适合发挥作用的地方：从一个具体业务场景开始，把 AI 逐步沉淀为组织内部真正可用的能力。

MCP（Model Context Protocol）是什么：为什么它让 AI 工具调用变得标准化

过去一段时间，MCP 成为 AI 领域讨论频率很高的关键词之一。它的重要性，并不在于第一次让模型具备工具调用能力，而在于它开始尝试用更统一的方式，定义模型与外部工具、数据源和业务系统之间的连接关系。

如果用一句话概括：

MCP 是一种让模型与工具之间的协作方式逐步标准化的协议。

它解决的核心问题不是“AI 能不能调用工具”，而是“不同模型、不同平台、不同工具之间，能否使用更一致的方式互相理解”。

一、在 MCP 之前，AI 工具调用的问题是什么

在 MCP 出现之前，AI 调工具当然可以实现，但实现方式往往非常碎片化。

常见情况包括：

一个模型接 Slack，需要一套单独方案
同一个模型接 Notion，又需要另一套方案
平台换掉后，工具接入方式往往也要跟着变化
模型升级或切换时，连接代码常常需要重新适配

这会带来几个直接问题：

每一个连接几乎都需要定制实现
工具数量越多，接入复杂度越高
更换模型或平台时，迁移成本明显增加
模型能力迭代很快，但连接层长期处于碎片化状态

很多团队真正遇到的瓶颈，并不在模型能力本身，而在模型与业务工具之间的连接层。

二、MCP 实际上在标准化什么

MCP 标准化的，并不是某一个具体工具，而是模型与工具之间的交互方式。

更具体地说，它试图回答这些问题：

模型如何知道一个工具能做什么
工具如何描述自身能力、参数与返回结构
模型如何发起调用
工具返回结果后，模型如何继续处理

在没有统一协议时，这些事情往往依赖每个平台、每个插件、每个开发者自己约定。MCP 的价值在于：

把原本散落在不同系统中的私有约定，拉回到一个更可通用的协议层。

三、为什么 MCP 常被类比为“AI 世界的 USB-C”

很多人会把 MCP 类比为 USB-C，这个比喻非常直观。

USB-C 的价值不在于它发明了显示器、键盘或硬盘，而在于它统一了连接方式，让不同设备之间的接入更容易形成标准。

MCP 在 AI 世界中的意义也类似：

它不是去发明邮件系统
不是去发明数据库
不是去发明搜索、文档与日历工具

而是让这些外部能力在面对模型时，可以更一致地描述自己、暴露自己并被调用。

从这个角度看，MCP 的真正意义不在某一个工具，而在整个连接生态的演进。

四、为什么 MCP 会让工具调用更标准化

工具调用是否真正“标准化”，关键不在于是否能调用，而在于调用行为是否足够可预期、可迁移、可复用。

MCP 的价值主要体现在以下四个方面。

1. 工具能力可以被更清晰地描述

一个工具如果想被模型调用，至少需要清楚说明：

它是什么
它能做什么
它需要哪些输入参数
它会返回什么样的结果

当这些信息能够通过统一方式表达时，模型与平台对工具的理解成本就会显著降低。

2. 模型与工具之间的耦合度下降

在过去，很多工具调用方式都强依赖具体平台。

今天可以在某个平台里使用，换到另一个平台就可能需要重新接入；今天某个模型可以调用，换模型后又需要单独适配。

协议一旦趋于统一，模型与工具之间的关系就更接近“通过标准接口协作”，而不是“彼此深度绑定”。

3. 工具接入逐步从工程问题转向配置问题

这并不意味着工程工作会消失，而是意味着很多过去必须依赖手写胶水代码的地方，未来可能越来越多地转化为：

描述工具能力
配置认证方式
设定调用边界
控制权限与行为

当连接成本下降时，真正重要的问题就会从“怎么接”转向“为什么接、接哪些、如何治理”。

4. 跨平台复用能力增强

如果一个工具通过 MCP 暴露能力，那么它的价值就不再局限于某一个平台内部使用，而有机会被多个支持 MCP 的系统接入。

这会改变整个生态的建设方式：

平台不再需要各自维护完全独立的插件体系，而可能通过协议层共享越来越多的能力。

五、MCP 对 Dify 这类平台意味着什么

对于 Dify 这类 AI 应用平台而言，MCP 的价值尤其明显。

因为 Dify 本身处在一个非常关键的位置：

一侧连接模型
一侧连接知识库、工作流、工具与业务系统

如果没有统一协议，平台往往需要依赖大量插件，或者为不同工具维护不同接法。而 MCP 带来的变化是：

Dify 构建出的应用能力可以进一步向外暴露
外部 MCP Server 也可以被接入到 Dify 的 Agent 或流程之中
工具调用开始从“平台私有能力”逐步转向“协议能力”

这使得 Dify 不只是应用构建平台，也更容易成为企业 AI 连接体系中的一部分。

六、MCP 与 API 的区别是什么

很多人在第一次接触 MCP 时，都会问：

“这和 API 有什么不同？”

两者相关，但并不相同。

MCP 更像是模型接入这些能力时的协作方式

它关注的是：

模型如何理解工具
工具如何向模型暴露能力
参数与返回结果如何被统一描述
整个调用过程如何被更一致地组织

因此可以这样理解：

API 是工具本身的能力暴露，MCP 是模型与工具之间更标准化的交互协议。

七、MCP 可能带来的变化

如果 MCP 继续发展，最直接的变化通常会体现在三个层面。

1. 模型竞争会部分转向连接能力竞争

未来比拼的可能不只是“哪个模型更强”，还包括：

谁更容易接企业系统
谁更容易调度外部能力
谁更适合成为工作流中的执行节点

2. AI 工具生态会更加模块化

模型、平台、工具与业务系统之间的边界会逐渐更清晰。

这意味着企业不必被迫完全绑定在某一个闭环产品中，而可以通过更灵活的方式组织能力。

3. 设计问题会比接线问题更重要

当连接方式越来越标准化后，真正拉开差距的，将不再只是“能不能接”，而是：

接哪些工具
在什么场景下调用
给模型多大权限
哪些步骤仍然保留人工控制

也就是说，AI 应用的重点会越来越从“技术接通”转向“工作流设计与治理设计”。

八、MCP 不是万能答案

当然，MCP 并不意味着一旦采用协议，所有问题都会自动消失。

它至少还受到以下现实条件制约：

工具侧是否真正按标准暴露能力
平台侧是否具备足够好的 MCP 支持能力
权限控制是否被设计清楚
企业是否愿意将关键系统接入这类开放式调用体系

此外，标准化并不等于安全，也不等于治理自动完成。

即使一个工具已经具备标准化调用方式，企业仍然必须明确：

谁可以调用
在什么场景下调用
可以读取什么、写入什么
调用失败时如何处理

因此，MCP 解决的是“连接方式标准化”的问题，而不是“所有接入风险自动消失”的问题。

结语

MCP 之所以值得关注，并不是因为它第一次让 AI 学会调用工具，而是因为它正在把原本高度私有化、一次性适配的连接模式，逐步推向更标准化的阶段。

从长期看，它的真正意义可能不只是“接得更快”，而是让整个 AI 生态更接近一套可组合系统：

模型负责理解与生成
工具负责能力执行
平台负责组织与治理
协议负责把它们更稳定地连接起来

这也是为什么 MCP 在今天格外重要。它不仅是一个技术名词，更是 AI 从“会聊天”走向“会接系统”的过程中，一个非常关键的基础层变化。

RAG 的核心问题：为什么知识库检索结果不准，从 chunk 策略到 embedding 模型选型

很多团队在建设 RAG 时，最先关注的通常是生成模型：

使用哪一个大模型回答
在哪个平台中搭建
提示词应该如何编写

但在正式运行后，最常见的问题往往不是“模型不会回答”，而是“系统根本没有检索到正确资料”。

换句话说，RAG 的核心问题通常不在生成端，而在检索端。

如果检索结果本身不准，那么后续模型越强，反而越容易在错误上下文之上生成看似合理、实际偏离的问题答案。

本文将围绕这一问题展开：为什么知识库检索结果经常不准，以及从 chunk 策略到 embedding 模型选型，企业在实践中应如何理解与处理。

一、为什么 RAG 经常表现“不准”

RAG 的理想流程通常是：

用户提问
→ 系统从知识库检索最相关内容
→ 模型基于这些内容生成回答

问题主要集中在第二步。现实中，检索不准通常有三种典型表现：

资料明明存在，却没有被检索到
检索命中了内容，但不是最关键的那一段
检索返回了很多片段，但噪音过多，反而降低回答质量

很多团队会把这些问题归因于“大模型不够稳定”，但实际更常见的原因通常包括：

文档切分方式不合理
数据清洗不足
用户提问与文档写法存在明显语义落差
embedding 模型与业务语料不匹配
检索参数没有根据场景进行调优

二、第一层问题：chunk 策略决定检索上限

RAG 的基础动作之一，是将长文档切分为多个 chunk，再对这些 chunk 进行向量化与检索。

问题在于，文档一旦被切开，原本属于完整上下文的语义关系就有可能被破坏。

一个典型例子

原始文档中的句子可能是：

“员工在入职满六个月后可获得 10 天年假。”

如果在切分后只保留：

“六个月后可获得 10 天”

这段话虽然还保留了部分信息，但在脱离上下文后，其真实含义已经变得模糊。它究竟是在描述年假、补贴、试用期还是培训安排，系统并不能自然判断。

这就是很多 RAG 系统最常见的第一类问题：信息仍然存在，但切分后语义不再完整。

三、chunk 不是越小越好，也不是越大越好

在很多实践中，团队容易形成一种直觉：把 chunk 切得更小，检索就会更精确。

但实际情况并不是这样简单。

chunk 太大的问题

噪音增加
多个主题被混在同一个片段中
检索虽然命中，但真正关键的信息被埋没在长段落之中

因此，chunk 策略的本质是在平衡两件事：

语义完整度
检索聚焦度

更合理的实践方式

不同文档类型，通常应该采用不同切分方式：

制度类文档：按条款或章节切分
FAQ 类文档：按问答对切分
合同类文档：按条款切分
产品文档：按功能点或主题切分

也就是说，更有效的 chunk 策略通常不是固定字数，而是基于文档语义结构进行切分。

四、第二层问题：提问方式与文档写法之间存在明显落差

RAG 不准的另一个常见原因，是用户问题与知识库文档在表达方式上的差异。

例如用户会直接提问：

“休假有几天？”
“这个能报吗？”
“台风时该注意什么？”

而文档中的表达方式则往往更加正式：

“年次有给休暇の付与日数”
“旅費精算規程第八条”
“災害時の行動基準”

用户提问通常更口语化、更模糊、更压缩；文档写法则更正式、更完整、更专业。即使语义相关，两者在向量空间中的距离也未必足够接近。

这也是为什么越来越多团队会引入 Query Rewrite、HyDE 等增强策略：

先把用户问题改写成更接近制度语言或文档语言的形式
再用改写后的查询进入检索

从本质上看，这类方法是在弥合“提问方式”与“文档写法”之间的落差。

五、第三层问题：数据质量通常比模型选择更重要

很多 RAG 系统之所以表现不稳定，并不是因为策略不高级，而是因为底层数据本身就不够干净。

常见问题包括：

同一内容上传了多个版本
旧版和新版制度混在一起
PDF 文字提取错误
OCR 扫描质量不稳定
一个文档中混入多个不相关主题
页眉页脚、页码、签章等噪音进入正文

在这种情况下，再好的 embedding 模型也只能对低质量数据进行向量化。

因此，一个非常重要的原则是：

RAG 的检索质量，首先取决于数据入口是否足够干净。

上传前的清洗、去重、版本控制与结构整理，往往比后期复杂调优更值得优先投入。

六、为什么 embedding 模型选型非常关键

在很多平台中，embedding 往往被视为一个默认组件，似乎只要有就足够使用。

但实际上，embedding 模型直接决定了系统如何理解“相似”。

因为向量检索的本质，不是关键词匹配，而是 embedding 模型如何把文本映射到语义空间。

这意味着什么

同一句话，在不同 embedding 模型中，可能会形成不同的语义邻近关系。例如：

有的模型更擅长英文技术语料
有的模型更适合日文或中文业务文本
有的模型更适合短句查询
有的模型在长文上下文压缩上更稳定

如果企业知识库主要是制度、合同、内部规范等业务语料，却选择了并不适合这类文本结构的 embedding 模型，那么检索不准就是非常自然的结果。

七、embedding 模型应该如何评估

在企业实践中，embedding 模型选型通常至少应考虑四个维度。

1. 语言匹配度

知识库主要是什么语言，用户主要用什么语言提问。

如果知识库与用户查询语言存在差异，就需要重点关注模型在跨语言语义对齐上的表现。

2. 文本类型匹配度

是 FAQ、制度、合同、产品文档还是资讯文本，不同语料类型通常对应不同表现特点。

4. 成本与速度

企业正式上线时，还需要考虑：

建库成本
重建索引成本
检索响应速度
是否支持本地或私有化部署

因此，embedding 模型选型不应只看“哪个最先进”，而应重点看“哪个最适合当前业务语料与实际部署条件”。

八、为什么单纯更换大模型通常无法解决 RAG 问题

当团队发现 RAG 表现不佳时，常见第一反应是更换更强的生成模型。

但如果检索拿到的上下文本身就不准确，那么再强的生成模型也无法从根本上解决问题。它能做的通常只有以下几种：

基于错误上下文生成错误答案
在噪音过多的上下文中生成偏离重点的答案
在资料不足时，用常识进行补全

这也是为什么在实际建设中，更推荐按照以下顺序优化：

数据清洗
chunk 设计
查询改写或检索增强
embedding 模型评估
最后再优化生成模型与提示词

九、一个更现实的优化顺序

如果企业正在建设内部 RAG 系统，建议优先按以下顺序排查问题。

第一步：检查数据质量

是否存在重复文档
是否混入旧版资料
PDF 是否可稳定提取文本
内容是否按主题合理拆分

第二步：检查 chunk 策略

是否按语义结构而不是纯字数切分
是否存在上下文被切断的问题
是否出现一个 chunk 覆盖多个主题

第三步：检查查询方式

用户问题是否口语化、模糊化
是否需要 Query Rewrite 或 HyDE
多轮对话中是否需要做指代消解

第四步：检查 embedding 模型

是否适合当前语言
是否适合当前文档类型
是否做过实际对比测试，而不是直接使用默认选项

十、RAG 的本质不是“把资料塞进去”

很多人会把 RAG 理解为：

“只要把公司资料上传进去，AI 就会懂。”

但从系统角度看，RAG 更接近一套检索系统，生成模型只是这套系统的最后一层表达能力。

它的关键并不是“记住多少”，而是：

在正确的时机
从正确的位置
找到正确的上下文
再交给模型进行组织与输出

因此，RAG 的核心从来不是“有没有知识库”，而是“检索系统是否真正理解你的文档结构和用户问题”。

结语

知识库检索结果不准，通常不是单一问题，而是多个层面叠加的结果：

chunk 切分方式不合理
数据质量不足
用户提问与文档表达差距过大
embedding 模型与语料不匹配
检索参数未围绕业务场景调优

所以，RAG 的核心问题并不是“怎么让模型更会回答”，而是：

怎么让系统先找到真正应该被回答的内容。

一旦把这一顺序理清，很多原本看起来像“模型不够聪明”的问题，都会被还原为更具体、也更适合被解决的检索工程问题。

提示词工程的误区：日本企业最常见的 3 种写法错误

在多数企业开始导入 AI 应用时，提示词通常是最先被学习、也是最容易立刻产生结果的部分。

这很正常。提示词门槛低、反馈快、修改成本也相对较低，因此常常成为团队接触 AI 的第一入口。

但在真实业务环境中，问题也往往从这里开始出现：

很多企业把提示词当作万能解法。

结果是，原本属于流程设计、知识组织、权限控制或系统结构的问题，被持续压到提示词层解决。最终不仅输出效果不稳定，也会让团队误以为“AI 就是不可靠”。

如果从企业导入场景来看，最常见的误区并不是“不知道怎么写提示词”，而是“让提示词承担了不属于它的责任”。

下面结合企业常见实践，归纳三类最典型的写法错误。

误区一：把所有要求都堆进一个超长提示词

这是最常见的一类错误。

常见写法通常会包含：

角色定义
十几条规则说明
大段业务背景
输出格式要求
风险提示
真实性要求
最后才给出真实任务

看起来非常完整，但在实际使用中往往问题很多。

为什么这是一个问题

1. 多种责任被混在一起

提示词中同时承担了：

业务规则说明
流程控制逻辑
数据背景补充
格式约束
风险治理要求

这些原本就不应全部交给一段提示词来处理。

2. 可维护性会快速下降

一旦业务变化，团队很难判断该改哪一段内容。最终提示词会越写越长，直到无人愿意继续维护。

3. 长提示词并不等于高质量设计

提示词越长，只代表塞入的信息越多，并不意味着结构更清晰。很多时候，长提示词只是让规则彼此冲突、边界更加模糊。

更适合的做法

在正式业务场景中，更推荐将不同责任拆到不同层次：

业务知识交给知识库
流程控制交给 Workflow
工具调用交给 Agent 或 Tool 层
输出格式单独约束
提示词只负责当前节点该完成的任务

也就是说，提示词应该是系统中的一个部件，而不是整套系统本身。

误区二：把“业务知识缺失”误判为“提示词不够强”

这是企业中非常高频的一类误判。

当 AI 回答不准确时，很多团队的第一反应通常是：

“是不是提示词没写清楚？”
“再补一条规则试试？”
“再强调一次不要乱说？”

但在实际项目中，更常见的真实原因是：系统本身没有拿到足够准确、足够完整的业务知识。

典型表现

例如：

企业制度没有被整理进知识库
上传文档版本混乱
检索没有命中真正相关内容
PDF 文本提取质量较差
问题本身依赖实时数据，但系统并未接入对应工具

在这种情况下，无论如何修改提示词，模型仍然只能在知识不足的前提下继续“猜测”。

为什么这是一个结构性问题

提示词可以约束模型如何表达，但无法替代知识本身。

如果上下文本身是错的、缺的或脏的，那么再精心设计提示词，也只是在错误基础上做局部修饰。

更适合的做法

当结果不理想时，应先判断问题究竟发生在哪一层：

是知识库没有命中？
是检索策略存在问题？
是数据本身不完整？
还是输出表达层需要优化？

很多企业在这一点上投入了大量无效时间：本应去清洗文档、重做 chunk、优化检索，却持续在提示词层反复调试。

因此，第二个核心误区是：

把系统层问题，误当成提示词层问题。

误区三：只写“请准确、专业、简洁”，却不给出可执行边界

很多企业的提示词都会出现类似表达：

请准确回答
请专业说明
请简洁明了
请不要编造
请站在企业视角作答

这些要求本身没有问题，但往往缺少真正可执行的边界。

为什么这仍然不够

因为“准确”“专业”“简洁”都属于抽象要求。

对于模型来说，真正关键的是：

回答依据来自哪里
什么情况下必须拒答
什么情况下必须追问
输出必须满足什么结构
可以总结到什么程度
不允许跨越哪些边界

如果这些边界没有说明，模型只能自行理解“专业”的含义，而这种理解未必符合企业要求。

一个典型例子

很多企业会写：

“请基于公司资料回答，不要乱说。”

但通常不会进一步说明：

如果资料不足应该怎么办
如果资料之间相互冲突应该怎么办
如果问题超出权限范围应该怎么办
如果涉及审批、法务或个案判断应该怎么办

结果就是，模型有时过度保守，有时又会继续推断，回答风格与边界很难保持一致。

更适合的做法

在企业场景中，应将抽象要求改写为明确规则，例如：

仅基于提供的参考资料回答
若资料中无明确依据，必须明确说明“当前资料未提供足够信息”
不得根据常识补全企业制度
输出统一采用“结论 / 依据 / 建议动作”的结构
遇到审批、法务或个案判断时，必须建议人工处理

当边界被写成可执行规则时，模型的行为才更容易稳定下来。

为什么这些错误在企业环境中特别常见

这三类问题高频出现，并不是因为企业不重视提示词，恰恰相反，是因为企业太容易把提示词视为最低成本的控制手段。

对企业来说，修改提示词通常意味着：

不需要调整系统架构
不需要重新清洗数据
不需要重做工作流
不需要重新接外部系统

因此，很多问题都会被优先推到提示词层解决。

但在业务真正跑起来后，团队会逐渐意识到：

提示词确实重要
但提示词只能解决它本应负责的那部分问题

当提示词被迫承担知识结构、流程设计、权限控制与治理边界这些职责时，问题通常只会越来越复杂。

一个更成熟的理解方式：从 Prompt Engineering 走向系统设计

企业在 AI 使用过程中，通常会经历一个认知转变。

更成熟的阶段则会问：

“哪些问题本来就不该由提示词解决？”

在正式项目中，更推荐从系统层面理解 AI 应用，至少拆分为以下几个层次：

Prompt 层：约束当前节点行为
Knowledge 层：提供业务依据
Workflow 层：组织流程与状态
Tool 层：接入实时能力与执行动作
Governance 层：控制权限、边界与审计

一旦按照这样的方式来理解，许多原本堆积在提示词中的混乱问题，就会自然被拆解开来。

给企业的一个简明检查表

如果团队怀疑当前提示词设计已经出现问题，可以快速做一次自查。

如果出现以下现象，就值得警惕

提示词不断加长，规则越来越多
同时描述业务知识、流程逻辑与输出格式
回答不准时，只会继续补提示词
无法区分系统问题与提示词问题
抽象要求很多，可执行规则很少

更有效的判断方式，是先问自己三个问题

这个问题真的应该由提示词解决吗？
还是更应该由知识库、工作流或工具层承担？
当前提示词中，是否已经明确了可执行、可验证的边界？

结语

提示词工程当然重要，但企业最常见的问题并不是“不会写提示词”，而是“让提示词承担了过多本不属于它的工作”。

最典型的三类错误，本质上都指向同一个问题：

把系统设计问题，压缩成了提示词写作问题。

因此，更成熟的提示词实践并不是让提示词不断变长，而是让系统职责不断变清晰：

该由提示词承担的，写清楚
不该由提示词承担的，交给知识、流程与治理层处理

当企业做到这一点时，提示词才会真正从“反复试错的写法技巧”转变为“稳定系统中的明确指令”。

AI Agent 的局限性：哪些任务不适合交给 Agent 做

AI Agent 很容易让人形成一种直观印象：只要给出目标，它就可以自己理解任务、自己调用工具、自己执行流程，并最终完成工作。

这种想象并不完全错误。Agent 在某些场景中确实非常有价值，尤其适合需要调用外部工具、处理多步任务、允许一定动态决策的工作。

但一旦进入真实业务，就必须首先承认一个前提：

Agent 不是万能执行体，而是一种只适用于特定任务结构的系统形态。

如果任务本身并不适合 Agent，越强调其“自主性”，风险通常越高。

本文将围绕这一点展开，说明哪些任务不适合交给 Agent，以及企业在设计 Agent 时应优先关注哪些边界。

一、先明确：Agent 更擅长处理什么任务

在讨论局限性之前，首先需要明确 Agent 的适用边界。

通常来说，Agent 更适合以下类型的任务：

目标明确，但过程路径可以动态选择
需要调用外部工具或系统
允许一定程度的试错与迭代
对过程完全固定的要求不高
最终结果存在合理范围，而不是唯一标准答案

例如：

搜集资料并整理
查询多个系统后生成摘要
调用工具完成标准动作
在开放信息环境中执行探索性任务

但在企业实践中，常见问题恰恰在于：很多并不属于这一类的任务，也被误交给 Agent 处理。

二、不适合交给 Agent 的第一类任务：高确定性、低容错任务

如果一个任务要求：

每一步都必须严格正确
流程必须完全可预测
一旦出错，后果明显且代价较高

那么它通常不适合直接交给 Agent。

典型场景

财务结算
付款审批
合同最终审定
生产控制指令
权限变更与账号开通
法务、合规、审计中的关键决策动作

为什么不适合

Agent 的本质，是在一定目标约束下进行自主决策。这意味着它天然会带来：

路径不完全固定
调用顺序可能变化
对模糊输入的解释存在差异
对异常情况的处理存在不确定性

而对于高确定性任务来说，组织真正需要的通常不是“自主完成”，而是“按规定准确执行”。

这类任务通常更适合：

固定 Workflow
明确规则引擎
人工审核节点
严格状态机控制

也就是说，越是容错空间极低的任务，越不应将控制权大量交给 Agent。

三、不适合交给 Agent 的第二类任务：责任边界不清的任务

企业中还有一类任务，看起来适合让 Agent 自主处理，但实际上风险更高——那就是责任边界并不明确的任务。

例如

判断某份合同是否可以签署
判断某个客户是否可以特殊放款
判断某项制度是否适用于特殊个案
决定是否允许越权审批
决定内部争议应如何处理

为什么这类任务风险高

因为它们往往不是简单的信息检索或动作执行问题，而是涉及：

权责划分
情境判断
规则解释
风险承担主体

一旦让 Agent 直接做出这类决定，问题不仅在于其判断是否准确，更在于：

最终结果应由谁承担责任。

因此，凡是需要明确责任归属、需要人工签字或需要组织背书的任务，都不适合完全交给 Agent 处理。

四、不适合交给 Agent 的第三类任务：目标本身高度模糊的任务

很多人会认为 Agent 擅长处理模糊任务，但更准确地说，Agent 擅长的是“目标清楚、路径开放”的任务，而不是“目标本身不清楚”的任务。

例如

“帮我把这件事处理好”
“看看这里有什么问题”
“帮我优化一下”
“你自己想办法完成”

这类输入的问题，不是执行能力不够，而是任务定义本身就不完整。

为什么不适合

当目标模糊时，Agent 很容易在没有明确约束的情况下自行补全任务理解。这会导致：

目标被误读
执行范围被扩大
结果看似积极，但方向可能已经偏离

因此，在这类场景中，更合理的做法通常不是直接放权，而是先让系统：

追问目标
澄清范围
确认约束条件
明确成功标准

换句话说，模糊目标并不是 Agent 的天然优势，反而常常是其最容易失控的起点。

五、不适合交给 Agent 的第四类任务：要求强可解释性的任务

有些业务场景并不是不能接受错误，而是不能接受“说不清为什么做出这个结果”。

为什么不适合直接依赖 Agent

Agent 虽然可以保留部分执行日志，但在多轮推理、多工具调用、多步判断之后，真正导致某个结果的完整链路往往并不总是足够稳定、足够清晰。

而在高可解释性场景中，企业通常更需要的是：

每一步依据清楚
规则边界清楚
数据来源清楚
最终责任清楚

这类任务通常更适合：

固定推理链
强制引用依据
结构化输出
严格的人机协同流程

也就是说，如果“可解释性”比“执行灵活性”更重要，那么 Agent 往往不是首选形态。

六、不适合交给 Agent 的第五类任务：核心系统控制任务

Agent 很适合帮助企业“调工具”，但这并不意味着应该直接赋予它核心系统的高权限控制能力。

为什么风险更高

Agent 的一个核心特征，是它会根据上下文自主判断下一步动作。这意味着，一旦权限过大，它不仅可能“调错工具”，还可能“在正确工具上执行错误动作”。

因此，在核心系统场景中，Agent 更适合承担：

读取信息
提供建议
生成草稿
准备操作计划

而不适合承担：

直接执行不可逆操作
持有过高权限
在没有人工确认的前提下写回关键系统

七、为什么企业容易高估 Agent

企业之所以容易对 Agent 形成过高预期，通常来自以下几个原因。

1. 被“自主完成任务”的叙事吸引

“只要告诉它目标，它就能自己完成”这类表达非常有吸引力，但往往会弱化边界设计的重要性。

3. 把模型能力高估为系统能力

模型会说、会推理，并不意味着整个系统就具备稳定执行复杂业务的能力。

企业中的真实系统通常同时涉及：

数据
权限
流程
工具
审计
异常处理

Agent 只是这套系统中的一种执行方式，而不是整个系统本身。

八、一个更实用的判断标准

如果团队正在判断某项任务是否适合交给 Agent，可以先问以下五个问题：

这个任务允许一定试错吗？
这个任务的成功标准是否足够明确？
即使执行路径发生变化，结果仍然可接受吗？
出错后果是否可逆、可控？
是否可以把执行权限控制在安全范围内？

如果其中多个问题的答案是否定的，那么这项任务通常不适合由 Agent 主导执行。

九、更成熟的做法：让 Agent 只承担它擅长的部分

这并不意味着 Agent 没有价值。恰恰相反，Agent 的价值非常明确，只是更适合承担它真正擅长的部分，例如：

检索
协调
调工具
起草
汇总
提供建议

而不应轻易扩展到：

最终决定
高风险执行
权责判断
不可逆操作

在成熟企业系统中，更常见、也更合理的方式是：

让 Agent 负责前半段的信息获取、工具调用与建议生成，再把高风险决策与最终执行交给人工或固定流程兜底。

结语

AI Agent 的局限性，并不主要在于模型“不够聪明”，而在于很多任务从结构上就不适合被交给一个具有自主性的执行体。

最不适合交给 Agent 的，通常包括以下几类任务：

高确定性、低容错任务
责任边界不清的任务
目标高度模糊的任务
强可解释性任务
核心系统控制任务

因此，真正成熟的 Agent 设计，不是“尽可能让它什么都做”，而是：

先判断任务结构是否适合 Agent，再决定自主程度与权限边界。

只有这样，Agent 才更有可能成为企业系统中的效率放大器，而不是新的不确定性来源。

on-premise 部署 AI 应用的必要性：数据主权、合规与网络隔离的实际考量

在 AI 应用建设初期，很多团队都会优先选择 SaaS 方案。这是非常自然的路径，因为 SaaS 通常具备以下优势：

启动速度快
部署成本低
试用门槛低
更适合 PoC 和早期验证

但一旦 AI 应用进入正式业务阶段，组织通常很快会面对一个更实际的问题：

这些数据、这些流程、这些系统连接，是否适合长期运行在公共托管环境中。

这正是 on-premise（本地部署 / 私有部署）开始成为企业正式议题的原因。

本文不讨论“本地部署是否更先进”，而聚焦于更现实的判断标准：为什么企业在某些场景中，必须认真考虑 on-premise 部署 AI 应用。

一、on-premise 的本质不是“更重”，而是“更可控”

很多人第一次接触 on-premise 时，往往会把它直接理解为：

更复杂
更昂贵
更难维护
更适合大型企业

这些印象并不完全错误，但它们只是表面。

企业真正考虑 on-premise，通常并不是出于技术偏好，而是出于控制边界的需要。更准确地说，企业通常是为了控制以下三个边界：

数据边界
合规边界
网络边界

如果这些边界对业务而言足够重要，那么部署方式本身就不再只是技术选择，而会成为治理选择。

二、第一个核心原因：数据主权

AI 应用一旦进入企业场景，接触到的通常不只是公开文本，而是组织内部最真实、最敏感的数据资产。例如：

内部制度与知识文档
合同与法务资料
客户信息
财务数据
销售记录
研发资料
审计与风控文件

当这些内容进入 AI 工作流后，企业自然会提出一个问题：

这些数据究竟存放在哪里，谁能控制，谁能访问，谁能决定其流向。

为什么这会演变为数据主权问题

因为对多数企业而言，AI 已经不再只是一个聊天工具，而是在逐步成为读取、处理、整合核心经营信息的能力层。

在这种情况下，组织通常会非常关注：

数据是否停留在指定环境内
是否经过外部托管
是否可能发生跨区域处理
是否可以完全掌握访问与存储控制权

当这些要求足够强时，本地部署或私有部署就不再只是加分项，而可能成为前提条件。

三、第二个核心原因：合规要求通常不能后置处理

很多 AI 项目在试点阶段推进顺利，但一旦准备进入正式部署，就会被合规与安全审查卡住。

常见问题包括：

数据是否会离开公司指定区域
是否符合行业监管要求
是否满足审计留痕要求
是否满足客户合同中的数据处理约束
是否允许内部资料进入外部服务环境

对于某些行业来说，这些问题不是优化项，而是准入门槛。

特别容易受到合规要求影响的场景

金融
医疗
制造业核心研发
公共部门
大型集团企业
涉及客户敏感信息的 B2B 服务

在这些环境下，即使 SaaS 功能非常完整，如果无法满足合规要求，也很难真正进入正式业务系统。

为什么 on-premise 更容易满足一部分合规要求

这并不是因为本地部署天然更安全，而是因为它通常让企业拥有更多可证明、可配置的控制能力，例如：

数据路径更清晰
访问控制更可控
审计链路更容易定义
与现有安全架构更容易集成
不必额外解释数据出域问题

换句话说，on-premise 的价值在于：它让企业更容易把安全与合规要求直接落实到运行环境中。

四、第三个核心原因：网络隔离并不是少数场景

很多 AI 讨论默认的前提是：

系统可以稳定联网
外部 API 可以持续访问
云服务依赖是合理且默认的

但现实并不总是如此。很多企业内部环境对网络有非常明确的约束，例如：

内网与外网隔离
生产网与办公网隔离
研发环境不允许直接访问公网
高敏感系统禁止外部直连

在这样的环境中，即使业务非常希望引入 AI，也不能简单地把公共 SaaS 方案直接接入关键系统。

这时 on-premise 的意义非常直接

它可以让 AI 应用在企业现有网络结构中自然运行，例如：

部署在企业内网
访问本地文档系统
连接内部数据库
接入既有身份认证体系
在网络隔离环境中稳定工作

也就是说，on-premise 的价值不只是“数据不出企业”，还包括：

让 AI 应用能够真正嵌入企业当前的网络现实。

五、为什么很多企业会从 SaaS 试点走向私有部署

在企业实践中，一个非常常见的路径是：

先使用 SaaS 做 PoC
验证业务价值
开始接入真实业务数据
安全、法务、信息系统部门正式介入
最终转向私有部署或混合部署

这并不矛盾，反而是非常合理的演进路径。

SaaS 更适合验证需求，而 on-premise 更适合承接正式业务。

因此，企业真正需要思考的通常不是“只选一种模式”，而是：

哪个阶段适合 SaaS
哪个阶段必须转向私有部署
哪些数据可以进入公共环境
哪些数据必须保留在本地边界内

从这个角度看，部署方式更应该被理解为一条演进路径，而不是一次性决策。

六、on-premise 的代价也必须被正视

当然，on-premise 并不是零代价方案。

企业之所以不会一开始全面采用私有部署，原因就在于它确实更重。

常见代价包括

需要自行搭建和维护基础设施
需要处理版本升级
需要做监控与故障处理
需要完成备份、权限、网络与审计配置
需要更多工程与运维资源

因此，真正的问题从来不是：

“本地部署是否更好？”

而是：

“当前业务场景对边界控制的要求，是否已经高到足以支撑这些额外成本？”

如果答案是肯定的，那么 on-premise 就是必要投入；如果答案还是否定的，先采用 SaaS 验证价值通常会更高效。

七、哪些场景更适合优先考虑 on-premise

以下几类场景，通常更值得优先评估本地部署或私有部署。

2. 应用需要接入多个内网系统

如果关键能力依赖企业内部数据库、文件系统与业务系统，而这些系统本来就不能出网，那么本地部署会更自然。

5. 组织希望把 AI 建设为长期基础设施

如果目标不是单点工具，而是企业级 AI 应用底座，那么部署可控性的重要性通常会持续上升。

八、一个更现实的判断框架

企业在评估是否需要 on-premise 时，可以优先回答五个问题：

这个 AI 应用将处理哪些级别的数据？
这些数据是否允许进入外部托管环境？
这个应用是否必须接入内网系统？
当前行业监管或客户合同是否存在明确约束？
这个系统的目标是短期试点，还是长期运行？

如果这些问题中，有多个答案指向高敏感、高约束、高长期性，那么 on-premise 往往就不再只是增强选项，而更可能成为正式上线前提。

九、对 AI 平台而言，支持 on-premise 意味着什么

对于 Dify 这类企业 AI 平台而言，是否支持本地部署非常关键。

因为企业真正需要的，不只是“能否做出一个 AI 应用”，而是：

能否在自己的边界内运行
能否与既有系统稳定连接
能否满足治理要求
能否从试点平滑演进到平台化建设

如果一个平台只能在公共云中运行，那么它能够覆盖的企业场景天然会受限。相反，如果平台同时支持 SaaS 与私有部署，企业就可以根据不同阶段与不同数据级别，选择更合适的建设路径。

结语

on-premise 部署 AI 应用的必要性，最终都指向一个问题：

企业是否需要真正掌控 AI 应用所处的运行边界。

这背后的关键考量，通常并不是技术偏好，而是三类非常现实的要求：

数据主权
合规要求
网络隔离

在试点阶段，SaaS 往往已经足够；但当 AI 开始接触核心知识、核心流程与核心系统时，本地部署通常就不再只是“更稳妥的选项”，而可能成为“是否能够正式落地”的基础条件。

因此，是否需要 on-premise，不应只由技术团队单独判断，而应由业务价值、数据敏感度与治理要求共同决定。

phase-2

本阶段按与 phase-1 相同的目录方式组织，聚焦 Dify 协会 Members Only 内容。

phase-2 公开资料候选索引

说明：以下是与该阶段各主题相关的公开资料候选。优先保留 note.com、zenn.dev、Dify 官方文档、Enterprise 文档与其他日文页面。

phase-2/2-1/01-制造业设备故障排查机器人.md

检索词：Dify 製造業設備故障 RAG
note 命中：4
站点搜索命中：2

note.com 候选

リコー「H.D.E.E.N」が示す暗黙知AI化の本質：4,500エージェントの実績が教える段階的実装の成功法則 | https://note.com/shin48ya/n/n14d3ec2acaf5
英単語/熟語リスト＜TOEIC 600＞#1-1 | https://note.com/ginjib/n/nd373bdd52c80
英単語/熟語リスト＜TOEIC 600＞#2-1 | https://note.com/ginjib/n/ne592d080cccd
【ChatGPTによる和訳】Rocket Lab USA, Inc. (NASDAQ:RKLB) Q4 2024 Earnings Call Transcript | https://note.com/american_stock/n/n21a7d6d00ca2

zenn.dev / 官方文档 / 其他日文页面

ローカルLLMの実用性が爆上げ：オフライン環境でも使える … | https://zenn.dev/taku_sid/articles/20250402_local_llm
Developers Summit 2026 Day2, 3 公開資料・Xアカウント … | https://zenn.dev/h_yoshikawa0724/articles/2026-02-22-developers-summit-2026

phase-2/2-1/02-法务合同比对-Workflow.md

检索词：Dify 契約書 workflow human in the loop
note 命中：6
站点搜索命中：8

note.com 候选

Human-in-the-Loopの活用事例　Difyでの具体的な運用パターン9選 | https://note.com/nocode_solutions/n/n91655a876f4d
生成AIをツールから習慣へ。Berkeley Lawのエグゼクティブ講座で再起動します。From Tool to Habit: Rebooting with Berkeley Law’s GenAI Executive Program. | https://note.com/ishii_jumpei/n/n6683a7454a76
『エージェンティック AI』：DXデイリーワード | https://note.com/kitorhythm/n/n2a9d9bab6361
イスラム教に搾取される日本人と苦悩の人生を歩む被害者 Japanese exploited by Islam and victims walking a life of suffering. Englsih after Japanese | https://note.com/aideepdown/n/n32e0b25bbd48

zenn.dev / 官方文档 / 其他日文页面

Human-in-the-Loopの活用事例 Difyでの具体的な運用 … | https://zenn.dev/nocodesolutions/articles/62a03c6770b824
Human-in-the-Loopの概念をDifyに落とし込み、AIの暴走を … | https://zenn.dev/nocodesolutions/articles/df0d883c7d1f79
AI AgentとKG：L5エージェントを実現する知識基盤 | https://zenn.dev/knowledge_graph/books/knowledge-graph-llm-guide/viewer/kg-and-ai-agents
Dify チャットフローを AI が生成する仕組みを AI で作った話 | https://zenn.dev/ryoyoshii/articles/05d2ffe846f518
Build Appで作る業務効率化AI【実例5選】 | https://zenn.dev/unikoukokun/articles/621ab7ed081242

phase-2/2-1/03-社内稟議自动草稿生成.md

检索词：Dify 稟議生成構造化出力
note 命中：0
站点搜索命中：4

zenn.dev / 官方文档 / 其他日文页面

2025/04/01付近に発売されたDify本4冊の比較 | https://zenn.dev/arrowkato/articles/dify_book_comparison
「AIエージェント」開発について | https://zenn.dev/headwaters/articles/fec5638eab414e
2025 AI Agentの現況と課題（勉強会資料） | https://zenn.dev/fl4tlin3/articles/abc18da303dddc
Developers Summit 2026 Day2, 3 公開資料・Xアカウント … | https://zenn.dev/h_yoshikawa0724/articles/2026-02-22-developers-summit-2026

phase-2/2-1/04-多语言客服-Agent.md

检索词：Dify 多言語カスタマーサポート Agent
note 命中：6
站点搜索命中：8

note.com 候选

n8nでできること完全ガイド｜業務自動化×AI連携を実践例でわかる | https://note.com/weel_media/n/n17758fb2a49c
AIエージェント開発フリーランス需要109%増2026年Q1：Lancers×クラウドワークスで今月受注できる高単価AI案件5種と月収15万円への90日ロードマップ | https://note.com/shiodome_098/n/nb86da4189390
AIエージェントで問い合わせ対応を自動化｜24時間対応を実現する方法 | https://note.com/tateru_ai/n/n919b556b609f
AIエージェントの業務活用事例10選｜中小企業の導入パターン | https://note.com/tateru_ai/n/ndfc110d90da9

zenn.dev / 官方文档 / 其他日文页面

知識ベースを使用したカスタマーサービスボット | https://docs.dify.ai/ja/use-dify/tutorials/customer-service-bot
エージェント | https://docs.dify.ai/ja/use-dify/nodes/agent
AIエージェントのみでBPO 企業を作り上げる方法：Dify+Ollama … | https://zenn.dev/ippeisuzuki/articles/71971d747c101b
Dify の基礎基本まとめ〜ノーコードで LLM アプリを開発する〜 ✨ | https://zenn.dev/okikusan/articles/e0ac79e54d1ab0
Difyを使ってLeSS用語回答Bot（RAG）を実現 | https://zenn.dev/bm_sms/articles/bce457fbc281ce

phase-2/2-1/05-HR-入职文件处理流水线.md

检索词：Dify 人事書類 PDF 自動化
note 命中：6
站点搜索命中：8

note.com 候选

ノーコードでAIエージェントを作る全手順〜月10万円の副業につなげた実例付き〜 | https://note.com/ample_swan1803/n/n7e54530c77c0
「LLMでDXしたい」と言う前に知っておくべき全体像。JTC→コンサル→スタートアップといろんなDXを見てきたワイが整理する | https://note.com/haisupena/n/n9b6ca8024c5f
生成AIワークフローの実践：AIの真骨頂である「業務の自動化」に踏み出す｜第5章 | https://note.com/dxcj/n/nd67a14989562
【初心者向け】チャットボットと何が違う？　自律的に働く「AIエージェント」徹底解説　導入から活用まで | https://note.com/tomohiko_naba/n/n22d374696739

zenn.dev / 官方文档 / 其他日文页面

Azure AI Document IntelligenceのOCR機能を使ってPDFを … | https://zenn.dev/solvio/articles/9d9643ec24dd96
Human-in-the-Loopの活用事例 Difyでの具体的な運用 … | https://zenn.dev/nocodesolutions/articles/62a03c6770b824
【Dify】ナレッジパイプライン調査レポート2/3 - 文脈を理解した「 … | https://zenn.dev/upgradetech/articles/fa118f1eba541c
専用教科書！ナレッジベースを作りましょう！ | https://zenn.dev/hamaup/books/6c09e513a52bdc/viewer/fef868
（ノード）知識検索ノード：ナレッジの取得 → RAG｜Dify完全ガイド | https://zenn.dev/kentaichimura/books/e48a042e40c657/viewer/147487

phase-2/2-2/01-知识库检索结果不相关.md

检索词：Dify ナレッジ検索 TopK Score Threshold Rerank
note 命中：0
站点搜索命中：7

zenn.dev / 官方文档 / 其他日文页面

【Dify】RAG大全：仕組みと設定を徹底解説 | https://zenn.dev/upgradetech/articles/ac9099a6489abe
ハイブリッド検索 | 日本語 | https://legacy-docs.dify.ai/ja-jp/learn-more/extended-reading/retrieval-augment/hybrid-search
チャンク / インデックス / 検索方法 / ReRank / メタデータ | https://zenn.dev/kentaichimura/books/e48a042e40c657/viewer/2fbfb4
インデックス方法と検索設定を指定 | https://docs.dify.ai/ja/use-dify/knowledge/create-knowledge/setting-indexing-methods
Rerank | 日本語 | https://legacy-docs.dify.ai/ja-jp/learn-more/extended-reading/retrieval-augment/rerank

phase-2/2-2/02-Workflow-节点超时频繁.md

检索词：Dify Workflow タイムアウトリトライ非同期
note 命中：1
站点搜索命中：1

note.com 候选

Dify API workflowディレクトリ | https://note.com/aoyama_sys/n/nbd50dac8bce9

zenn.dev / 官方文档 / 其他日文页面

Flaky Test におけるパイプラインの再実行 max_auto_reruns … | https://zenn.dev/kameoncloud/articles/0182e15840a92d

phase-2/2-2/03-同一问题每次回答不一致.md

检索词：Dify Temperature プロンプト出力安定
note 命中：6
站点搜索命中：8

note.com 候选

第2回：【Dify】ReActとFunction Callingの技術的差異と使い分け | https://note.com/niti_technology/n/n46032ff32cc1
【第7回ローカルLLM】AIを「システム」から「ツール」へ：全社員が直感操作できるWeb UIの作り方 | https://note.com/eques_ai_/n/n9849da7e4bf4
【2026年最新】AITuber・AIキャラクター作成ツール完全まとめ ── 配信ツールからチャットAI、PNGtuberまで全部紹介 | https://note.com/95inari/n/n835d61feb479
AIに「忖度」をさせない：合議制プロトコルによるAI意思決定の構造改革 | https://note.com/dear_quokka1974/n/n1fc07218f675

zenn.dev / 官方文档 / 其他日文页面

LLM | 日本語 | https://legacy-docs.dify.ai/ja-jp/guides/workflow/node/llm
Dify × Claudeでつくる、2分週報AI | https://zenn.dev/deepflowdesign/articles/dify-claude-weekly-report-ai
AIエージェントフレームワーク実装比較 | https://zenn.dev/dalab/articles/770a39a24c1940
現場で使える！Dify x Pythonハイブリッド開発実践！ | https://zenn.dev/sapeet/articles/edfee5b30d79a8
（基礎知識）AIエージェントの基本：Function Calling / ReAct | https://zenn.dev/kentaichimura/books/e48a042e40c657/viewer/395147

phase-2/2-2/04-大文件上传失败.md

检索词：Dify PDF アップロード大容量失敗
note 命中：4
站点搜索命中：8

note.com 候选

教員のAIツール選び方完全ガイド──ChatGPT・Claude・Gemini、どれを選ぶ？ | https://note.com/lush_quail8536/n/n8fe031b778b3
DifyのAIアプリケーション構築ツールと、n8nの外部サービス連携の自動化ワークフローツール組み合わせ工夫 | https://note.com/cognitive_01/n/na21f0db9b41b
ノーコードで業務にAIを取り入れる時代へ：Dify完全ガイド（2025年最新版） | https://note.com/ranxxx/n/n0d1b2885e172
ChatGPTとの違いは？Difyのメリット・デメリットを元エンジニアが徹底比較 | https://note.com/hide6631/n/n0a79e1e8a27d

zenn.dev / 官方文档 / 其他日文页面

ファイルアップロード | 日本語 | https://legacy-docs.dify.ai/ja-jp/guides/workflow/file-upload
Weaviate 移行ガイド：クライアント v4 とサーバー 1.27+ への … | https://docs.dify.ai/ja/self-host/troubleshooting/weaviate-v4-migration
ステップ2：ナレッジパイプラインをオーケストレーションする | https://docs.dify.ai/ja/use-dify/knowledge/knowledge-pipeline/knowledge-pipeline-orchestration
レッスン 3：ワークフローの頭脳（LLM ノード） | https://docs.dify.ai/ja/use-dify/tutorials/workflow-101/lesson-03
Dify + Llama 3 で遊んでみる (1) | https://zenn.dev/derwind/articles/dwd-llm-dify01

phase-2/2-2/05-Agent-工具调用陷入死循环.md

检索词：Dify Agent 無限ループ最大反復
note 命中：3
站点搜索命中：7

note.com 候选

第1回：【Dify】ReActエージェントの基本構造と「思考・行動・観察」ループ | https://note.com/niti_technology/n/nb8640f15a899
効果的な AIエージェント設計方法：Anthropic公開の資料要約 | https://note.com/kakeyang/n/nf919725fdce0
OpenAI o1 previewにreflectionプロンプトっぽい動作のエージェントを実装案を考えてもらう | https://note.com/hamachi_jp/n/n87482831981f

zenn.dev / 官方文档 / 其他日文页面

エージェント | https://docs.dify.ai/ja/use-dify/nodes/agent
繰り返し処理（ループ） | 日本語 | https://legacy-docs.dify.ai/ja-jp/guides/workflow/node/loop
ループ - Dify Docs | https://docs.dify.ai/ja/use-dify/nodes/loop
Self-Correction in Coding：Difyでワンショット生成の限界を … | https://zenn.dev/nocodesolutions/articles/1fd0c75476d302
AIが自ら「検索し直す」。DeepSeek-R1とDifyが作る高度な … | https://zenn.dev/nocodesolutions/articles/0c24477dac9882

phase-2/2-3/01-生产环境-vs-测试环境.md

检索词：Dify 本番環境テスト環境構成
note 命中：6
站点搜索命中：8

note.com 候选

【悲報】9割がハマるDifyの罠7選｜導入で失敗しないためのチェックリスト | https://note.com/sone_ai/n/nfee16bbba037
ConoHa VPSとは？AIツールを試したい人のための“最初の1台“ガイド | https://note.com/ryo_ai_dev/n/ne69c4d14217c
【構築フェーズ③】ツールを設定・構築する | https://note.com/kaizen_workout/n/nee0b96508720
React 経由の重大脆弱性と、2024〜2025年の Dify 脆弱性をまとめてみた話 | https://note.com/jumao/n/n979d9409ad5c

zenn.dev / 官方文档 / 其他日文页面

（ノード）HTTPリクエストノード｜Dify完全ガイド | https://zenn.dev/kentaichimura/books/e48a042e40c657/viewer/a11f91
Difyの.env.exampleを毎回目視で見てる人へ：安全に同期する … | https://zenn.dev/zozotech/articles/9add3a5c2de5cc
TerraformでDify AIプラットフォームをAWSに構築する完全ガイド | https://zenn.dev/zuzuzu/articles/dify_building
モデルプロバイダー - Dify Docs | https://docs.dify.ai/ja/use-dify/workspace/model-providers
モデルの認証情報を管理 | https://docs.dify.ai/versions/3-5-x/ja/user-guide/model-configuration/manage-model-credential

phase-2/2-3/02-Helm-Chart-values关键参数.md

检索词：Dify Helm values.yaml 設定
note 命中：2
站点搜索命中：8

note.com 候选

DifyをAzure Kubernetes Service (AKS)で動かせるようにしました。 | https://note.com/k_7tsumi/n/n347b0db42499
普通のおじさんでも使えるDify | https://note.com/aiojisan2024/n/ne46593daf97c

zenn.dev / 官方文档 / 其他日文页面

helmを使って、minikubeでDifyをデプロイしてみた | https://zenn.dev/data_and_ai/articles/703ac71eea4b01
Difyで作ったLLM ApplicationをAzure Kubernetes Serviceに … | https://zenn.dev/microsoft/articles/dify_on_azure
Kubernetes on Jetson Linux + Ollama + Dify でローカルLLM … | https://zenn.dev/ussvgr/scraps/81168b96a16bc9
Dify on Azure | https://zenn.dev/yusu29/scraps/8bc6a603989789
ACKにデプロイしたDifyのDBをマネージドにする | https://zenn.dev/maipippi/articles/c4b4e7e99c1c65

phase-2/2-3/03-多租户权限设计.md

检索词：Dify マルチテナント Workspace 権限
note 命中：1
站点搜索命中：3

note.com 候选

Dify 弱点 | https://note.com/aoyama_sys/n/n1884f48bc2a3

zenn.dev / 官方文档 / 其他日文页面

Dify 触ってみたメモ | https://zenn.dev/yamato0811/scraps/7ba74410173165
フロントエンドから読み解くDifyアーキテクチャ | https://zenn.dev/takapom/articles/27ed1389beccb7
【保存版：Dify導入済の企業向け】n8n導入するべき？Difyとの … | https://zenn.dev/upgradetech/articles/eea37f22313816

phase-2/2-3/04-License-管理实务.md

检索词：Dify Enterprise License 有効期限更新
note 命中：2
站点搜索命中：8

note.com 候选

CISSPメモまとめ | https://note.com/swign/n/n8edb2b98aa1b
Linuxのトリセツ | https://note.com/hachilock/n/n68d2dd018011

zenn.dev / 官方文档 / 其他日文页面

環境変数の説明 | 日本語 | https://legacy-docs.dify.ai/ja-jp/getting-started/install-self-hosted/environments
Dify チャットフローを AI が生成する仕組みを AI で作った話 | https://zenn.dev/ryoyoshii/articles/05d2ffe846f518
コードが書けなくても使える！「Dify用コード生成プロンプト」を … | https://zenn.dev/upgradetech/articles/79d5bff364cbc7
AI AgentとKG：L5エージェントを実現する知識基盤 | https://zenn.dev/knowledge_graph/books/knowledge-graph-llm-guide/viewer/kg-and-ai-agents
Developers Summit 2026 Day2, 3 公開資料・Xアカウント … | https://zenn.dev/h_yoshikawa0724/articles/2026-02-22-developers-summit-2026

phase-2/2-3/05-升级版本注意事项.md

检索词：Dify Enterprise アップグレード移行ロールバック
note 命中：1
站点搜索命中：5

note.com 候选

【ChatGPTによる和訳】Best Buy (BBY) Q4 2025 Earnings Call Transcript | https://note.com/american_stock/n/n3dd632ffef8a

zenn.dev / 官方文档 / 其他日文页面

DifyをAWSでセルフホストする際のデータフローとセキュリティ対策 | https://zenn.dev/upgradetech/articles/8b7773dc2de4b3
週刊AI駆動開発 - 2025年12月28日 | https://zenn.dev/pppp303/articles/weekly_ai_20251228
【生成 AI 時代の LLMOps】プロンプト管理編 | https://zenn.dev/google_cloud_jp/articles/db61e6617020a4
開発者生産性Conference 2024に参加してきました！ | https://zenn.dev/communitio/articles/199322793252ba
週刊AI駆動開発 - 2026年03月08日 | https://zenn.dev/pppp303/articles/weekly_ai_20260308

phase-2 资料来源索引

本文件用于记录 phase-2 当前已经收集到、且对正文最有帮助的公开资料。优先来源为 note.com、zenn.dev，以及 Dify 官方 / Enterprise 官方公开文档。

一、2-1 深度 Use Case

1. 制造业设备故障排查机器人

note.com
- リコー「H.D.E.E.N」が示す暗黙知AI化の本質：4,500エージェントの実績が教える段階的実装の成功法則
  https://note.com/shin48ya/n/n14d3ec2acaf5
zenn.dev
- ローカルLLMの実用性が爆上げ：オフライン環境でも使える …
  https://zenn.dev/taku_sid/articles/20250402_local_llm
说明
- 直接写“Dify + 制造业设备故障排查”的公开文章仍然偏少，目前更多是“制造业知识结构化 + 图表型资料 + 本地部署”的组合证据。

2. 法务合同比对 Workflow

note.com
- Human-in-the-Loopの活用事例　Difyでの具体的な運用パターン9選
  https://note.com/nocode_solutions/n/n91655a876f4d
zenn.dev
- Human-in-the-Loopの活用事例 Difyでの具体的な運用 …
  https://zenn.dev/nocodesolutions/articles/62a03c6770b824
- Human-in-the-Loopの概念をDifyに落とし込み、AIの暴走を …
  https://zenn.dev/nocodesolutions/articles/df0d883c7d1f79
- DifyとGradioで作るPDF処理ワークフローアプリケーション
  https://zenn.dev/tregu0458/articles/fbd86a6f3b4869

3. 社内稟議自动草稿生成

note.com
- 稟議なんか通せない。だから余ったPCで勝手にAI環境を作ることにした
  https://note.com/kusanone_dx/n/nd2952fe10842
- 【コスト削減】Difyで実現する企業の業務効率化｜明日から使える事例10選
  https://note.com/sone_ai/n/n65c4c48417ac
zenn.dev
- Human-in-the-Loopの活用事例 Difyでの具体的な運用 …
  https://zenn.dev/nocodesolutions/articles/62a03c6770b824
说明
- 这个题目更偏“企业内部文书自动化 + 审批场景”，直接命中不强，但可由 HITL + 结构化输出 + 日本企业稟議语境拼出来。

4. 多语言客服 Agent

note.com
- AIエージェントで問い合わせ対応を自動化｜24時間対応を実現する方法
  https://note.com/tateru_ai/n/n919b556b609f
官方文档
- 知識ベースを使用したカスタマーサービスボット
  https://docs.dify.ai/ja/use-dify/tutorials/customer-service-bot
- エージェント
  https://docs.dify.ai/ja/use-dify/nodes/agent
- Agent | Dify
  https://legacy-docs.dify.ai/guides/workflow/node/agent

5. HR 入职文件处理流水线

note.com
- Human-in-the-Loopの活用事例　Difyでの具体的な運用パターン9選
  https://note.com/nocode_solutions/n/n91655a876f4d
zenn.dev
- 【脱・OCR】Dify×VLMで、あらゆる画像・PDFを思い通りのJSONに変換する
  https://zenn.dev/nocodesolutions/articles/c7fc07a13a701a
- DifyとGradioで作るPDF処理ワークフローアプリケーション
  https://zenn.dev/tregu0458/articles/fbd86a6f3b4869
- Human-in-the-Loopの活用事例 Difyでの具体的な運用 …
  https://zenn.dev/nocodesolutions/articles/62a03c6770b824

二、2-2 踩坑记录与解法

检索参数 / Rerank

Dify Docs
- Specify the Index Method and Retrieval Settings
  https://docs.dify.ai/en/guides/knowledge-base/create-knowledge-and-upload-documents/setting-indexing-methods
Legacy Docs
- Re-ranking
  https://legacy-docs.dify.ai/learn-more/extended-reading/retrieval-augment/rerank
- Integrate Knowledge Base within Application
  https://legacy-docs.dify.ai/guides/knowledge-base/integrate-knowledge-within-application
GitHub Discussion
- Doubt about the topk and threshold usage in rerank stage settings
  https://github.com/langgenius/dify/discussions/3171

Agent 死循环 / 最大迭代次数 / Memory

Dify Docs
- Agent
  https://docs.dify.ai/en/use-dify/nodes/agent
Legacy Docs
- Agent
  https://legacy-docs.dify.ai/guides/workflow/node/agent
Environment Variables
- https://docs.dify.ai/getting-started/install-self-hosted/environments

大文件上传 / 环境变量 / 上传限制

Dify Docs
- Environment Variables
  https://docs.dify.ai/getting-started/install-self-hosted/environments
- Deploy Dify with Docker Compose
  https://docs.dify.ai/en/self-host/quick-start/docker-compose

三、2-3 Enterprise 部署最佳实践

Helm / Kubernetes / values.yaml

Dify Enterprise Docs
- Dify Helm Chart
  https://enterprise-docs.dify.ai/en-us/deployment/advanced-configuration/dify-helm-chart
- Deployment FAQ
  https://enterprise-docs.dify.ai/en-us/deployment/faq/deploying
- Kubernetes
  https://enterprise-docs.dify.ai/en-us/deployment/prerequisites/kubernetes
- Resources Checklist
  https://enterprise-docs.dify.ai/versions/3-7-x/en-us/deployment/resources-checklist

License

Dify Enterprise Docs
- License Activation
  https://enterprise-docs.dify.ai/versions/3-0-x/en-us/deployment/license-activation

高可用 / 生产部署

Alibaba Cloud Community
- High Availability and Performance: Best Practices for Deploying Dify based on ACK
  https://www.alibabacloud.com/blog/high-availability-and-performance-best-practices-for-deploying-dify-based-on-ack_601874

四、原始抓取文件

本轮已抓取并保存在：

research-public/
phase-2/2-1/sources/

后续如果要继续把 phase-2 做深，建议优先继续补抓：

2-2 与 2-3 中命中最强的官方文档全文
更多日文企业博客中的 Dify / RAG / Workflow / HITL 落地案例

制造业设备故障诊断机器人：使用Dify知识库+工作流程的实用设计指南

简介

在制造业，每次设备出现故障，都会请资深工程师过来，依靠经验和直觉反复应对。然而，随着技术工人不断老龄化和退休，这种基于个人的失败应对模式是不可持续的。设备手册、SOP、过去的维修记录、报警代码列表——虽然这些信息存在于公司内部，但它是分布式的、非结构化的，对现场响应能力没有贡献。

本文从架构设计到调优，实际讲解了如何结合Dify的知识库和工作流程构建制造设备故障诊断助手。

背景和问题

制造业故障响应的现实

作业	详情
知识变得个性化	经验丰富的工程师的隐性知识没有记录在案，退休后就消失了
信息分散	手册、SOP、人工费率和MES数据分散在不同的系统中
现场口语表达	难以搜索，例如“该设备正在发出噪音”、“警报已响，但仍在工作”
响应速度要求	需要立即响应，因为当线路停止时，损失会逐分钟增加
安全限制	许多工厂网络是封闭网络，这可能会限制云API的使用

为什么 Dify 适合您

Dify 通过以下方式适应制造故障诊断场景：

通过知识库对多个知识源进行集成管理
使用工作流程进行路由和条件分支的可视化设计
使用**自托管（Docker Compose）**进行本地/封闭网络部署
微调搜索参数，例如重新排名和分数阈值
通过HTTP请求节点与MES/SCADA等外部系统联动

整体架构

flowchart TD
    A[現場担当者の問い合わせ] --> B[Dify Chatbot / API]
    B --> C{質問分類ノード}
    C -->|設備仕様| D[KB: 静的知識]
    C -->|標準手順| E[KB: SOP・アラームコード]
    C -->|過去事例| F[KB: 修理記録・ナレッジ]
    C -->|現在状態| G[HTTP Request: MES/SCADA]
    D --> H[回答生成ノード]
    E --> H
    F --> H
    G --> H
    H --> I[構造化回答出力]
    I --> J{信頼度チェック}
    J -->|高| K[現場担当者へ回答]
    J -->|低| L[エスカレーション: 保全チームへ通知]

知识库层次结构设计

设计理念：4层模型

将所有文档放入一个知识库是制造业中一种致命的反模式。我们建议采用“分层知识设计”，根据信息的性质划分知识库，并为每种问题类型切换搜索目的地。

####第一层：设备静态知识库

存储目标	示例
设备使用说明书	CNC加工机操作手册v3.2
保养手册	月度检查程序手册
零件清单/分解图	主轴单元零件清单
规格/安装要求	电源规格/环境条件列表

作用：回答“这个设备原本应该如何工作？”的问题。

大块策略：分为章节、子系统和部分模块。避免分割成固定数量的字符。

####第二层：标准操作/故障响应知识库

存储目标	示例
SOP（标准操作程序）	注塑机换模SOP
报警代码列表	E-401：液压异常，E-502：伺服过载
故障诊断流程图	振动异常诊断树
定期检查清单	每日、每周、每月检查项目

作用：回答“如果出现这种异常，默认情况下你会如何处理？”

分块策略：分为报警代码单元和程序段落单元。理想情况下，一个块对应一个应对路径。

第三层：历史案例知识库

存储目标	示例
修理工（工作报告）	2024/11/05 3号线主轴轴承更换
失败审核记录	为什么为什么分析表
更换零件历史记录	近两年伺服电机更换历史
在团体/团队之间分享知识	夜班时常发生的E-302如何处理备忘录

角色：回答“过去出现类似症状时，您实际上是如何解决的？”

块策略：1 次失败 = 1 个块。添加设备 ID、日期和警报代码作为元数据。

####第四层：实时辅助信息（外部协作）

来源	如何获取
MES运行状况	使用 HTTP 请求节点进行 API 调用
SCADA报警日志（最新）	使用 HTTP 请求节点进行 API 调用
维护计划	HTTP 请求或知识库
设备/备件库存	使用 HTTP 请求节点进行 ERP API 调用

作用：回答“这件装备目前的状态如何？”最好使用工作流的 HTTP 请求节点实时获取它，而不是将其放入知识库中。

工作流程设计细节

###问题分类节点（LLM节点）

它接收用户输入并将其分为以下四类。

System Prompt:
あなたは製造業設備の問い合わせ分類エンジンです。
ユーザーの質問を以下のカテゴリに分類してください。

1. SPEC - 設備の仕様・原理・構造に関する質問
2. SOP - 標準手順・アラームコード・点検に関する質問
3. CASE - 過去の故障事例・修理履歴に関する質問
4. STATUS - 現在の設備状態・稼働状況に関する質問

カテゴリ名のみを出力してください。複数該当する場合はカンマ区切りで出力。

条件分支节点

根据分类结果切换搜索目标知识库。使用 Dify Workflow 的 IF/ELSE 节点 或 问题分类器节点。

IF category contains "SPEC" → Knowledge Retrieval(静的知識KB)
IF category contains "SOP"  → Knowledge Retrieval(SOP・アラームKB)
IF category contains "CASE" → Knowledge Retrieval(事例KB)
IF category contains "STATUS" → HTTP Request(MES/SCADA API)

如果有多个类别，则并行搜索，合并结果，并将其传递给答案生成节点。

###答案生成节点（LLM节点）

System Prompt:
あなたは製造業の設備保全エキスパートアシスタントです。
以下のフォーマットで回答してください。

## 初期判断
[症状に対する第一印象]

## 考えられる原因（優先度順）
1. ...
2. ...
3. ...

## 推奨する確認手順
1. ...
2. ...

## 確認すべきログ・センサー・部品
- ...

## エスカレーション判断
[人手による対応が必要かどうかの判断]

注意事項:
- 推測の域を出ない場合は明示すること
- 安全に関わる作業は必ず「有資格者による実施」を注記すること
- 検索結果に該当情報がない場合は「該当情報なし」と明示すること

调整搜索参数

调整概念

在制造业的故障诊断中，“通过一个参数设置对应所有问题类型”是不现实的。这是因为最佳参数根据问题类别而不同。

参数	SPEC（规格）	SOP（程序）	案例（示例）
搜索模式	混合动力	混合动力	语义
前 K	3	3-5	3-5 5-8
分数门槛	0.5	0.5 0.45	0.45 0.3-0.4
重新排名	关闭	开	开
重新排序模型	-	bge-reranker	bge-reranker

调音记录模板

在实际调优过程中，我们建议保留以下记录。

圆形	变化	测试题	预期结果	实际结果	判决
R1	语义/Top-K=3/阈值=0.5	E-401报警如何处理？	从 SOP 返回操作步骤	返回正确的 SOP	好的
R2	语义/Top-K=3/阈值=0.5	和上个月主轴振动一样吗？	案例：从KB返回对应的人工费率	退回不相关的SOP	异常
R3	Top-K=6 / 阈值=0.35 / 重新排名=ON	和上个月主轴振动一样吗？	从案例KB中返回相应的人工费率	返回正确的案例	好的

Chunk设计的实用要点

警报代码文档的块示例

---
alarm_code: E-401
equipment: 油圧ユニット HU-200
severity: WARNING
---

## E-401: 油圧圧力低下

### 症状
油圧系統の圧力が設定値を下回った場合に発報。設備は低速運転を継続するが、加工精度が低下する可能性がある。

### 考えられる原因
1. 油圧ポンプの摩耗
2. リリーフバルブの設定ずれ
3. 油圧ホースからのリーク
4. 作動油の劣化（粘度低下）

### 対処手順
1. 油圧計で実測圧力を確認
2. ポンプ周辺の油漏れを目視確認
3. 作動油のサンプリング検査を実施
4. 異常が認められた場合、ラインを停止し保全チームに連絡

添加元数据

将文档上传到 Dify 知识库时，在文件名和文档描述中包含以下元数据将提高搜索准确性。

设备ID/设备名称
警报代码（如果适用）
文档类别（手册/SOP/示例/清单）
最后更新

型号	参数数量	日语支持	推荐用途
Llama 3.1 8B	8B	中等	问题分类/轻任务
Qwen2.5 14B	14B	14B好	答案生成/摘要
Command R+	104B	104B好	高度准确的答案生成
嵌入：多语言-e5	-	好	用于知识搜索的嵌入

操作流程及持续改进

###反馈循环设计

flowchart LR
    A[故障発生] --> B[ボットに問い合わせ]
    B --> C[回答を確認]
    C --> D{解決?}
    D -->|Yes| E[解決記録を KB に追加]
    D -->|No| F[保全チームが対応]
    F --> G[対応結果を工単に記録]
    G --> E
    E --> H[ナレッジベース更新]
    H --> I[検索精度が向上]

定期保养项目

频率	工作详情
每周	回顾未回答/低分答案
每月	知识库新增故障案例
季刊	重新调整搜索参数
半年度	块策略审查/重新划分

实施步骤

第 1 阶段（2-3 周）：使用警报代码列表和关键 SOP 填充知识库。开始作为基本的问答机器人工作。
第 2 阶段（1-2 个月）：添加了结构化的过去修理工/故障记录。引入问题分类节点，实现搜索目的地自动排序。
第 3 阶段（2-3 个月）：添加了用于 MES/SCADA 协作的 HTTP 请求节点。现在可以根据实时情况提供答案。
第 4 阶段（持续）：根据现场反馈不断改进知识和参数。

总结

制造业的设备故障诊断机器人不仅仅是上传手册。 知识的层次结构，根据问题类型的搜索路由，优化块设计，以及在操作阶段不断积累知识 - 通过将这些设计在一起，它就成为第一次在该领域使用的工具。

Dify的知识库+工作流程组合为这一需求提供了足够的灵活性。特别是，通过使用自托管版本，可以满足制造业特有的安全需求（封闭网络、禁止外部数据传输），大大降低了企业实施的门槛。

最重要的是，不要将这个项目定位为“人工智能引入项目”，而是“领域知识结构化项目”。隐性知识如何转化为可搜索资产的设计质量决定了机器人的实用性。

法律合约比较工作流程：使用Dify的传输节点和Human-in-the-Loop进行实际设计

简介

在公司法律事务中，审查合同是最耗时的工作之一。检查新合同的草稿与公司自己的模板之间的差异，掌握业务伙伴发送的修订版本（红线版本）的变化，检查多个相关合同之间的条款一致性——尽管这些工作需要高度的专业知识，但大部分时间都花在“提取常规差异”上。

本文使用 Dify 的工作流程功能来解释法律合同审查系统的设计和实现，该系统可以自动对多个文件进行合同比较，同时需要人工确认高风险条款。

背景和问题

合同审查现状

挑战	影响
每个案例所需时间	标准外包合同 2-4 小时，复杂合同几天
忽视条款的风险	自动续订条款、适用法律的变更等很可能在人工检查中被忽视
版本控制的复杂性	当Word的更改历史记录被多次合并时，跟踪更改变得困难
个性化	只有特定的律师和法律工作人员才了解判断标准
拥堵等待点评	法务部瓶颈导致业务速度放缓

这个工作流程解决什么问题

常规差异提取的自动化：委托逐条比较LLM
风险分类标准化：使用一致的标准确定每个条款的风险级别
人在环：高风险、低置信度的决策总是传递给人类。
多文件支持：使用迭代节点进行顺序处理

整体架构

flowchart TD
    A[契約書ファイルアップロード<br>主契約 + テンプレート + 附属書] --> B[ファイル解析ノード]
    B --> C[契約タイプ分類]
    C --> D[迭代ノード:<br>ファイルごとに条項抽出]
    D --> E[条項マッピング・差異検出]
    E --> F[リスク分級ノード]
    F --> G{高リスク条項あり?}
    G -->|Yes| H[Human-in-the-Loop:<br>法務担当に確認依頼]
    G -->|No| I[レビュー結果出力]
    H --> J{承認 / 差戻し}
    J -->|承認| I
    J -->|差戻し| K[修正指示付きで再レビュー]
    K --> E
    I --> L[構造化レポート出力]

工作流节点设计细节

节点1：文件接收/预处理

在 Dify Workflow 中的启动节点上传文件。接受多个文件时，向每个文件添加元数据。

{
  "files": [
    {
      "name": "master_agreement_v2.pdf",
      "role": "review_target",
      "type": "主契約",
      "version": "v2.0"
    },
    {
      "name": "standard_template_2024.pdf",
      "role": "template",
      "type": "業務委託契約テンプレート",
      "version": "2024年版"
    },
    {
      "name": "appendix_a.pdf",
      "role": "attachment",
      "type": "別紙A（SLA条件）",
      "version": "v1.0"
    }
  ]
}

方法	应用案例	备注
文本PDF直接分析	Word → PDF 转换	最准确且成本低
OCR（Tesseract等）	扫描 PDF	注意日语OCR的准确性
VLM（视觉语言模型）	包含表格、图形和印章混合的文档	利用 GPT-4o / Claude的视觉功能

节点 4：迭代节点提取子句

使用 Dify Workflow 中的 迭代节点 对每个上传的文件应用相同的子句提取过程。

迭代ノードの設定:
- 入力配列: files[]
- 各イテレーションの処理:
  1. テキスト抽出
  2. LLM ノードで条項単位に分割
  3. 各条項をJSON配列として出力

子句提取的 LLM 提示示例：

以下の契約書テキストから、主要条項を抽出してください。
各条項について以下のフィールドを出力してください。

- clause_id: 条番号（例: "第3条第2項"）
- clause_title: 条項名（例: "秘密保持義務"）
- clause_text: 条文全文
- clause_category: カテゴリ（以下から選択）
  [契約主体, 契約期間, 業務範囲, 報酬・支払条件, 
   知的財産権, 秘密保持, 損害賠償, 解除条件, 
   自動更新, 準拠法・管轄, 反社会的勢力排除, その他]

JSON配列で出力してください。

使用迭代节点的原因：如果将所有文件的文本一次性输入LLM，由于上下文窗口的限制，子句很可能会被忽略。通过按顺序处理每个文件并保留中间结果，您可以稍后准确地跟踪在哪个文件中检测到此差异。

节点 5：子句映射/差异检测（LLM 节点）

接收传输节点输出的每个文件的条款列表，并将模板与待审核的条款进行匹配。

System Prompt:
あなたは契約書の比較分析エキスパートです。
テンプレート条項とレビュー対象の条項を比較し、
以下のフォーマットで差異を報告してください。

各条項について:
{
  "clause_category": "...",
  "template_clause": "テンプレート側の条文",
  "review_clause": "レビュー対象側の条文",
  "status": "identical | modified | added | deleted | missing",
  "diff_summary": "差異の要約（日本語）",
  "risk_level": "high | medium | low | info",
  "risk_reason": "リスク判定の根拠"
}

リスク判定基準:
- high: 損害賠償上限の撤廃、自動更新の無制限化、排他的拘束、
        準拠法の変更、データ越境義務、競業避止の過度な拡大
- medium: 支払条件の変更、解除条件の非対称性、保証範囲の縮小
- low: 通知期間の軽微な変更、形式的な文言修正
- info: 差異はあるが実質的影響なし

节点6：风险分类和汇总

聚合差异检测结果并生成审核摘要。

{
  "total_clauses_compared": 24,
  "identical": 15,
  "modified": 6,
  "added": 2,
  "deleted": 1,
  "high_risk_count": 2,
  "medium_risk_count": 3,
  "requires_human_review": true,
  "high_risk_clauses": ["..."]
}

人在环审核节点设计

为什么不完全自动化？

人工智能在合同审查中的作用是“检测和分类差异”，而不是做出“法律判断”。法律责任最终落在人类身上，因此将高风险决策委托给人工智能无论从合规性还是实践的角度来看都是不可接受的。

设计触发条件

状况	判断逻辑	分行目的地
有一个高风险条款	`high_risk_count >= 1`	请务必将其发送给人工
对差异的信心不足	LLM表示缺乏证据	转移到人类
合同结构异常	缺少主要条款（损坏赔偿、取消等）	转移到人类
越权的可能性	合同金额超出审批权限门槛	升级
OCR 质量差	文本提取质量得分低于阈值	传递给人类

人类输入节点分支

Dify 的人工输入节点本身支持三个分支：

接受：法律部门确认并批准→继续报告输出
DENY：法律部门发回→给出更正指示并返回有条件分支
超时：在一定时间内没有响应 → 保持搁置状态而不自动批准

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
契約書レビュー: 人間による確認が必要です
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

■ 高リスク条項:

1. 第12条（損害賠償）
   テンプレート: 賠償上限は委託料の12ヶ月分
   レビュー対象: 賠償上限の記載なし（無制限）
   → リスク: 損害賠償上限の撤廃

2. 第15条（自動更新）
   テンプレート: 1年ごとの自動更新、解約通知3ヶ月前
   レビュー対象: 3年ごとの自動更新、解約通知6ヶ月前
   → リスク: ロックイン期間の大幅延長

■ 判断をお願いします: [承認] [差戻し]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

条款比较清单

主要比较术语

类别	检查点	典型风险
合同实体	更改各方描述/关联公司的范围	义务归属不明确
合同期限	开始日期、结束日期、自动续订条件	意外锁定
补偿/付款	金额/付款地点/延误损坏费	现金流风险
知识产权	归属和许可范围	作品权利的丧失
保密	定义、期限、例外情况、剩余期限	信息泄露的责任范围
损害赔偿	上限、豁免和间接损害的处理	意想不到的高额补偿
取消条件	未经通知而取消/未经通知而取消/影响	突然终止合同的风险
适用法律/司法管辖区	适用法律/管辖权/仲裁条款	发生争议时不利的管辖权
数据处理	个人信息/跨境转移/删除义务	违反个人信息保护法
排除反社会势力	声明和保证/取消权	合规风险

设计输出报告

结构化输出 (JSON)

以结构化 JSON 格式输出，假设与下游合同管理系统和工作流程审批系统协作。

{
  "review_id": "REV-2026-0412-001",
  "review_date": "2026-04-12",
  "reviewer_ai": "Dify Workflow v1.2",
  "reviewer_human": "法務部 田中",
  "contract_type": "業務委託契約",
  "review_target": "master_agreement_v2.pdf",
  "template": "standard_template_2024.pdf",
  "summary": {
    "total_clauses": 24,
    "differences": 9,
    "high_risk": 2,
    "medium_risk": 3,
    "human_review_status": "approved_with_comments"
  },
  "high_risk_details": [
    {
      "clause_id": "第12条",
      "category": "損害賠償",
      "diff_summary": "賠償上限の記載が削除されている",
      "recommendation": "上限条項の追記を交渉"
    }
  ],
  "recommendations": [
    "第12条の損害賠償上限を明記するよう交渉を推奨",
    "第15条の自動更新期間を1年に短縮するよう修正依頼"
  ]
}

实现说明和反模式

不该做的事情

立即将整个合同放入LLM并询问“有什么区别？” - 如果你不将其分解为条款，重要的差异将被隐藏。
不区分处理主合同、附录和变更备忘录——版本和应用优先级混淆
将AI判断结果作为最终判断——以法律责任由人类承担为前提进行设计。
风险等级判断标准与组织规则分离——与审批权限、合规政策挂钩
不要定义Human-in-the-Loop的触发条件——如果不清楚在什么条件下所有病例应该发送给人类，就会出现两个极端：所有病例都发送给人类，或者所有病例都被传递。

实施步骤

相	期间	内容
第一阶段	2 周	PoC 具有简单的合同类型，例如 NDA。与模板一对一比较。
第二阶段	1 个月	扩大到业务外包合同。支持传输节点中的多个文件，包括附件。
第三阶段	1-2个月	人在环的全面运作。根据法律团队的反馈调整风险标准。
第四阶段	继续	API与合同管理系统联动。积累审核绩效数据，提高判断准确性。

API合作示例

Dify Workflow 可以作为 REST API 发布，因此可以从现有合同管理系统中调用。

curl -X POST 'https://dify.example.com/v1/workflows/run' \
  -H 'Authorization: Bearer {api_key}' \
  -H 'Content-Type: multipart/form-data' \
  -F 'inputs={"contract_type":"業務委託契約"}' \
  -F 'files=@master_agreement_v2.pdf' \
  -F 'files=@standard_template_2024.pdf' \
  -F 'response_mode=blocking' \
  -F 'user=legal_team_tanaka'

总结

法律合同比对工作流程的本质不是“让人工智能读合同”，而是构建一个系统，自动提取可标准化的差异，并将高风险决策可靠地委托给人类。

Dify 的传输节点可以实现多个文件的顺序处理，Human-in-the-Loop 节点的 ACCEPT / DENY / TIMEOUT 分支保证了 Workflow 层面法律审查所需的“人类做出最终决定”的原则。

重要的是，不要将此工作流程定位为“法律部门的省力工具”，而是“合同风险可视化和标准化的基础”。人工智能发现差异，对风险进行分类，人类进行决策——不断重复这个循环，就可以提高整个组织的合同风险管理能力。

内部审批文件自动生成草稿：使用Dify练习结构化输出和提示设计

简介

在日本企业中，审批文件是构成决策过程的核心文件。实施新工具、申请预算、与外部供应商签订合同——所有重要决策都必须通过通告批准。然而，创建批准文件需要相当长的时间。一份审批文件耗时几个小时到一整天的情况并不少见，包括整理背景、计算成本效益、识别风险、写下与相关部门协调的事项。

在本文中，我们将解释一个系统的设计，该系统使用 Dify 以结构化格式自动生成审批文件草稿，然后由人工检查和修改，然后放入审批流程。重点不是“写得好”，而是始终如一地生成与组织批准的格式一致且没有间隙的结构化输出。

背景和问题

创建ringi文档的实际问题

作业	详情
准备工作所需的工时量	事业部经理日常工作中写审批文件
格式不一致	各部门格式不同，增加审稿人负担
缺少必需的物品	提交的意见书通常是在没有预算基础或风险评估的情况下发送的
缺乏定量信息	投资回报率和投资回收期不明确进入审批流程
审批文件拥堵	审批文件准备拖延，项目开工延误

为什么是“自动草稿”而不是“自动生成”？

批准文件是组织内部的正式决策文件，最终责任由申请人和批准人承担。由于以下原因，原样提交人工智能生成的内容是不合适的。

数字准确性：人工智能不应猜测预算金额、投资回报率或投资回收期。
特定于组织的背景：人工智能无法确定过去的情况或内部政治考虑
责任：申请人对批准文件的内容负责。

因此，人工智能的作用将仅限于“安排结构、生成草稿、澄清缺失的项目”，最终的设计将由人类完成。

整体架构

flowchart TD
    A[申請者: 要件を入力] --> B[入力情報の構造化ノード]
    B --> C[稟議タイプ判定]
    C --> D[テンプレート選択]
    D --> E[LLM ドラフト生成]
    E --> F[不足項目チェック]
    F --> G{不足項目あり?}
    G -->|Yes| H[不足項目リスト提示<br>+ 暫定ドラフト出力]
    G -->|No| I[完全ドラフト出力]
    H --> J[Human-in-the-Loop:<br>申請者が確認・補完]
    I --> J
    J --> K[最終稟議書出力]
    K --> L[承認ワークフロー連携<br>API / メール / Slack]

审批文件结构化格式设计

标准字段定义

生成审批文件草稿最重要的是输出格式的稳定性。它基于固定字段的结构化输出而不是长的自然句子。

{
  "ringi_title": "Dify Enterprise 版 導入に関する稟議",
  "applicant": {
    "name": "",
    "department": "",
    "position": "",
    "date": "2026-04-12"
  },
  "background": {
    "current_situation": "現状の課題を記述",
    "trigger": "稟議提出のきっかけ"
  },
  "purpose": "本稟議の目的を1-2文で記述",
  "proposal": {
    "overview": "提案の概要",
    "scope": "適用範囲・対象部門",
    "timeline": "想定スケジュール"
  },
  "cost": {
    "initial_cost": "初期費用（税込）",
    "running_cost": "月額/年額ランニングコスト",
    "total_budget": "稟議申請金額",
    "budget_source": "予算科目",
    "payment_terms": "支払条件"
  },
  "expected_benefits": {
    "quantitative": "定量的な効果（工数削減○時間/月 等）",
    "qualitative": "定性的な効果"
  },
  "roi": {
    "payback_period": "投資回収期間",
    "calculation_basis": "算出根拠"
  },
  "risks": [
    {
      "risk": "リスク項目",
      "probability": "高/中/低",
      "impact": "高/中/低",
      "mitigation": "対策"
    }
  ],
  "alternatives": [
    {
      "option": "代替案",
      "pros": "メリット",
      "cons": "デメリット",
      "reason_not_selected": "不採用理由"
    }
  ],
  "approval_items": "承認を求める事項を明確に記述",
  "attachments": ["見積書", "製品資料", "PoC報告書"],
  "compliance_check": {
    "personal_data": "個人情報の取扱い有無",
    "security_review": "セキュリティ審査の要否",
    "legal_review": "法務確認の要否"
  },
  "missing_fields": ["未入力または情報不足のフィールド一覧"]
}

按审批类型进行字段调整

审批类型	附加字段	可选字段
SaaS/工具介绍	安全检查表、数据存储位置	-
外包/外包	承包商信息、合同形式、验收条件	投资回报率（如果难以计算）
人才招聘	职位类型、职级、期望年薪范围	替代品比较
资本投资	折旧期、租赁与购买比较	-
活动/商务旅行	目的、参与者、预期结果	投资回收期

提示设计：按版本比较

###版本1：自由生成类型

System Prompt:
あなたは社内稟議書の作成をサポートするアシスタントです。
ユーザーの入力に基づいて稟議書のドラフトを作成してください。

结果趋势：

文本易于阅读，但字段不稳定
必需的项目（预算、风险等）可能会被遗漏。
它往往采用无法直接导入审批系统或表格的格式。

版本 2：模板绑定类型

System Prompt:
あなたは社内稟議書の作成支援アシスタントです。
以下のフィールドに従って、構造化された稟議書ドラフトを JSON 形式で出力してください。

必須フィールド:
- ringi_title: 稟議件名
- background: 背景・現状の課題
- purpose: 目的
- proposal: 提案概要
- cost: コスト（初期費用、ランニングコスト、合計）
- expected_benefits: 期待効果（定量・定性）
- risks: リスクと対策
- approval_items: 承認を求める事項

すべてのフィールドを必ず出力してください。
情報が不足している場合は、そのフィールドに "【要入力】" と記載してください。

结果趋势：

显着改善现场覆盖范围
但是，如果“[需要输入]”过多，草案的实用性就会降低。
如果输入信息较少，有时会通过猜测来填写信息。

###版本3：结构化+漏检+安全约束型（推荐）

System Prompt:
あなたは社内稟議書の整理・構造化アシスタントです。
以下のルールに厳密に従ってください。

【役割の定義】
- あなたは稟議書の「整理者」であり、「意思決定者」ではありません
- 入力情報に基づいてドラフトを構造化する役割のみを担います

【出力ルール】
1. 指定された JSON フォーマットで出力すること
2. 入力情報に含まれない数値（予算額、ROI、期間等）は絶対に推測・捏造しないこと
3. 情報が不足しているフィールドは "【要確認】" と明記すること
4. missing_fields に不足項目を一覧として出力すること
5. 金額には必ず税込/税抜を明記すること
6. 根拠のない効果の誇張は行わないこと

【フォーマット】
{上記の JSON フォーマットを挿入}

【重要な禁止事項】
- 予算額の推測禁止
- ROI の捏造禁止
- 投資回収期間の推測禁止
- 存在しない比較データの生成禁止

结果趋势：

现场覆盖范围和准确性之间的最佳平衡
缺失的项目被清楚地标明，因此申请人需要填写的内容一目了然。
显着降低制造风险

设计输入信息

为什么自由文本输入不够

如果您只是输入自由文本，例如“我想介绍 Dify”。如果创建批准文件，草稿的质量就会很低。通过需要最少量的结构化输入，可以显着提高输出质量。

变量名	类型	必填	描述
`request_summary`	文字	是的	您想申请什么（自由文本）
`department`	选择	是的	应用部
`budget_range`	选择	没有	大致预算范围（~500,000/~2,000,000/~5,000,000/超过 5,000,000）
`urgency`	选择	没有	紧急程度（正常/紧急/紧急）
`target_start_date`	日期	没有	期望的开始日期
`related_documents`	文件	没有	估算、建议等的附件
`additional_context`	文字	没有	其他信息（过去的历史、相关批准等）

从附件中提取信息

当附加报价或提案时，Dify的VLM/参数提取节点用于自动提取金额、供应商名称、合同条款等，并将其反映在草稿审批文件中。

flowchart LR
    A[見積書PDF] --> B[VLM / テキスト抽出]
    B --> C[パラメータ抽出ノード]
    C --> D["金額: ¥3,600,000<br>ベンダー: ○○株式会社<br>期間: 12ヶ月"]
    D --> E[稟議書ドラフトに反映]

人在环设计

需要人工确认的情况

触发条件	原因
预算字段未填写	无金额的审批文件无法提交审批流程
风险评估为空白	不审查风险就审批是组织控制的问题
个人信息、法律事务、安全涉入旗帜	需要专门部门事先确认
高价值案例（超出阈值）	根据审批机关要求升级
效果描述被AI判定“证据不足”	防止高估预期效果

确认流程设计

Dify Human-in-the-Loop ノードの表示例:

━━━━━━━━━━━━━━━━━━━━━━
稟議書ドラフト: 確認をお願いします
━━━━━━━━━━━━━━━━━━━━━━

■ 件名: Dify Enterprise 版 導入に関する稟議

■ 不足項目:
  ⚠ 初期費用が未入力です
  ⚠ 投資回収期間の算出根拠がありません
  ⚠ セキュリティ審査の要否が未回答です

■ ドラフト内容:
  [JSON / Markdown 形式のドラフトを表示]

■ アクション:
  [承認して次へ] [修正して再生成]
━━━━━━━━━━━━━━━━━━━━━━

与下游系统的合作

连接到审批工作流程

审批文件草案最终确定后，使用 Dify Workflow 中的 HTTP 请求节点 将其链接到公司的审批系统。

合作伙伴	方法	笔记
工作流程审批系统（ServiceNow等）	休息 API	按原样发布 JSON
谷歌表单	通过 Google Apps 脚本	映射到表单字段
松弛	网络钩子	发送批准请求通知
电子邮件	SMTP/SendGrid API	将包含草稿的电子邮件发送给审批者
通通	休息 API	在应用程序中注册为记录

API调用示例（kintone联动）

curl -X POST 'https://{subdomain}.cybozu.com/k/v1/record.json' \
  -H 'X-Cybozu-API-Token: {api_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "app": 123,
    "record": {
      "稟議件名": {"value": "Dify Enterprise 版 導入"},
      "申請部門": {"value": "情報システム部"},
      "申請金額": {"value": "3600000"},
      "ステータス": {"value": "ドラフト確認済み"}
    }
  }'

实施最佳实践

要做的事情

首先确定输出格式 — 在提示之前定义需要哪些 JSON 字段
显式输出缺失项 — 定义 missing_fields 为必填字段
按审批类型切换提示 — SaaS实施和人员招聘所需项目不同
在金额字段插入安全约束 — 在提示中明确声明不允许猜测。
必须包括人机交互 — 不允许完全自动化提交

不该做的事情

只需“写审批文件”即可自由文本输入操作 — 输入的结构决定输出的质量
让人工智能估算预算金额和投资回报率 — 会破坏审批者的信任并破坏对整个系统的信任。
对所有审批类型应用相同的模板 — 需要按类型进行优化
以长自然句子输出 — 无法连接到下游系统

实施步骤

相	期间	内容
第一阶段	1-2 周	PoC 仅限于 SaaS 实施批准。使用固定模板生成草稿。
第二阶段	2-4 周	扩大审批类型（外包/资本投资）。添加了从附件中自动提取的功能。
第三阶段	1-2个月	API与审批系统集成。人在环的全面运作。
第四阶段	继续	根据使用历史改进提示。在知识库中积累过去批准的批准，以提高文本的质量。

总结

自动生成内部审批文件草稿最重要的不是“写得好”，而是按照组织批准的格式可靠地生成结构化输出并澄清缺失的信息。

通过使用Dify的Workflow，您可以无需代码构建一系列流程，包括输入结构化→类型确定→模板选择→草稿生成→缺陷检测→人工确认→系统联动。特别是，通过采用第3版（结构化+缺陷检测+安全约束式）的提示设计，可以大幅减少申请人的准备时间，同时降低AI造数的风险。

审批文件是日本企业决策的“界面”，其质量直接关系到组织决策的速度。使用人工智能生成结构化草稿是标准化和加速该界面的有效方法。

多语言客户支持代理：使用 Dify Agent 进行工具协作、回退和内存管理的实用设计

简介

对于全球运营的公司来说，多语言客户支持是一个不可避免的问题。传统上，支持是通过为每种语言组织支持团队或使用翻译工具来处理的，但随着LLM增强的多语言处理能力，现在用单个AI代理支持多种语言是一种现实的方法。

然而，设计多语言客户支持代理时最重要的不是它是否可以支持多种语言。 GPT-4o和Claude等模型可以在没有提示的情况下处理多语言输入和输出。真正的设计挑战在于工具调用链的稳定性、回退策略的清晰性以及会话内存的正确管理。

在本文中，我们将解释构建企业级多语言客户支持代理的设计模式，重点关注 Dify 的 Agent 节点。

背景和问题

多语言客户支持的现状

问题	常规回应	AI 代理解决方案
确保每种语言的人员安全	雇用每种语言的母语人士	单代理自动检测和切换语言
24小时支持	轮班制度/与海外基地的协调	代理提供 24/365 的主要支持
响应质量的变化	通过手册和培训实现标准化	通过知识库 + 提示实现响应质量标准化
与业务系统协作	操作人员手动参考和输入	通过代理调用工具实现自动协作
升级判断	取决于操作者个人判断	使用基于规则+情绪检测的自动升级

Dify Agent 节点的主要功能

Dify 的 Agent 节点原生支持以下配置项。

设置项目	描述
代理策略	从函数调用/ReAct
工具清单	代理可用的工具列表
说明	对Agent的指示（相当于系统提示）
查询	用户输入
最大迭代次数	工具调用的最大迭代次数
内存	对话历史记录保留开/关
窗口尺寸	保留的通话轮数

整体架构

flowchart TD
    A[ユーザー入力<br>任意の言語] --> B[Dify Agent ノード]
    B --> C{意図判定}
    C -->|FAQ| D[Knowledge Base 検索]
    C -->|注文照会| E[Tool: 注文検索API]
    C -->|配送状況| F[Tool: 物流追跡API]
    C -->|工単作成| G[Tool: チケット作成API]
    C -->|クレーム/感情的| H[Tool: 人間エスカレーション]
    C -->|不明| I[フォールバック: 確認質問]
    D --> J[回答生成<br>入力と同じ言語で]
    E --> J
    F --> J
    G --> J
    H --> K[人間オペレーターに転送]
    I --> J
    J --> L[ユーザーへ返答]

工具设计细节

工具列表和定义

Agent 的准确性很大程度上取决于工具描述的质量。抽象的解释不允许LLM选择合适的工具。

工具1：订单搜索

name: search_order
description: |
  顧客の注文情報を検索します。
  以下の場合に使用してください：
  - 顧客が注文番号を提示して状況を確認したい場合
  - 顧客が「注文」「購入」「買った」等のキーワードを含む質問をした場合
  以下の場合は使用しないでください：
  - 注文番号が不明で、顧客が一般的な質問をしている場合
  - 返品・返金に関する質問の場合（create_ticket を使用）
parameters:
  order_id:
    type: string
    required: true
    description: 注文番号（例: ORD-20260412-001）

工具2：物流追踪

name: track_shipment
description: |
  配送状況を追跡します。
  以下の場合に使用してください：
  - 顧客が「届かない」「配送」「いつ届く」等の配送関連の質問をした場合
  - 注文検索の結果、ステータスが「発送済み」の場合
parameters:
  tracking_number:
    type: string
    required: true
    description: 追跡番号

工具 3：创建工单

name: create_ticket
description: |
  カスタマーサポートチケットを作成します。
  以下の場合に使用してください：
  - 顧客が返品・返金を希望する場合
  - 商品の不具合を報告する場合
  - Agent では解決できない問題の場合
parameters:
  customer_id:
    type: string
    required: true
  issue_type:
    type: string
    enum: [return, refund, defect, complaint, other]
    required: true
  description:
    type: string
    required: true
    description: 問題の概要（日本語で記載）

工具 4：常见问题解答搜索（知识库）

name: search_faq
description: |
  FAQ ナレッジベースを検索します。
  以下の場合に使用してください：
  - 顧客が製品の使い方、仕様、ポリシーに関する一般的な質問をした場合
  - 注文や配送に直接関係しない質問の場合

工具 5：人为升级

name: escalate_to_human
description: |
  人間のオペレーターにエスカレーションします。
  以下の場合に必ず使用してください：
  - 顧客が明らかに怒っている、または強い不満を表明している場合
  - 法的な言及（訴訟、消費者庁等）がある場合
  - 3回以上ツール呼び出しを試みても解決できない場合
  - 返金額が50,000円を超える場合
parameters:
  reason:
    type: string
    required: true
  priority:
    type: string
    enum: [normal, high, urgent]
    required: true
  conversation_summary:
    type: string
    required: true
    description: これまでの会話の要約

设计Agent指令（系统提示）

あなたは多言語カスタマーサポートの AI アシスタントです。

【言語ルール】
- ユーザーが使用した言語と同じ言語で回答してください
- 言語の切替が検出された場合は、新しい言語に合わせてください
- 製品名・ブランド名は原語のまま使用してください

【回答構造】
1. まず結論を述べる
2. 次に根拠や状況を説明する
3. 最後に次のアクションを提示する

【ツール呼び出しルール】
- ツールを呼び出す前に、必要なパラメータが揃っているか確認すること
- パラメータが不足している場合は、推測せずユーザーに確認すること
- 1つの質問に対してツール呼び出しは最大3回までとする
- ツール呼び出しが失敗した場合は、エラー内容をユーザーに伝え、
  代替手段を提示すること

【禁止事項】
- 注文のキャンセル・返金の自動実行（チケット作成まで）
- 個人情報（クレジットカード番号等）の取得要求
- 他社製品との比較における他社の誹謗
- 未確認の情報に基づく断定的な回答

【エスカレーション条件】
以下の場合は必ず escalate_to_human を呼び出すこと：
- 顧客の感情が強くネガティブ（怒り、失望、脅し等）
- 法的措置への言及
- 3回のツール呼び出しで解決できない場合
- 自分の回答に自信がない場合

设计后备策略

3 层后备模型

Fallback 是 Agent 无法返回最佳答案时的一种疏散策略。在客户支持中，后备设计是最重要的问题之一，因为“给出错误的响应”比“无法回答”要严重得多。

flowchart TD
    A[ユーザーの質問] --> B{ツール呼び出し<br>条件を満たす?}
    B -->|Yes| C[ツール呼び出し実行]
    B -->|No| D[第1層: Knowledge Base 検索]
    C --> E{成功?}
    E -->|Yes| F[回答生成]
    E -->|No| G[第2層: 確認質問]
    D --> H{該当情報あり?}
    H -->|Yes| F
    H -->|No| G
    G --> I{情報取得成功?}
    I -->|Yes| C
    I -->|No| J[第3層: 人間エスカレーション]

第 1 层：知识库后备

如果不满足调用该工具的条件（无订单号、无发货信息等），请先搜索知识库。如果您可以用常见问题解答、产品规格、政策文档等静态信息来回答，请到此为止。

第 2 层：确认问题回退

如果知识库未提供答案，请向用户询问缺少的信息。

確認質問の例:
- 「注文番号をお教えいただけますか？注文確認メールに記載されています。」
- 「お問い合わせの製品名をお聞かせください。」
- 「いつ頃ご注文されましたか？おおよその日付で構いません。」

重要的是不要调用工具来猜测缺失的信息。如果您使用错误的订单号进行搜索，您将面临返回他人信息的风险。

第 3 层：人为升级

如果出现以下任何情况，请立即上报给人工操作员：

条件	检测方法
顾客负面情绪强烈	LLM 的情感分析
提及法律诉讼	关键词检测+LLM判断
三个或更多失败的工具调用	计算迭代次数
退款金额超过阈值	检查工具返回值
无法验证身份	工具调用结果的差异

会话内存管理

内存窗口设计

Dify Agent 节点的内存设置允许您控制保留的对话轮数（窗口大小）。设置适当的窗口大小与答案质量和成本/延迟之间的平衡直接相关。

场景	推荐的窗口尺寸	原因
单身常见问题	2-3 圈	较少依赖于上下文
订单查询	4-6 圈	需要提供订单号和产品名称参考
处理退货和投诉	6-8 圈	了解流程很重要
复杂的技术支持	8-10 圈	步骤的上下文很重要

窗口大小权衡

如果太大：由于不相关的过去信息，导致令牌成本增加、延迟增加、答案准确性降低
如果太小：无法解决您之前提到的问题，再次请求相同的信息。

对于长对话会话，使用“摘要机制”是有效的，该机制将超出窗口大小的对话转换为摘要文本并将其包含在上下文中。

多语言支持的实现点

语言检测和切换

LLM具有自动检测输入语言并以相同语言做出响应的能力。但需要注意以下几点。

积分	对策
混合输入（日语/英语等）	在说明中指定以主要语言回答
语言切换检测	如果使用的语言与上一回合不同，请调整为新语言
工具输出语言	如果 API 响应是英语，请将响应翻译成用户的语言
专有名词的处理	产品和公司名称应以其原始语言使用

多语言知识库

方法	优势	缺点
按语言分类的知识库	针对每种语言优化的答案	维护成本高
单个 KB（主要语言）	维护方便	小语种搜索准确率下降
单个 KB + 嵌入的多语言支持	良好的平衡性	取决于嵌入模型的多语言性能

推荐的方法是使用多语言嵌入模型搜索单个知识库（日语+英语）。 multilingual-e5-large和bge-m3等模型支持跨语言的语义搜索。

选择代理策略

函数调用与 ReAct

项目	函数调用	反应
工作原理	LLM 结构和输出工具调用	思考→行动→观察循环
准确度	高（适用于兼容型号）	取决于型号
兼容型号	GPT-4o、Claude、Gemini等	大多数LLM
调试	可通过工具调用日志进行追踪	可视化思维过程
推荐用途	生产经营	原型/调试

建议在实际客户支持操作中使用函数调用。可以预期工具调用的高精度和可预测的行为。

设置最大迭代次数

限制代理重复工具调用的最大次数。客户支持建议 3-5 次。

少于3次：无法回应复杂询问
超过5次：无限循环风险、延迟增加、客户等待时间增加

运行监控

要监控的指标

指标	目标值	警报条件
自动解析率	60-70%	一星期低于50%
平均响应时间	3秒内	超过 5 秒
升级率	20-30%	超过 40%
工具调用成功率	超过95%	低于 90%
客户满意度 (CSAT)	4.0/5.0或以上	小于 3.5

实施步骤

相	期间	内容
第一阶段	2 周	常见问题解答仅限自动应答。知识库+简单的聊天机器人。
第二阶段	1 个月	切换到代理节点。添加了订单搜索和交付跟踪工具。
第三阶段	1-2个月	添加了升级票证创建。实施后备策略。
第四阶段	继续	扩展多语言知识库。通过分析对话日志改进提示工具。

总结

在设计多语言客户支持代理时，语言支持并不是一个差异化因素，因为它可以通过LLM的基本功能来实现。以下三点才是真正考验设计质量的。

工具调用链的稳定性：具体描述工具，明确调用条件。
清晰的后备策略：三层设计：知识库→审查问题→人员升级
正确管理会话内存：根据场景设置Window Size并使用汇总机制

Dify 的代理节点允许您通过 GUI 来配置函数调用/ReAct 选择、工具定义、内存设置和最大迭代次数，为构建企业级客户支持代理提供充分的基础。

HR 入职文档处理流程：从使用 Dify Workflow 进行 PDF 分析到 HR 系统集成的实施指南

简介

在新员工入职过程中，人力资源部门需要处理大量的文件。简历、居民记录、个人编号通知卡、银行账户结单、养老金笔记本副本、各种誓言——从这些文件中准确提取必要信息并将其登记到人力资源系统中，每人需要几十分钟到一个小时。 4月份的大批量招聘期间，这项工作密集发生，给人力资源部门造成了瓶颈。

在本文中，我们将介绍如何使用 Dify 的 Workflow 设计和实现一个端到端管道，自动从 PDF/图像格式的加入文档中提取信息，并经过验证和人工验证后将其注册到人力资源系统中。

背景和问题

###入公司办理文件实况

作业	详情
文件多样性	文本 PDF、扫描 PDF 和照片图像的混合
手写信息的存在	地址变更通知和银行账户通知表格包含手写信息
转录错误的风险	手动转录可能会导致姓名汉字、帐号和地址错误
个人信息保密	处理マイナンバー、帐户信息等存在安全限制。
旺季集中	4月份将同时聘用数十名应届毕业生加入公司
文件不完整/不充分	如果提交的文件有任何缺陷，您必须将其退回并重新提交。

流水线的优点

项目	手工加工	Dify管道
每人处理时间	30-60 分钟	5-10 分钟（包括人工确认）
转录错误率	2-5%	低于0.5%（经人工验证）
检测文档缺陷的时机	输入期间检测到	上传后立即自动检测
流程追溯	纸质	记录所有步骤

整体架构

flowchart TD
    A[書類アップロード<br>PDF / 画像] --> B[ファイル振分けノード]
    B --> C{ファイル形式判定}
    C -->|テキスト PDF| D[テキスト抽出]
    C -->|スキャン PDF / 画像| E[VLM / OCR 処理]
    D --> F[パラメータ抽出ノード<br>構造化 JSON 出力]
    E --> F
    F --> G[フィールド検証ノード]
    G --> H{検証結果}
    H -->|全項目 OK| I[Human-in-the-Loop<br>最終確認]
    H -->|不備あり| J[不備通知<br>再提出依頼]
    I --> K{承認?}
    K -->|Yes| L[人事システム連携<br>HTTP Request]
    K -->|修正| M[修正入力]
    M --> G
    L --> N[処理完了・ログ記録]

节点设计细节

节点1：文件接收（起始节点）

Dify Workflow 的起始节点接受以下输入。

变量名	类型	必填	描述
`employee_name`	文字	是的	未来雇员姓名
`employee_id`	文字	是的	员工编号（接受临时编号）
`entry_date`	日期	是的	预计加入日期
`documents`	文件[]	是的	连接文档（多个文件）
`document_types`	文字	没有	每个文件的文档类型（逗号分隔）

节点2：文件格式确定/分发

分发每个上传文件的处理方法。

判定ロジック:
- 拡張子が .pdf でテキスト抽出可能 → テキスト PDF ルート
- 拡張子が .pdf でテキスト抽出不可 → スキャン PDF ルート（VLM）
- 拡張子が .jpg / .png / .heic → 画像ルート（VLM）

节点3：文本提取

用于扫描 PDF/图像

使用 Dify 的 Vision 兼容模型（GPT-4o、Claude 等）直接从图像中提取结构化数据。使用VLM直接提取相对于传统OCR管道（图像→字符识别→后处理）具有以下优势：

项目	传统OCR	VLM直接提取
支持表格格式	需要单独的结构分析	理解并提取表结构
手写字符	准确度显着降低	可以根据上下文进行估计
复合布局	需要布局分析	直观地理解和处理
存在印章印记/身份证照片	识别错误的原因	可以确定哪些因素应该被忽略

节点4：参数提取（LLM节点）

从提取的文本或图像中输出结构化 JSON。

System Prompt:
あなたは HR 書類処理の専門アシスタントです。
以下の入社書類から、指定されたフィールドを正確に抽出してください。

【抽出フィールド】
{
  "personal_info": {
    "full_name_kanji": "氏名（漢字）",
    "full_name_kana": "氏名（カタカナ）",
    "date_of_birth": "生年月日（YYYY-MM-DD）",
    "gender": "性別",
    "nationality": "国籍"
  },
  "address": {
    "postal_code": "郵便番号（XXX-XXXX）",
    "prefecture": "都道府県",
    "city": "市区町村",
    "street": "番地以降",
    "building": "建物名・部屋番号"
  },
  "contact": {
    "phone": "電話番号",
    "email": "メールアドレス",
    "emergency_contact_name": "緊急連絡先氏名",
    "emergency_contact_phone": "緊急連絡先電話番号",
    "emergency_contact_relationship": "続柄"
  },
  "bank_account": {
    "bank_name": "銀行名",
    "branch_name": "支店名",
    "account_type": "口座種別（普通/当座）",
    "account_number": "口座番号",
    "account_holder": "口座名義（カタカナ）"
  },
  "tax_social": {
    "my_number": "マイナンバー（12桁）",
    "pension_number": "基礎年金番号",
    "health_insurance_number": "健康保険証番号"
  }
}

【重要ルール】
1. 書類に記載がないフィールドは null を設定すること
2. 読み取りに自信がないフィールドは
   {"value": "読み取り値", "confidence": "low", "note": "理由"}
   の形式で出力すること
3. マイナンバーは12桁の数字であること。桁数が合わない場合は
   confidence を "low" に設定すること
4. 絶対に推測や補完を行わないこと

将 value、confidence（高/中/低）、source_file 分配给每个字段。低置信度的字段被设计为在随后的人机循环中由人类检查。

节点 5：字段验证

对提取的数据执行基于规则的验证。

検証ルール:
1. 郵便番号: XXX-XXXX 形式であること
2. 電話番号: 0X-XXXX-XXXX または 0XX-XXX-XXXX 形式
3. メールアドレス: 有効な形式であること
4. マイナンバー: 12桁の数字であること（※ 重要：原则上不应入 LLM —— 详见后面"マイナンバー处理"章节）
5. 口座番号: 通常 7 桁の数字（**ゆうちょ銀行は「記号 5 桁 - 番号 8 桁」形式で異なる**；ネット銀行も口座番号桁数が異なる場合あり——銀行コードに基づき分岐検証する）
6. 生年月日: **雇用形態に応じた最低就業年齢を満たすこと**（正社員は通常 18 歳以上、アルバイト・高卒採用は中学卒業後の 4 月以降であれば 15 歳から可——労働基準法第 56 条）
7. 必須フィールド: 氏名、住所、銀行口座が全て入力済みであること

Dify Workflow 允许您使用代码节点 (Python/JavaScript) 实现这些验证。

# コードノードでの検証例
import re
import json

def validate_fields(data):
    errors = []
    warnings = []
    
    # 郵便番号チェック
    postal = data.get("address", {}).get("postal_code", "")
    if postal and not re.match(r"^\d{3}-\d{4}$", postal):
        errors.append({
            "field": "address.postal_code",
            "value": postal,
            "message": "郵便番号の形式が不正です（XXX-XXXX）"
        })
    
    # マイナンバーチェック
    my_number = data.get("tax_social", {}).get("my_number", "")
    if isinstance(my_number, dict):
        # confidence が low の場合
        warnings.append({
            "field": "tax_social.my_number",
            "value": my_number.get("value"),
            "message": my_number.get("note"),
            "requires_human_review": True
        })
    elif my_number and not re.match(r"^\d{12}$", str(my_number)):
        errors.append({
            "field": "tax_social.my_number",
            "value": my_number,
            "message": "マイナンバーは12桁の数字である必要があります"
        })
    
    # 口座番号チェック
    account = data.get("bank_account", {}).get("account_number", "")
    if account and not re.match(r"^\d{7}$", str(account)):
        errors.append({
            "field": "bank_account.account_number",
            "value": account,
            "message": "口座番号は7桁の数字である必要があります"
        })
    
    return {
        "is_valid": len(errors) == 0,
        "errors": errors,
        "warnings": warnings,
        "requires_human_review": len(warnings) > 0
    }

节点 6：人在环

在以下情况下请求人力资源代表确认：

触发条件	严重性	回应
字段 `confidence: low` 存在	高	突出显示该字段并请求确认
存在验证错误	高	显示错误详细信息并请求更正
必填字段为空	高	请求重新提交丢失的文件
提取マイナンバー/帐号	必填	机密信息必须始终由人工进行最终检查
姓名中的汉字和假名不匹配	中等	检查拼写是否正确

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
入社書類処理: 確認が必要です
━━━━━━━━━━━━━━━━━━━━━━━━━━━━

■ 対象者: 山田 太郎（社員番号: EMP-2026-0501）
■ 入社予定日: 2026-05-01

■ 要確認項目:

  ⚠ マイナンバー: 123456789012
    → スキャン品質が低く、3桁目が不明確です。
       原本を確認してください。

  ⚠ 基礎年金番号: 未検出
    → 年金手帳のコピーが提出されていない可能性があります。

■ 抽出結果（全項目）:
  [構造化データを表示]

■ アクション:
  [承認] [修正して承認] [書類再提出依頼]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━

###节点7：人力资源系统联动（HTTP Request节点）

将经过验证的数据从 Dify Workflow 的 HTTP 请求节点发送到 HR 系统的 API。由于结构化 JSON 是按原样 POST 的，因此字段映射设计很重要。

链接系统的示例：

系统	合作方式	报名详情
人力资源大师（COMPANY等）	休息 API	基本信息/地址/家庭信息
薪资系统（免费人事劳动事务等）	休息 API	银行账户/社保信息
考勤系统（KING OF TIME等）	休息 API	员工人数/部门
活动目录 / IdP	LDAP / SCIM	账户自动创建
Google Workspace / Microsoft 365	管理API	电子邮件地址/小组分配

安全设计

个人信息的处理

就业文件包含需要特别严格管理的个人信息，例如マイナンバー和银行帐户信息。

⚠️ 法律警告 — マイナンバー处理

マイナンバーは番号法で「特定個人情報」として定義され、漏えい時には刑事罰を含む厳しい処分が科される。本書では以下を強く推奨：

原则不入 LLM：マイナンバー字段在 OCR / VLM 抽出后必须由人事担当が手入力で確認，不要将含マイナンバー的画像 / 文本投入云端 LLM API（哪怕“学習しない“設定であっても）

如确需 LLM 辅助：仅限 self-hosted Dify + 国内 region + 本地 VLM（不出境）+ 强制マスキング（中间 8 桁置换为 ✕）+ 全程監査ログ

プロンプトに「绝对不要推测」だけでは合规要件を満たさない —— 上記 1 / 2 のいずれかが必要

详见経済産業省「マイナンバーガイドライン」+ 個人情報保護委員会「特定個人情報の適正な取扱いに関するガイドライン」。

对策	实施方法
通讯加密	Dify 与各系统之间的 HTTPS / TLS 1.3
临时数据存储的限制	完成工作流程执行后自动删除临时文件
访问控制	使用 Dify 工作区权限限制处理人员
审核日志	所有操作（上传、提取、确认、注册）均记录在日志中
本地部署	如果保密性高，在封闭网络上运行 Dify 自托管版本
マイナンバー的特殊管理	优先：人事担当が手入力；如必须 OCR 抽出，仅 self-hosted + マスキング + 監査ログ三件套同时满足

如果由于个人信息保护的原因无法将マイナンバー和帐户信息发送到外部云端，您可以通过在封闭网络上运行 Dify 自托管版本（Docker Compose）并与本地 VLM 结合来完全避免向外部发送数据。

错误处理

可能出现的错误及对策

错误	检测方法	纠正措施
PDF 已加密	解析文件时出错	请求解密
图像分辨率低	VLM信心普遍较低	请求重考/重新扫描
意外的文档类型	文档类型确定中“未知”	升级至人力资源
人力资源系统API错误	通过 HTTP 响应代码检测	重试 3 次后存储在保留队列中
提取数据不一致	验证节点中检测到不一致	发送以供人工确认

实施步骤

相	期间	内容
第一阶段	2 周	仅用于简历的 PoC。验证文本提取→JSON转换的准确性。
第二阶段	2-4 周	扩大文件种类（账户通知书、在留卡等）。添加了对 VLM 扫描的支持。
第三阶段	1-2个月	实施验证节点/人在环。 API与人力资源系统集成。
第四阶段	继续	开发批处理。监控和提高提取精度。

总结

HR入职文档处理流程的核心不是“AI能读PDF吗？”，而是以可追溯、可重复的方式自动化分析、提取、验证、人工验证、系统注册等一系列流程。 Dify Workflow 提供了一个平台，允许您直观地设计和操作以下所有内容：文件输入接收、使用 VLM/OCR 提取信息、使用代码节点进行验证、使用人机交互进行人工验证以及使用 HTTP 请求节点进行外部系统链接。

以下三个设计原则尤为重要。

结构化输出：以字段JSON形式输出，而不是自然文本，并分配confidence和source
需要人工验证：高度机密字段（マイナンバー、帐号）必须始终由人工进行最终检查。
安全设计：考虑采用自托管版本，并根据个人信息的处理方式限制数据的临时存储。

通过遵循这些原则，您可以创建一个确保准确性和安全性的管道，同时显着减轻人力资源部门在繁忙时期的文档处理负担。

[LangGenius 社内事例] 在 IDE 里自助查生产数据：LangGenius 内部打造的 Ops Smart Assistant

简介

这里先做一个术语说明：产品名 Ops Smart Assistant 里的 “Ops” 就是 Operations 的简写，对应中文的运维——公司里负责生产环境、服务器、监控、日志这些基础设施的角色。下面正文里统一用“运维“来指这些同事，产品名本身保留英文。

生产环境一旦出问题，一分钟都很贵。但真正在写代码的开发者，往往既没有 Grafana / Sentry / Kubernetes 的查询权限，也不熟悉 PromQL。结果是一张老剧本：开 ticket → 在运维频道里 @ 人 → 等。与此同时，运维同事一天大半时间花在重复回答同一类问题上，真正的基础设施工作反而被挤压。

LangGenius 自己也踩过这个坑。于是我们用 Dify 搭了一个面向内部工程师的“Ops Smart Assistant“：用户只需要用自然语言问一句，助手自动把问题路由到正确的后端工具，再把仪表盘截图和 AI 分析一起送回用户熟悉的入口（Cursor / VS Code / Web）。

本文把我们自己跑下来的这套使用模式和设计取舍整理出来，作为 LangGenius 内部一个真实发生、持续在用的 use case 记录。

背景与问题

“等待税“是真实存在的

角色	遇到的痛点
开发者	查一条简单的服务指标，要开 ticket、切多个 dashboard，半天过去了
运维（Ops）工程师	每天几十条重复问题占用带宽，基础设施建设进度被持续稀释
团队整体	故障第一分钟的响应能力被“权限+熟练度“两道墙锁住

为什么传统 ChatOps 不够用

传统 ChatOps 机器人通常是“命令式“的：/metrics billing cpu 24h 这种固定语法。对偶尔才查一次生产的开发者来说，记命令本身就是一道门槛。更关键的是，返回结果往往只是一张图或一段 JSON，没有解读，开发者拿到之后还是要去问人。

我们想要的是一个“懂人话、会路由、能解释“的前端：开发者怎么在 Slack 里描述问题，就怎么在这里问。

为什么适合用 Dify 来做

Dify 在这个场景里有几个天然契合的点：

自然语言前端 + 工具编排后端：开发者只面对一个自然语言入口，路由、取数、合成这些事交给后端处理。
统一的权限边界：工具调用集中在 Dify 侧，后端凭证不落到客户端，便于审计和收敛爆炸半径。
多入口复用：同一个 Dify 应用可以同时支撑 Cursor 插件、VS Code 扩展和 Web 页面，不用为每个入口重写一套逻辑。
结果可组合：能把“仪表盘截图 + AI 分析“这样的复合回答一次性拼出来，而不是让用户自己再做二次加工。

工作方式：从使用者视角

用自然语言问。 在 IDE 里直接输入一句 “最近 24 小时 billing 服务的 CPU 使用率怎么样？” ，不需要记命令，不需要切窗口。
系统自动路由。 助手判断这是一个指标类问题，调起 metrics 工具组，而不是去查日志。
图文一起回。 拿到的是一张 Grafana 仪表盘截图加上一段 AI 生成的解读，秒级返回。
在熟悉的地方收答案。 不强迫开发者换工具，Cursor、VS Code、Web 三端都能用同一套后端。

对开发者来说，体验上的变化是：“查生产“这件事从一件要排期的事，变成一件随手做的事。

落地效果

维度	之前	现在
查询耗时	数小时级（等回应 + 自己切 dashboard）	30 秒级
运维重复问答	每日数十条	显著减少，带宽让位给更高价值工作
开发者体验	离开 IDE、切多个工具、等人	不离 IDE，自助完成

效果本身并不神奇，Dify 也不是唯一能做到这件事的工具。真正省下来的，是整个组织在“日常小问题“上的协同成本——这些成本平时看不见，但一旦被压掉就很难再回去。

我们自己沉淀下来的经验

跑到今天，我们自己总结出几条值得写下来的经验：

从只读场景起步。 先做查询，再考虑做任何写操作（重启 Pod、改配置）。权限边界一旦放开就很难收回来。
权限放在编排层，不要放在 Prompt 层。 不要指望模型“不去调危险工具“，而是从编排层面就不把危险工具暴露给用户入口。
给“我不知道“留一条明确的兜底路径。 宁可让助手说“这个问题我没把握，建议联系 oncall“，也不要让它用幻觉编一个像样的答案。
不要一上来追求 dashboard 覆盖度。 先覆盖最高频的 3-5 类问题，把这些打穿、打稳，剩下的长尾再逐步扩展。
把使用入口贴到开发者已经在的地方。 Cursor 插件 / VS Code 扩展 / Web——哪里是开发者的默认工作环境，入口就放在哪里。如果要他们多记一个新工具，大概率不会用。

小结

Ops Smart Assistant 本质上不是一个新工具，而是 LangGenius 把自然语言入口、工具编排、结果合成这三件事用 Dify 串起来，让“查生产“这件小事在内部不再需要跨人协作。它压掉的是开发者和运维之间一段平时看不见的隐性成本——先做查询，再谈闭环；先服务开发者，再服务组织，这是我们自己跑下来最想留给后来者的一句话。

知识库搜索返回不相关的结果：分块策略、嵌入模型和 Top-K/Score 阈值的联合调优

简介

尽管 Dify 的知识库确实有文档，但用户的问题却得到了不相关的答案——这是企业部署中最常报告的问题之一。许多团队尝试先修复提示，但根本原因往往在提示之前的搜索层。

本文重点介绍了 Dify 知识库搜索的三个要素：Top-K、Score Threshold 和 Rerank 模型，并讲解了包括分块策略和嵌入模型选择在内的综合调优方法。

症状

如果您看到以下行为，则可能需要调整搜索图层。

症状	典型的表面图案
文档中写了却返回“信息未找到”	分数阈值太高或上下文被分块切断
引用与问题完全无关的段落	Top-K太大，混入噪音，不使用Rerank
多次点击类似内容会导致重要信息被埋没	多个知识库之间的重复，嵌入模型缺乏精度
日语问题返回英文文档片段	多语言嵌入的准确性问题，知识库不按语言分隔
即使对于同一个问题，每次搜索结果也会略有不同	搜索模式设置不一致，矢量搜索中近似搜索引起波动

参数	推荐值	笔记
块大小	500-1000 代币	日语每个字符大约 1-2 个标记
重叠	50-100 个代币	防止段落边界上的信息丢失
分割方式	基于段落的优先级	建议使用语义分割而不是自动分割（基于换行符）

型号	日本精度	维数	笔记
`text-embedding-3-large` (OpenAI)	高	3072	3072多语言支持，成本高
`text-embedding-3-small` (OpenAI)	中到高	1536	1536性价比好
`multilingual-e5-large`	高	1024	1024开源、自托管
`bge-m3` (BAAI)	高	1024	1024支持多种语言和长文本
`cl-nagoya/sup-simcse-ja-large`	日语专业	1024	1024日语单语准确率高

典型的错误配置模式和诊断

模式 1：Top-K 太小（Top-K = 1~2）

問題：ユーザーの表現とドキュメントの表現にギャップがある場合、
      正解チャンクが候補に入らずに漏れる
対策：Top-K を 5〜8 に拡大し、Rerank で絞り込む

模式 2：分数阈值太高（0.8 或更高）

問題：「該当する情報が見つかりません」が頻発する
      実際にはスコア 0.6〜0.7 の有用なチャンクが存在している
対策：閾値を 0.3〜0.5 に下げてから徐々に調整

模式 3：增加 Top-K 而不重新排序

問題：類似度スコアの低いノイズチャンクが大量に LLM に渡される
      コンテキストウィンドウが無関係な情報で埋まる
対策：Top-K を大きくするなら必ず Rerank を有効にする

模式 4：无需重新排名的混合搜索

問題：ベクトル検索と全文検索の結果がスコア体系の異なるまま混在
      統合的なランキングができず、結果の質が不安定
対策：ハイブリッド検索には Rerank を必ず併用する

解决方案

第 1 步：检查块的质量

首先，在 Dify 的知识库管理屏幕上直观地检查实际的块内容。

确认点：

一个块是否对应一个主题？
重要信息是否被切断？
是否有任何不必要的文本，例如页眉和页脚？

如果出现问题，请更改块设置并重新索引。

第 2 步：设置搜索模式和重新排名

推荐配置：

场景	搜索模式	重新排名	前 K	分数门槛
内部常见问题解答/手动搜索	混合动力	有效	3~5	0.5
技术文献检索	混合动力	有效	5~8	0.4
合同/法律文件检索	矢量	有效	3~5	0.6
错误代码/型号搜索	全文	不需要	3	0.3
多语言混合文档	混合动力	有效	8~10	0.4

步骤 3：选择 Rerank 模型

# Cohere Rerank（多言語対応、日本語精度高）
reranking_model:
  provider: cohere
  model: rerank-multilingual-v3.0

# Jina Rerank（軽量、コスト低）
reranking_model:
  provider: jina
  model: jina-reranker-v2-base-multilingual

第四步：逐步调整参数

推荐的调整步骤：

将 Top-K 设置为较大的值（8 到 10）并确保有足够的候选者。
将分数阈值设置为较低水平 (0.3)，以确保切割不会太粗糙。
启用重新排名以查看重新评分后最佳结果的质量
逐渐减少Top-K (5-6)
逐渐提高分数阈值 (0.4-0.5)
用真实的用户问题进行测试，检查准确性和噪音之间的平衡

步骤 5：检查工作流程节点中的搜索设置

工作流中的知识搜索节点允许您独立于知识库本身的设置来覆盖参数。如果这些双重设置不一致，就会导致意外行为。

# Workflow ナレッジ検索ノードの設定例
knowledge_retrieval:
  dataset_ids:
    - "dataset_abc123"
  retrieval_mode: "multiple"    # single / multiple
  top_k: 5
  score_threshold: 0.5
  reranking:
    enabled: true
    model: "rerank-multilingual-v3.0"

注意事项

1.知识库设计指南

坚持1个知识库=1个领域的原则。避免在一个知识库中混合来自不同领域的文档
在上传文档之前执行预处理以删除不必要的页眉、页脚和目录页面
定期对块质量进行采样并检查分割的有效性。

2. 嵌入模型选择清单

是否支持目标内容的主要语言？
日语技术术语和专有名词可以正确矢量化吗？
输入令牌的最大数量是否足以满足块大小？
成本和准确性之间的平衡是否符合运营要求？

3.搜索质量监控

建立一个系统来持续监控搜索结果的质量。

# 検索品質テストスクリプトの例
test_queries = [
    {"query": "有給休暇の申請方法は？", "expected_doc": "就業規則_休暇.pdf"},
    {"query": "VPN接続がタイムアウトする", "expected_doc": "IT_FAQ_ネットワーク.pdf"},
    {"query": "経費精算の締め日はいつ？", "expected_doc": "経理マニュアル.pdf"},
]

for test in test_queries:
    results = dify_api.knowledge_retrieval(
        query=test["query"],
        dataset_id="your_dataset_id",
        top_k=5
    )
    # 期待するドキュメントが上位に含まれているか確認
    hit = any(test["expected_doc"] in r["document_name"] for r in results)
    print(f"Query: {test['query']} -> {'PASS' if hit else 'FAIL'}")

4. 运行期间故障排除清单

知识库的块粒度是否合适？（检查是否太粗或太细）
完整的上下文是否由于块划分而断开？
Embedding 模型是否适合目标语言？
[ ]多个知识库之间是否存在相似内容重复的情况？
工作流节点的搜索设置与主知识库的设置是否不一致？
是否启用了重新排序模型（尤其是在混合搜索期间）？
分数阈值是否过于严格并排除有效结果？

总结

当搜索结果不合适时，首先要检查的不是“模型为什么出错”，而是“系统搜索了什么以及发现了什么”。 Dify 的知识库搜索是一个分块 → 嵌入 → 搜索模式 → Rerank → Top-K/Score Threshold 的多层流程，仅调整一层并不能产生足够的效果。

特别重要的是，当与 Rerank 关联时，Top-K 和 Score Threshold 的行为会发生变化。了解此规范并从检查块质量开始逐步调整，是实现稳定搜索精度的最短路径。

参考资料

-インデックス方法と検索設定を指定 | Dify Docs -Re-ranking | Dify Legacy Docs -Integrate Knowledge Base within Application | Dify Legacy Docs -GitHub Discussion #3171: Top-K and threshold usage in rerank stage

工作流节点超时频繁发生：超时设置、节点优化和异步模式实用指南

简介

一旦我们将 Dify 的工作流程投入生产，我们经常会遇到“节点超时”错误——许多企业团队都会遇到这种情况。虽然很容易简单地认为这是“模型响应缓慢”，但它实际上是整体流程设计、输入数据的大小、由于外部依赖而导致的响应时间以及缺乏重试策略的组合。

在本文中，我们将系统分析Workflow节点超时的原因，并讲解具体的解决方案，包括节点分裂、上下文优化、异步处理模式等。

症状

症状	可能发生的情况
LLM 节点过早中止，返回不完整的响应	输入长、指令复杂、上下文量大
HTTP请求节点超时	外部API响应慢，违反速率限制
整个 Workflow在几分钟后以错误结束	中间变量的扩展、串行节点的堆叠
超时仅在特定时间内增加	并发执行数增加，负载集中于外部服务
PDF/图像处理等流程不稳定	VLM处理、OCR、大文件分析

原因分析

了解工作流程执行约束

Dify 的 Workflow 不能无限消耗资源。官方环境变量文档中指定了以下限制：

环境变量	默认值	意义
`MAX_VARIABLE_SIZE`	`204800` (200KB)	单个变量的最大大小（字节）
`WORKFLOW_MAX_EXECUTION_STEPS`	`500`	工作流程的最大执行步骤数
`WORKFLOW_MAX_EXECUTION_TIME`	`1200`	最大工作流程执行时间（秒）
`HTTP_REQUEST_MAX_CONNECT_TIMEOUT`	`300`	HTTP请求节点连接超时（秒）
`HTTP_REQUEST_MAX_READ_TIMEOUT`	`600`	HTTP请求节点读取超时（秒）
`HTTP_REQUEST_MAX_WRITE_TIMEOUT`	`600`	HTTP请求节点写入超时（秒）

五层超时发生

flowchart TD
    A[タイムアウト発生] --> B{どのレイヤー?}
    B --> C[LLM応答遅延]
    B --> D[外部API遅延]
    B --> E[中間変数の肥大化]
    B --> F[同時実行数の飽和]
    B --> G[ファイル処理の長時間化]
    
    C --> C1[入力トークン過大]
    C --> C2[出力生成が長い]
    C --> C3[モデル選定が不適切]
    
    D --> D1[レート制限]
    D --> D2[外部サービス障害]
    D --> D3[タイムアウト設定不足]
    
    E --> E1[上流ノードの出力未圧縮]
    E --> E2[ループによる変数蓄積]
    
    F --> F1[Worker数不足]
    F --> F2[キュー詰まり]
    
    G --> G1[大容量PDF]
    G --> G2[VLM処理]
    G --> G3[OCR処理]

第 1 层：LLM 节点响应延迟

LLM 节点超时的最常见原因是输入上下文太大。

典型例：
- ナレッジベースから Top-K=10 で取得したチャンクをすべて LLM に投入
- 上流ノードの出力（数千トークン）をそのまま下流に伝搬
- 1つの LLM ノードに「抽出 → 要約 → フォーマット → 結論生成」を全部させる

估计输入大小和响应时间：

输入令牌的数量	GPT-4o 响应时间指南	Claude 3.5 Sonnet响应时间指南
1,000 或更少	2-5 秒	2-5 秒
5,000	5-15 秒	5-12 秒
20,000	15-40 秒	12-30 秒
50,000 或更多	40-120 秒	30-90 秒

第 2 层：外部 API/工具节点延迟

如果HTTP请求节点或自定义工具节点依赖于外部服务，则该服务的响应时间将成为瓶颈。

常见案例：

第三方 API 速率限制（429 请求过多）
数据库查询延迟
外部 SaaS 服务的维护窗口

第 3 层：中间变量膨胀

上游节点的输出直接传递到下游并在每个节点累积，这违反了 MAX_VARIABLE_SIZE 限制。

ノード A（LLM）→ 出力 5KB
  → ノード B（LLM）→ 入力 5KB + 出力 8KB = 13KB
    → ノード C（LLM）→ 入力 13KB + 出力 10KB = 23KB
      → ノード D（LLM）→ 入力 23KB + ...

第 4 层：文件处理特性

处理 PDF、图像和 VLM（视觉语言模型）的流程比基于文本的流程需要更多数量级的处理时间。

解决方案

###方案一：节点分裂（最有效）

不要在单个 LLM 节点上承担多项职责，而是按功能分隔节点。

之前（反模式）：

[単一LLMノード]
プロンプト: 以下のドキュメントを読み、
  1. 重要なポイントを抽出し
  2. 要約を作成し
  3. JSON形式でフォーマットし
  4. 推奨アクションを提案してください

之后（推荐模式）：

[ノード1: 抽出] → [ノード2: 要約] → [ノード3: フォーマット] → [ノード4: 推奨]

好处：

每个节点的输入/输出更小，降低超时风险
即使中间节点发生故障，您也只能重试该节点。
轻量级模型可用于轻型处理，高性能模型可用于重型决策。

解决方案 2：压缩上下文

# 悪い例：上流の全出力をそのまま渡す
llm_node:
  context: "{{node_a.output}}"  # 5000トークンの生テキスト

# 良い例：要約ノードを挟んで圧縮する
summary_node:
  model: gpt-4o-mini           # 軽量モデルで要約
  prompt: "以下を300字以内で要約: {{node_a.output}}"

llm_node:
  context: "{{summary_node.output}}"  # 300字程度に圧縮済み

解决方案 3：使用不同的模型

任务类型	推荐型号	原因
文本分类/路由	gpt-4o-mini / Claude 3.5 Haiku	速度快、成本低
摘要/信息提取	gpt-4o-mini / Claude 3.5 Sonnet	平衡
复杂的推理和判断	gpt-4o / Claude Opus	强调准确性
代码生成/分析	Claude 3.5 Sonnet	代码处理能力强

###方案四：HTTP请求节点超时设置

# HTTP リクエストノードの設定
http_request:
  url: "https://api.example.com/process"
  method: POST
  timeout:
    connect: 10        # 接続タイムアウト（秒）
    read: 30           # 読み取りタイムアウト（秒）
    write: 30          # 書き込みタイムアウト（秒）
  retry:
    max_attempts: 3    # 最大リトライ回数
    backoff: exponential

解决方案 7：异步处理模式

对于本质上需要较长处理时间的流，不要期望同步响应并采用异步处理模式。

sequenceDiagram
    participant User as ユーザー
    participant API as Dify API
    participant WF as Workflow
    participant CB as コールバック

    User->>API: タスク投入（POST /workflows/run）
    API->>User: task_id を即時返却
    API->>WF: バックグラウンド実行開始
    WF->>WF: ノード1 → ノード2 → ... → ノードN
    WF->>CB: 完了通知（Webhook）
    User->>API: 結果取得（GET /workflows/{task_id}）
    API->>User: 処理結果を返却

异步 Dify API 调用示例：

# Workflow をブロッキングモードで実行（同期）
curl -X POST 'https://api.dify.ai/v1/workflows/run' \
  -H 'Authorization: Bearer {api_key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": {"query": "処理対象テキスト"},
    "response_mode": "blocking"
  }'

# Workflow をストリーミングモードで実行（非同期）
curl -X POST 'https://api.dify.ai/v1/workflows/run' \
  -H 'Authorization: Bearer {api_key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": {"query": "処理対象テキスト"},
    "response_mode": "streaming"
  }'

注意事项

1. 工作流程设计审查清单

三个或更多职责是否集中在一个 LLM 节点上？
你知道上游节点的输出大小吗？
是否为外部 API 调用配置了超时和重试？
文件处理节点是否包含在串行链中？
条件分支是否跳过了不必要的进程？

2. 进行负载测试

在投入生产之前，请在以下条件下进行测试：

# 並行実行テスト（10件同時）
for i in $(seq 1 10); do
  curl -X POST 'https://api.dify.ai/v1/workflows/run' \
    -H 'Authorization: Bearer {api_key}' \
    -H 'Content-Type: application/json' \
    -d '{"inputs": {"query": "テスト入力'$i'"}, "response_mode": "blocking"}' &
done
wait

3. 监控和警报

定期查看工作流程执行日志并监控以下指标：

指标	警告阈值	对应动作
平均节点执行时间	超过 30 秒	考虑分裂节点
超时率	超过 5%	识别并优化罪魁祸首节点
中间变量的平均大小	超过 100KB	上下文压缩简介
工作流程整体执行时间	超过5分钟	考虑去同步

4. 故障排除步骤

发生超时时建议的调查顺序：

日志中识别：检查哪个节点出现超时
Check input size：检查输入变量到对应节点的大小
检查外部依赖：检查外部API的响应时间和状态
检查并发执行：检查同一时间段内Workflow执行的数量
考虑分裂可能性：考虑是否可以分裂/简化相应的节点。
考虑异步：如果处理本质上是长时间运行的，请切换到异步模式

总结

工作流程超时问题不是“模型速度问题”，而是“流程设计问题”。真正稳定的流程来自于通过节点分裂实现的职责分离、通过上下文压缩控制输入大小、失败时重试和降级路径以及针对固有的长操作的异步设计。

简单地增加环境变量的超时值只是权宜之计。根本的解决办法在于审查工作流程设计本身。

参考资料

-Environment Variables - Dify Docs -Dify と Gradio で作る PDF 処理ワークフローアプリケーション -Dify x VLM であらゆる画像・PDF を JSON に変換する

同一问题每次回答不一致

#同一个问题每次都有不同的答案：温度、系统提示、搜索稳定性调整

简介

“我问同样的问题，但每次都得到不同的答案”——这是在企业环境中运行 Dify 的团队最常见的抱怨之一。从用户的角度来看，这个问题似乎是一个“不稳定的系统”，但实际上并不意味着系统坏了，而是表明LLM的输出控制设计不当。

在本文中，我们分析了导致答案差异的三个层面（LLM 参数、提示结构和搜索稳定性），并解释了实现稳定、企业质量输出的具体技术。

症状

症状	示例
事实是一样的，但每次的表述却不同	“带薪休假每年20天”和“每年授予的带薪休假天数为20天”
答案的结构和顺序发生变化	项目符号的顺序发生变化
同一个问题引用了不同的信息	因为每次搜索结果都会改变，所以引用了不同的chunk
答案长度差异很大	同样的问题返回 3 行答案和 15 行答案
很少会返回矛盾的答案	“可能”与“不可能”混杂

原因分析

答案的差异不是单一原因造成的，而是三层因素共同作用的结果。

flowchart TD
    A[回答の不一致] --> B[レイヤー1: LLMパラメータ]
    A --> C[レイヤー2: プロンプト構造]
    A --> D[レイヤー3: 検索の安定性]
    
    B --> B1[Temperature が高い]
    B --> B2[Top-P が高い]
    B --> B3[Presence/Frequency Penalty]
    
    C --> C1[役割定義が曖昧]
    C --> C2[出力形式が未指定]
    C --> C3[判断基準が不明確]
    
    D --> D1[検索結果が毎回異なる]
    D --> D2[Top-K が大きすぎる]
    D --> D3[Rerank スコアの揺れ]

第 1 层：LLM 参数的影响

温度（最重要）

温度是控制 LLM 输出中概率分布“平坦度”的参数。

温度值	行为	适用场景
0.0	0.0近确定性输出（始终选择最可能的标记）	分类、数据提取、代码生成
0.1~0.3	轻微变化，同时保持高稳定性	常见问题解答、手册参考、合同检查
0.4~0.7	适度变化	一般写作、电子邮件起草
0.8~1.0	高创造力	头脑风暴、文案写作
超过1.0	非常不同（不可预测）	通常不使用

重要：设置温度 = 0.0 并不能保证输出完全相同。由于LLM提供商的基础设施中浮点运算和批处理的差异，可能会出现轻微的波动。

Top-P（核采样）

Top-P 只考虑累积概率达到指定值的 token 候选者。当与温度结合使用时，这两个参数都会影响输出多样性。

# 安定性を最大化する設定例
llm_settings:
  temperature: 0.1
  top_p: 0.9          # 1.0に近いほど制約が少ない
  max_tokens: 2048
  presence_penalty: 0.0
  frequency_penalty: 0.0

配置 Dify LLM 节点

Dify 的 LLM 节点允许为每个节点单独配置这些参数。

# Workflow LLM ノードの設定
llm_node:
  model: gpt-4o
  temperature: 0.1        # 安定性重視
  top_p: 0.95
  max_tokens: 1024
  system_prompt: |
    あなたは社内規定に基づいて回答するアシスタントです。
    ...

第 2 层：提示结构的影响

仅降低温度并不能保证稳定性。如果提示的结构不明确，模型在决定如何回答时具有很高的自由度，并且每次都会使用不同的方法进行响应。

不稳定提示示例：

あなたは社内のヘルプデスクです。
ユーザーの質問に丁寧に答えてください。

在此提示符下，以下内容未定义：

答案的格式（项目符号或段落）
信息来源的优先级（知识库信息或一般知识）
大约答案长度
未找到信息时的行为
是否允许猜测或完成。

稳定提示示例：

あなたは株式会社ABCの社内ITヘルプデスクアシスタントです。

## 回答ルール
1. 回答は必ず「結論」「詳細」「参考情報」の3セクションで構成すること
2. 回答の根拠は、提供されたコンテキスト情報のみに基づくこと
3. コンテキストに該当する情報がない場合は「この質問についての情報は
   現在のナレッジベースに含まれていません。IT部門（内線: 1234）に
   お問い合わせください」と回答すること
4. 推測や一般的な知識に基づく補完は行わないこと
5. 回答は200文字以内に収めること

## 出力フォーマット
### 結論
[1〜2文で端的に回答]

### 詳細
[必要に応じて箇条書きで補足]

### 参考情報
[参照したドキュメント名を記載]

第 3 层：搜索稳定性

使用知识库时，如果每次为同一问题搜索不同的块，则传递给 LLM 的上下文会发生变化，结果答案也会有所不同。

搜索结果不稳定的原因：

原因	机制
向量搜索的近似	ANN（近似最近邻）算法并不能保证完美的再现性
Top-K 太大	边界附近的块可能会被替换
有许多具有相似分数的块	分数差异较小导致排名变化
搜索多个知识库	不同知识库结果的合并顺序不稳定

解决方案

步骤 1：适当设置温度

每种场景的推荐设置：

应用	温度	顶P	原因
内部常见问题	0.0～0.1	0.9	0.9事实准确传达是重中之重
合同审查	0.0	0.0 0.9	0.9法律风险要求的一致性
技术文档解答	0.1~0.2	0.95	0.95准确性与自然性之间的平衡
电子邮件起草	0.3-0.5	0.95	0.95表达方式的适当变化
创意产生	0.7～0.9	0.95	0.95需要多样化的想法

第 2 步：将结构约束纳入提示中

强制结构化输出：

## System Prompt

以下のフォーマットに従って回答してください。
フォーマットから逸脱しないでください。

回答フォーマット:
---
【判定】: [該当 / 非該当 / 判定不能]
【根拠】: [コンテキストから引用した該当箇所]
【補足】: [必要な場合のみ、1〜2文で補足]
---

强制 JSON 输出（在工作流节点之间传递数据）：

以下のJSON形式で出力してください。JSON以外のテキストは出力しないでください。

{
  "category": "技術質問 | 手続き質問 | クレーム | その他",
  "confidence": 0.0〜1.0,
  "answer": "回答テキスト",
  "source": "参照したドキュメント名"
}

步骤 3：确保搜索稳定性

# 安定性重視のナレッジベース検索設定
knowledge_retrieval:
  retrieval_mode: hybrid
  top_k: 3                    # 小さめに設定して境界の揺れを抑制
  score_threshold: 0.6        # 高めに設定して低スコアの不安定チャンクを除外
  reranking:
    enabled: true
    model: rerank-multilingual-v3.0

提高搜索稳定性的要点：

减少Top-K：如果Top-K=3，前三名的结果会比较稳定。如果设置Top-K=10，底部的替换会更加激烈。
将分数阈值设置得较高：分数较低的区块更容易因分数波动而导致排名波动。
启用Rerank：Rerank模型在一致的基础上重新评分，提高结果的稳定性。
在单个知识库中搜索：合并多个知识库会增加结果的稳定性

步骤 4：通过输出后处理增强稳定性

在 LLM 输出中添加后处理可以吸收表面波动。

flowchart LR
    A[ユーザー質問] --> B[ナレッジ検索]
    B --> C[LLM生成]
    C --> D[フォーマット検証ノード]
    D -->|OK| E[回答返却]
    D -->|NG| F[フォーマット修正ノード]
    F --> E

使用代码节点进行格式验证的示例：

import json

def main(text: str) -> dict:
    """LLM出力が指定フォーマットに準拠しているか検証する"""
    try:
        result = json.loads(text)
        required_keys = ["category", "confidence", "answer", "source"]
        
        for key in required_keys:
            if key not in result:
                return {
                    "valid": False,
                    "error": f"必須キー '{key}' が欠落しています",
                    "original": text
                }
        
        if result["confidence"] < 0 or result["confidence"] > 1:
            return {
                "valid": False,
                "error": "confidence の値が範囲外です",
                "original": text
            }
        
        return {"valid": True, "data": result}
    
    except json.JSONDecodeError:
        return {
            "valid": False,
            "error": "JSON パース失敗",
            "original": text
        }

步骤 5：利用种子值（适用于支持的模型）

一些 LLM 提供商支持 seed 参数，该参数允许您指定相同的种子以提高输出的可重复性。

# OpenAI API の seed パラメータ（対応モデルの場合）
llm_settings:
  model: gpt-4o
  temperature: 0.0
  seed: 42                # 固定シード値

注意：种子参数“增加”输出的再现性，但不“保证”完整的同一性。此外，如果无法直接从 Dify 节点设置屏幕设置种子，则需要通过 API 进行自定义设置。

注意事项

1.应用设计的参数设计文档

构建新的 Dify 应用程序时，请提前决定以下事项：

项目	决定	示例
温度	价值取决于用途	常见问题解答：0.1，草稿：0.5
输出格式	固定模板	JSON/3 节结构
答案长度	上限和下限	100-300 个字符
缺乏信息时的行为	固定短语	“暂无信息”
猜测的可能性	允许/禁止	不允许

2. 执行回归测试

定期询问同一组问题并检查答案的一致性。

import hashlib

def test_consistency(api_client, query: str, runs: int = 5):
    """同じ質問を複数回実行し、回答の一貫性を確認する"""
    answers = [api_client.chat(query=query)["answer"] for _ in range(runs)]
    hashes = [hashlib.md5(a.encode()).hexdigest() for a in answers]
    unique = len(set(hashes))
    rate = 1 - (unique - 1) / runs
    return {"query": query, "unique_answers": unique, "consistency_rate": rate}

for q in ["有給休暇の申請方法は", "経費精算の締め日はいつ", "VPN接続できない場合の対処法"]:
    r = test_consistency(client, q)
    print(f"[{'OK' if r['consistency_rate']>=0.8 else 'WARN'}] {q}: {r['consistency_rate']:.0%}")

3.稳定性检查表

温度设置是否符合目的？
是否在系统提示符下指定输出格式？
行为是否定义为“如果没有信息”？
提示中是否明确说明是否可以猜测或补全？
知识库搜索中的Top-K 是否是最低限度的必要条件？
分数阈值设置得足够高吗？
是否启用重新排名？
是否有定期回归测试的机制？

总结

当出现差异时，仅关注温度是不够的。要实现真正的企业品质、稳定输出，必须统筹设计以下三层：

LLM参数层：根据目的设置Temperature，抑制不必要的发散
提示结构层：显式定义输出格式、判断标准、拒绝条件，限制模型自由度。
搜索稳定层：关注Top-K，设置更高的分数阈值，并通过Rerank持续重新评分。

在这三层中，改进提示结构往往是最有效的。如果降低温度不能解决问题，我们建议首先检查提示的结构。

参考资料

-LLM ノード | Dify Docs（日本語） -Dify x Claude でつくる2分週報 AI -現場で使える！Dify x Python ハイブリッド開発実践

大文件上传失败：大小限制、UPLOAD_FILE_SIZE_LIMIT、Nginx设置、分割上传实践

简介

在知识库建设项目中，经常出现“尝试上传大于100MB的PDF失败”的问题。文件越大，问题就越超出“上传失败”的范围，并级联到反向代理限制、后端配置限制、存储写入以及后续的解析、分块和索引。

在本文中，我们确定了导致大文件上传失败的多个层，并解释了实用的解决方案，从更改每个层的设置到构建预处理管道。

症状

症状	错误消息示例	故障层
上传在浏览器中途停止	（网络错误）	浏览器/客户端
413 请求实体太大	`413 Payload Too Large`	Nginx / 反向代理
文件大小限制错误	`File size exceeds the limit`	Dify后端
上传成功但处理未完成	（超时/状态仍在处理中）	分析/指标处理
写入 S3/MinIO 时出错	`PutObject failed` / `Connection reset`	对象存储

原因分析

大文件上传失败发生在以下五层中的一层（或多层）：

flowchart TD
    A[ファイルアップロード] --> B[レイヤー1: ブラウザ/クライアント]
    B --> C[レイヤー2: リバースプロキシ Nginx/Ingress]
    C --> D[レイヤー3: Dify バックエンド]
    D --> E[レイヤー4: オブジェクトストレージ]
    E --> F[レイヤー5: 後続処理パイプライン]
    
    B -.->|タイムアウト| B1[接続切れ]
    C -.->|413エラー| C1[body size制限]
    D -.->|サイズ制限| D1[UPLOAD_FILE_SIZE_LIMIT]
    E -.->|書込失敗| E1[権限/容量]
    F -.->|処理超過| F1[解析タイムアウト]

第 2 层：反向代理（Nginx/Kubernetes 入口）

这是最常见的故障点。 Dify 的自托管环境几乎总是以 Nginx 或 Kubernetes Ingress 为前端。在默认设置中，请求正文大小限制通常在 1MB 到 10MB 左右。

Nginx 默认设置：

# デフォルト: client_max_body_size 1m;
# → 1MB を超えるファイルが 413 エラーで拒否される

第 3 层：配置 Dify 后端

Dify 本身也将文件大小的上限设置为环境变量。

环境变量	默认值	描述
`UPLOAD_FILE_SIZE_LIMIT`	`15` (MB)	单个文件最大上传大小
`UPLOAD_FILE_BATCH_LIMIT`	`5`	一次可上传的文件数
`UPLOAD_IMAGE_FILE_SIZE_LIMIT`	`10` (MB)	图像文件的最大大小
`ETL_TYPE`	`dify`	文档分析引擎（dify/非结构化）

第 4 层：对象存储

Dify 支持以下文件存储位置：

本地文件系统 -亚马逊S3 -Azure Blob 存储 -谷歌云存储
腾讯云 COS -华为云OBS
MinIO（S3兼容）

每个存储对分段上传和单次上传限制的支持不同（S3：5GB、Azure Blob：256MB 等），因此请提前检查。

###第5层：后续处理管道

即使文件本身上传成功，还需要进行以下后续处理才能将其注册到知识库中，并且每次都有超时的风险。

アップロード → テキスト抽出 → チャンク分割 → Embedding生成 → ベクトルDB書込

对于超过 100MB 的 PDF：

文本提取需要几分钟到几十分钟
大量 API 调用来生成数千个块的嵌入
大量写入矢量数据库

注意事项

1. 预上传清单

上传文件之前，请检查以下内容：

文件大小是否小于或等于 UPLOAD_FILE_SIZE_LIMIT？
Nginx / Ingress 的 client_max_body_size 够用吗？
您是否删除了不必要的页面（空白、封面、目录、索引）？
如果是扫描版PDF，是否经过OCR处理？
文件是否损坏？（检查是否可以用PDF阅读器打开。）

2.设置值的一致性检查

检查各层的限值是否一致。

Nginx client_max_body_size  >=  UPLOAD_FILE_SIZE_LIMIT  >=  実際のファイルサイズ

常见矛盾的例子：

nginx	Dify	结果
1m（默认）	15MB	Nginx 413 错误
200m	15MB（默认）	Dify 后端大小错误
200m	200MB	OK（但要注意后续处理超时）

3.大文件操作流程标准化

flowchart TD
    A[原本PDF] --> B{サイズ > 15MB?}
    B -->|No| C[そのままアップロード]
    B -->|Yes| D[前処理パイプライン]
    D --> E[空白ページ除去]
    E --> F[OCR処理 if スキャンPDF]
    F --> G{サイズ > 15MB?}
    G -->|No| C
    G -->|Yes| H[チャプター/ページ分割]
    H --> I[分割ファイルを順次アップロード]
    C --> J[インデックス処理完了を確認]
    I --> J
    J --> K[検索品質テスト]

4. 监控

定期通过API调用GET /datasets/{dataset_id}/documents，检查每个文档的indexing_status是否变为completed。如果长时间停留在processing，则怀疑后续管道超时。

总结

上传大于 100MB 的 PDF 失败通常无法通过更改单个设置来解决。 Nginx 的请求体大小限制、Dify 的 UPLOAD_FILE_SIZE_LIMIT、对象存储配置以及后续的解析管道超时都会产生级联效应。

最有效的方法不仅是调整上传限制，还需要构建文件预处理管道，在上传之前将大文件分割并优化为合适的大小。这不仅提高了上传成功率，还提高了知识库的搜索质量。

参考资料

-Environment Variables - Dify Docs -Deploy Dify with Docker Compose -ファイルアップロード | Dify Docs（日本語） -ナレッジパイプラインをオーケストレーションする | Dify Docs

Agent工具调用陷入死循环：明确工具定义、最大迭代次数、后备设计

简介

Dify 的 Agent 一遍又一遍地调用同一个工具，或者陷入“信息未找到→再次搜索→再次未找到”的循环——这个问题不仅浪费代币成本，而且严重降低了用户体验。

乍一看，Agent的无限循环似乎是由于模型不智能造成的，但实际上，这主要是系统设计问题。 Dify的官方文档明确指出，Maximum Iterations设置存在于Agent节点上，并且可以通过环境变量MAX_ITERATIONS_NUM来设置平台级别的上限。也就是说，通过适当设计以下三个要素可以显着缓解这个问题：平台上限设置+工具定义质量+提示退出条件。

症状

症状	里面发生了什么
同一工具连续调用 5 次或以上	工具返回值无法正确解释
特工一直说“我会再调查一下”	提示
使用不同的参数重复使用相同的工具	使用该工具的条件不明确，您尝试通过更改参数来解决它们
需要几分钟才能得到回复	迭代次数没有上限，一直运行到达到成本限制
答案止于“验证工具结果…”	该工具返回错误，但代理无法理解该错误

原因分析

原因 1：工具定义（描述）不明确

工具描述是模型确定何时使用该工具以及期望什么的最重要输入。

坏例子：

tool:
  name: search_database
  description: "データベースを検索します"

该定义不清楚：

它是什么样的数据库？
它支持什么类型的查询？
如果没有找到结果怎么办？
结果将以什么格式返回？

好例子：

tool:
  name: search_employee_database
  description: |
    社員情報データベースを検索します。
    入力: 社員名（姓名）または社員番号
    出力: 社員名、部署、内線番号、メールアドレスを含むJSON
    制約: 
    - 部分一致検索に対応
    - 結果が見つからない場合は空の配列 [] を返す
    - 一度に最大10件まで返す
    注意: 退職者の情報は含まれません

原因 2：工具的错误处理不足

当工具返回错误或结果为空时，代理通常会将其解释为“重试可能会更改结果”。

ループの例:
1. Agent: search_database("田中太郎") → 結果なし
2. Agent: "もう少し調べてみます"
3. Agent: search_database("田中 太郎") → 結果なし
4. Agent: "別の方法で検索します"
5. Agent: search_database("タナカタロウ") → 結果なし
6. Agent: "さらに調べます..."  → 以後繰り返し

原因 3：未设置最大迭代次数

Dify的Agent节点有一个Maximum Iterations参数，但是如果默认值限制不够，就会导致成本膨胀然后停止。

设置	价值	描述
代理节点的最大迭代次数	默认值	每节点迭代限制
`MAX_ITERATIONS_NUM` 环境变量	平台层面	适用于所有代理的全局上限

###原因4：提示没有退出条件

很多系统提示只提供“回答用户问题”的正面指示，而没有明确何时放弃。

典型问题提示：

あなたは社内ヘルプデスクアシスタントです。
ユーザーの質問に対して、利用可能なツールを活用して
正確な回答を提供してください。

仅凭这条指令，代理就会优先考虑“提供准确的答案”，并继续尝试，即使找不到答案也不会放弃。

###原因5：工具之间的角色划分不明确

当多个工具具有相似的功能时，代理可能无法决定使用哪一个，并进入交替调用它们的循环。

1. Agent: search_knowledge_base("VPN設定方法") → 部分的な結果
2. Agent: search_faq("VPN設定方法") → 別の部分的な結果
3. Agent: "もう少し調べます"
4. Agent: search_knowledge_base("VPN 設定 手順") → 似た結果
5. Agent: search_faq("VPN接続できない") → 別の結果
6. → 繰り返し

解决方案

解决方案 1：适当设置最大迭代次数

代理节点级别：

在 Dify 的 Workflow 编辑器中选择 Agent 节点并设置 Maximum Iterations。

使用案例	建议的迭代次数	原因
简单的信息搜索（常见问题解答）	3-5	3-5 1-2 次搜索就足够了
复杂的任务（调查/分析）	5 至 8	需要多种工具的组合
多步骤加工	8 至 12	假设逐步处理
最多也不过如此	15	15超过这个值几乎肯定会导致无限循环

平台级别（自托管环境）：

# .env ファイル
MAX_ITERATIONS_NUM=15    # 全Agent共通の最大イテレーション数

解决方案 2：改进工具定义

包含每个工具的以下信息：

tools:
  - name: search_employee
    description: |
      社員情報を検索します。
      
      【用途】社員の連絡先、所属部署を調べるとき
      【入力】社員名（姓または名）、または社員番号（E+数字5桁）
      【出力形式】
        - 見つかった場合: {"found": true, "employees": [...]}
        - 見つからなかった場合: {"found": false, "message": "該当なし"}
      【制限事項】
        - 退職者は検索対象外
        - 一度に10件まで
      【注意】結果が見つからなかった場合、パラメータを変えて
        再度呼び出しても結果は変わりません。
    parameters:
      query:
        type: string
        description: "社員名または社員番号"
        required: true

  - name: search_knowledge_base
    description: |
      社内ナレッジベースを検索します。
      
      【用途】社内規程、手順書、マニュアルの内容を調べるとき
      【入力】自然言語のクエリ（日本語）
      【出力形式】
        - 関連チャンクのリスト（最大5件、relevance_score付き）
        - 関連情報がない場合: 空リスト []
      【このツールで検索できないもの】
        - 社員の個人情報 → search_employee を使用
        - リアルタイムのシステム障害情報 → check_system_status を使用
      【注意】同じクエリで2回以上呼び出しても結果は同じです。
        結果が不十分な場合はクエリの表現を変えてください。

解决方案 3：在系统提示符中指定退出条件

# System Prompt

あなたは株式会社ABCの社内ヘルプデスクAIアシスタントです。

## 基本ルール
- 利用可能なツールを活用して、ユーザーの質問に正確に回答してください
- 回答の根拠は必ずツールの検索結果に基づくこと

## 退出条件（重要）
以下の条件に該当する場合は、ツール呼び出しを停止し、
適切な回答を返してください：

1. **同じツールを2回呼び出しても有効な結果が得られない場合**
   → 「申し訳ございませんが、現在のナレッジベースにはこの質問に
      該当する情報が見つかりませんでした。IT部門（内線: 1234）に
      お問い合わせください。」

2. **ツールがエラーを返した場合**
   → エラー内容をユーザーに伝え、別の問い合わせ方法を案内してください

3. **ユーザーの質問が対応範囲外の場合**
   → 対応範囲外であることを伝え、適切な問い合わせ先を案内してください

4. **すでに十分な情報が得られている場合**
   → 追加のツール呼び出しは不要です。得られた情報で回答してください

## 禁止事項
- 同じツールを同じパラメータで2回以上呼び出さないこと
- 3回連続でツール呼び出しが空結果だった場合、それ以上の試行を行わないこと
- 「もう少し調べます」「別の方法で検索します」と言って呼び出しを続けないこと

解决方案 4：设计后备路径

如果代理陷入困境，请设计一个渐进的后备方案。

flowchart TD
    A[ユーザー質問] --> B[ツール呼び出し 1回目]
    B --> C{有効な結果?}
    C -->|Yes| D[回答生成]
    C -->|No| E[ツール呼び出し 2回目 クエリ変更]
    E --> F{有効な結果?}
    F -->|Yes| D
    F -->|No| G[フォールバック: ナレッジベース直接検索]
    G --> H{有効な結果?}
    H -->|Yes| I[ナレッジベースの情報で回答]
    H -->|No| J[人間への引き継ぎメッセージ]

工作流程中的实现： 在Agent节点后面放置一个IF/ELSE节点，如果Agent输出包含“Not Found”，则分支到知识库直接搜索节点，如果仍然没有结果，则分支到LLM节点进行人工切换。

解决方案 5：明确工具之间的角色界限

## ツール使用ガイドライン（System Prompt に含める）

利用可能なツールと使い分け：

| 質問の種類 | 使用するツール | 使わないツール |
|-----------|--------------|--------------|
| 社員の連絡先・部署 | search_employee | search_knowledge_base |
| 社内規程・手順 | search_knowledge_base | search_employee |
| システム障害の状況 | check_system_status | search_knowledge_base |
| 会議室の予約状況 | check_room_availability | search_employee |

重要: 上記の対応表に従ってツールを選択してください。
対応表にないタイプの質問には、ツール呼び出しを行わず
「この種類のお問い合わせには対応しておりません」と回答してください。

解决方案 6：使用代理日志进行调试

如果出现死循环，首先检查Agent日志。

检查要点：

检查项目	评判标准
重复调用的工具	工具定义需要改进
每次的参数都一样吗？	如果它们相同，则模型不会解释结果
思想内容	“我会进一步调查”→退出条件不充分
当达到最大迭代次数时是否会停止？	如果没有达到，有可能是没有设置上限

从 Dify 控制台的“日志和注释”选项卡中，选择有问题的对话，并循环浏览每次迭代的想法/操作/观察，以确定循环的起点。

注意事项

1. 代理设计清单

构建新代理时请确保以下事项：

是否设置了最大迭代次数（建议：5-10）？
每个工具的描述是否指定了没有结果时的行为？
系统提示符是否包含退出条件？
多种工具的角色界限是否清晰？
是否设计了后备路径（移交至人工等）？
该工具的错误响应是否采用代理可以理解的格式？

2. 测试场景

上线前，请务必测试以下“故障场景”：

测试案例	预期行为
搜索不存在的员工姓名	2次内回答“未找到”
知识库中没有的问题	3次内回退消息
如果该工具返回错误	提供带有错误消息的替代方案
超出范围的问题	指导范围外无需调用工具
模棱两可的问题	一次搜索后要求用户确认

3.成本监控

代理的无限循环直接体现在代币成本上。

# 環境変数でコスト関連の上限を設定
MAX_ITERATIONS_NUM=15              # イテレーション上限
WORKFLOW_MAX_EXECUTION_TIME=300    # 5分でタイムアウト

监控指标：

指标	警告阈值	回应
每个对话的平均迭代次数	超过 5	工具定义/及时审查
每次对话的令牌消耗	超过 10,000	代理设计评审
连续调用同一工具的次数	超过3次	加强退出条件
最大迭代达成率	超过 10%	审查上限及退出条件

4. 代理逐渐复杂化

与其从一开始就拥有所有工具，不如分阶段添加工具：阶段1（仅知识库搜索）→阶段2（+员工搜索）→阶段3（+系统状态确认）→阶段4（+预订/申请系统），并验证每个阶段的退出条件和路由。

总结

Agent死循环的根本原因不是模型效率低下，而是系统不知道什么时候停止。通过同时设计以下三个要素可以实现有效的对策：

平台上限：用Maximum Iterations和MAX_ITERATIONS_NUM设置物理停止条件
工具定义的澄清：在每个工具的描述中指定目的、输入/输出、限制以及结果为空时的行为。
提示退出条件：在系统提示中包含明确的规则，例如“多次尝试无结果则停止”和“不要使用相同的参数再次调用相同的工具”。

如果缺少这三个要素中的任何一个，就会存在无限循环的风险。 Agent 的设计不仅要考虑“它能做什么”，还要考虑“何时放弃”。

参考资料

-エージェント | Dify Docs（日本語） -Agent | Dify Legacy Docs -Environment Variables - Dify Docs -ReAct エージェントの基本構造と「思考・行動・観察」ループ | note.com

生产环境与验证环境——配置差异、资源设计、安全增强实用指南

仅仅因为您可以在测试环境中运行 Dify Enterprise 并不意味着您可以直接将其用于生产。验证环境和生产环境的区别不仅仅是用户数量的增加，而是可用性、可观察性、恢复能力的基本风险模型不同。

Dify Enterprise 官方文档（Resources Checklist）明确规定了两类推荐规范：测试部署和生产部署。验证环境仅需要 1 个工作节点、4 个 CPU/16 GB RAM，但生产环境需要 6 个工作节点、每个工作节点 8 个 CPU/32 GB RAM，并且 PostgreSQL、Redis 和 Qdrant 必须在集群配置中运行。也就是说，官方定义的“验证”和“生产”是完全不同的风险模型。

在本文中，我们将根据资源、持久性、日志、安全性和备份这五个轴来整理日本企业的企业 IT 团队在将 Dify Enterprise 部署到生产环境时应记住的配置差异。

1. 资源规模的差异

1.1 官方推荐规格对比

项目	验证环境	生产环境
工作节点数量	1	6 个或更多
每个节点的 CPU	4 个虚拟CPU	8 个 vCPU
每个节点的内存	16GB	32GB
PostgreSQL	单一最低配置	HA配置（主+备）
Redis	单实例	哨兵或集群
Qdrant（矢量数据库）	单节点	3 个或更多节点的集群
对象存储	本地或MinIO最低配置	S3 兼容存储（冗余）

1.2 Kubernetes资源定义概念

在验证环境中，无需指定 resources.requests / resources.limits 即可工作，但在生产中必须定义它。以下为实际生产参考值。

# values.yaml -- 本番環境向け API サーバーのリソース例
api:
  replicas: 3
  resources:
    requests:
      cpu: "2"
      memory: "4Gi"
    limits:
      cpu: "4"
      memory: "8Gi"

worker:
  replicas: 3
  resources:
    requests:
      cpu: "2"
      memory: "4Gi"
    limits:
      cpu: "4"
      memory: "8Gi"

web:
  replicas: 2
  resources:
    requests:
      cpu: "500m"
      memory: "1Gi"
    limits:
      cpu: "1"
      memory: "2Gi"

sandbox:
  replicas: 2
  resources:
    requests:
      cpu: "500m"
      memory: "512Mi"
    limits:
      cpu: "1"
      memory: "1Gi"

1.3 副本数量的设计准则

组件	验证	生产	理由
应用程序接口	1	3+	API 故障对所有用户立即产生影响
工人	1	3+	确保工作流执行队列处理的并行性
网页	1	2+	前端交付冗余
沙盒	1	2+	代码执行环境的安全分离
企业	1	2	许可证管理/管理控制台可用性

要点：阿里云ACK最佳实践文章中也明确推荐生产环境中API/Worker/Web/Sandbox的多副本部署。

2. 持久性的差异

2.1 验证环境

验证环境中，emptyDir或者Node本地存储没有问题。目的是验证功能，不要求数据持久性。

# 検証環境 -- 永続化を最小限に
persistence:
  enabled: false

2.2 生产环境

在生产中，将以下所有内容连接到外部持久存储。

# 本番環境 -- 外部依存の明示
externalPostgres:
  enabled: true
  host: "dify-prod-pg.ap-northeast-1.rds.amazonaws.com"
  port: 5432
  username: "dify"
  database: "dify_production"
  existingSecret: "dify-pg-credentials"
  existingSecretPasswordKey: "password"

externalRedis:
  enabled: true
  host: "dify-prod-redis.xxxxx.apne1.cache.amazonaws.com"
  port: 6379
  existingSecret: "dify-redis-credentials"
  existingSecretPasswordKey: "password"

externalS3:
  enabled: true
  bucket: "dify-prod-storage"
  region: "ap-northeast-1"
  existingSecret: "dify-s3-credentials"

2.3 持久性检查表

PostgreSQL：使用托管数据库（例如 RDS / Cloud SQL）启用自动备份
Redis：使用托管服务，例如 ElastiCache / Memorystore
Vector DB (Qdrant)：使用持久卷 (PVC) 或外部集群
对象存储：启用 S3 / GCS / Azure Blob 版本控制
在 Git 存储库中管理 value.yaml 本身

3.日志级别和可观察性

3.1 验证环境日志设置

在验证环境中，启用DEBUG级别并优先考虑早期问题检测和行为确认。

# 検証環境
env:
  LOG_LEVEL: "DEBUG"

3.2 生产环境日志设置

如果在生产中始终启用 DEBUG，日志量将会爆炸，从而增加存储成本和噪音。通常，应将其设置为 WARNING 或更高，并在必要时暂时降低为 INFO。

# 本番環境
env:
  LOG_LEVEL: "WARNING"

3.3 生产过程中需要收集的日志类别

类别	应用	建议保留期限
错误日志	故障检测/根本原因分析	超过90天
审核日志（访问/更改）	合规/内部控制	1年多
API请求日志	绩效分析/计费	30 天
工作流程执行日志	业务逻辑调试	60 天

3.4 可观测性栈推荐配置

graph LR
    A[Dify Pods] -->|stdout/stderr| B[Fluentd / Fluent Bit]
    B --> C[Elasticsearch / OpenSearch]
    C --> D[Kibana / Grafana]
    A -->|metrics| E[Prometheus]
    E --> D
    A -->|traces| F[Jaeger / Tempo]
    F --> D

在生产环境中，至少安装Metrics（Prometheus）和日志聚合（Fluentd + Elasticsearch）。创建一个可视化工作流执行延迟和错误率的仪表板将大大改善对故障的初始响应。

4. 增强安全性

4.1 秘密管理

在验证环境中，我倾向于按原样使用默认的 Secret 值，但在生产中我肯定会更改它。

# 本番環境 -- 必ず変更すべき Secret
api:
  secretKey: ""  # 外部 Secret Manager から注入
  innerApiKey: ""  # 同上

# Kubernetes Secret で管理する例
# kubectl create secret generic dify-secrets \
#   --from-literal=SECRET_KEY=$(openssl rand -hex 32) \
#   --from-literal=INNER_API_KEY=$(openssl rand -hex 32)

4.2 网络政策

由于沙箱容器执行用户提交的代码，因此在生产中使用NetworkPolicy严格限制外部通信。

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: sandbox-restrict
spec:
  podSelector:
    matchLabels:
      app: dify-sandbox
  policyTypes:
    - Egress
  egress:
    - to:
        - podSelector:
            matchLabels:
              app: dify-api
      ports:
        - port: 5001
    # 外部インターネットへの通信はブロック

4.3 入口 TLS

ingress:
  enabled: true
  className: "nginx"
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
  tls:
    - secretName: dify-tls
      hosts:
        - console.dify.example.co.jp
        - api.dify.example.co.jp
  hosts:
    - host: console.dify.example.co.jp
      paths:
        - path: /
          pathType: Prefix

4.4 安全检查表

项目	验证	生产
随机秘密生成	可选	必填
TLS 终止	不需要	必填
网络策略（沙箱）	不需要	必填
Pod 安全标准	不需要	限制推荐
RBAC（Kubernetes）	默认	最小特权原则
单点登录集成	不需要	推荐（SAML/OIDC）
图像扫描	不需要	CI/CD 所需

5. 备份策略

5.1 验证环境

在验证环境中，备份频率可能较低。重点放在重建环境的便利性上。

5.2 生产环境备份设计

目标	方法	频率	保留期限
PostgreSQL	托管数据库自动快照	每日	30 天
PostgreSQL (WAL)	持续归档	实时	7 天
对象存储	版本控制+跨区域复制	实时	90 天
矢量数据库 (Qdrant)	快照API	每日	14 天
value.yaml / Helm 配置	Git 存储库	每当改变	无限期
Kubernetes 宣言	维莱罗	每日	30 天

5.3 执行恢复测试

仅仅进行备份是不够的。建议至少每季度进行一次以下恢复测试。

1.从PostgreSQL快照恢复新实例并检查Dify是否正常启动 2.验证回滚到特定版本的对象存储 3.使用Velero检查整个集群恢复过程 4. 验证恢复时间 (RTO) 和恢复点 (RPO) 是否满足 SLA 要求

6.环境隔离的最佳实践

6.1 推荐配置

graph TB
    subgraph "本番クラスタ"
        A[namespace: dify-production]
    end
    subgraph "ステージングクラスタ"
        B[namespace: dify-staging]
    end
    subgraph "検証クラスタ"
        C[namespace: dify-testing]
    end
    D[GitOps リポジトリ] --> A
    D --> B
    D --> C

6.2 按环境管理values.yaml

helm-values/
  base/
    values.yaml          # 共通パラメータ
  overlays/
    testing/
      values.yaml        # 検証固有の上書き
    staging/
      values.yaml        # ステージング固有の上書き
    production/
      values.yaml        # 本番固有の上書き

每个环境的values.yaml 都像Kustomize 一样继承基础，并且仅覆盖特定于环境的差异。这可以防止验证和生产之间的配置偏差。

6.3 各个环境的许可证管理

Dify Enterprise 许可证与 Kubernetes 命名空间绑定，因此每个环境都需要单独的许可证。关于License账本管理，请参考《04-License-管理实践》一文。

7. 总结 – 生产迁移清单

上线前请检查以下内容。

已为所有组件设置资源定义（CPU/内存请求/限制）
副本数量满足可用性要求（API/Worker为3个及以上）
PostgreSQL/Redis/对象存储连接到外部托管服务
所有秘密均已替换为随机生成的值。
TLS 终止已配置
应用沙盒网络策略
日志级别已设置为 WARNING 或更高
日志聚合基础设施（Fluentd + Elasticsearch等）正在运行
备份是自动的并且经过恢复测试
[ ]values.yaml 由 Git 管理
许可证已在生产命名空间中激活
已在临时环境中进行了相当于生产的负载测试。

验证环境是“检查某些东西是否有效的地方”，而生产环境是“承诺服务的地方”。尽管两者应该共享相同的部署方法，但风险假设却有根本的不同。明确反映这种配置差异是 Dify Enterprise 稳定运行的第一步。

Helm Chart value.yaml 重要参数的完整指南 - 确定所需更改、按环境调整和维护默认值的标准

在 Kubernetes 上部署 Dify Enterprise 时，values.yaml 是最重要的文件，决定了部署的整体情况。正如官方安装命令helm upgrade -i dify -f values.yaml dify/dify所示，所有生产环境配置差异都被合并到该文件中。

参数有很多，但您不需要全部了解。重要的是将参数分为三层：“必须更改的参数”、“需要针对每个环境调整的参数”和“可以保留为默认的参数”，并对其进行优先级管理。

另外，公式中提供了dify-ee-helm-chart-values-generator来处理数值的复杂性，可用于生成初始配置。

1.values.yaml整体结构

helm show values dify/dify输出的主要部分如下。

values.yaml
├── global              # グローバル設定（イメージレジストリ、プルシークレット等）
├── api                 # API サーバー設定
├── worker              # Worker サーバー設定
├── web                 # Web フロントエンド設定
├── sandbox             # コード実行 Sandbox 設定
├── enterprise          # Enterprise 固有設定（License 等）
├── ingress             # Ingress / ドメイン設定
├── persistence         # 永続化設定
├── externalPostgres    # 外部 PostgreSQL 接続
├── externalRedis       # 外部 Redis 接続
├── externalS3          # 外部オブジェクトストレージ接続
├── postgresql          # 内蔵 PostgreSQL（検証用）
├── redis               # 内蔵 Redis（検証用）
└── pluginDaemon        # プラグイン Daemon 設定

2.必须改变的参数（Must Change）

以下参数不应在生产中使用其默认值。

2.1 域和入口

ingress:
  enabled: true
  className: "nginx"  # 環境に応じて alb, traefik 等
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
    nginx.ingress.kubernetes.io/proxy-body-size: "50m"
  tls:
    - secretName: dify-tls-cert
      hosts:
        - console.dify.example.co.jp
        - api.dify.example.co.jp
        - app.dify.example.co.jp
        - upload.dify.example.co.jp
        - enterprise.dify.example.co.jp
  hosts:
    console:
      host: console.dify.example.co.jp
    api:
      host: api.dify.example.co.jp
    app:
      host: app.dify.example.co.jp
    upload:
      host: upload.dify.example.co.jp
    enterprise:
      host: enterprise.dify.example.co.jp

注意：Dify Enterprise 有多个端点：控制台/api/应用程序/上传/企业/触发器。提前设计您的 DNS 和通配符证书。

2.2 秘密/内部通信密钥

api:
  secretKey: ""       # 必ず強ランダム値に変更
  innerApiKey: ""     # 必ず強ランダム値に変更

生成示例：

# 32 バイトの hex 文字列を生成
openssl rand -hex 32

**在生产中，我们建议使用 existingSecret，而不是在 value.yaml 中以纯文本形式编写。 **

api:
  existingSecret: "dify-api-secrets"
  existingSecretKeys:
    secretKey: "SECRET_KEY"
    innerApiKey: "INNER_API_KEY"

2.3 企业许可模式

enterprise:
  enabled: true
  licenseMode: "online"   # オフライン環境では "offline" に変更

对于离线模式，请参考官方License激活文档，了解如何放置License文件。

2.4 外部数据库连接

在生产中，禁用内置 PostgreSQL 并使用外部托管数据库。

# 内蔵 PostgreSQL を無効化
postgresql:
  enabled: false

# 外部 PostgreSQL を有効化
externalPostgres:
  enabled: true
  host: "dify-prod.cluster-xxxx.ap-northeast-1.rds.amazonaws.com"
  port: 5432
  username: "dify_app"
  database: "dify_production"
  existingSecret: "dify-postgres-secret"
  existingSecretPasswordKey: "password"
  sslMode: "require"    # 本番では SSL 必須

2.5 外部Redis连接

redis:
  enabled: false

externalRedis:
  enabled: true
  host: "dify-prod.xxxxx.apne1.cache.amazonaws.com"
  port: 6379
  existingSecret: "dify-redis-secret"
  existingSecretPasswordKey: "password"
  useSsl: true

2.6 外部对象存储

externalS3:
  enabled: true
  bucket: "dify-enterprise-prod"
  region: "ap-northeast-1"
  endpoint: ""  # AWS S3 の場合は空、MinIO の場合は URL を指定
  existingSecret: "dify-s3-secret"
  existingSecretKeys:
    accessKey: "AWS_ACCESS_KEY_ID"
    secretKey: "AWS_SECRET_ACCESS_KEY"

3.每个环境需要调整的参数（Per-Environment）

3.1 副本数量

组件	验证	分期	生产
api.replicas	1	2	3+
工人.replicas	1	2	3+
网络副本	1	1	2+
沙盒.replicas	1	1	2+
企业.副本	1	1	2

3.2 资源限制

# 本番向け -- 各コンポーネントに明示的に定義
api:
  resources:
    requests:
      cpu: "2"
      memory: "4Gi"
    limits:
      cpu: "4"
      memory: "8Gi"

worker:
  resources:
    requests:
      cpu: "2"
      memory: "4Gi"
    limits:
      cpu: "4"
      memory: "8Gi"

web:
  resources:
    requests:
      cpu: "500m"
      memory: "512Mi"
    limits:
      cpu: "1"
      memory: "1Gi"

sandbox:
  resources:
    requests:
      cpu: "500m"
      memory: "512Mi"
    limits:
      cpu: "1"
      memory: "1Gi"

3.3 日志级别

# 検証環境
api:
  env:
    LOG_LEVEL: "DEBUG"

# 本番環境
api:
  env:
    LOG_LEVEL: "WARNING"

3.4 SMTP设置（邮件通知）

api:
  env:
    MAIL_TYPE: "smtp"
    SMTP_SERVER: "smtp.example.co.jp"
    SMTP_PORT: "587"
    SMTP_USE_TLS: "true"
    SMTP_USERNAME: "dify-noreply@example.co.jp"
    MAIL_DEFAULT_SEND_FROM: "Dify Enterprise <dify-noreply@example.co.jp>"
  existingSecret: "dify-smtp-secret"

3.5 SSO/SAML 集成

在企业版中，可以使用 SAML/OIDC 进行 SSO。与 Azure AD 或 Okta 链接时，请设置以下内容。

enterprise:
  sso:
    enabled: true
    protocol: "saml"
    # 具体的な IdP 設定は管理コンソールから行う

3.6 沙盒网络限制

sandbox:
  env:
    ALLOWED_SYSCALLS: ""  # 許可するシステムコールを限定
  networkPolicy:
    enabled: true
    # 許可する通信先を明示的に指定

4. 可以保留默认的参数（Keep Default）

除非有特殊要求，以下内容无需更改。

参数类别	原因
实验性功能标志	稳定版就可以不用开启
未使用的插件设置	不要触动未使用插件的设置
未使用的云提供商的连接设置	使用 AWS 时，忽略 GCP/Azure 特定项目
图像标签（如果包含在 Helm Chart 版本中）	无需指定单独的标签，因为它们由图表版本管理
内部端口号	除非有特殊要求，否则使用默认端口

5.参数分类汇总表

分类	参数示例	更改时间
必须改变	ingress.hosts、secretKey、innerApiKey、externalPostgres、externalRedis、externalS3、enterprise.licenseMode	首次部署之前
每个环境	副本、资源、LOG_LEVEL、SMTP、SSO、网络策略	搭建环境时
保持默认	实验标志、未使用的插件、内部端口	仅在需要时

6.values.yaml 的版本控制

6.1 使用 Git 存储库进行管理

value.yaml 是基础设施代码本身，由 Git 管理。

infra-repo/
├── helm/
│   └── dify/
│       ├── base-values.yaml        # 全環境共通
│       ├── testing-values.yaml     # 検証環境上書き
│       ├── staging-values.yaml     # ステージング上書き
│       └── production-values.yaml  # 本番環境上書き
├── secrets/
│   └── README.md                   # Secret の管理方針を記載
└── scripts/
    └── deploy.sh                   # デプロイスクリプト

6.2 部署命令示例

# 本番デプロイ（base + 環境別の values を重ねて適用）
helm upgrade -i dify dify/dify \
  -n dify-production \
  -f helm/dify/base-values.yaml \
  -f helm/dify/production-values.yaml \
  --wait --timeout 10m

养成在部署之前使用 helm diff 插件检查更改的习惯。

7. 故障排除

价值观引起的常见问题

症状	原因	治疗
Pod 发生 CrashLoopBackOff	错误的数据库连接信息	检查 externalPostgres 的主机/端口/凭据
502 入口	服务名称或端口不匹配	使用 `kubectl get svc` 检查实际服务
许可证认证错误	许可证模式不匹配	检查在线/离线设置并重启企业pod
文件上传失败	S3 凭证不正确	检查外部S3凭证和存储桶策略
发送邮件失败	SMTP 设置不正确	SMTP_SERVER / PORT / TLS / 检查身份验证信息
OOM 杀死	资源限制缺失	检查 `kubectl describe pod` 上的事件并增加限制

9. 总结

Helm Chart 的 value.yaml 是 Dify Enterprise 部署的“蓝图”。虽然没有必要破译所有参数，但建议按照以下优先顺序进行处理。

首日支持：Domain/Secret/External DB/Redis/S3/License模式
搭建环境时支持：副本数量、资源限制、日志级别、SMTP、SSO
运行开始后实施：根据需要添加实验性功能和插件设置

使用Git管理values.yaml，针对每个环境将其分开，并在部署前使用helm diff检查差异。养成这三个习惯是Dify Enterprise稳定运营的基础。

多租户权限设计——工作空间分离、角色层次结构和 API 密钥范围实用指南

企业中的多租户设计并不是简单的“每个部门分离账户”。 如何隔离数据、如何共享模型、如何继承权限 ——回答这三个问题至关重要。

Dify 将工作区、团队成员和模型提供者设计为不同的管理层。除此之外，企业版还增加了组织管理、SSO联动、审计日志等治理功能。在本文中，我们将从实践层面解释日本公司在内部部署 Dify Enterprise 时使用的权限设计模式。

1. Dify 权限模型概述

1.1 整理基本概念

graph TB
    subgraph "プラットフォームレベル"
        A[System Admin]
        B[Model Providers]
        C[License 管理]
    end
    subgraph "Workspace レベル"
        D[Workspace A<br/>営業部]
        E[Workspace B<br/>カスタマーサポート部]
        F[Workspace C<br/>法務部]
    end
    subgraph "Workspace 内"
        G[Apps]
        H[Knowledge Base]
        I[Tools]
        J[Members & Roles]
    end
    A --> D
    A --> E
    A --> F
    B -.->|共有可能| D
    B -.->|共有可能| E
    B -.->|共有可能| F
    D --> G
    D --> H
    D --> I
    D --> J

1.2 角色层次结构

Dify 具有以下角色层次结构。

角色	范围	主要权威
系统管理员	全平台	所有工作区管理、模型配置、许可证管理、SSO 配置
工作区所有者	特定工作区	会员管理、app/知识库全部权限
工作区管理员	特定工作区	应用管理、知识库管理、会员邀请
编辑	特定工作区	应用程序创建/编辑、知识库编辑
会员	特定工作区	应用程序使用（以阅读为主）

1.3 隔离边界

资源	检疫单位	描述
应用	工作空间	每个工作区内的独立管理
知识库	工作空间	关闭工作区中的文档/矢量数据
会员	工作空间	同一用户可以属于多个工作区
模型提供者	平台	可以共享设置，可以在工作区的基础上管理使用限制
API 密钥	工作区 + 应用程序	按申请发布
审核日志	平台	所有工作区操作都记录在一处

2.租户设计模式

2.1 模式A：强隔离模型（部门完全分离）

graph LR
    subgraph "法務部 Workspace"
        A1[契約書レビューApp]
        A2[法務ナレッジベース]
        A3[専用 Model Provider]
    end
    subgraph "人事部 Workspace"
        B1[採用FAQ App]
        B2[人事ナレッジベース]
        B3[専用 Model Provider]
    end
    A1 -.- A2
    B1 -.- B2

应用场景：法务、人力资源、财务、企业策划等处理高度机密数据的部门。

特点：

知识库是完全独立的
模型提供商还为每个部门单独设置（单独的 API 密钥并单独管理使用情况）
原则上禁止或尽量减少并发会员资格
定期审查审核日志

与values.yaml相关的设置：

# Workspace 間のデータ分離は Dify のアプリケーション層で実現
# インフラレベルでは以下を確認
enterprise:
  enabled: true
  # 監査ログの有効化
  auditLog:
    enabled: true
    retention: "365d"

2.2 模式B：共享基础设施+数据分离模型

graph TB
    subgraph "プラットフォーム共有層"
        M[共有 Model Provider<br/>GPT-4o / Claude]
        P[共有プラグイン]
    end
    subgraph "営業部 Workspace"
        C1[商談支援 App]
        C2[営業ナレッジベース]
    end
    subgraph "CS部 Workspace"
        D1[問合せ対応 App]
        D2[CS ナレッジベース]
    end
    M -->|利用| C1
    M -->|利用| D1
    C1 -.- C2
    D1 -.- D2

应用场景：销售、市场、客户支持等部门，共享基础模型效率较高。

特点：

模型提供商在平台级别集中管理（成本优化）
工作区中独立的知识库和应用程序
允许成员属于多个工作区
工具（网络搜索、计算器等）共享。

2.3 模式C：跨项目模型

graph TB
    subgraph "DX推進PJ Workspace"
        E1[業務分析 App]
        E2[PJナレッジベース]
    end
    subgraph "営業部 Workspace"
        F1[営業 App]
        F2[営業ナレッジベース]
    end
    U1[ユーザーA<br/>DX推進 + 営業] --> E1
    U1 --> F1
    U2[ユーザーB<br/>DX推進のみ] --> E1

应用场景：有跨部门项目的公司。同一用户属于多个具有不同角色的工作区。

3.权限设计的最佳实践

3.1 最小权限原则

System Admin は最小人数（2-3 名）に限定する
  └── 通常業務では Workspace Admin 以下のロールを使用
      └── アプリ利用のみのユーザーは Member ロールで十分

具体建议：

用户类型	推荐角色	原因
信息系统部管理员	系统管理员	负责管理整个平台
负责部门AI推广	工作区所有者/管理员	部门中的应用和知识管理
应用程序开发人员	编辑	创建/编辑工作流程/代理
普通用户	会员	仅限应用程序使用

3.2 模型提供商管理政策

模型提供者设置对于成本控制和安全性都很重要。

推奨アプローチ:
1. System Admin がプラットフォームレベルで利用可能なモデルを設定
2. Workspace ごとに利用可能なモデルを制限（必要に応じて）
3. 各モデルの API キーは Secret Manager で一元管理
4. 月次でモデル利用量をレビュー

模型提供者配置示例（平台级别）：

供应商	型号	用途	访问限制
开放人工智能	GPT-4o	高级推理任务	所有工作区
开放人工智能	GPT-4o-迷你	日常任务	所有工作区
人择	Claude 3.5 Sonnet	长文本处理/分析	仅限特定工作区
Azure 开放人工智能	GPT-4o（日本地区）	数据主权要求适用	法律/人力资源工作空间

3.3 知识库访问控制

知识库类型	访问范围	经营方针
全公司常见问题	从所有工作区引用	由系统管理员管理，只读
部门特定知识	在此工作空间内	由工作区管理员管理
项目具体	在此工作空间内	由项目负责人管理
机密文件	严格限制	审核查看历史记录

4. API 密钥范围

4.1 API密钥颁发单位

Dify API 密钥是为每个应用程序颁发的。与外部系统协作时，应遵循以下原则。

1 つの API キー = 1 つのアプリケーション = 1 つのユースケース

反模式：跨多个系统重复使用一个 API 密钥。

4.2 API 密钥管理最佳实践

# 外部システムからの Dify API 呼び出し例
# 各システムごとに個別の API キーを発行する

# CRM システム → 商談要約 App
# API Key: app-xxxx1111 (CRM 専用)

# チャットボット → FAQ 回答 App
# API Key: app-xxxx2222 (チャットボット専用)

# 社内ポータル → ドキュメント検索 App
# API Key: app-xxxx3333 (ポータル専用)

4.3 API密钥生命周期管理

相	行动	负责人
发布	由 Workspace 管理员从应用程序发布	应用管理员
分销	通过 Secret Manager 提供给合作伙伴	基础设施团队
旋转	每 90 天颁发一个新密钥并吊销旧密钥	应用管理员
到期	立即删除不再需要的密钥	应用管理员
审计	发放钥匙的每月库存	保安团队

5. 通过 SSO 链接进行身份验证集成

5.1 推荐配置

在企业版中，可以使用 SAML 2.0/OIDC 进行 SSO。

sequenceDiagram
    participant User as ユーザー
    participant Dify as Dify Enterprise
    participant IdP as IdP (Azure AD / Okta)
    
    User->>Dify: ログイン要求
    Dify->>IdP: SAML AuthnRequest
    IdP->>User: 認証画面
    User->>IdP: 認証情報入力
    IdP->>Dify: SAML Response (属性付き)
    Dify->>Dify: Workspace / ロール自動割り当て
    Dify->>User: ダッシュボード表示

5.2 IdP 属性映射

IdP 属性	定义属性	用途
电子邮件	用户名	唯一标识符
显示名称	显示名称	界面展示
部门	工作空间分配	自动放置在适当的工作区
团体	角色分配	基于 IdP 组授予角色

5.3 实施SSO时的注意事项

预定义首次登录时自动分配工作区的规则
检查 IdP 端的组更改何时反映在 Dify 角色中
维护一个本地管理员帐户以应对紧急情况（以防 IdP 失败）
对齐 SSO 会话超时和 Dify 会话超时

6. 审计与合规

6.1 应记录在审核日志中的事件

活动类型	录制内容	保留期限
登录/注销	用户、IP、时间戳	1 年
应用程序创建/编辑/删除	操作员、目标应用程序、变更	1 年
知识库更新	操作员，添加/删除文档	1 年
API 密钥颁发/撤销	运算符、目标键、原因	1 年
添加/删除成员	操作员、目标用户、角色	1 年
模型提供商设置更改	操作员、更改前后的设置	1 年

6.2 进行定期审查

月次レビュー:
  - 各 Workspace のメンバー一覧と最終ログイン日を確認
  - 90 日以上ログインのないアカウントを無効化
  - API キーの棚卸し（不要なキーの失効）
  - Model 利用量のコスト確認

四半期レビュー:
  - ロール割り当ての妥当性確認
  - Workspace 構成の見直し
  - 監査ログの異常パターン確認
  - アクセス権限のレビュー（J-SOX 対応）

7. 典型组织结构示例

7.1 中型公司设计示例（500人，5个部门）

工作空间	人数	隔离模型	模型提供者	主要应用
销售部	50	50基础设施共享+数据分离	共享（GPT-4o、GPT-4o-mini）	商务谈判总结、提案生成
计算机科学部	30	基础设施共享+数据分离	分享	询问解答，升级判断
法律部	10	10强隔离	仅限 Azure OpenAI (日本)	合同审查、法律检索
市场部	20	基础设施共享+数据分离	分享	内容生成、市场分析
DX推广项目	15	15跨项目	分享	业务分析、PoC验证

系统管理员角色将仅限于信息系统部门的两人，每个工作空间的所有者将是部门经理或人工智能推广负责人。

8. 总结

多租户权限设计的核心是“共享效率”和“数据边界”的平衡。我们将遵循以下五项原则：

工作空间 = 租户边界：为每个部门或项目创建工作空间，隔离知识库和应用程序
模型提供者可以共享：为了提高成本效率，底层模型在平台级别进行管理，并根据需要按工作空间进行限制。
最小权限原则：系统管理员应限制在最少的人数，一般用户应被赋予最少的必要角色。
API密钥按用例分配：1 key = 1 app = 1 彻底遵循合作原则
审计和定期审查：启用审计日志记录并每月盘点会员关键成本。

权威设计一旦决定并没有结束；必须有一个持续审查它以响应组织变化的操作流程。

License管理实践–激活、续费、监控、合规操作指南

安装时激活后，Dify Enterprise 的许可证管理不会结束。 到期日期监控、续订程序、分配给多个实例、响应命名空间更改——这些需要作为持续的操作任务纳入 SOP（标准操作程序）中。

从官方文档中可以确认的一个重要事实是，许可证与 Kubernetes 集群的命名空间绑定在一起。换句话说，许可证管理是基础设施操作的一部分，而不仅仅是管理屏幕上的点击操作。

1. License的基本结构

1.1 License与部署环境的关系

graph TB
    subgraph "Dify Enterprise License"
        L[License ID: DIFY-ENT-xxxx]
    end
    subgraph "Kubernetes Cluster"
        subgraph "namespace: dify-production"
            A[dify-enterprise Pod]
            B[dify-api Pod]
            C[dify-worker Pod]
        end
    end
    L -->|bound to namespace| A
    A -->|License 検証| B
    A -->|License 検証| C

1.2 主要限制

项目	内容
装订单元	Kubernetes 命名空间
激活方法	线上/线下
更新后操作	需要重新启动 `dify-enterprise` 部署
更改命名空间时	需要重新激活

1.3 在线模式 vs 离线模式

项目	在线模式	离线模式
互联网连接	必填	不需要
value.yaml 设置	`licenseMode: "online"`	`licenseMode: "offline"`
激活	从管理控制台输入许可证密钥	手动部署许可证文件
更新	从管理控制台更新操作	放置新的许可证文件后重新启动 Pod
应用场景	标准云环境	气隙环境，严格的网络政策

2.激活步骤

2.1 在线激活

# 1. values.yaml で License モードを確認
enterprise:
  enabled: true
  licenseMode: "online"

# 2. Helm デプロイ（または既存環境の場合は upgrade）
helm upgrade -i dify dify/dify \
  -n dify-production \
  -f values.yaml \
  --wait

# 3. Enterprise 管理コンソールにアクセス
#    https://enterprise.dify.example.co.jp
#    → License 画面で License キーを入力

# 4. アクティベーション成功を確認
kubectl get pods -n dify-production -l app=dify-enterprise
# STATUS が Running であること

2.2 离线激活

# 1. values.yaml で License モードをオフラインに変更
enterprise:
  enabled: true
  licenseMode: "offline"

# 2. Helm デプロイ
helm upgrade -i dify dify/dify \
  -n dify-production \
  -f values.yaml \
  --wait

# 3. License ファイルの配置
#    公式ドキュメントの手順に従い、License ファイルを
#    所定のパスに配置する

# 4. Enterprise Pod を再起動
kubectl rollout restart deployment/dify-enterprise -n dify-production

# 5. 起動確認
kubectl rollout status deployment/dify-enterprise -n dify-production

2.3 激活后确认清单

可以登录企业管理控制台
许可证信息（到期日期和计划详细信息）正确显示。
API / Worker / Web Pod 正常处于运行状态。
应用程序创建和执行工作正常。
将License信息以截图或文本形式记录在账本中

3.许可证账本管理

3.1 管理三个账本

在企业运营中，会维护以下三个账本。

####账本1：License基本信息

项目	录制内容	示例（フィクション）
许可证编号	唯一标识符	（契約書記載の番号）
计划类型	版本名称	（契約プランによる）
出版日期	许可证发布日期	2026-01-15
有效期	有效期	2027-01-14
承包商	采购机构名称	示例有限公司
销售	联系方式	（担当営業の連絡先）
授权用户数量	上限	（契約により異なる）
允许的工作空间数量	上限	（契約により異なる）

账本2：实例信息

项目	录制内容	示例
集群名称	Kubernetes 集群标识符	产品集群 apne1
命名空间	许可证目的地	dify 生产
环境类型	生产/分期/验证	生产
经理	基础设施经理	山田太郎
用户部	主要用户组织	全公司
Dify版本	当前版本	3.7.2

账本 3：更新/操作历史记录

日期和时间	操作详情	表演者	笔记
2026-01-15	首次激活	山田太郎	在线模式
2026-04-01	版本升级3.6→3.7	山田太郎	许可证重新验证
2026-07-01	许可证刷新	山田太郎	从管理控制台实施
2026-10-15	续约谈判开始	佐藤花子	有效期 90 天前

4. 监控过期日期

4.1 多阶段警报设计

许可证到期将直接导致Dify Enterprise完全暂停，请预留足够的时间应对。

gantt
    title License 有効期限アラートスケジュール
    dateFormat  YYYY-MM-DD
    section アラート
    90日前通知 (更新交渉開始)   :milestone, m1, 2026-10-15, 0d
    60日前通知 (契約締結目標)   :milestone, m2, 2026-11-14, 0d
    30日前通知 (技術準備完了)   :milestone, m3, 2026-12-15, 0d
    14日前通知 (最終確認)       :milestone, m4, 2026-12-31, 0d
    7日前通知 (緊急対応)        :milestone, m5, 2027-01-07, 0d
    期限満了                    :milestone, m6, 2027-01-14, 0d

剩余天数	警报级别	行动	通知目的地
90 天	信息	开始续约谈判并获取报价	采购部+信息系统部
60 天	警告	签订合同并获取新的许可证密钥	采购部+信息系统部
30 日	警告	技术更新准备工作完成	信息系统部
14日	高	已执行更新工作并确认操作	信息系统部
7 天	关键	如果不完整则紧急升级	管理层+所有利益相关者

4.2 自动监控实施政策

自动监控可以通过以下方式实现：

Shell 脚本 + cron：每天执行一个脚本，从 Enterprise Pod 检索许可证到期日期，并根据剩余天数通过 Slack/电子邮件通知您。
Prometheus + AlertManager：将剩余许可证天数公开为指标并在 PrometheusRule 中定义警报

4.3 使用 Prometheus 进行指标监控

# PrometheusRule 例
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: dify-license-alerts
  namespace: monitoring
spec:
  groups:
    - name: dify-license
      rules:
        - alert: DifyLicenseExpiringSoon
          expr: dify_license_days_remaining < 30
          for: 1h
          labels:
            severity: warning
          annotations:
            summary: "Dify License の有効期限が 30 日以内です"
            description: "残り {{ $value }} 日です。更新手続きを確認してください。"
        - alert: DifyLicenseExpiryCritical
          expr: dify_license_days_remaining < 7
          for: 1h
          labels:
            severity: critical
          annotations:
            summary: "Dify License の有効期限が 7 日以内です"
            description: "残り {{ $value }} 日です。至急更新してください。"

5. 许可证更新程序

5.1 更新流程

sequenceDiagram
    participant PM as 購買担当
    participant Dify as Dify Sales
    participant IT as 情報システム部
    participant K8s as Kubernetes Cluster
    
    PM->>Dify: 更新見積もり依頼 (90日前)
    Dify->>PM: 見積もり提出
    PM->>PM: 社内承認プロセス
    PM->>Dify: 発注 (60日前)
    Dify->>IT: 新 License キー送付
    IT->>IT: ステージング環境で検証 (30日前)
    IT->>K8s: 本番 License 更新 (14日前)
    K8s->>K8s: enterprise Pod 再起動
    IT->>IT: 動作確認・台帳更新

5.2 更新实施流程（通用）

# 1. ステージング環境で事前検証（新 License キーまたはファイルを適用）

# 2. 本番環境で License 更新
#    オンライン: 管理コンソールから新しい License キーを入力
#    オフライン: 新しい License ファイルを配置

# 3. enterprise Pod を再起動（更新反映のため必須）
kubectl rollout restart deployment/dify-enterprise -n dify-production
kubectl rollout status deployment/dify-enterprise -n dify-production --timeout=300s

# 4. 動作確認
curl -s https://enterprise.dify.example.co.jp/api/health | jq .
# 管理コンソールで新しい有効期限が反映されていることを確認

6. 多个实例的许可证分发

6.1 按环境划分的分配策略

如果您的公司运营多个 Dify Enterprise 实例，请明确您的许可证分配政策。

环境	优先	许可证类型	笔记
生产	首要任务	普通许可证	到期对业务影响最大
分期	高	正版授权	生产升级前需要验证
验证/开发	中等	评估许可证或普通许可证	优先级较低，因为更容易重建
灾难恢复站点	高	普通许可证	发生故障时立即切换

6.2 更改命名空间的注意事项

由于许可证链接到命名空间，因此在以下情况下需要重新激活。

如果更改命名空间名称
如果迁移到另一个集群
故障转移到 DR 集群时

# namespace 変更時の対応手順
# 1. 新 namespace にデプロイ
helm upgrade -i dify dify/dify \
  -n dify-production-v2 \
  -f values.yaml \
  --wait

# 2. 再アクティベーション
#    管理コンソールから License キーを再入力
#    オフラインの場合は License ファイルを再配置

# 3. 旧 namespace のクリーンアップ
kubectl delete namespace dify-production-old

6.3 DR（灾难恢复）环境中的许可证

在容灾环境中，检查是否需要容灾License，记录故障切换时的重新激活过程，并提前将License文件放置到离线环境中。恢复训练期间还应验证许可证激活。

7. 合规性和内部控制

7.1 许可证相关控制点

控制项目	内容	频率
许可证库存	检查所有实例的许可证状态	季刊
使用状态回顾	检查用户和工作空间的数量是否在许可证限制内	每月
遵守合同条件	检查License使用范围是否符合合同条件	季刊
账本的准确性	检查账本记录是否与实际环境相符	季刊
追踪踪迹	保留激活和更新的工作记录	每次

7.2 审核准备情况

在准备内部审计和外部审计（J-SOX 等）时，准备许可证分类账、续订审批流程文件、工作记录、有效期监控日志和纠正程序。

8. 常见问题及解决方法

症状	原因	治疗
Enterprise Pod 无法启动	许可证未激活	从管理控制台激活
“许可证已过期”错误	有效期	执行更新程序并重新启动 Pod
命名空间迁移后身份验证错误	许可证命名空间不匹配	使用新命名空间重新激活
离线模式下不反映更新	忘记重启 Pod	执行 `kubectl rollout restart`
管理控制台不显示License信息	Enterprise Pod 异常	检查 Pod 日志并在必要时重新部署
达到用户限制	扩大用途	考虑升级您的许可证

9. 总结

下面总结了可靠许可证管理的五个原则。

维护账本：创建三个账本：License基本信息、实例信息、操作历史记录，并保持最新。
设置多步骤警报：提前90 / 60 / 30 / 14 / 7天分5步通知，以便提前进行续订流程。
将更新流程转化为SOP：登台验证→生产更新→操作确认→标准化账本更新流程
注意与命名空间的链接：始终记住，迁移、灾难恢复或更改命名空间时需要重新激活。
确保合规性：通过定期进行库存、使用情况审查和跟踪存储来为审核做好准备。

该许可证是 Dify Enterprise 的“运营先决条件”。如果此过程被中断，所有服务都将停止。这就是为什么将许可证管理定位为基础设施运营 SOP 中的首要项目非常重要。

版本升级笔记–迁移、兼容性验证、回滚策略实用指南

升级 Dify Enterprise 不仅仅是“更换镜像并重启”那么简单。 数据库迁移、配置文件变更、依赖组件版本一致性、API兼容性 – 由于这些东西同时发生变化，没有提前准备的升级将直接导致生产失败。

官方文档还明确指出“升级步骤可能因版本而异”，有必要检查每个版本的不同步骤。本文为日本公司的运营团队提供了安全执行升级的综合指南。

1. 升级概述

1.1 升级后发生的三件事改变

graph LR
    A[バージョンアップグレード] --> B[イメージ更新]
    A --> C[設定変更]
    A --> D[データマイグレーション]
    B --> B1[API / Worker / Web / Sandbox / Enterprise]
    C --> C1[values.yaml の新規・廃止パラメータ]
    C --> C2[.env の変更点]
    D --> D1[PostgreSQL スキーマ変更]
    D --> D2[Vector DB インデックス再構築]
    D --> D3[オブジェクトストレージの構造変更]

1.2 升级影响范围

影响范围	内容	风险等级
应用层	Dify各组件镜像更新	中等
数据库层	PostgreSQL 架构迁移	高
配置层	更改值.yaml / .env	中等
外部链接	API端点响应格式的更改	高
插件/提供商	插件守护程序和模型提供程序兼容性	中等
许可证	版本和许可证兼容性	低到中

2.升级前准备（Pre-Upgrade）

2.1 仔细阅读发行说明

升级的第一步是仔细阅读目标版本的发行说明。

检查要点：

重大更改：对现有功能的不兼容更改
弃用：弃用的功能和参数
迁移注意事项：数据库迁移的特别注意事项
新配置：添加配置项
已知问题：已知问题

# GitHub の Release ページを確認
# https://github.com/langgenius/dify/releases

# Enterprise 固有の変更は Enterprise Docs を確認
# https://enterprise-docs.dify.ai/en-us/deployment/

2.2 检查配置文件差异

# Docker Compose の場合: .env.example の差分を確認
diff .env.example .env.example.new

# Helm の場合: values.yaml の差分を確認
helm show values dify/dify --version <新バージョン> > values-new.yaml
diff values.yaml values-new.yaml

更改values.yaml中应特别注意的模式：

图案	通讯
添加新参数	检查默认值并在必要时明确设置
更改参数名称	用新名称替换旧名称
弃用参数	从values.yaml中删除（保留它会导致错误）
更改默认值	检查这是否是预期的行为，并在必要时澄清旧值
改变结构	修改 YAML 层次结构以匹配新格式

2.3 进行备份

**升级前切勿跳过备份。 **

# 1. PostgreSQL のフルバックアップ
pg_dump -h <DB_HOST> -U <DB_USER> -d dify_production \
  -F c -f dify_backup_$(date +%Y%m%d_%H%M%S).dump

# 2. オブジェクトストレージのスナップショット
aws s3 sync s3://dify-enterprise-prod s3://dify-enterprise-prod-backup-$(date +%Y%m%d)

# 3. Vector DB (Qdrant) のスナップショット
curl -X POST "http://qdrant-host:6333/collections/dify/snapshots"

# 4. values.yaml の退避
cp values.yaml values.yaml.backup.$(date +%Y%m%d)

# 5. Kubernetes リソースの全体バックアップ（Velero を利用する場合）
velero backup create dify-pre-upgrade-$(date +%Y%m%d) \
  --include-namespaces dify-production \
  --wait

2.4 记录当前环境的状态

将当前版本和设置记录在 helm list、kubectl get pods -o wide 和 helm get values dify 中。

3.暂存环境中的验证（Staging Validation）

3.1 暂存验证流程

graph TD
    A[Release Note 確認] --> B[ステージング環境バックアップ]
    B --> C[ステージングでアップグレード実施]
    C --> D{マイグレーション成功?}
    D -->|Yes| E[機能テスト実施]
    D -->|No| F[ログ確認・原因調査]
    F --> G[修正対応]
    G --> C
    E --> H{全テスト合格?}
    H -->|Yes| I[本番アップグレード計画策定]
    H -->|No| J[問題の切り分け]
    J --> K{回避策あり?}
    K -->|Yes| L[回避策を本番計画に反映]
    K -->|No| M[アップグレード延期]
    L --> I

3.2 分阶段验证清单

项目	确认详情	通过/失败
Pod 启动	所有组件均处于运行状态
数据库迁移	已完成且无错误
管理控制台	登录及基本操作正常
应用运营	现有应用程序运行正常
运行工作流程	现有工作流程按预期工作
代理执行	Agent可以成功调用工具
知识库	搜索工作正常
API调用	外部API调用成功
文件上传	文件上传及处理成功
单点登录	单点登录成功
许可证	许可证信息显示正确
插件	使用中的插件工作正常

4. 执行生产升级

4.1 配置维护时段

推奨スケジュール:
- 曜日: 水曜日または木曜日（週末前に問題発見の余裕を持つ）
- 時間帯: 22:00 - 02:00 JST（利用者が最少の時間帯）
- 所要時間: 2〜4 時間（検証含む）
- 事前通知: 1 週間前にユーザーへ通知

4.2 Helm 升级流程

# 1. メンテナンスモード（任意: Ingress でメンテナンスページを表示）
kubectl apply -f maintenance-ingress.yaml

# 2. 最新の Helm Chart を取得
helm repo update

# 3. アップグレード前の最終確認
helm diff upgrade dify dify/dify \
  -n dify-production \
  -f base-values.yaml \
  -f production-values.yaml \
  --version <新バージョン>

# 4. アップグレード実行
helm upgrade dify dify/dify \
  -n dify-production \
  -f base-values.yaml \
  -f production-values.yaml \
  --version <新バージョン> \
  --wait \
  --timeout 15m

# 5. Pod の起動状況を確認
kubectl get pods -n dify-production -w

# 6. マイグレーション完了を確認
kubectl logs -n dify-production deployment/dify-api --tail=100 | grep -i migration

# 7. 動作確認（ヘルスチェック）
curl -s https://api.dify.example.co.jp/health | jq .

# 8. メンテナンスモード解除
kubectl apply -f production-ingress.yaml

4.3 使用 Docker Compose 升级

Docker Compose环境下，按照以下顺序执行：docker compose down → git checkout <新タグ> → .env 差异确认/反映 → docker compose pull && docker compose up -d → 迁移日志确认。

5. 优先风险领域

5.1 数据库迁移

数据库架构更改是风险最高的领域。

リスクパターン:
1. 大規模テーブルへのカラム追加 → ロック時間の延長
2. インデックスの再構築 → 一時的なクエリ遅延
3. データ変換を伴うマイグレーション → 実行時間の予測困難
4. 複数マイグレーションの連鎖 → 中間での失敗時の復旧が複雑

对策：

使用与生产环境相同的数据量测量临时环境中的迁移时间
在执行迁移之前始终进行数据库备份
对于大规模迁移，确保更长的维护窗口

5.2 API 兼容性

如果外部系统使用Dify API，请注意以下更改。

更改类型	影响	行动
更改端点	API调用失败	更新链接系统的 URL
更改请求参数	拒绝请求	修改合作伙伴系统请求结构
更改响应格式	解析处理错误	修正联动系统的响应处理
认证方式变更	身份验证错误	兼容新的认证方式
更改速率限制	节流	调整通话频率

升级后，为聊天完成 API (/v1/chat-messages) 和工作流程执行 API (/v1/workflows/run) 准备操作检查脚本，并在临时环境和生产环境中执行它们。

5.3 插件/提供商兼容性

確認すべき項目:
- Plugin Daemon のバージョン要件
- 利用中のモデルプロバイダ（OpenAI, Anthropic, Azure OpenAI 等）の互換性
- カスタムツールの動作
- Vector DB（Qdrant, Weaviate, Milvus 等）のクライアントバージョン

6. 回滚策略

6.1 回滚决策标准

情况	判断	原因
Pod 无法启动	立即回滚	全面停止服务
数据库迁移失败	立即回滚	数据不一致风险
关键功能不起作用	30分钟内决定	违反 SLA 的风险
轻微的 UI 问题	无需回滚	等待下个版本修复
性能恶化	根据情况确定	先查明原因

6.2 使用 Helm 回滚

# Helm のリリース履歴を確認
helm history dify -n dify-production

# 直前のリビジョンにロールバック
helm rollback dify <前のリビジョン番号> -n dify-production --wait

# ロールバック後の確認
kubectl get pods -n dify-production
curl -s https://api.dify.example.co.jp/health | jq .

6.3 数据库回滚

仅使用 Helm 无法完成数据库迁移后的回滚。

# 1. Dify の全 Pod を停止
kubectl scale deployment --all --replicas=0 -n dify-production

# 2. PostgreSQL をバックアップから復元
pg_restore -h <DB_HOST> -U <DB_USER> -d dify_production \
  --clean --if-exists \
  -F c dify_backup_YYYYMMDD_HHMMSS.dump

# 3. 旧バージョンにロールバック
helm rollback dify <前のリビジョン番号> -n dify-production --wait

# 4. Pod の起動を確認
kubectl get pods -n dify-production -w

# 5. 動作確認
curl -s https://api.dify.example.co.jp/health | jq .

6.4 无法回滚的情况

如果迁移涉及数据转换或者外部链接目标已更改为新的 API，则回滚将很困难。在这种情况下，解决方案是使用“向前修复”——在新版本中修复问题，而不是恢复到以前的版本。

7. 支持版本跳转

作为一般规则，一次升级一个步骤 (v3.5.0 → v3.6.0 → v3.7.0)。如果必须跳过它，请查看中间版本的所有发行说明，并在临时环境中使用生产数据进行完整的演练。

8.升级后后续

升级后一周，重点监控API响应时间、错误率、Pod重启次数、DB连接数、内存使用情况。

8.1 升级后检查清单

所有 Pod 均稳定处于 Running 状态
数据库迁移已成功完成
现有应用程序运行正常
工作流程/代理按预期运行
知识库搜索工作正常。
外部API链接工作正常。
许可证被正确识别
SSO登录工作正常
文件上传工作正常。
管理控制台正常显示。
错误日志中没有异常模式。
性能指标在可接受的范围内
Ledger（版本信息）已更新
向用户发送升级完成通知

9. 总结

Dify Enterprise 升级包含四个阶段：计划→验证→执行→验证。五个最重要的原则是：

请务必阅读发行说明：步骤可能因版本而异
进行备份：三件套：数据库、对象存储和配置文件
一定要通过分期验证：在接近实际数据的环境中进行演练
提前准备回滚过程：记录恢复数据库快照的步骤。
增强升级后监控：密切监控指标和日志一周

“先升级再考虑”是你最应该避免的做法。安全升级意味着在运行之前清除所有迁移、兼容性检查和回滚路径。

phase-3

本阶段对应合作伙伴培训 Partners 内容。

phase-3 公开资料候选索引

说明：以下是与该阶段各主题相关的公开资料候选。优先保留 note.com、zenn.dev、Dify 官方文档、Enterprise 文档与其他日文页面。

phase-3/3-1/01-Docker-Compose-部署全流程.md

检索词：Dify Docker Compose デプロイ
note 命中：6
站点搜索命中：8

note.com 候选

「ローカル版Dify」スターターガイド！メリットや動かし方、ローカルLLM等の設定方法を紹介 | https://note.com/weel_media/n/n51a43dc02000
【DSL配布】Dify Human-in-the-Loopで営業メールを承認制にする | https://note.com/jun_ichikawa/n/ndf795dc36e5c
Multicaが凄いきになる：AIエージェントを本物のチームメイトに変えるオープンソースの管理型プラットフォーム | https://note.com/humble_bobcat51/n/n2ec52eddb09f
愛（AI）と共に：✨n8nやDifyを使いたい❣️⛵️Dockerが突破口になるかも☝️ | https://note.com/watabin/n/n2f77c4663204

zenn.dev / 官方文档 / 其他日文页面

Docker ComposeでDifyをデプロイする | https://docs.dify.ai/ja/self-host/quick-start/docker-compose
Docker Compose デプロイ | 日本語 | https://legacy-docs.dify.ai/ja-jp/getting-started/install-self-hosted/docker-compose
[Dify] 1. DockerでDifyを立ち上げる | https://zenn.dev/headwaters/articles/4f3fa5e41e7dc6
Deploy Dify with Docker Compose | https://docs.dify.ai/en/self-host/quick-start/docker-compose
Difyをローカルで動かしてみる。3分でコピペで可能。 | https://zenn.dev/minedia/articles/dify-docker-compose

phase-3/3-1/02-Helm-Chart-部署全流程.md

检索词：Dify Helm Kubernetes デプロイ
note 命中：6
站点搜索命中：8

note.com 候选

4基のH200環境におけるQwen3.5-397B-A17Bの展開とDify連携、およびネイティブマルチモーダルLLMの包括的研究 | https://note.com/aiojisan2024/n/nfb9a611d5685
フリーランス1年目を振り返る | https://note.com/syam_grit/n/n3c47652830be
DifyをAzure Kubernetes Service (AKS)で動かせるようにしました。 | https://note.com/k_7tsumi/n/n347b0db42499
ボタン一発で！ーAzure × Dify でノーコード AI エージェント開発環境をクラウドに構築 | https://note.com/sasaki_akio/n/n6af6b1a97341

zenn.dev / 官方文档 / 其他日文页面

helmを使って、minikubeでDifyをデプロイしてみた | https://zenn.dev/data_and_ai/articles/703ac71eea4b01
Difyで作ったLLM ApplicationをAzure Kubernetes Serviceに … | https://zenn.dev/microsoft/articles/dify_on_azure
生成AIアプリ開発ツールDifyをAWS EKSに導入してみた | https://zenn.dev/aki366/articles/0eb696bedf277c
Kubernetes on Jetson Linux + Ollama + Dify でローカルLLM … | https://zenn.dev/ussvgr/scraps/81168b96a16bc9
Dify on Azure | https://zenn.dev/yusu29/scraps/8bc6a603989789

phase-3/3-1/03-License-激活与验证.md

检索词：Dify Enterprise License Activation
note 命中：5
站点搜索命中：8

note.com 候选

By the way | https://note.com/198619891990/n/nf1acb5f793ef
AI Synchro Pro Ultra 9:Reinventing the Internal Engine of Artificial Intelligence for the Next Hundred Years* No/3 | https://note.com/caoru358max/n/n9b9167b8ee33
Omniversal Governance Framework | https://note.com/caoru358max/n/n94e25a7a29a4
【ChatGPTによる和訳】Udemy, Inc. (NASDAQ:UDMY) Q1 2025 Earnings Call Transcript | https://note.com/american_stock/n/n69f6bedf3e89

zenn.dev / 官方文档 / 其他日文页面

【保存版：Dify導入済の企業向け】n8n導入するべき？Difyとの … | https://zenn.dev/upgradetech/articles/eea37f22313816
Dify導入個人メモ | https://zenn.dev/metalmental/articles/20241003_dify
Environment Variables | https://docs.dify.ai/en/self-host/configuration/environments
Team Members Management | https://legacy-docs.dify.ai/guides/management/team-members-management
「n8n」を試す | https://zenn.dev/kun432/scraps/bdc9977f2f8ad6

phase-3/3-1/04-基础运维操作手册.md

检索词：Dify 運用ログエラー再起動
note 命中：6
站点搜索命中：8

note.com 候选

Claude Coworkに「構築ガイド」を渡したら、Difyのローカル環境が10分で立ち上がった話 | https://note.com/keitaro_aigc/n/na345e943a729
【保存版・初心者OK】月1万円→1,000円台に。Difyとn8nを1台のVPSで動かす完全ガイド｜SSL対応＆トラブル解決付き | https://note.com/ai_restart/n/nd882767068c6
非エンジニアが10年前のノートPCに最新AIを突っ込んだら、維持費数百円で動く最強の自律型AI執事に覚醒してしまった【第2話】心停止するAI。非同期処理の壁と「500エラー」を乗り越えた夜明け | https://note.com/goodsun931/n/nca1ffed1d086
Docker Sandbox × Claude Code で作る安全なAI作業環境 | https://note.com/satocomm/n/n5417e2de2024

zenn.dev / 官方文档 / 其他日文页面

【Dify】アプデで「Weaviate 1.19 is not supported」が出た時の … | https://zenn.dev/kotap/articles/ea3b5995b8ba44
Azure VM上のDify「Internal Server Error」の原因と対処 | https://zenn.dev/ytksato/articles/6cb73e68a568e6
【M4 Mac mini / 16GB】AI検証ログ #05：ナレッジパイプライン … | https://zenn.dev/dadu/articles/30b9d7031463d2
Self-Correction in Coding：Difyでワンショット生成の限界を … | https://zenn.dev/nocodesolutions/articles/1fd0c75476d302
WindowsでDifyを使いこなす！ | https://zenn.dev/shohei6117/scraps/90393b95105072

phase-3/3-1/05-SSO-集成配置.md

检索词：Dify SSO SAML OIDC
note 命中：6
站点搜索命中：4

note.com 候选

Keycloakを少しずつ | https://note.com/noritux/n/na1dbd9b6cde8
migration.fm Monthly News / April, 2026 | https://note.com/a_kuratani/n/n1370485c5d01
Cursor 2.0リリース！新AIモデル「Composer」の使い方・料金を徹底解説 | https://note.com/ai__worker/n/n401c78900117
Dify 全体像の解説【2025/02/20】 | https://note.com/smoothiestudio/n/n41365393c55b

zenn.dev / 官方文档 / 其他日文页面

【Dify Enterprise版】ログイン時の認証機能について | https://zenn.dev/upgradetech/articles/1029808cbc6991
Dify導入個人メモ | https://zenn.dev/metalmental/articles/20241003_dify
TIL (Things / Today I’ve learned) | https://zenn.dev/thr/scraps/a8fa435d4c2aa6
https://enterprise-docs.dify.ai/ | https://enterprise-docs.dify.ai/

phase-3/3-2/01-知识库三种构建方式.md

检索词：Dify ナレッジ構築方法
note 命中：6
站点搜索命中：8

note.com 候选

CTO が自ら顧客の前に立つ理由 — ナレッジワーク FDE の面白さ | https://note.com/knowledgework/n/n83b1b7949710
Difyで話題の「16タイプ診断」を作ってみた！チャットフローで作るコンサルBotのすすめ | https://note.com/weel_media/n/nd8fe23b955d8
【2026年版】AI×チャットボット構築代行完全ガイド｜プログラミング不要で法人向け高単価副業を月10万円で受ける方法 | https://note.com/skysee_/n/n61ec6c671870
「あるはずの情報が見つからない」── Dify RAGチャットボット開発で踏んだ落とし穴と自動評価システムの構築 | https://note.com/kadinche/n/n87b77918dab9

zenn.dev / 官方文档 / 其他日文页面

ナレッジをクイック作成 - Dify Docs | https://docs.dify.ai/ja/use-dify/knowledge/create-knowledge/introduction
専用教科書！ナレッジベースを作りましょう！ | https://zenn.dev/hamaup/books/6c09e513a52bdc/viewer/fef868
ナレッジ - Dify Docs | https://docs.dify.ai/ja/use-dify/knowledge/readme
[Dify] 2. テキストファイルをからナレッジを作成する | https://zenn.dev/headwaters/articles/e2cc40a31cdd11
ナレッジベース作成 | 日本語 | https://legacy-docs.dify.ai/ja-jp/guides/knowledge-base/create-knowledge-and-upload-documents

phase-3/3-2/02-提示词设计规范.md

检索词：Dify プロンプト設計ベストプラクティス
note 命中：6
站点搜索命中：8

note.com 候选

ハーネスエンジニアリングとは？ OpenAIが「コードを1行も書かず100万行」を実現した設計手法 | https://note.com/kazu_t/n/nbd4a66d91fc0
Dify 本番運用レベルで安全に構築 | https://note.com/aoyama_sys/n/n0c7dfe55f48f
「LLMに“こうしろ“と言っても聞かない」1週間で学んだ、エージェント設計の急所 | https://note.com/maron0917/n/n16b05484096c
生成AIに学習させる方法3選──ファインチューニング・RAG・プロンプト設計を目的別に選ぶ | https://note.com/ai_laboratories/n/n4d7335acf246

zenn.dev / 官方文档 / 其他日文页面

Difyで始めるAIエージェント開発 ― 安全な社内活用のため … | https://zenn.dev/difymaster/articles/44b788166d8858
Dify チャットフローを AI が生成する仕組みを AI で作った話 | https://zenn.dev/ryoyoshii/articles/05d2ffe846f518
【Dify】会話変数とコンテキストエンジニアリングを徹底的に深 … | https://zenn.dev/nocodesolutions/articles/79e235c9311ff0
API 基づく開発 - Dify Docs | https://docs.dify.ai/versions/legacy/ja/user-guide/application-publishing/developing-with-apis
GitHub × Dify コードレビューAI 導入マニュアル（完全詳細ガイド） | https://zenn.dev/yamamoto620/articles/44dd2d7fbe9273

phase-3/3-2/03-Workflow-节点类型与组合模式.md

检索词：Dify Workflow 条件分岐反復 human in the loop
note 命中：0
站点搜索命中：8

note.com 候选

当前未检索到足够相关的 note.com 结果

zenn.dev / 官方文档 / 其他日文页面

Human-in-the-Loopの活用事例 Difyでの具体的な運用 … | https://zenn.dev/nocodesolutions/articles/62a03c6770b824
Human-in-the-Loopの概念をDifyに落とし込み、AIの暴走を … | https://zenn.dev/nocodesolutions/articles/df0d883c7d1f79
（ノード）ロジック関連ノード：条件分岐 / 質問分類器 / ループ … | https://zenn.dev/kentaichimura/books/e48a042e40c657/viewer/811951
【おじさんでもできた】DifyのHuman Inputノードで承認 … | https://zenn.dev/ojisan_ai_lab/articles/9c9122de1ad3e4
Dify チャットフローを AI が生成する仕組みを AI で作った話 | https://zenn.dev/ryoyoshii/articles/05d2ffe846f518

phase-3/3-2/04-Agent-工具定义规范.md

检索词：Dify Agent ツール定義説明
note 命中：6
站点搜索命中：8

note.com 候选

実はClaude Codeで、DifyやZapierのような「自動化ワークフロー」もつくれる | https://note.com/kajiken0630/n/ne3f5b9161bd5
国内AIエージェント動向(2026/4/1号) | https://note.com/yasuhitoo/n/ne72b855e32ad
第4回 Claude SkillsとAIエージェントの未来——今学ぶことが、次世代AI活用の土台になる | https://note.com/takayuki_sase/n/n14513db9367d
非エンジニアのためのAIエージェント完全ガイド | https://note.com/clean_eagle110/n/nf1d4ebdd0c3c

zenn.dev / 官方文档 / 其他日文页面

エージェント | https://docs.dify.ai/ja/use-dify/nodes/agent
エージェント | https://docs.dify.ai/versions/legacy/ja/user-guide/build-app/agent
エージェント | 日本語 | https://legacy-docs.dify.ai/ja-jp/guides/workflow/node/agent
[AI Agent Jump Start：応用編#7] Dify | https://zenn.dev/dxclab/articles/ddceffea0903f3
（ツール）ツール概要｜Dify完全ガイド：導入から本番 … | https://zenn.dev/kentaichimura/books/e48a042e40c657/viewer/5a13f8

phase-3/3-2/05-API-集成对接指南.md

检索词：Dify API 連携ガイド
note 命中：6
站点搜索命中：8

note.com 候选

n8nでできること完全ガイド｜業務自動化×AI連携を実践例でわかる | https://note.com/weel_media/n/n17758fb2a49c
【2026年版】AI×チャットボット構築代行完全ガイド｜プログラミング不要で法人向け高単価副業を月10万円で受ける方法 | https://note.com/skysee_/n/n61ec6c671870
生成AIを「使う」から「作る」へ。岩手大学でDify×LINE Bot×RAGの学生向けワークショップを実施！ | https://note.com/protoout/n/nbea08ffeab79
【2026年3月版】GitHub AIリポジトリTop12完全解説｜OpenClaw 31万スターの衝撃からClaude Dispatchまで | https://note.com/yasuda_forceai/n/n32f1ce72d4bb

zenn.dev / 官方文档 / 其他日文页面

DeepSeek & Dify連携ガイド：多段階推論を活用したAI … | https://legacy-docs.dify.ai/ja-jp/learn-more/use-cases/integrate-deepseek-to-build-an-ai-app
データソース認証 - Dify Docs | https://docs.dify.ai/ja/use-dify/knowledge/knowledge-pipeline/authorize-data-source
外部ナレッジベースAPI | 日本語 | https://legacy-docs.dify.ai/ja-jp/guides/knowledge-base/external-knowledge-api-documentation
【Dify 入門】Difyで独自情報を付与したチャットボットを構築して | https://zenn.dev/solvio/articles/9b0b34e3c3a847
（Dify基礎）DifyアプリのAPI化：作ったアプリを公開 | https://zenn.dev/kentaichimura/books/e48a042e40c657/viewer/20a99e

phase-3/3-3/01-部署验收标准.md

检索词：Dify 導入チェックリスト稼働確認
note 命中：1
站点搜索命中：8

note.com 候选

#460 Harbor 2.13 を Rocky Linux 9 に導入した手順とポイントまとめ ―― Linux・コンテナ・レジストリ初心者向けインストール体験記 ―― | https://note.com/tsysk/n/nf92e58762b9a

zenn.dev / 官方文档 / 其他日文页面

レッスン 3：ワークフローの頭脳（LLM ノード） | https://docs.dify.ai/ja/use-dify/tutorials/workflow-101/lesson-03
プラグイン開発ガイドライン | https://docs.dify.ai/ja/develop-plugin/publishing/standards/contributor-covenant-code-of-conduct
（ノード）コード実行ノード｜Dify完全ガイド | https://zenn.dev/kentaichimura/books/e48a042e40c657/viewer/155720
（ノード）ユーザー入力 / 出力ノード｜Dify完全ガイド | https://zenn.dev/kentaichimura/books/e48a042e40c657/viewer/b1ee2d
30分間クイックスタート - Dify Docs | https://docs.dify.ai/ja/use-dify/getting-started/quick-start

phase-3/3-3/02-基础功能验证项目.md

检索词：Dify ナレッジテストケース
note 命中：6
站点搜索命中：8

note.com 候选

「あるはずの情報が見つからない」── Dify RAGチャットボット開発で踏んだ落とし穴と自動評価システムの構築 | https://note.com/kadinche/n/n87b77918dab9
「自動デバッグ」をループ的に行う自律型エージェントをDify上に構築してみた | https://note.com/nocode_solutions/n/ncc238b99d789
AIが自ら「検索し直す」。DeepSeek-R1とDifyが作る高度なRAG構築の最前線 | https://note.com/nocode_solutions/n/nbe6c159a5460
【2026年3月版】GitHub AIリポジトリTop12完全解説｜OpenClaw 31万スターの衝撃からClaude Dispatchまで | https://note.com/yasuda_forceai/n/n32f1ce72d4bb

zenn.dev / 官方文档 / 其他日文页面

ナレッジ検索テスト | https://docs.dify.ai/ja/use-dify/knowledge/test-retrieval
【Dify】RAG大全：仕組みと設定を徹底解説 | https://zenn.dev/upgradetech/articles/ac9099a6489abe
【Dify】ナレッジパイプライン調査レポート2/3 - 文脈を理解した「 … | https://zenn.dev/upgradetech/articles/fa118f1eba541c
質問分類器 - Dify Docs | https://docs.dify.ai/ja/use-dify/nodes/question-classifier
ナレッジベースリストを取得 | https://docs.dify.ai/api-reference/%E3%83%87%E3%83%BC%E3%82%BF%E3%82%BB%E3%83%83%E3%83%88/%E3%83%8A%E3%83%AC%E3%83%83%E3%82%B8%E3%83%99%E3%83%BC%E3%82%B9%E3%83%AA%E3%82%B9%E3%83%88%E3%82%92%E5%8F%96%E5%BE%97

phase-3/3-3/03-客户移交文档模板.md

检索词：システム引き継ぎドキュメントテンプレート運用
note 命中：6
站点搜索命中：8

note.com 候选

士業のための“クラウド禁止でも事故らない“書類OCR運用ガイド | https://note.com/akiufmi_dx/n/nbba52729473a
週刊｜話題のAI新製品・新機能ニュース(2026/3/29〜4/4号) | https://note.com/yasuhitoo/n/na5f8b05d4c65
ClaudeCodeとGitでコンサルの仕事を完結させる | https://note.com/yusaku_0426/n/n35734433594a
AIエージェントが19人の社員になった日 — ソロ創業者のリアル運用記録 | https://note.com/tpaiagentcom_tk/n/ne94a9b784059

zenn.dev / 官方文档 / 其他日文页面

「引き継ぎ書が使えない」は、もう終わらせよう。AIと作る「生きた … | https://zenn.dev/recurrenthub/articles/f1bfa2241a804f
離任に向けた引き継ぎ資料（詳細版） | https://zenn.dev/ted99/articles/7b29f8e896cc8f
離任に向けた引き継ぎ資料(サマリ版) | https://zenn.dev/ted99/articles/1e357fb74b2d36
Claude Cowork x Agent Skillsによる定型業務の即時引き継ぎ | https://zenn.dev/kobarutosato/articles/54ce4eb416e38a
GitHub Copilotで1ヶ月に100個のドキュメントを作成した話 | https://zenn.dev/j____takumi/articles/create_docs_by_copilot

phase-3/3-3/04-常见客户问题-QA-库.md

检索词：Dify よくある質問トラブルシュート
note 命中：1
站点搜索命中：7

note.com 候选

【AI時短術】動画を投げるだけで画像付きマニュアルが完成する時代 | https://note.com/keito_12kk2/n/n4a9477084459

zenn.dev / 官方文档 / 其他日文页面

[Dify]openAIプラグインインストールエラーを解決した話 | https://zenn.dev/zuzuzu/articles/dify_plugin_install_error
Dify個人検証レポート（前編） | https://zenn.dev/kayu_san/articles/f7138773bce95a
Difyをローカルで動かしてみる。3分でコピペで可能。 | https://zenn.dev/minedia/articles/dify-docker-compose
WindowsでDifyを使いこなす！ | https://zenn.dev/shohei6117/scraps/90393b95105072
「完全自律型」AIエージェント至高論への違和感〜ワークフロー … | https://zenn.dev/pharmax/articles/d1d3695e4114c0

phase-3/3-3/05-升级与续费提醒机制.md

检索词：SaaS 更新通知ライセンス更新案内テンプレート
note 命中：2
站点搜索命中：8

note.com 候选

Palantir AIPCon 9 レポート：海軍、GE、SAP、医療。あらゆる現場を「再鍛造」する産業用OSの衝撃 | https://note.com/zenkok/n/n7a1dabfd8585
京都でホームページ制作を依頼する前に押さえるべき5つのコツ | https://note.com/pikoz/n/nf6785cedf9b3

zenn.dev / 官方文档 / 其他日文页面

n8nを使って面倒くさいリリースノートのチェックを自動化してみた | https://zenn.dev/cloud_ace/articles/n8n-google-cloud-release-note
インフラエンジニアがスタートアップで情シスを兼任した時のメモ | https://zenn.dev/ruchika/articles/66ba0b8e2a57a9
MIT ライセンスは「リンクで完結してよい」とは書かれていない | https://zenn.dev/kyoten/articles/d3aa2e8ac17ad1
Copilotに対して多分みんなが思っていることへのカウンター | https://zenn.dev/headwaters/articles/20250602-copilot
SaaS設計レビュー観点チェックリスト【2025年版】 | https://zenn.dev/kanaria007/articles/101e51dbcf2135

Docker Compose 完整部署指南──从必备准备到服务启动、验证和故障排除

体验 Dify Enterprise 的最快方法是使用 Docker Compose 进行部署。在本文中，我们将在命令级别详细解释在一台服务器上启动所有 Dify Enterprise 服务并从浏览器访问它们的步骤。

定位：Docker Compose 非常适合 PoC、验证和培训目的。有关生产环境中的高可用性配置，请参阅 Helm Chart デプロイガイド。

1.先决条件

1.1 硬件要求

项目	最低规格	推荐规格
中央处理器	4 核	8核以上
内存	16GB	32 GB 或更多
磁盘	50 GB 固态硬盘	100 GB SSD 或更多

如果您要向矢量数据库输入大量数据，请提供更多磁盘和内存空间。

1.2 软件要求

软件	版本	验证命令
Docker 引擎	24.0 或更高	`docker version`
Docker Compose (V2)	2.23 或更高	`docker compose version`
git	git任何	`git --version`

Docker Compose V1（docker-compose 命令）已弃用。请使用V2（docker compose子命令格式）。

1.3 网络要求

拉取对 Docker Hub 或私有注册表的访问权限
打开端口80/443（nginx监听）
对于内部代理环境，设置 HTTP_PROXY / HTTPS_PROXY

# Docker のバージョン確認
docker version --format '{{.Server.Version}}'

# Docker Compose V2 の確認
docker compose version

2. 存储库克隆和目录结构

2.1 获取源码

# Dify リポジトリをクローン
git clone https://github.com/langgenius/dify.git
cd dify/docker

如果提供了企业版的私有存储库，请替换该 URL。

2.2 主目录结构

dify/docker/
├── docker-compose.yaml          # メインの Compose 定義
├── docker-compose.middleware.yaml # ミドルウェアのみの構成（開発用）
├── .env.example                 # 環境変数テンプレート
├── nginx/
│   ├── nginx.conf.template      # nginx 設定テンプレート
│   └── proxy.conf.template      # プロキシ設定テンプレート
├── volumes/                     # 永続化データの格納先
│   ├── db/                      # PostgreSQL データ
│   ├── redis/                   # Redis データ
│   └── weaviate/                # ベクトルデータベース
└── ssrf_proxy/
    └── squid.conf.template      # SSRF プロキシ設定

3.设置环境变量(.env)

3.1 复制模板

cp .env.example .env

3.2 主要设置项

.env 文件是决定 Dify 行为的最重要的配置文件。我将分以下几类进行解释。

####服务基本设置

# ── モード設定 ──
MODE=api      # api | worker（単独起動時に使用）

# ── シークレットキー ──
# 必ず変更してください。openssl rand -base64 42 などで生成
SECRET_KEY=sk-xxxxxxxxxxxxxxxxxxxx

# ── ログレベル ──
LOG_LEVEL=INFO    # DEBUG | INFO | WARNING | ERROR

数据库连接

# ── PostgreSQL ──
DB_USERNAME=postgres
DB_PASSWORD=difyai123456    # 必ず変更してください
DB_HOST=db
DB_PORT=5432
DB_DATABASE=dify

# 接続プール
SQLALCHEMY_POOL_SIZE=30
SQLALCHEMY_MAX_OVERFLOW=10

Redis 连接

# ── Redis ──
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=difyai123456    # 必ず変更してください
REDIS_DB=0

# Celery ブローカー（Worker が使用）
CELERY_BROKER_URL=redis://:difyai123456@redis:6379/1

####向量数据库

# ── ベクトルストア ──
VECTOR_STORE=weaviate    # weaviate | qdrant | milvus | pgvector など

# Weaviate の場合
WEAVIATE_ENDPOINT=http://weaviate:8080
WEAVIATE_API_KEY=WVF5YThaHlkYwhGUSmCRgsX3tD5ngdN8pkih   # ⚠ これは .env.example のデフォルト値です。本番では必ず変更してください

存储设置

# ── ファイルストレージ ──
STORAGE_TYPE=local             # local | s3 | azure-blob | google-storage
STORAGE_LOCAL_PATH=storage     # local の場合のパス

# S3 互換ストレージの場合
S3_ENDPOINT=https://s3.amazonaws.com
S3_BUCKET_NAME=dify-storage
S3_ACCESS_KEY=your-access-key
S3_SECRET_KEY=your-secret-key
S3_REGION=ap-northeast-1

nginx / 公共 URL

# ── nginx ──
NGINX_HTTPS_ENABLED=false
NGINX_PORT=80
NGINX_SSL_PORT=443

# ── サービスの公開 URL ──
# 外部からアクセスする際の URL（nginx 経由）
CONSOLE_WEB_URL=http://your-server-ip
CONSOLE_API_URL=http://your-server-ip
SERVICE_API_URL=http://your-server-ip
APP_WEB_URL=http://your-server-ip

3.3 安全注意事项

请务必更改以下默认值。

项目	原因
`SECRET_KEY`	用于会话签名和加密（生产环境必须用 `openssl rand -base64 42` 重新生成）
`DB_PASSWORD`	PostgreSQL 密码
`REDIS_PASSWORD`	Redis密码
`WEAVIATE_API_KEY`	矢量数据库认证（`.env.example` 中的默认值 `WVF5YThaHlkYwhGUSmCRgsX3tD5ngdN8pkih` 务必更换）

# シークレットキーの生成例
openssl rand -base64 42

4. docker-compose.yaml 中的服务配置

4.1 整体架构

graph TB
    Client[ブラウザ / API クライアント]
    Client --> nginx

    subgraph "Docker Compose ネットワーク"
        nginx[nginx<br/>リバースプロキシ<br/>:80 / :443]
        nginx --> web[web<br/>Next.js フロントエンド<br/>:3000]
        nginx --> api[api<br/>Flask API サーバー<br/>:5001]

        api --> db[(db_postgres<br/>PostgreSQL<br/>:5432)]
        api --> redis[(redis<br/>Redis<br/>:6379)]
        api --> weaviate[(weaviate<br/>ベクトル DB<br/>:8080)]
        api --> sandbox[sandbox<br/>コード実行<br/>:8194]
        api --> ssrf_proxy[ssrf_proxy<br/>Squid<br/>:3128]
        api --> plugin_daemon[plugin_daemon<br/>プラグイン実行]

        worker[worker<br/>Celery Worker]
        worker --> db
        worker --> redis
        worker --> weaviate

        worker_beat[worker_beat<br/>Celery Beat<br/>定期タスク]
        worker_beat --> redis
    end

4.2 各个服务的作用

核心服务

服务名称	角色	基础图像	内部端口
`api`	提供REST API。 LLM调用、知识库操作、工作流执行等核心处理	`langgenius/dify-api`	5001
`worker`	Celery worker。处理异步任务（文档索引、电子邮件发送等）	`langgenius/dify-api`	-
`worker_beat`	芹菜节拍。安排定期任务（统计汇总、清理等）	`langgenius/dify-api`	-
`web`	基于 Next.js 的前端 UI。提供管理控制台和应用程序屏幕	`langgenius/dify-web`	3000
`plugin_daemon`	插件执行环境。管理工具和模型提供商插件	`langgenius/dify-plugin-daemon`	-

基础设施服务

服务名称	角色	基础图像	内部端口
`db`	PostgreSQL。存储持久数据，例如用户、应用程序、对话历史记录等。 `postgres:15-alpine`	5432
`redis`	雷迪斯。用于缓存、Celery 任务队列、会话管理	`redis:7-alpine`	6379
`weaviate`	矢量数据库。存储知识库嵌入索引	`semitechnologies/weaviate`	8080
`nginx`	反向代理。将外部请求分发到 web/api	`nginx:latest`	80, 443
`sandbox`	用于代码执行的沙箱环境。用于工作流代码节点	`langgenius/dify-sandbox`	8194
`ssrf_proxy`	基于 Squid 的代理。网络隔离防止SSRF攻击	`ubuntu/squid:latest`	3128

4.3 服务之间的依赖关系

docker-compose.yaml的depends_on定义的启动顺序如下。

db, redis ← api ← nginx
db, redis ← worker
redis     ← worker_beat
           ← web ← nginx
           ← sandbox ← api
           ← ssrf_proxy ← api
weaviate  ← api, worker

重要：depends_on 只保证容器的启动顺序，不保证服务的 Ready 状态。建议使用 healthcheck 和 condition: service_healthy 的组合，因为 api 可能会在 PostgreSQL 或 Redis 完全启动之前尝试连接。

5.执行部署

5.1 启动服务

# docker ディレクトリにいることを確認
cd dify/docker

# 全サービスをバックグラウンドで起動
docker compose up -d

第一次启动时，需要几分钟时间来拉取 Docker 镜像。请根据您的线路速度稍等。

5.2 检查启动状态

# 全コンテナの状態を確認
docker compose ps

# 期待される出力例
# NAME          STATUS       PORTS
# api           Up (healthy) 5001/tcp
# worker        Up           
# worker_beat   Up           
# web           Up           3000/tcp
# db            Up (healthy) 5432/tcp
# redis         Up (healthy) 6379/tcp
# weaviate      Up           8080/tcp
# nginx         Up           0.0.0.0:80->80/tcp
# sandbox       Up           8194/tcp
# ssrf_proxy    Up           3128/tcp
# plugin_daemon Up

确保所有容器的状态为 Up。服务显示(healthy)表示健康检查已完成。

5.3 查看日志

# 全サービスのログをリアルタイムで表示
docker compose logs -f

# 特定サービスのログのみ
docker compose logs -f api
docker compose logs -f worker

# 直近 100 行を表示
docker compose logs --tail 100 api

6.运行验证

6.1 从浏览器访问

1.在浏览器中访问http://<サーバーIP> 2. 将首次显示设置屏幕。 3. 注册管理员账户（邮箱地址、密码） 4. 登录后如果显示仪表板，则说明登录成功。

6.2 API健康检查

# API サーバーの稼働確認（Dify 1.x の標準ヘルスエンドポイント）
curl -s http://localhost/console/api/health | python3 -m json.tool

# 期待される応答
# {
#     "pong": "ok",
#     "version": "..."
# }

メモ：旧版本では /v1/health も使われていましたが、Dify 1.x では /console/api/health が標準です。デプロイ後 200 を返さない場合は、docker compose ps で api コンテナが healthy になっているか確認してください。

6.3 检查各部件的连接

# PostgreSQL への接続確認
docker compose exec db psql -U postgres -d dify -c "SELECT version();"

# Redis への接続確認
docker compose exec redis redis-cli -a difyai123456 ping
# 期待される応答: PONG

# Weaviate の稼働確認
curl -s http://localhost:8080/v1/.well-known/ready

6.4 简单测试场景

要全面检查部署是否成功，请运行以下场景：

步骤	运营	检查点
1	登录控制台	UI显示正确
2	配置模型提供者	API 密钥保存成功
3	创建聊天应用程序	应用程序创建对话框有效
4	发送聊天	得到LLM的回应
5	创建知识库并上传文档	索引开始
6	在知识库聊天中提问	RAG将回答

7. 常用操作命令

7.1 停止和重新启动服务

# 全サービスを停止（データは保持）
docker compose stop

# 全サービスを停止し、コンテナとネットワークを削除（ボリュームは保持）
docker compose down

# 全サービスを停止し、ボリュームも削除（データ完全削除）
docker compose down -v

# 特定サービスの再起動
docker compose restart api
docker compose restart worker

7.2 更新

# 最新のソースを取得
git pull origin main

# 最新イメージの Pull と再起動
docker compose pull
docker compose up -d

# 特定サービスのみ更新
docker compose pull api web
docker compose up -d api web

7.3 资源监控

# コンテナごとの CPU / メモリ使用率をリアルタイム表示
docker stats

# 特定コンテナのリソース確認
docker stats api worker db redis

8. 故障排除

8.1 容器未启动

# コンテナの終了理由を確認
docker compose ps -a
docker compose logs <サービス名>

# よくある原因と対処
# 1. ポート競合 → 80 番ポートが別プロセスで使用中
sudo lsof -i :80

# 2. メモリ不足 → Docker Desktop のメモリ割り当てを確認
docker info | grep "Total Memory"

8.2 数据库连接错误

# PostgreSQL のログを確認
docker compose logs db

# 接続テスト
docker compose exec api python -c "
import psycopg2
conn = psycopg2.connect(
    host='db', port=5432,
    user='postgres', password='difyai123456',
    dbname='dify'
)
print('Connection OK')
conn.close()
"

常见原因：

.env 的 DB_PASSWORD 与实际 PostgreSQL 密码不匹配
API 在 PostgreSQL 初始化完成之前启动（→ docker compose restart api）

8.3 Redis连接错误

# Redis のログを確認
docker compose logs redis

# Redis への直接接続テスト
docker compose exec redis redis-cli -a difyai123456 info server

8.4 nginx 返回 502 Bad Gateway

# nginx のログを確認
docker compose logs nginx

# api / web コンテナが起動しているか確認
docker compose ps api web

# nginx の設定をテスト
docker compose exec nginx nginx -t

常见原因：

API 或 Web 仍在启动（等待启动完成）
.env的CONSOLE_API_URL设置不正确

8.5 Worker不处理任务

# Worker のログを確認
docker compose logs worker worker_beat

# Redis のキュー状態を確認
docker compose exec redis redis-cli -a difyai123456 llen celery

常见原因：

无法连接到Redis
CELERY_BROKER_URL配置错误

8.6 磁盘空间问题

# Docker が使用しているディスク容量を確認
docker system df

# 未使用のイメージ・コンテナ・ボリュームを削除
docker system prune -f

# 未使用ボリュームの削除（注意: データが失われる可能性あり）
docker volume prune -f

9. 启用 HTTPS

我们建议在接近生产的测试环境中启用 HTTPS。

9.1 创建自签名证书（用于验证）

mkdir -p nginx/ssl

openssl req -x509 -nodes -days 365 \
  -newkey rsa:2048 \
  -keyout nginx/ssl/server.key \
  -out nginx/ssl/server.crt \
  -subj "/CN=dify.local"

9.2 .env 更改

NGINX_HTTPS_ENABLED=true
NGINX_PORT=80
NGINX_SSL_PORT=443

# URL も https に変更
CONSOLE_WEB_URL=https://dify.local
CONSOLE_API_URL=https://dify.local
SERVICE_API_URL=https://dify.local
APP_WEB_URL=https://dify.local

9.3 重启

docker compose down
docker compose up -d

10. 服务故障的影响范围

对于运营来说，了解如果服务停止哪些功能将受到影响非常重要。

停止服务	影响范围
`nginx`	禁止所有访问
`api`	所有 API 调用均被禁用。 UI显示但无法检索数据
`web`	无法显示前端 UI。可以直接调用API
`worker`	文档索引创建，异步处理停止。聊天本身可能有效
`worker_beat`	周期性任务（如统计聚合）将不再执行
`db`	几乎所有功能都停止了。无法读取或写入用户身份验证、应用程序设置、对话历史记录
`redis`	缓存队列已停止。 API响应延迟，Worker任务处理停止
`weaviate`	知识库搜索是不可能的。聊天本身可以工作，但我无法使用 RAG
`sandbox`	工作流代码节点无法执行
`plugin_daemon`	插件（自定义工具/模型提供程序）不起作用

11. 迁移到生产环境

Docker Compose 非常适合验证和 PoC，但它对于生产操作有以下限制。

挑战	Docker Compose 的局限性	生产推荐配置
高可用性	单一主机故障导致全面中断	Kubernetes + ReplicaSet
缩放	仅手动缩放	HPA（水平 Pod 自动缩放器）
滚动更新	停机时间	Kubernetes 部署
监控	仅 Docker 统计信息	普罗米修斯 + Grafana
秘密管理	明文转`.env`	Kubernetes 秘密 / Vault
备份	手动脚本	Velero / 托管数据库

生产环境迁移请参考Helm Chart デプロイガイド。

总结

在本文中，我们使用以下流程解释了 Dify Enterprise 的 Docker Compose 部署。

检查先决条件 – 检查硬件和软件要求
克隆存储库 – 了解目录结构
环境变量设置 – .env文件中各项的含义及推荐值
理解服务配置 – 11个服务的角色和依赖关系
启动与验证 – 从docker compose up -d到运行确认
操作命令 – 停止、更新、监控等基本操作
故障排除 – 常见问题及其解决步骤

在使用 Docker Compose 了解系统的整体结构后，我们建议下一步使用 Helm Charts 部署 Kubernetes。

参考资料

-Docker Compose で Dify をデプロイする - Dify 公式ドキュメント -Deploy Dify with Docker Compose - Dify Docs (EN) -Dify GitHub リポジトリ

Helm Chart 完整部署指南 ─ 从 Kubernetes 环境准备到 Ingress 发布和运行

Kubernetes + Helm Chart 是在生产环境中运行 Dify Enterprise 时推荐的部署路径。在本文中，我们将全面讲解从检查集群先决条件到 helm install、Ingress 设置、操作验证和升级/回滚的所有内容。

必备知识：假设您了解 Kubernetes 的基本概念（Pod、Deployment、Service、PVC、Ingress）以及 kubectl 的基本操作。如果您先尝试 Docker Compose 版本，会更容易理解服务配置。 → Docker Compose デプロイガイド

1.先决条件

1.1 Kubernetes 集群要求

项目	要求
Kubernetes 版本	1.24 或更高
Helm	3.14 或更高
节点数量（推荐）	3 个或更多节点（生产）
每个节点的推荐规格	4 vCPU / 16 GB RAM 或更多
存储类	需要具有动态配置的 StorageClass
入口控制器	nginx-ingress 或同等控制器正在运行

1.2 外部资源

Dify Enterprise 的 Helm Chart 假设您已提前准备好以下外部资源。对于生产环境，我们建议使用托管服务。

资源	应用	推荐的托管服务示例
PostgreSQL	主数据库	Amazon RDS、Cloud SQL、Azure Database for PostgreSQL
Redis	缓存/任务队列	Amazon ElastiCache、云内存存储、Azure Redis 缓存
对象存储	文件/文档存储	Amazon S3、Google 云存储、Azure Blob 存储
矢量数据库	知识库索引	Weaviate 云、Qdrant 云、Zilliz (Milvus)

注意：可以配置 Helm Chart 以包含这些中间件，但在生产环境中，从数据持久性和可操作性的角度来看，我们建议使用托管服务。

1.3 检查工具版本

# Kubernetes バージョン確認（kubectl 1.28+ では --short は廃止のため -o yaml を使用）
kubectl version -o yaml

# Helm バージョン確認
helm version --short

# クラスタのノード状態確認
kubectl get nodes -o wide

# StorageClass の確認
kubectl get storageclass

# Ingress Controller の確認
kubectl get pods -n ingress-nginx

2.命名空间设计

2.1 为什么命名空间设计很重要

Dify Enterprise 有一个规范：许可证链接到命名空间。这意味着稍后更改您的命名空间可能需要您重新激活您的许可证。请一开始就仔细设计。

2.2 推荐的命名空间配置

# 開発環境
kubectl create namespace dify-dev

# ステージング環境
kubectl create namespace dify-staging

# 本番環境
kubectl create namespace dify-prod

2.3 命名空间设计指南

环境	命名空间	用途	许可证
发展	`dify-dev`	功能验证、开发人员测试	开发许可证
分期	`dify-staging`	发布前验证、负载测试	演出许可证
生产	`dify-prod`	最终用户的生产运营	生产许可证

# 以降の手順では本番環境を例に進めます
export NAMESPACE=dify-prod
kubectl config set-context --current --namespace=${NAMESPACE}

3.添加Helm存储库

⚠️ 重要：Dify 没有官方维护的 Helm Chart 仓库（helm.dify.ai 不存在）。OSS 部署需选用社区维护的 Chart 之一。Enterprise 版通过私有 OCI registry 分发，由 LangGenius / 合作伙伴提供。

3.1 存储库注册（社区 Chart 示例）

主要社区 Chart 选项（截至 2026-05）：

提供者	仓库
@BorisPolonsky（最常用）	`https://github.com/BorisPolonsky/dify-helm`
@LeoQuote (douban)	`https://github.com/douban/charts/tree/master/charts/dify`
@magicsong	`https://github.com/magicsong/ai-charts`
@Ruiruiz30（AKS Pipeline）	`https://github.com/Ruiruiz30/Dify-helm-chart-AKS`

# 示例：使用 BorisPolonsky/dify-helm
git clone https://github.com/BorisPolonsky/dify-helm.git
cd dify-helm

# 或者将其作为 chart dependency 通过 raw GitHub 引用
# 注意：community charts 没有统一的 helm repo URL，
# 通常通过 git clone 后 `helm install` 本地路径
helm install dify-staging . -f values.staging.yaml

如使用 Dify Enterprise，请联系 LangGenius / 合作伙伴获取私有 OCI registry 凭证 + Chart 版本号。Enterprise Chart 与上面任何 OSS 社区 Chart values schema 都不通用，请勿混用。

3.2 检查默认值

# デフォルトの values.yaml を確認（全設定項目の一覧）
helm show values dify/dify > values-default.yaml

# ファイルを開いて構造を把握
less values-default.yaml

我们建议创建自定义值文件并覆盖它，而不是直接编辑默认值。

4. 自定义values.yaml

4.1 创建自定义值文件

以下是生产环境的自定义 values.yaml 配置示例。

# values-prod.yaml
# Dify Enterprise 本番環境設定

# ── グローバル設定 ──
global:
  # 外部からアクセスする URL
  host: "dify.example.com"
  enableTLS: true
  edition: "enterprise"
  # シークレットキー（必ず変更）
  secretKey: "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# ── API サービス ──
api:
  replicaCount: 2
  resources:
    requests:
      cpu: "1"
      memory: "2Gi"
    limits:
      cpu: "2"
      memory: "4Gi"
  env:
    LOG_LEVEL: "INFO"

# ── Worker サービス ──
worker:
  replicaCount: 2
  resources:
    requests:
      cpu: "1"
      memory: "2Gi"
    limits:
      cpu: "2"
      memory: "4Gi"

# ── Web フロントエンド ──
web:
  replicaCount: 2
  resources:
    requests:
      cpu: "500m"
      memory: "512Mi"
    limits:
      cpu: "1"
      memory: "1Gi"

# ── Plugin Daemon ──
pluginDaemon:
  replicaCount: 1
  resources:
    requests:
      cpu: "500m"
      memory: "512Mi"
    limits:
      cpu: "1"
      memory: "1Gi"

4.2 外部数据库配置

# values-prod.yaml（続き）

# ── PostgreSQL（外部マネージドサービス） ──
postgresql:
  # Chart 内蔵の PostgreSQL を無効化
  enabled: false

externalPostgresql:
  host: "dify-db.xxxxxxxxxxxx.ap-northeast-1.rds.amazonaws.com"
  port: 5432
  username: "dify"
  password: "your-secure-password"   # Secret 経由を推奨
  database: "dify"
  sslMode: "require"

# ── Redis（外部マネージドサービス） ──
redis:
  enabled: false

externalRedis:
  host: "dify-redis.xxxxxxxxxxxx.apne1.cache.amazonaws.com"
  port: 6379
  password: "your-secure-password"
  useTLS: true

4.3 存储设置

# values-prod.yaml（続き）

# ── オブジェクトストレージ ──
storage:
  type: "s3"
  s3:
    endpoint: "https://s3.ap-northeast-1.amazonaws.com"
    bucketName: "dify-prod-storage"
    accessKey: "AKIAIOSFODNN7EXAMPLE"
    secretKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
    region: "ap-northeast-1"

4.4 向量数据库设置

# values-prod.yaml（続き）

# ── ベクトルデータベース ──
vectorStore:
  type: "weaviate"    # weaviate | qdrant | milvus | pgvector

  weaviate:
    endpoint: "https://your-cluster.weaviate.network"
    apiKey: "your-weaviate-api-key"

  # Qdrant を使用する場合
  # qdrant:
  #   endpoint: "https://your-cluster.qdrant.io"
  #   apiKey: "your-qdrant-api-key"

4.5 入口设置

# values-prod.yaml（続き）

# ── Ingress ──
ingress:
  enabled: true
  className: "nginx"
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
    nginx.ingress.kubernetes.io/proxy-body-size: "100m"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "300"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "300"
  hosts:
    - host: "dify.example.com"
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: dify-tls
      hosts:
        - "dify.example.com"

4.6 持久卷设置

使用Chart内置中间件（用于验证环境）时，需要进行PVC设置。

# 検証環境向け: Chart 内蔵ミドルウェア使用時
postgresql:
  enabled: true
  persistence:
    enabled: true
    storageClass: "gp3"
    size: "50Gi"

redis:
  enabled: true
  persistence:
    enabled: true
    storageClass: "gp3"
    size: "10Gi"

5. 管理秘密

5.1 创建 Kubernetes Secret

我们建议使用 Kubernetes Secret，而不是直接在 values.yaml 中写入密码。

# データベースパスワードの Secret
kubectl create secret generic dify-db-secret \
  --namespace=${NAMESPACE} \
  --from-literal=password='your-secure-db-password'

# Redis パスワードの Secret
kubectl create secret generic dify-redis-secret \
  --namespace=${NAMESPACE} \
  --from-literal=password='your-secure-redis-password'

# Dify シークレットキーの Secret
kubectl create secret generic dify-secret-key \
  --namespace=${NAMESPACE} \
  --from-literal=secretKey="$(openssl rand -base64 42)"

# S3 認証情報の Secret
kubectl create secret generic dify-s3-secret \
  --namespace=${NAMESPACE} \
  --from-literal=accessKey='AKIAIOSFODNN7EXAMPLE' \
  --from-literal=secretKey='wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY'

5.2 value.yaml 中的秘密引用

# Secret を参照する values.yaml の記述例
externalPostgresql:
  host: "dify-db.xxxxxxxxxxxx.ap-northeast-1.rds.amazonaws.com"
  port: 5432
  username: "dify"
  database: "dify"
  existingSecret: "dify-db-secret"
  existingSecretPasswordKey: "password"

6. 运行 Helm 安装

6.1 通过试运行初步确认

# テンプレートのレンダリング結果を確認（実際にはデプロイしない）
helm template dify dify/dify \
  --namespace=${NAMESPACE} \
  -f values-prod.yaml > rendered.yaml

# レンダリング結果を確認
less rendered.yaml

# dry-run で Kubernetes API への送信をシミュレート
helm install dify dify/dify \
  --namespace=${NAMESPACE} \
  -f values-prod.yaml \
  --dry-run

6.2 执行安装

# Helm Chart のインストール
helm upgrade --install dify dify/dify \
  --namespace=${NAMESPACE} \
  -f values-prod.yaml \
  --wait \
  --timeout 10m

helm upgrade --install 是幂等的，第一次作为安装，第二次以后作为升级。

6.3 检查安装状态

# Helm リリースの確認
helm list --namespace=${NAMESPACE}

# リリースの詳細確認
helm status dify --namespace=${NAMESPACE}

# 適用された values の確認
helm get values dify --namespace=${NAMESPACE}

7. 部署后验证

7.1 检查 Pod 状态

# 全 Pod の状態を確認
kubectl get pods --namespace=${NAMESPACE} -o wide

# 期待される出力例
# NAME                          READY   STATUS    RESTARTS   AGE   NODE
# dify-api-xxxxxxxxxx-xxxxx     1/1     Running   0          5m    node-1
# dify-api-xxxxxxxxxx-yyyyy     1/1     Running   0          5m    node-2
# dify-worker-xxxxxxxxxx-xxxxx  1/1     Running   0          5m    node-1
# dify-worker-xxxxxxxxxx-yyyyy  1/1     Running   0          5m    node-3
# dify-web-xxxxxxxxxx-xxxxx     1/1     Running   0          5m    node-2
# dify-web-xxxxxxxxxx-yyyyy     1/1     Running   0          5m    node-3

# Pod が Running にならない場合
kubectl describe pod <pod-name> --namespace=${NAMESPACE}
kubectl logs <pod-name> --namespace=${NAMESPACE}

7.2 检查服务和入口

# Service の確認
kubectl get svc --namespace=${NAMESPACE}

# Ingress の確認
kubectl get ingress --namespace=${NAMESPACE}

# Ingress の詳細（割り当てられた IP / ホスト名を確認）
kubectl describe ingress dify --namespace=${NAMESPACE}

7.3 检查 PVC

# 永続化ボリュームの状態確認
kubectl get pvc --namespace=${NAMESPACE}

# 全 PVC が Bound であることを確認
# NAME                STATUS   VOLUME         CAPACITY   STORAGECLASS
# dify-postgresql-0   Bound    pvc-xxxxxxxx   50Gi       gp3
# dify-redis-0        Bound    pvc-yyyyyyyy   10Gi       gp3

7.4 DNS和访问确认

# Ingress の EXTERNAL-IP を取得
INGRESS_IP=$(kubectl get ingress dify --namespace=${NAMESPACE} \
  -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
echo "Ingress IP: ${INGRESS_IP}"

# DNS が設定されるまでの間、/etc/hosts で一時的に名前解決
# sudo sh -c "echo '${INGRESS_IP} dify.example.com' >> /etc/hosts"

# ヘルスチェック
curl -sk https://dify.example.com/v1/health

# ブラウザでアクセス
# https://dify.example.com

7.5 综合操作检查表

# 以下のコマンドで全リソースの状態を一括確認
kubectl get all,ingress,pvc,secret --namespace=${NAMESPACE}

检查项目	命令/方法	预期结果
整个吊舱	`kubectl get pods`	全部运行 (1/1)
服务	`kubectl get svc`	ClusterIP 已分配
入口	`kubectl get ingress`	已分配地址
聚氯乙烯	`kubectl get pvc`	全部绑定
API 健康	`curl /v1/health`	`{"status": "ok"}`
用户界面访问	浏览器中的网址	显示初始设置屏幕
数据库连接	API Pod 日志	没有连接错误
Redis连接	Worker Pod 日志	没有连接错误

8.升级与回滚

8.1 升级

# リポジトリを最新化
helm repo update

# 新バージョンの確認
helm search repo dify/dify --versions

# values.yaml を更新した後にアップグレード
helm upgrade dify dify/dify \
  --namespace=${NAMESPACE} \
  -f values-prod.yaml \
  --wait \
  --timeout 10m

# 特定バージョンを指定してアップグレード
helm upgrade dify dify/dify \
  --namespace=${NAMESPACE} \
  -f values-prod.yaml \
  --version 1.2.3 \
  --wait

8.2 升级前检查清单

步骤	命令	目的
1.查看当前版本	`helm list -n ${NAMESPACE}`	当前发布信息
2. 检查变更	`helm diff upgrade dify dify/dify -f values-prod.yaml`	预先检查差异（helm-diff 插件）
3.数据库备份	托管服务快照	数据保护
4. 试运行	`helm upgrade --dry-run ...`	模板确认
5.执行	`helm upgrade ...`	升级执行力
6. 验证	`kubectl get pods`、`curl /health`	确认正常运行

8.3 回滚

# リリース履歴の確認
helm history dify --namespace=${NAMESPACE}

# 1 つ前のリビジョンにロールバック
helm rollback dify --namespace=${NAMESPACE}

# 特定のリビジョンにロールバック
helm rollback dify 3 --namespace=${NAMESPACE}

# ロールバック後の確認
kubectl get pods --namespace=${NAMESPACE}
helm status dify --namespace=${NAMESPACE}

9. 缩放

9.1 手动缩放

# values.yaml を変更して適用
# api:
#   replicaCount: 4

helm upgrade dify dify/dify \
  --namespace=${NAMESPACE} \
  -f values-prod.yaml

# または kubectl で直接スケール（一時的な対応）
kubectl scale deployment dify-api --replicas=4 --namespace=${NAMESPACE}

9.2 配置 HPA（水平 Pod 自动缩放器）

# values-prod.yaml に追加
api:
  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 10
    targetCPUUtilizationPercentage: 70
    targetMemoryUtilizationPercentage: 80

worker:
  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 8
    targetCPUUtilizationPercentage: 70

# HPA の状態確認
kubectl get hpa --namespace=${NAMESPACE}

# HPA の詳細確認
kubectl describe hpa dify-api --namespace=${NAMESPACE}

10. 监控和日志记录

10.1 检查Pod日志

# API サーバーのログ
kubectl logs -f deployment/dify-api --namespace=${NAMESPACE}

# Worker のログ
kubectl logs -f deployment/dify-worker --namespace=${NAMESPACE}

# 複数 Pod のログを同時に確認（stern を使用）
# brew install stern  (macOS)
stern dify-api --namespace=${NAMESPACE}
stern dify-worker --namespace=${NAMESPACE}

10.2 资源使用

# Pod のリソース使用量（metrics-server が必要）
kubectl top pods --namespace=${NAMESPACE}

# ノードのリソース使用量
kubectl top nodes

10.3 Prometheus / Grafana 集成

对于生产环境，我们建议使用 Prometheus + Grafana 监控指标。

# values-prod.yaml に追加
api:
  podAnnotations:
    prometheus.io/scrape: "true"
    prometheus.io/port: "5001"
    prometheus.io/path: "/metrics"

11. 故障排除

11.1 Pod 无法启动（待处理）

# Pod の詳細を確認
kubectl describe pod <pod-name> --namespace=${NAMESPACE}

# よくある原因:
# - リソース不足 → ノードの追加またはリソースリクエストの削減
# - PVC がバインドされない → StorageClass の確認
# - イメージ Pull 失敗 → imagePullSecrets の確認

11.2 Pod 发生 CrashLoopBackOff

# コンテナのログを確認
kubectl logs <pod-name> --namespace=${NAMESPACE} --previous

# よくある原因:
# - データベース接続失敗 → externalPostgresql の設定確認
# - Redis 接続失敗 → externalRedis の設定確認
# - SECRET_KEY が未設定 → values.yaml の global.secretKey 確認

11.3 Ingress无法访问

# Ingress Controller のログ
kubectl logs -f deployment/ingress-nginx-controller -n ingress-nginx

# Ingress リソースの確認
kubectl describe ingress dify --namespace=${NAMESPACE}

# バックエンド Service のエンドポイント確認
kubectl get endpoints --namespace=${NAMESPACE}

# よくある原因:
# - Ingress Controller が未インストール
# - className の不一致
# - TLS Secret が存在しない

11.4 知识库不起作用

# Worker のログを確認
kubectl logs -f deployment/dify-worker --namespace=${NAMESPACE}

# ベクトルデータベースへの接続確認
kubectl exec -it deployment/dify-api --namespace=${NAMESPACE} -- \
  curl -s http://weaviate-endpoint:8080/v1/.well-known/ready

# よくある原因:
# - ベクトルデータベースの接続情報が不正
# - Worker がダウンしている

11.5 常见错误及解决方法

错误	原因	解决方案
`ImagePullBackOff`	注册表认证失败	设置 `imagePullSecrets`
`Pending` (PVC)	没有存储类	使用`kubectl get sc`检查并创建
`CrashLoopBackOff`	设置错误	使用 `kubectl logs --previous` 检查日志
`502 Bad Gateway`	后端未启动	检查 Pod 状态和服务端点
`certificate verify failed`	TLS 设置不足	检查证书管理器日志和秘密

12. 生产运营的最佳实践

12.1 value.yaml 的 Git 管理

# values ファイルを Git で管理
mkdir -p dify-helm-config
cd dify-helm-config
git init

# 環境ごとの values ファイル
# values-dev.yaml
# values-staging.yaml
# values-prod.yaml

# Secret 値は values に含めず、Kubernetes Secret で管理
# .gitignore に機密情報を含むファイルを追加
echo "values-*-secrets.yaml" >> .gitignore

12.2 备份策略

目标	方法	频率
PostgreSQL	托管服务自动备份+手动快照	每日自动+预发布手动
Redis	托管服务自动备份	每日自动
对象存储	版本控制+跨区域复制	实时
矢量数据库	快照	每周
掌舵价值观	Git 存储库	关于改变

12.3 命名空间和许可证之间的关系

graph LR
    subgraph "Kubernetes クラスタ"
        NS1[dify-dev<br/>namespace]
        NS2[dify-staging<br/>namespace]
        NS3[dify-prod<br/>namespace]
    end

    L1[開発 License] --> NS1
    L2[ステージング License] --> NS2
    L3[本番 License] --> NS3

    style L1 fill:#e1f5fe
    style L2 fill:#fff3e0
    style L3 fill:#e8f5e9

重要说明：

许可证链接到命名空间，因此更改命名空间名称需要重新激活。
无法使用一个许可证部署到多个命名空间
许可证到期日期和席位数量取决于 Dify Enterprise 合同

总结

在本文中，我们使用以下流程解释了 Dify Enterprise 的 Helm Chart 部署。

前提条件 – Kubernetes/Helm版本要求及外部资源准备
命名空间设计 – 考虑与License联动的环境分离
添加 Helm 存储库 – 获取图表并检查值
自定义values.yaml – 外部DB、存储和Ingress设置
秘密管理 – 安全处理密码和认证信息
Helm Install – 从试运行到安装执行
部署后验证 – 检查 Pod、服务、Ingress 和 PVC
升级和回滚 – 安全更新程序
缩放 – 手动缩放和HPA设置
监控和日志记录 – 在运行过程中检查日志并收集指标
故障排除 – 常见问题及解决步骤

使用 Helm Chart 进行 Kubernetes 部署的初始设置比 Docker Compose 更复杂，但您可以利用生产操作所需的所有功能，例如高可用性、自动扩展和滚动更新。首先，在开发环境中对其进行彻底测试，然后在将其部署到生产环境之前对其进行暂存。

参考资料

-Dify Helm Chart - Dify Enterprise Docs -Kubernetes Prerequisites - Dify Enterprise Docs -Resources Checklist - Dify Enterprise Docs -Helm を使って minikube で Dify をデプロイしてみた - Zenn -Dify を Azure Kubernetes Service (AKS) で動かせるようにしました - note

License 激活与验证：Key 格式说明、激活接口、激活失败的排查步骤

关于 License，公开资料能确认的是激活方式、在线 / 离线模式、namespace 绑定与激活后重启 enterprise 服务的要求。

这篇培训内容的一个重点，是要把“公开可确认的部分”和“需要内部补充的部分”明确分开。公开文档已经足以支持一版激活流程培训：包括在线 / 离线激活、离线模式需要切换 licenseMode、激活后需重启 dify-enterprise、以及 namespace 绑定关系。但关于 License Key 的内部格式、商务发放机制和某些后台字段，公开资料确实没有完整披露。

一、从公开资料能确认的 License 激活边界

1. 激活流程是部署流程的一部分，不是独立动作

官方文档已经明确把激活放在 Enterprise Dashboard 初始化与部署步骤之后，这意味着培训时必须把“部署完成 → 后台初始化 → License 激活”讲成一条连续链路。

2. 在线与离线流程都已公开可确认

公开文档已经给出两套流程：

在线激活：输入 License ID
离线激活：切 licenseMode、复制 Cluster ID、回填 Offline Code

3. 验证动作至少包括状态确认与服务重启

官方文档明确说明，激活或刷新后需要重启 dify-enterprise，因此培训时不能把“看到已激活”当作结束，而应再验证服务生效状态。

二、已知公开信息

支持在线激活与离线激活
离线模式需要在 values.yaml 中切换 licenseMode
激活完成后需要重启 dify-enterprise
License 与 namespace 绑定

三、验证步骤建议

登录 Enterprise Dashboard
检查 License 状态
确认功能是否按授权生效
重启 enterprise 后再次确认状态保持

四、激活失败排查

namespace 是否与预期一致
网络是否允许在线激活
离线码是否匹配当前 Cluster ID
enterprise 服务是否已重启

五、需要你补充的部分

公开资料未充分披露 License Key 的内部格式细节与完整激活接口字段。如果你们内部培训需要展示这部分，请在本文件补充企业版后台截图、Key 样例脱敏版或正式 SOP。

公开资料线索

note.com

当前暂无特别强的 note.com 直接命中文章，当前更适合以 Enterprise 官方 License 文档为依据。

zenn.dev / 官方文档 / 其他公开页面

License Activation - Dify Enterprise Docs | https://enterprise-docs.dify.ai/versions/3-0-x/en-us/deployment/license-activation
Kubernetes - Dify Enterprise Docs | https://enterprise-docs.dify.ai/en-us/deployment/prerequisites/kubernetes
Dify Helm Chart - Dify Enterprise Docs | https://enterprise-docs.dify.ai/en-us/deployment/advanced-configuration/dify-helm-chart

这篇当前能从公开资料确认的有效信息

License 激活支持在线与离线两种模式
离线激活需要切换 licenseMode 并使用 Cluster ID / Offline Code
激活或刷新后需要重启 dify-enterprise 才会生效

基础运维操作手册：服务重启顺序、日志位置、常见报错代码对照表

合作伙伴培训里，运维手册的目标不是让每个人都会改代码，而是至少知道“问题在哪看、服务怎么重启、异常怎么分层”。

这篇内容虽然很大一部分属于交付经验，但也并不是完全没有公开依据。官方 Compose 与自部署文档已经明确给出了服务名称和基本运行方式，因此“看哪些日志、重启哪些服务”至少可以建立在公开服务结构之上；而社区文章则补充了升级后 Weaviate 报错、Internal Server Error、500 错误等一线排障案例。

一、从公开资料能确认的运维抓手

1. 先识别服务角色，再谈重启顺序

官方文档已经公开列出 api、worker、worker_beat、web、plugin_daemon、sandbox、db_postgres、redis 等服务，因此基础运维培训首先要让学员建立“故障现象对应哪类服务”的心智模型。

2. Compose 与 Kubernetes 的日志查看路径是公开可确认的

对于 Compose，可以直接走 docker compose logs <service>；对于 Kubernetes，则是 kubectl logs、deployment 与 pod 级排查。这些是培训里最基础也最实用的动作。

3. 社区公开文章已经能覆盖一部分典型错误

例如 Weaviate 版本不兼容、Azure VM 上的 Internal Server Error、知识管道导致的异常等，都说明 Dify 运维问题往往分布在依赖组件、版本升级和文件处理链路上。

二、重启顺序建议

如果只是前端异常，不要全量重启。建议按影响面最小原则处理：

单服务重启
依赖服务检查
最后才做整套重启

三、日志位置

Docker Compose：docker compose logs <service>
Kubernetes：kubectl logs deployment/<name> 或 pod 级日志
重点查看 api、worker、enterprise、sandbox

四、常见报错分层

认证 / 权限错误
数据库连接错误
Redis / 队列错误
对象存储错误
向量库检索错误
外部模型 Provider 错误

五、建议补充

若你们内部已有常见错误码对照表，建议后续直接补在本文件；公开资料通常不会把交付现场的报错经验写得这么全。

公开资料线索

note.com

【保存版・初心者OK】月1万円→1,000円台に。Difyとn8nを1台のVPSで動かす完全ガイド｜SSL対応＆トラブル解決付き | https://note.com/ai_restart/n/nd882767068c6

zenn.dev / 官方文档 / 其他公开页面

Docker ComposeでDifyをデプロイする | https://docs.dify.ai/ja/self-host/quick-start/docker-compose
【Dify】アプデで「Weaviate 1.19 is not supported」が出た時の … | https://zenn.dev/kotap/articles/ea3b5995b8ba44
Azure VM上のDify「Internal Server Error」の原因と対処 | https://zenn.dev/ytksato/articles/6cb73e68a568e6

这篇当前能从公开资料确认的有效信息

基础运维首先要建立服务角色与故障现象之间的对应关系
Compose 与 Kubernetes 的日志查看路径是公开明确的
社区已经沉淀了一部分升级报错、500 错误、依赖组件异常等一线案例

SSO 集成配置：SAML / OIDC 协议选择、IdP 配置参数、用户权限映射规则

SSO 集成通常是合作伙伴交付里最容易被低估的工作，因为它不只是“能不能登录”，还涉及用户标识、角色映射、组织同步和退出登录行为。

这一题的公开资料不像部署文档那么集中，但仍然有两个可靠来源：一是 Enterprise 侧关于认证能力的公开说明，二是社区围绕 Dify Enterprise 登录认证的经验文章。也就是说，这一题已经足够支撑一版培训稿，但如果你们内部有固定支持的 IdP 类型和字段映射模板，后续仍然值得补充。

一、从公开资料能确认的 SSO 培训边界

1. SSO 不是单纯的登录按钮配置

公开经验文章已经明确指出，Enterprise 登录认证涉及协议选择、IdP 配置、字段映射与用户进入后的权限边界。因此培训时必须把“认证成功之后系统如何识别与授权”一起讲清。

2. OIDC 与 SAML 的选择取决于企业现有身份基础设施

这一点虽然不是 Dify 独有，但在企业交付里非常关键：如果客户已经有现代化 OAuth / OIDC 体系，OIDC 更自然；如果客户是传统企业 IdP 体系，SAML 往往更常见。

3. 这一题公开资料能确认框架，但细节往往需要内部模板

公开资料已经足够说明方向与培训重点，但像 Okta、Azure AD、Google Workspace、Keycloak 等具体字段示例，通常还是要靠你们内部交付模板补上。

二、协议选择

OIDC：现代应用接入更常见，和 OAuth 生态更接近
SAML：在传统企业与部分既有 IdP 环境中仍然常见

三、培训重点

学员应掌握：

IdP 元数据 / issuer / client id / secret / redirect uri 各自作用
测试环境与生产环境回调地址不能混用
用户唯一标识字段用什么

四、权限映射建议

至少明确：

登录后创建什么角色
新用户默认进哪个 workspace
是否允许按部门自动映射权限

五、需要补充的部分

如果你们内部已有具体支持的 SSO 页面、字段截图和某个 IdP（如 Okta / Azure AD）的对接模板，建议后续补进这里。

公开资料线索

note.com

Keycloakを少しずつ | https://note.com/noritux/n/na1dbd9b6cde8

zenn.dev / 官方文档 / 其他公开页面

【Dify Enterprise版】ログイン時の認証機能について | https://zenn.dev/upgradetech/articles/1029808cbc6991
Dify Enterprise Docs | https://enterprise-docs.dify.ai/

这篇当前能从公开资料确认的有效信息

SSO 集成涉及协议选择、IdP 参数与登录后的权限映射
OIDC / SAML 应根据客户现有身份体系选择，而不是一刀切
具体字段映射和各 IdP 模板仍更适合由内部交付文档补足

构建知识库的三种方法–手动上传、API同步、网页抓取的使用指南

Dify 的知识库是检索增强生成 (RAG) 应用程序质量的最重要基础。在本文中，我们将实际讲解构建知识库的三种主要方法，以及每种方法的适用场景、设置要点以及嵌入模型选择标准。

1.知识库构建方法概述

Dify 具有三种主要方法来用数据填充知识库。

方法	概述	主要目标
手动上传（Web UI）	直接从 Dify 控制台上传文件	PoC/小型运营/非工程师
API同步（知识管道）	使用 Dataset API 从外部系统以编程方式输入大规模运营、CI/CD联动、定期更新
网页抓取（Firecrawl 联动）	通过指定URL自动获取网页并分块	公共文档/常见问题解答网站/帮助页面

flowchart LR
    A[データソース] --> B{構築方式の選択}
    B -->|少量・検証| C[手動アップロード]
    B -->|大規模・自動化| D[API 同期]
    B -->|Webコンテンツ| E[Web スクレイピング]
    C --> F[Knowledge Base]
    D --> F
    E --> F
    F --> G[RAG アプリケーション]

2.方法一：手动上传（Web UI）

2.1 适用场景

想要在 PoC（概念验证）阶段快速验证
文档数量不到几十个且更新不频繁
非工程业务团队管理知识
执行初始精度验证并调整块设置

2.2 操作流程

1.点击Dify控制台左侧菜单知识 2. 按**“创建知识”按钮 3. 选择从文件导入** 4. 拖放目标文件（支持格式：TXT、Markdown、PDF、DOCX、CSV、HTML） 5. 块设置/嵌入选择模型并**“保存并处理”**

2.3 支持的文件格式和限制

格式	最大尺寸	笔记
TXT / 降价	15 MB	最清洁的加工
PDF	15 MB	文本提取精度取决于 PDF 质量
DOCX	15 MB	表格和图像可能无法提取
CSV	15 MB	每一行都可以视为一个段
HTML	15 MB	标签移除后分块

2.4 Chunk配置最佳实践

# 推奨設定例
chunk_mode: automatic       # 自動分割を推奨（初回）
max_segment_length: 500     # トークン数ベース
overlap: 50                 # セグメント間の重複トークン
separator: "\n\n"           # 段落区切りを優先

设置理念：

短块（300-500 个标记）：注重精度。适用于常见问题解答、定义集合和程序手册
长块（800-1500 个标记）：专注于维护上下文。技术说明和报告
重叠：防止上下文中断。设置为总数的10-15%左右。

2.5 手动上传的限制

预处理（OCR、清理、元数据添加）必须提前手动完成
不适合大量文件的批量更新
无版本控制或差异更新机制

3.方法二：API同步（Dataset API / Knowledge Pipeline）

3.1 适用场景

定期更新100+文档
需要与内部CMS/文档管理系统自动联动
我想为 OCR、文本清理、元数据提取等构建一个预处理管道。
希望将知识更新自动化作为 CI/CD 管道的一部分

3.2 Dataset API的基本结构

Dify 提供以下端点作为数据集 API。

# ベースURL
BASE_URL="https://your-dify-instance.com/v1"

# データセット作成
curl -X POST "${BASE_URL}/datasets" \
  -H "Authorization: Bearer ${DATASET_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "製品マニュアル_v2",
    "permission": "only_me"
  }'

3.3 文档输入的API流程

# ドキュメントをテキストで投入
curl -X POST "${BASE_URL}/datasets/${DATASET_ID}/document/create-by-text" \
  -H "Authorization: Bearer ${DATASET_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "FAQ_営業部門.md",
    "text": "## よくある質問\n\nQ: 納期の目安は？\nA: 通常2-3営業日です。",
    "indexing_technique": "high_quality",
    "process_rule": {
      "mode": "automatic"
    }
  }'

# ファイルアップロードによる投入
curl -X POST "${BASE_URL}/datasets/${DATASET_ID}/document/create-by-file" \
  -H "Authorization: Bearer ${DATASET_API_KEY}" \
  -F "file=@/path/to/document.pdf" \
  -F 'data={"indexing_technique":"high_quality","process_rule":{"mode":"automatic"}}'

3.4 知识管道设计模式

flowchart TD
    A[外部データソース] --> B[抽出 Extract]
    B --> C[前処理 Transform]
    C --> C1[OCR変換]
    C --> C2[HTMLクリーニング]
    C --> C3[メタデータ付与]
    C --> C4[重複排除]
    C1 --> D[Dataset API 投入]
    C2 --> D
    C3 --> D
    C4 --> D
    D --> E[Embedding & Index]
    E --> F[Knowledge Base]

3.5 自动同步脚本示例（Python）

import os
import requests
import hashlib
from pathlib import Path

DIFY_BASE_URL = os.environ["DIFY_BASE_URL"]
DATASET_API_KEY = os.environ["DATASET_API_KEY"]
DATASET_ID = os.environ["DATASET_ID"]

HEADERS = {
    "Authorization": f"Bearer {DATASET_API_KEY}"
}

def compute_hash(filepath: str) -> str:
    """ファイルのハッシュ値を計算（差分検知用）"""
    return hashlib.md5(Path(filepath).read_bytes()).hexdigest()

def upload_document(filepath: str, dataset_id: str):
    """ドキュメントを Dataset API 経由でアップロード"""
    url = f"{DIFY_BASE_URL}/v1/datasets/{dataset_id}/document/create-by-file"
    with open(filepath, "rb") as f:
        response = requests.post(
            url,
            headers=HEADERS,
            files={"file": f},
            data={
                "data": '{"indexing_technique":"high_quality","process_rule":{"mode":"automatic"}}'
            }
        )
    response.raise_for_status()
    return response.json()

def sync_directory(directory: str, dataset_id: str):
    """ディレクトリ内の全ドキュメントを同期"""
    supported_ext = {".txt", ".md", ".pdf", ".docx", ".csv"}
    for path in Path(directory).rglob("*"):
        if path.suffix.lower() in supported_ext:
            print(f"Uploading: {path.name}")
            result = upload_document(str(path), dataset_id)
            print(f"  -> Document ID: {result['document']['id']}")

if __name__ == "__main__":
    sync_directory("./docs", DATASET_ID)

3.6 API 同步最佳实践

实施差异更新：记录文件哈希并仅重新填充更改的文档
使用元数据：添加文档类别、更新日期和版本作为元数据
控制批量大小：一次输入大量可能会导致超时。一次处理 50-100 个项目
错误处理：确保包含重试逻辑和失败日志记录

4.方法三：网页抓取（Firecrawl配合）

4.1 适用场景

我想将公共帮助网站和常见问题解答页面变成知识
我想定期抓取公司的网络文档以使其保持最新状态。
想要避免手动复制和粘贴的麻烦吗？

4.2 Firecrawl配置

Dify 与 Firecrawl 配合，支持网页自动抓取、文本提取、输入知识库。

环境变量设置（自托管）：

# docker-compose.yml または .env
FIRECRAWL_API_KEY=fc-xxxxxxxxxxxxx

4.3 通过网络抓取创建知识的过程

在知识创建屏幕上选择**“从网站同步”**
输入目标URL（例如https://docs.example.com/）
指定爬网设置：
- 最大页面：要抓取的最大页面数
- 抓取子页面：是否也包含子页面。
- 排除路径：要排除的路径模式
在预览中查看获得的结果
调整块设置并保存并处理

4.4 网页抓取时的注意事项

注意事项	对策
需要 JavaScript 渲染的页面	使用 Firecrawl 的无头浏览器功能
需要登录页面	切换到API同步方式
经常更新的页面	安排定期抓取
robots.txt 的限制	爬行前检查。如果是内部站点，添加权限设置
检索到的内容中有很多噪音	通过排除路径/CSS 选择器进行细化

5.嵌入模型选择标准

构建知识库时选择的嵌入模型是一个重要的设置，直接影响搜索的准确性。

5.1 Dify 中可用的主要嵌入模型

型号	维数	日语支持	特点
`text-embedding-3-large` (OpenAI)	3072	3072好	准确度高。成本较高
`text-embedding-3-small` (OpenAI)	1536	1536好	性价比好
`text-embedding-ada-002` (OpenAI)	1536	1536是的	遗产。不推荐新用途
相干 `embed-multilingual-v3.0`	1024	1024好	强大的多语言支持
本地模型（来自 Ollama）	变量	取决于型号	没有数据发送到外部

5.2 日语内容的选择指南

判断フロー:
├── データを外部に送信できない
│   └── ローカルモデル（Ollama + multilingual-e5-large 等）
├── 多言語混在コンテンツ
│   └── Cohere embed-multilingual-v3.0
├── 日本語中心 + 高精度を求める
│   └── text-embedding-3-large
└── コストを抑えたい
    └── text-embedding-3-small

5.3 索引方法选择

方法	说明	推荐场景
高品质	嵌入矢量搜索	生产环境。强调精度
经济	关键词搜索（倒排索引）	以成本为导向。早期概念验证

推荐：对于生产环境始终选择高质量。经济模式仅允许关键字匹配，不允许语义搜索。

6. 方法选择的决策树

根据项目情况选择流程如下所示。

flowchart TD
    START[Knowledge Base 構築開始] --> Q1{ドキュメント数は?}
    Q1 -->|50件以下| Q2{更新頻度は?}
    Q1 -->|50件超| Q3{データソースは?}
    Q2 -->|月1回以下| MANUAL[手動アップロード]
    Q2 -->|週1回以上| API[API 同期]
    Q3 -->|社内CMS/DB| API
    Q3 -->|公開Webサイト| WEB[Web スクレイピング]
    Q3 -->|ファイルサーバ| API
    MANUAL --> TUNE[Chunk 設定チューニング]
    API --> TUNE
    WEB --> TUNE
    TUNE --> VERIFY[検索精度検証]
    VERIFY --> PROD[本番運用]

7. 施工后质量验证检查表

建立知识库后，请使用以下方面验证其质量：

搜索测试：询问至少 10 个预期问题，看看相关细分是否返回较高水平。
检查块粒度：段是否太小而无法丢失上下文？
噪音检查：是否混入了任何不必要的页眉、页脚或菜单字符串？
元数据确认：文档名称和来源信息是否正确指定？
嵌入模型一致性：不同模型是否混合在同一个知识库中？
重复数据删除：是否存在多个具有相同内容的片段？

8. 故障排除

常见问题及解决方案

症状	原因	治疗
PDF 内容未正确提取	扫描版 PDF（图片 PDF）	提前进行OCR处理并转换为文本PDF
搜索结果不准确	块太大/太小	调整 `max_segment_length`
提交API超时	文件太大	分档提前提交
无法通过网页抓取检索页面	需要 JavaScript 渲染	检查 Firecrawl 设置
日语搜索准确率较差	嵌入模型不支持日语	更改为多语言兼容型号

9. 总结

选择正确的构建知识库的方法并不重要，重要的是根据项目的规模、数据来源、更新频率、团队结构来选择最合适的方法。

决策轴	手动上传	API同步	网页抓取
初始建设成本	低	中高	低中
运营成本	高（手工作业）	低（自动化）	低中
预处理灵活性	低	高	中等
对于非工程师	可能	不可能	可能（设置后）
规模宏大	不适合	最佳	中等规模

在实际项目中，最常见的方法是通过手动上传快速验证 PoC，然后在投入生产时构建 API 同步管道。专门用于捕获公共内容时，网络抓取非常有效。

提示设计标准——系统提示结构、角色设置、输出约束、Few-shot、变量注入

使用 Dify 构建高质量应用程序时，提示设计是决定应用程序行为的最重要步骤。在本文中，我们将通过将企业 AI 应用程序中的提示与 Dify 的功能联系起来，对设计提示的标准方法进行实用说明。

1. Prompt设计的基本原则

1.1 从“即时工程”到“情境工程”

现代LLM应用程序开发需要的不仅仅是制作单个提示字符串。 Dify 中的提示设计必须被视为上下文工程，它集成了以下元素。

元素	Dify 支持的功能	角色
系统提示	应用程序“说明”字段	AI行为和约束的定义
用户输入	用户输入变量	接收动态输入
背景	知识库联动	外部知识的注入
对话历史记录	对话记忆设置	维持过去的对话
变量	会话变量/环境变量	动态参数管理

1.2 企业提示三大要求

再现性：相同的输入可以获得稳定的输出。
可维护性：可以被团队成员阅读、理解和修改
可扩展性：当需求发生变化时，结构必须能够进行部分修改。

2.系统提示结构模板

2.1 推荐结构

我们建议将系统提示分为以下六个部分：

# ロール定義
あなたは{{role_name}}です。{{role_description}}

# タスク定義
以下のタスクを実行してください:
- {{task_1}}
- {{task_2}}

# 入力仕様
ユーザーから以下の情報が提供されます:
- {{input_description}}

# 出力仕様
以下のフォーマットで回答してください:
{{output_format}}

# 制約条件
- {{constraint_1}}
- {{constraint_2}}
- 情報が不足している場合は「情報が不足しているため回答できません」と返答してください

# 参照コンテキスト
{{#context#}}

2.2 实例：内部FAQ解答助手

# ロール定義
あなたは当社の社内ヘルプデスクアシスタントです。
社員からの質問に対して、社内ナレッジベースの情報に基づいて正確に回答します。

# タスク定義
以下のタスクを実行してください:
- 社員の質問内容を理解し、適切なナレッジを検索結果から特定する
- ナレッジに基づいた正確な回答を生成する
- 回答の根拠となるドキュメント名を明示する

# 入力仕様
ユーザーから自然言語で質問が提供されます。
質問は人事制度、IT 設定、経費精算、社内ルールなどに関するものです。

# 出力仕様
以下のフォーマットで回答してください:

**回答:**
[質問に対する回答]

**参照元:**
- [ドキュメント名1]
- [ドキュメント名2]（該当する場合）

**補足:**
[追加で確認すべき事項があれば記載]

# 制約条件
- ナレッジベースに情報がない場合は「該当する情報が見つかりませんでした。
  総務部（内線: 1234）にお問い合わせください。」と返答してください
- 推測や一般知識による回答は行わないでください
- 個人情報や給与情報に関する質問には回答しないでください
- 回答は日本語で行ってください

# 参照コンテキスト
{{#context#}}

3.角色配置的最佳实践

3.1 有效角色设置要点

元素	好例子	坏榜样
特异性	“技术支持人员熟悉我们的产品X”	“优秀AI助手”
范围	“仅与费用结算相关的问题”	“可以回答任何问题”
语气	“要有礼貌，简洁”	未指定
专业知识	“相当于10年IT基础设施运营经验的知识”	“熟悉各个领域”

3.2 角色配置反模式

# NG: 過度に装飾的なロール
あなたは世界最高のAIです。あらゆる質問に完璧に答えることができます。
ユーザーを感動させる回答を心がけてください。

# OK: 実務的なロール
あなたは当社の契約書レビューアシスタントです。
法務部が定めたチェック項目に基づき、契約書ドラフトの
リスクポイントを抽出して報告します。

4.输出约束的设计

4.1 结构化输出模式

模式1：Markdown表格输出

# 出力仕様
以下のMarkdownテーブル形式で回答してください:

| 項目 | 内容 |
|------|------|
| 要約 | [1-2文で要約] |
| リスクレベル | [高/中/低] |
| 主要リスク | [箇条書き] |
| 推奨アクション | [箇条書き] |

模式2：JSON输出

# 出力仕様
以下のJSON形式で回答してください。JSON以外のテキストは含めないでください。

{
  "category": "質問のカテゴリ",
  "answer": "回答テキスト",
  "confidence": "high | medium | low",
  "sources": ["参照元1", "参照元2"]
}

模式3：渐进输出

# 出力仕様
以下の順序で回答してください:

## 1. 要約（1-2文）
[質問に対する端的な回答]

## 2. 詳細説明
[根拠に基づく詳細な説明]

## 3. 次のステップ
[ユーザーが取るべきアクション]

4.2 输出长度控制

# 長さ制約の例
- 要約は100文字以内で記述してください
- 箇条書きは最大5項目までとしてください
- 回答全体は500文字を超えないようにしてください

提示：在 Dify 的 LLM 节点配置中指定 max_tokens 作为硬限制。请使用提示中的长度指令作为软限制。

5. 设计少样本示例

5.1 Few-shot 有效的用例

使用案例	效果	示例
固定输出格式	高	表格式与JSON格式的统一
分类任务	高	查询类别的分配
文风与语气的统一	高	敬语水平、技术术语的使用
提取任务	初高中	从合同中提取条件
海量知识注入	低（不推荐）	应该使用知识库

5.2 少样本模板

# Few-shot Examples

## 例1
ユーザー: 有給休暇の残日数を確認したいのですが
アシスタント:
**回答:**
有給休暇の残日数は、社内ポータルの「勤怠管理」>「有給休暇照会」から確認できます。

**参照元:**
- 勤怠管理マニュアル v3.2

**補足:**
前年度繰越分の有効期限は翌年度末までです。詳細は人事部にご確認ください。

## 例2
ユーザー: 来月の部門の売上予測を教えてください
アシスタント:
**回答:**
申し訳ございません。売上予測に関する情報はナレッジベースに含まれておりません。
経営企画部（内線: 5678）にお問い合わせください。

**参照元:**
- 該当なし

**補足:**
売上データへのアクセスが必要な場合は、上長の承認を得たうえで
経営企画部にデータ提供を依頼してください。

5.3 少样本设计指南

至少包含 2 个示例，建议 3-5 个示例
包括正常情况和异常情况（可以回答的情况和不能回答的情况）
示例中使用的格式必须与输出规范完全匹配。
太长的少数示例会淹没上下文窗口，因此请保持简洁

6. 使用 Dify 变量

6.1 变量的类型和使用

Dify 允许您在 Prompt 中使用以下变量表示法。

变量类型	符号	用途
用户输入变量	`{{variable_name}}`	从表单
上下文变量	`{{#context#}}`	知识库搜索结果
对话变量	`{{#conversation.var_name#}}`	对话过程中积累的状态
系统变量	`{{#sys.query#}}`	当前用户输入

6.2 使用变量的动态提示示例

# ロール定義
あなたは{{company_name}}の{{department}}向けアシスタントです。

# タスク定義
{{task_type}}タスクを実行してください。

# 言語設定
回答は{{output_language}}で行ってください。

# ユーザーの質問
{{#sys.query#}}

# 参照情報
{{#context#}}

应用程序设置中的变量定义示例：

变量名	类型	默认值	描述
`company_name`	文字	-	目标公司名称
`department`	选择	销售部	目标部门
`task_type`	选择	常见问题解答	任务类型
`output_language`	选择	日语	回答语言

6.3 使用会话变量进行状态管理

通过在工作流中设置对话变量，您可以维护多轮交互中的状态。

# 会話変数の活用例
現在のユーザー情報:
- ユーザー名: {{#conversation.user_name#}}
- 前回の問い合わせカテゴリ: {{#conversation.last_category#}}
- 対応ステータス: {{#conversation.status#}}

上記の情報を踏まえて、継続的なサポートを行ってください。

7. 测试和迭代提示

7.1 Dify 调试功能

利用 Dify 控制台中的“调试和预览”面板来验证提示行为。

测试程序：

编写系统提示符
在右侧预览面板中输入变量值 3.发送测试消息
检查并修正输出结果 5、修改后重新测试

7.2 测试用例设计

# Prompt テストケース一覧

## 正常系テスト
| # | 入力 | 期待される出力 | 確認ポイント |
|---|------|---------------|-------------|
| 1 | 有給の申請方法は？ | 手順の説明 | フォーマット準拠 |
| 2 | WiFiのパスワードは？ | パスワード情報 | 参照元が明示される |
| 3 | 出張精算の締め日は？ | 締め日の回答 | 正確な日付 |

## 異常系テスト
| # | 入力 | 期待される出力 | 確認ポイント |
|---|------|---------------|-------------|
| 4 | 社長の年収は？ | 回答拒否 | 個人情報制約が機能 |
| 5 | 明日の天気は？ | スコープ外回答 | 業務外質問の処理 |
| 6 | (空文字) | エラーハンドリング | 空入力の処理 |

7.3 质量检查表

角色定义是否具体，任务范围是否明确？
输出格式是否一致？
是否定义了信息不足时的行为？
很少的例子涵盖了正常和异常系统？
变量绑定是否正确？
知识库上下文是否正确注入？
答案的长度是否合适（不要太罗嗦/不要太短）？
日语的表达方式是否自然，敬语的程度是否一致？

8. 常见问题及解决方法

问题	原因	对策
输出格式损坏	约束不明确	添加少量示例以阐明格式
捏造不属于知识范围的信息	幻觉	强化“不在知识范围内不回答”约束
答案太冗长	无长度限制	设置字符限制和`max_tokens`
忽略角色	系统弱提示	将角色定义放在开头并重复约束
谈话中途偏离正轨	充满上下文	利用会话内存限制设置和摘要功能
多种语言混合	语言规范尚不清楚	“始终用日语回答”

9. Prompt设计的团队运作

9.1 版本控制

prompts/
├── faq-assistant/
│   ├── v1.0_system_prompt.md
│   ├── v1.1_system_prompt.md    # 出力フォーマット修正
│   ├── v2.0_system_prompt.md    # Few-shot 追加
│   └── changelog.md
├── contract-review/
│   ├── v1.0_system_prompt.md
│   └── changelog.md
└── README.md

9.2 回顾视角

在团队内查看提示时的观点：

角色和范围：任务边界是否清晰？
再现性：其他团队成员能否得到相同的结果？
安全：是否存在机密信息泄露的风险？
可维护性：需求变化时是否清楚要修改哪里？
测试结果：正常/异常系统测试是否通过？

10. 总结

为公司设计提示时最重要的不是使用巧妙的表达方式，而是要有一个职责明确、约束明确、可以由团队维护的结构。

设计元素	要点
角色设置	定义具体角色和范围
输出限制	使用Few-shot 进行显式格式和固定
变量的利用	确保动态参数的可重用性
测试	正常和异常系统测试用例的准备
运营	版本控制和团队评审系统

将 Dify 的 Prompt 设计从个人技能提升为可由团队管理的设计学科，是构建企业级质量应用程序的第一步。

工作流节点类型和组合模式——顺序执行、条件分支、重复和人机循环实用指南

Dify 的 Workflow 是一个强大的功能，可以让您直观地构建以 LLM 为中心的业务逻辑。在本文中，我们将系统地解释每种节点类型的特征以及实践中经常出现的组合模式。重点不是节点的“功能列表”，而是“在哪些场景下如何组合它们”。

1.工作流的基本概念

1.1 聊天流和工作流的区别

Dify 有两种流程构建模式。

项目	聊天流程	工作流程
应用	互动应用	批处理/API协作
输入	用户的自然语言消息	定义的变量（文本、文件等）
输出	聊天消息	结构化数据
对话记忆	是的	没有
执行触发	用户留言发送	API调用/手动执行

1.2 工作流执行模型

flowchart LR
    START[Start ノード] --> PROCESS[処理ノード群]
    PROCESS --> END[End ノード]
    
    subgraph PROCESS[処理フロー]
        direction TB
        A[LLM] --> B[Code]
        B --> C[IF/ELSE]
        C --> D[HTTP Request]
    end

2. 主节点类型详细信息

2.1 起始节点

工作流入口点。定义输入变量。

# Start ノードの入力変数定義例
variables:
  - name: document_text
    type: string
    required: true
    description: "処理対象のドキュメントテキスト"
  - name: language
    type: select
    options: ["ja", "en", "zh"]
    default: "ja"
  - name: file
    type: file
    required: false
    allowed_types: ["pdf", "docx"]

2.2 LLM节点

调用LLM进行文本生成、分类、提取等的核心节点。

设置项目：

参数	描述	推荐值
型号	LLM模式使用	根据任务选择
温度	随机性控制	分类：0，世代：0.3-0.7
最大代币	输出令牌的最大数量	按任务设定
系统提示	人工智能指令	使用结构化模板
背景	浏览知识库	如有必要，请连接

LLM节点提示描述示例：

以下のテキストを分析し、JSON形式で結果を返してください。

入力テキスト:
{{document_text}}

出力形式:
{
  "summary": "100文字以内の要約",
  "category": "contract | invoice | report | other",
  "risk_level": "high | medium | low",
  "key_entities": ["抽出されたエンティティのリスト"]
}

2.3 代码节点

运行 Python 或 JavaScript 代码的节点。用于数据转换、计算和格式化。

# Code ノード例: LLM出力のJSON解析と検証
import json

def main(llm_output: str) -> dict:
    """LLMの出力をパースして構造化データに変換"""
    try:
        result = json.loads(llm_output)
        # バリデーション
        required_keys = ["summary", "category", "risk_level"]
        for key in required_keys:
            if key not in result:
                result[key] = "N/A"
        # risk_level の正規化
        valid_levels = {"high", "medium", "low"}
        if result.get("risk_level") not in valid_levels:
            result["risk_level"] = "medium"
        return {"result": result, "is_valid": True}
    except json.JSONDecodeError:
        return {"result": None, "is_valid": False}

2.4 HTTP请求节点

调用外部API的节点。用于内部系统协调以及与外部服务的集成。

# HTTP Request ノード設定例
method: POST
url: "https://api.internal.example.com/tickets"
headers:
  Content-Type: "application/json"
  Authorization: "Bearer {{api_token}}"
body:
  type: json
  content: |
    {
      "title": "{{ticket_title}}",
      "description": "{{llm_output}}",
      "priority": "{{risk_level}}",
      "assignee": "auto"
    }
timeout: 30
retry:
  max_retries: 3
  retry_interval: 5

2.5 IF/ELSE节点（条件分支）

根据条件对流进行分支的节点。

# IF/ELSE 条件設定例
conditions:
  - if: "{{category}} == 'contract' AND {{risk_level}} == 'high'"
    then: "法務レビューフローへ"
  - elif: "{{category}} == 'contract' AND {{risk_level}} != 'high'"
    then: "自動処理フローへ"
  - else: "一般処理フローへ"

可在条件表达式中使用的运算符：

操作员	说明	示例
`==`	平等	`{{status}} == 'approved'`
`!=`	不等于	`{{category}} != 'other'`
`contains`	包含	`{{text}} contains '緊急'`
`not contains`	不包括在内	`{{output}} not contains 'エラー'`
`is empty`	空	`{{input}} is empty`
`is not empty`	不为空	`{{result}} is not empty`
`>`、`<`、`>=`、`<=`	数值比较	`{{score}} >= 0.8`

2.6 问题分类器节点

使用 LLM 将用户输入分类为预定义类别的节点。允许基于自然语言的分支，这比 IF/ELSE 更灵活。

# Question Classifier 設定例
model: gpt-4o-mini
classes:
  - name: "技術サポート"
    description: "製品の技術的な問題、エラー、設定に関する質問"
  - name: "料金・契約"
    description: "プラン、料金、契約更新、解約に関する質問"  
  - name: "一般問い合わせ"
    description: "その他の質問、フィードバック、要望"

2.7 迭代节点

对数组数据重复执行相同处理的节点。

# Iteration ノード設定例
input: "{{document_list}}"  # 配列型の変数
# 配列の各要素に対して内部フローを実行
# 内部フローでは {{item}} で現在の要素を参照
output: "{{results}}"  # 処理結果の配列
parallel_mode: false  # 順次実行（true で並列実行）
max_iterations: 50    # 最大反復回数
error_handling: continue  # エラー時も継続

2.8 循环节点

重复处理直到满足条件的节点。迭代是数组遍历，而循环是基于条件的迭代。

# Loop ノード設定例
max_iterations: 10
break_condition: "{{quality_score}} >= 0.9 OR {{iteration_count}} >= 5"
# ループ内で LLM による生成 → Code で品質スコア計算 → 条件判定

2.9 人在环（HITL）节点

涉及人类判断和认可的节点。需要对高风险操作和低置信度结果进行人工审查。

# HITL ノード設定例
title: "契約書レビュー承認"
description: "AIが高リスクと判定した契約書です。内容を確認して承認してください。"
display_variables:
  - "{{contract_summary}}"
  - "{{risk_points}}"
  - "{{recommended_action}}"
actions:
  - label: "承認"
    value: "approved"
  - label: "差し戻し"
    value: "rejected"  
  - label: "法務部にエスカレーション"
    value: "escalated"
timeout: 86400  # 24時間（秒）

2.10 端节点

定义工作流输出的终端节点。

# End ノード設定例
outputs:
  - name: final_result
    type: string
    value: "{{processed_output}}"
  - name: metadata
    type: object
    value: "{{processing_metadata}}"

3. 组合模式

3.1 模式1：顺序执行

最简单的模式。处理从输入到输出呈线性流动。

flowchart LR
    S[Start] --> L1[LLM: 分類]
    L1 --> K[Knowledge Base 検索]
    K --> L2[LLM: 回答生成]
    L2 --> E[End]

适用场景：

内部常见问题解答
文件摘要
生成标准报告

实施示例：文档摘要工作流程

步骤	节点	加工详情
1	开始	接收文档文本
2	LLM	确定文档的语言/类别
3	LLM	提取要点
4	代码	格式化输出
5	结束	返回结构化摘要

3.2 模式2：条件分支（Branching）

根据输入内容和中间结果切换处理路径的模式。

flowchart TD
    S[Start] --> QC[Question Classifier]
    QC -->|技術サポート| KB1[Knowledge: 技術文書]
    QC -->|料金・契約| KB2[Knowledge: 契約情報]
    QC -->|一般| L1[LLM: 一般回答]
    KB1 --> L2[LLM: 技術回答生成]
    KB2 --> L3[LLM: 契約回答生成]
    L1 --> E[End]
    L2 --> E
    L3 --> E

适用场景：

多域查询响应
按语言处理分支
根据风险级别更改处理

3.3 模式 3：迭代

对多个数据项重复相同过程的模式。

flowchart TD
    S[Start: 文書リスト] --> SP[Code: リスト分割]
    SP --> IT[Iteration]
    subgraph IT[反復処理]
        direction LR
        I1[LLM: 分析] --> I2[Code: スコア算出]
    end
    IT --> AG[Code: 結果集約]
    AG --> E[End]

适用场景：

多个文件的批量分析
批量处理（发票处理、合同检查）
每条记录的单独评估和汇总

带有代码节点的预处理示例：

def main(raw_text: str) -> dict:
    """テキストを段落リストに分割"""
    paragraphs = [p.strip() for p in raw_text.split("\n\n") if p.strip()]
    return {"items": paragraphs, "count": len(paragraphs)}

3.4 模式 4：人在环流程

一种涉及人类对人工智能处理结果的认可的模式。

flowchart TD
    S[Start] --> L1[LLM: 契約書分析]
    L1 --> IF{リスクレベル判定}
    IF -->|高リスク| HITL[Human Review]
    IF -->|低リスク| AUTO[自動承認]
    HITL -->|承認| PROC[処理実行]
    HITL -->|差し戻し| L1
    HITL -->|エスカレーション| ESC[法務部通知]
    AUTO --> PROC
    PROC --> HTTP[HTTP: 社内システム登録]
    HTTP --> E[End]
    ESC --> E

适用场景：

合同和法律文件的审查
大额订单审批流程
当对人工智能判断的信心较低时的回退
有合规要求的企业

3.5 模式 5：使用循环提高质量（迭代细化）

一种自动评估LLM输出质量并在不符合标准时重新生成的模式。

flowchart TD
    S[Start] --> L1[LLM: 初回生成]
    L1 --> C1[Code: 品質スコア算出]
    C1 --> IF{スコア >= 閾値?}
    IF -->|Yes| E[End: 出力]
    IF -->|No| L2[LLM: フィードバック付き再生成]
    L2 --> C1

代码节点中质量评估示例：

import json
import re

def main(llm_output: str, expected_format: str) -> dict:
    """LLM出力の品質を評価"""
    score = 0.0
    feedback = []
    
    # JSON 形式の妥当性チェック
    try:
        parsed = json.loads(llm_output)
        score += 0.4
    except json.JSONDecodeError:
        feedback.append("出力がJSON形式ではありません")
        return {"score": score, "feedback": "; ".join(feedback)}
    
    # 必須フィールドの存在チェック
    required_fields = ["summary", "category", "risk_level"]
    present = sum(1 for f in required_fields if f in parsed)
    score += 0.3 * (present / len(required_fields))
    
    missing = [f for f in required_fields if f not in parsed]
    if missing:
        feedback.append(f"不足フィールド: {', '.join(missing)}")
    
    # 要約の長さチェック
    if "summary" in parsed and 10 <= len(parsed["summary"]) <= 200:
        score += 0.3
    else:
        feedback.append("要約の長さが不適切です（10-200文字）")
    
    return {
        "score": round(score, 2),
        "feedback": "; ".join(feedback) if feedback else "OK",
        "is_acceptable": score >= 0.8
    }

4.典型业务场景的推荐配置

商业场景	推荐图案	主节点配置
内部常见问题机器人	顺序+分支	问题分类器 → 知识 → LLM → 结束
合同审查	迭代+HITL	开始 → 迭代(LLM) → IF/ELSE → HITL → HTTP → 结束
自动生成报告	顺序+循环	开始→LLM→代码（评估）→循环（再生）→结束
多语言客户支持	分公司	开始 → LLM（语言检测）→ IF/ELSE → 每种语言的知识 → LLM → 结束
数据提取管道	迭代	开始→代码（分割）→迭代（LLM提取）→代码（聚合）→HTTP→结束
审批流程	HITL	开始→LLM（分析）→HITL（审批）→HTTP（系统联动）→结束

5. 工作流程设计最佳实践

5.1 节点设计原则

单一职责：将一个进程分配给一个节点。避免将多个任务塞进 LLM 节点
显式变量名称：使用有意义的名称，例如 contract_risk_analysis_result 而不是 output
错误处理：使用 IF/ELSE 处理每个节点的故障情况
可测试性：允许中间节点的输出发送到末端节点进行验证。

5.2 性能考虑因素

优化要点	方法
减少 LLM 来电次数	尽可能使用一次LLM课程
并行化迭代	考虑 `parallel_mode: true`
HTTP 超时	根据外部API响应时间设置
缓存中间结果	使用代码节点避免冗余计算
限制最大迭代次数	设置循环/迭代的上限

5.3 调试技巧

一步一步：用Dify的“一步一步运行”功能检查每个节点的输入和输出
查看日志：在执行日志中查看各节点的处理时间和输出
测试数据：为正常系统和异常系统准备测试数据。
部分执行：仅提取并测试有问题节点周围的区域

6.常见问题及解决方法

问题	原因	对策
LLM节点输出不稳定	温度高/提示不明确	更低的温度+严格指定输出格式
迭代中途停止	处理一个元素时出错	设置错误处理：继续
HTTP 请求超时	外部API响应慢	延长超时+重试设置
IF/ELSE 中的意外分支	条件表达式的意外计算	检查日志中的变量类型和值
整体工作流程缓慢	许多LLM电话	节点整合+利用并行性
由于 HITL 导致处理延迟	审批人未回复	超时设置+通知机制

7. 总结

设计工作流的关键不是记住各个节点的功能，而是理解节点如何组合在一起以满足业务需求的模式。

组合图案	特点	复杂性
顺序执行	简单可靠	低
条件分支	根据输入灵活处理	中等
迭代处理	批处理必备	中等
HITL	结合人类判断	中高
循环（质量改进）	自动提高输出质量	高

我们建议采用分步方法，从顺序执行模式开始了解基本结构，然后根据业务需求添加条件分支和迭代。

Agent工具定义标准–OpenAPI架构设计、参数描述、LLM调用准确性优化

Dify的Agent是一个允许LLM自主选择和执行工具来完成任务的功能。代理稳定性几乎与工具定义的质量直接相关。在本文中，我们将对定义标准、测试方法和操作指南进行实用的解释，以使LLM能够准确地调用工具。

1.Agent中工具定义的作用

1.1 为什么工具定义决定了 Agent 的准确性

Agent的操作流程如下。

flowchart LR
    U[ユーザー入力] --> A[Agent LLM]
    A --> TD{ツール選択判断}
    TD -->|ツールA| TA[ツールA実行]
    TD -->|ツールB| TB[ツールB実行]
    TD -->|ツール不要| DR[直接回答]
    TA --> A
    TB --> A
    DR --> R[最終回答]
    A --> R

当LLM选择工具时，是指工具的名称、描述和参数定义。换句话说，这些定义直接作为LLM决策的基础。

定义元素	对LLM的影响
工具名称	何时使用的第一印象
描述	决定使用的主要依据
参数名称	猜测要通过什么的依据
参数说明	生成参数值的依据
必填/可选	确定所需的输入
枚举/格式	了解价值约束

1.2 常见问题

工具描述不明确，LLM 选择了错误的工具
由于参数定义不足，LLM 传递了错误的值
多个工具的描述相似，导致LLM混乱
由于未定义的故障后备而导致代理循环

2. 如何定义自定义工具

2.1 Dify 中的工具添加流程

1.点击Dify控制台顶部的工具菜单 2. 选择 自定义工具 > 创建自定义工具 3. 输入工具名称和 OpenAPI 架构 4. 配置身份验证设置（API 密钥、Bearer Token等） 5. 通过运行测试验证操作 6. 将工具链接到代理应用程序

2.2 OpenAPI schema 的基本结构

Dify 自定义工具在 OpenAPI 3.0 / Swagger 2.0 格式架构中定义。

openapi: "3.0.0"
info:
  title: "社内チケット管理API"
  version: "1.0.0"
  description: "社内ITサポートチケットの作成・検索・更新を行うAPI"

servers:
  - url: "https://api.internal.example.com/v1"

paths:
  /tickets:
    post:
      operationId: "createTicket"
      summary: "新しいサポートチケットを作成する"
      description: |
        社内ITサポートチケットを新規作成します。
        ユーザーがIT機器の故障、ソフトウェアの不具合、アカウントの問題を
        報告する場合に使用してください。
        一般的な質問への回答や、IT以外の問題には使用しないでください。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - title
                - category
                - description
              properties:
                title:
                  type: string
                  description: "チケットのタイトル。問題を簡潔に表す30文字以内の文字列。"
                  example: "VPN接続エラー"
                category:
                  type: string
                  enum: ["hardware", "software", "network", "account", "other"]
                  description: |
                    問題のカテゴリ。以下から選択:
                    - hardware: PC、モニター、キーボード等の物理的な機器の問題
                    - software: アプリケーションのインストール、動作不良、ライセンス
                    - network: WiFi、VPN、インターネット接続の問題
                    - account: パスワードリセット、アカウントロック、権限の問題
                    - other: 上記に該当しない問題
                description:
                  type: string
                  description: "問題の詳細説明。発生状況、エラーメッセージ、影響範囲を含む。"
                priority:
                  type: string
                  enum: ["critical", "high", "medium", "low"]
                  default: "medium"
                  description: |
                    優先度。以下の基準で選択:
                    - critical: 業務が完全に停止している（全社影響）
                    - high: 業務に重大な支障がある（部門影響）
                    - medium: 業務に一部支障がある（個人影響）
                    - low: 改善要望、将来的な対応でよいもの
      responses:
        "201":
          description: "チケット作成成功"
          content:
            application/json:
              schema:
                type: object
                properties:
                  ticket_id:
                    type: string
                    description: "作成されたチケットのID"
                  status:
                    type: string
                    description: "チケットのステータス"
        "400":
          description: "リクエストパラメータが不正"
        "401":
          description: "認証エラー"

  /tickets/search:
    get:
      operationId: "searchTickets"
      summary: "サポートチケットを検索する"
      description: |
        既存のサポートチケットを検索します。
        ユーザーが過去のチケットの状況を確認したい場合や、
        類似の問題が報告されていないか調べる場合に使用してください。
        新しいチケットを作成する場合は createTicket を使用してください。
      parameters:
        - name: keyword
          in: query
          required: false
          schema:
            type: string
          description: "検索キーワード。チケットのタイトルと説明文を全文検索。"
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum: ["open", "in_progress", "resolved", "closed"]
          description: "チケットのステータスでフィルタリング"
        - name: created_after
          in: query
          required: false
          schema:
            type: string
            format: date
          description: "指定日以降に作成されたチケットを検索。ISO 8601形式（例: 2026-01-15）"
      responses:
        "200":
          description: "検索結果"
          content:
            application/json:
              schema:
                type: object
                properties:
                  tickets:
                    type: array
                    items:
                      type: object
                      properties:
                        ticket_id:
                          type: string
                        title:
                          type: string
                        status:
                          type: string
                        created_at:
                          type: string
                  total_count:
                    type: integer

3. 如何撰写有效的描述

3.1 描述三要素

工具描述必须包括以下三个要素：

1. このツールが「何をするか」（What）
2. 「いつ使うべきか」（When）
3. 「いつ使うべきでないか」（When NOT）

3.2 比较好的和坏的描述

不好的例子1：太模糊

# NG
description: "情報を検索します"

好例子1：具体清晰的界限

# OK
description: |
  社内ナレッジベースから技術文書を検索します。
  ユーザーが製品の仕様、設定手順、トラブルシューティング方法を
  尋ねている場合に使用してください。
  料金、契約、人事に関する質問には使用しないでください。

糟糕的例子2：多种工具之间的界限不明确

# NG: ツールA
description: "データを取得します"

# NG: ツールB
description: "情報を返します"

好例子2：清晰的差异化

# OK: ツールA - チケット検索
description: |
  過去のサポートチケットをキーワードやステータスで検索します。
  ユーザーが「前に報告した問題のステータスを知りたい」
  「同じ問題が報告されていないか確認したい」場合に使用してください。

# OK: ツールB - ナレッジ検索
description: |
  社内技術ドキュメントから解決方法を検索します。
  ユーザーが「この問題をどう解決すればよいか」
  「設定手順を教えてほしい」場合に使用してください。

3.3 参数描述指南

原理	好例子	坏榜样
指定类型和格式	`ISO 8601形式の日付文字列（例: 2026-04-12）`	`日付`
表示可能的值	`enum: ["high", "medium", "low"]`	`優先度を文字列で`
包括示例	`例: "VPN接続エラー"`	没有例子
表示字符限制	`30文字以内の文字列`	`文字列`
明确必需/可选	`required: true` + 原因	未指定
表示默认值	`default: "medium"`	未指定

4. 认证设置

4.1 Dify 支持的认证方式

方法	设置位置	应用
API 密钥（标头）	将键分配给标题	通用API密钥认证
API 密钥（查询）	为查询参数分配键	对于遗留 API
不记名令牌	`Authorization: Bearer xxx`	OAuth 2.0 令牌
基本身份验证	`Authorization: Basic xxx`	用户名/密码认证
无	没有认证	公共API、内部网络

4.2 身份验证配置最佳实践

# Dify カスタムツール認証設定
authentication:
  type: "api_key"
  api_key_header: "X-API-Key"
  # API Key は環境変数またはシークレットマネージャーから取得
  # ハードコーディングしない

在 Dify 身份验证设置屏幕上输入 API 密钥（不要直接将其写入架构中）
在生产环境中，提供定期轮换密钥的机制。
最小权限（如果只读就可以，则不要授予写入权限）

5. Agent指令设计

除了工具定义之外，Agent的系统提示（指令）也极大地影响了工具选择的准确性。

5.1 代理指令模板

あなたはITサポートアシスタントです。
社員からのIT関連の問い合わせに対応します。

## 対応可能な業務
- 技術的な問題のトラブルシューティング
- サポートチケットの作成と状況確認
- 社内技術ドキュメントの検索

## ツール使用のルール
1. まず searchKnowledge で解決方法を検索してください
2. 解決方法が見つかった場合は、ツールの結果に基づいて回答してください
3. 解決方法が見つからない場合は、createTicket でチケットを作成してください
4. ユーザーが過去のチケットについて尋ねた場合は searchTickets を使用してください

## ツール使用の制約
- チケット作成前に必ずユーザーに内容を確認してください
- 1回の会話で同じツールを3回以上呼び出さないでください
- ツールの実行に失敗した場合は、エラー内容をユーザーに伝えてください

## 回答の制約
- IT以外の質問（人事、経理等）は対応範囲外であることを伝えてください
- 不明な点がある場合は推測せず、ユーザーに確認してください

5.2 确定工具使用的优先级

当代理拥有多个工具时，在说明中指定使用顺序可以提高准确性。

## ツール使用の優先順位
1. searchKnowledge（最優先）: まず社内ナレッジを検索
2. searchTickets: ナレッジで解決しない場合、類似チケットを検索
3. createTicket（最後の手段）: 上記で解決しない場合のみ新規チケット作成

6.测试方法

6.1 工具定义的测试矩阵

测试视角	测试案例	预期结果
选择正确的工具	“VPN 无法连接”	搜索知识叫做
选择正确的工具	“上周的门票状况如何？”	searchTickets 称为
正确的工具选择	“我的电脑坏了，我想请求维修”	调用 createTicket
抑制不必要的工具调用	“今天天气怎么样？”	回答“超出范围”而不调用该工具
参数正确性	“为网络问题创建票证”	类别： “网络”
收集所需参数	“创建票证”（信息不足）	与用户确认缺失信息
错误处理	工具返回 500 错误	通知用户错误

6.2 测试执行流程

1.在Dify控制台的调试面板发送测试消息 2.查看工具调用日志：

选定的工具名称
传递的参数
工具响应

通过与预期结果比较来发现问题 4.修改描述或参数定义
重新测试

6.3 逐步测试方法

Phase 1: 単体テスト
├── 各ツールが正しく呼び出されるか（10ケース/ツール）
├── パラメータが正しく渡されるか
└── エラーレスポンスの処理

Phase 2: 統合テスト
├── 複数ツールの選択判断（20ケース）
├── ツール間の連携（検索→作成の流れ）
└── 会話のマルチターンでの一貫性

Phase 3: エッジケーステスト
├── 曖昧な入力への対応
├── 複数ツールが該当しうる入力
├── 大量の出力を返すツール
└── タイムアウト・エラーケース

7. 管理和扩展工具数量

7.1 刀具数量与精度的关系

工具数量	LLM选拔精准度	建议措施
1-3	1-3高（稳定）	可以按原样操作
4-7	中等（需要谨慎）	加强描述差异化
8-15	降低风险	考虑划分类别和嵌套代理
16+	不推荐	始终拆分代理

7.2 代理嵌套模式

如果您有大量工具，请将代理分层。

flowchart TD
    U[ユーザー入力] --> RA[ルーティング Agent]
    RA -->|IT関連| ITA[IT Agent]
    RA -->|人事関連| HRA[HR Agent]
    RA -->|経理関連| FNA[Finance Agent]
    ITA --> T1[チケットAPI]
    ITA --> T2[ナレッジ検索]
    HRA --> T3[勤怠API]
    HRA --> T4[休暇API]
    FNA --> T5[経費API]
    FNA --> T6[請求API]

8. 常见问题及解决方法

问题	原因	对策
LLM 选择了错误的工具	描述相似/不明确	指定“何时使用”和“何时不使用”
参数值无效	类型/格式规范不足	添加枚举、格式、示例
无需调用工具直接回答	使用该工具的条件尚不清楚	明确规定了该工具的使用规则
多次调用同一个工具	无循环检测	使用指令
忽略工具响应	回复太长	简洁地格式化回复
跳过所需参数	未设置必填	模式中明确要求

9. 清单

在将工具定义投入生产之前，请检查以下内容：

模式质量

operationId 是一个唯一且易于理解的名称吗？
摘要是否在一行中表示了该功能？
描述是否包括什么/何时/何时不？
参数类型、格式和约束是否准确？
所需标志设置正确吗？
是否涵盖了枚举的所有可能值？
它包含示例吗？

代理指令

是否明确说明了使用工具的规则和优先级？
是否定义了工具使用限制（次数限制等）？
问题的行为是否超出了定义的范围？

测试

您是否为每个工具执行了至少 10 个测试用例？
是否涵盖正常系统、异常系统和边缘情况？
多种工具之间的选择判断是否准确？
在错误情况下我们是否正确回退？

10. 总结

Agent工具定义的质量直接关系到Agent的可靠性。

元素	最重要的一点
描述	不仅要写“做什么”，还要写“何时使用、何时不使用”
参数	指定所有类型、格式、约束和示例
代理须知	指定工具使用的规则和优先级
测试	系统验证刀具选择准确性和参数有效性
缩放	当工具数量增加时拆分Agent

构建稳定的Agent的关键是将工具定义设计为不仅是“API规范”，而且是“LLM的说明”。

API 集成指南 – 聊天/完成/工作流端点、身份验证、流媒体、Webhooks

为了将使用 Dify 构建的应用程序集成到业务系统中，通过 API 进行协作至关重要。在本文中，我们将对 Dify 提供的各种 API 端点的结构、身份验证方法、请求/响应格式、流支持和 webhook 协作进行实际解释。

1. Dify API 整体结构

1.1 API分类

Dify 的 API 大致分为两层。

层	目的	认证密钥	目标受众
应用程序API	执行已发布的应用程序（聊天、完成、工作流程）	应用程序 API 密钥	应用程序用户/前端
管理API	应用程序/数据集管理操作	数据集 API 密钥	管理员/后台

1.2 按应用程序类型划分的端点

应用程序类型	主要终点	方法
聊天应用程序	`/v1/chat-messages`	发布
完成应用程序	`/v1/completion-messages`	发布
工作流程应用程序	`/v1/workflows/run`	发布
知识库	`/v1/datasets`	获取/发布

flowchart TD
    CLIENT[クライアントアプリ] --> AUTH{認証}
    AUTH --> |App API Key| APP[Application API]
    AUTH --> |Dataset API Key| DS[Dataset API]
    APP --> CHAT[Chat: /v1/chat-messages]
    APP --> COMP[Completion: /v1/completion-messages]
    APP --> WF[Workflow: /v1/workflows/run]
    DS --> DSOP[Dataset CRUD]
    DS --> DOC[Document CRUD]

2. 身份验证

2.1 获取API密钥

在 Dify 控制台中打开应用程序
点击左侧菜单**“API访问”**
在**“API Key”**部分生成新密钥
复制您的密钥并妥善保管

2.2 认证头格式

Authorization: Bearer {api_key}

请求示例：

curl -X POST "https://your-dify-instance.com/v1/chat-messages" \
  -H "Authorization: Bearer app-xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"inputs": {}, "query": "こんにちは", "user": "user-001"}'

2.3 API 密钥管理最佳实践

项目	推荐
储存地点	环境变量或秘密管理器
硬编码为代码	禁止
提交到 Git 存储库	禁止（添加到`.gitignore`）
旋转	定期（每 90 天等）
权力分离	App API Key 和 Dataset API Key 分开管理
监控	监控API调用日志

3. 聊天应用 API

3.1 发送消息

向交互式应用程序发送消息并获得 AI 响应。

端点： POST /v1/chat-messages

请求正文：

{
  "inputs": {
    "company_name": "株式会社Example",
    "department": "営業部"
  },
  "query": "有給休暇の申請方法を教えてください",
  "user": "user-001",
  "conversation_id": "",
  "response_mode": "blocking",
  "files": []
}

参数说明：

参数	类型	必填	描述
`inputs`	对象	是的	应用程序中定义的输入变量的值
`query`	字符串	是的	用户留言
`user`	字符串	是的	用户标识符（最终用户 ID）
`conversation_id`	字符串	没有	对话 ID。使用空字符串开始新对话
`response_mode`	字符串	是的	`blocking`（同步）或 `streaming`（流式）
`files`	数组	没有	参考上传文件

响应（阻塞模式）：

{
  "event": "message",
  "message_id": "msg-xxxxxxxx",
  "conversation_id": "conv-xxxxxxxx",
  "mode": "chat",
  "answer": "有給休暇の申請は、社内ポータルの「勤怠管理」メニューから...",
  "metadata": {
    "usage": {
      "prompt_tokens": 512,
      "completion_tokens": 128,
      "total_tokens": 640,
      "total_price": "0.0064",
      "currency": "USD"
    },
    "retriever_resources": [
      {
        "dataset_id": "ds-xxxxx",
        "dataset_name": "社内規程集",
        "document_id": "doc-xxxxx",
        "document_name": "勤怠管理規程.pdf",
        "segment_id": "seg-xxxxx",
        "score": 0.92,
        "content": "有給休暇の申請は..."
      }
    ]
  },
  "created_at": 1712899200
}

3.2 获取通话记录

端点： GET /v1/messages

curl -X GET "https://your-dify-instance.com/v1/messages?conversation_id=conv-xxxxx&user=user-001&limit=20" \
  -H "Authorization: Bearer app-xxxxxxxxxxxxxxxxxxxx"

3.3 获取对话列表

端点： GET /v1/conversations

curl -X GET "https://your-dify-instance.com/v1/conversations?user=user-001&limit=20" \
  -H "Authorization: Bearer app-xxxxxxxxxxxxxxxxxxxx"

4. 完成应用程序API

4.1 文本完成请求

用于一次性文本生成（没有对话上下文）。

端点： POST /v1/completion-messages

{
  "inputs": {
    "document_text": "本契約は、甲が乙に対して...",
    "task_type": "要約"
  },
  "user": "user-001",
  "response_mode": "blocking"
}

回复：

{
  "event": "message",
  "message_id": "msg-xxxxxxxx",
  "mode": "completion",
  "answer": "本契約は、甲（発注者）と乙（受注者）の間で...",
  "metadata": {
    "usage": {
      "prompt_tokens": 1024,
      "completion_tokens": 256,
      "total_tokens": 1280
    }
  },
  "created_at": 1712899200
}

5. 工作流程应用程序 API

5.1 执行工作流程

端点： POST /v1/workflows/run

{
  "inputs": {
    "document_list": ["契約書A.pdf", "契約書B.pdf"],
    "analysis_type": "リスク分析",
    "output_format": "json"
  },
  "user": "user-001",
  "response_mode": "blocking"
}

回复：

{
  "workflow_run_id": "wr-xxxxxxxx",
  "task_id": "task-xxxxxxxx",
  "data": {
    "id": "wr-xxxxxxxx",
    "workflow_id": "wf-xxxxxxxx",
    "status": "succeeded",
    "outputs": {
      "final_result": "...",
      "metadata": {}
    },
    "elapsed_time": 12.5,
    "total_tokens": 2048,
    "total_steps": 5,
    "created_at": 1712899200,
    "finished_at": 1712899213
  }
}

5.2 检查工作流程执行状态

端点： GET /v1/workflows/run/{workflow_run_id}

curl -X GET "https://your-dify-instance.com/v1/workflows/run/wr-xxxxxxxx" \
  -H "Authorization: Bearer app-xxxxxxxxxxxxxxxxxxxx"

5.3 停止工作流程

端点： POST /v1/workflows/tasks/{task_id}/stop（Service API） or POST /api/workflows/tasks/{task_id}/stop（Web API）

# Dify 1.x 真实端点（与 Chat Message 的停止端点格式一致）
curl -X POST "https://your-dify-instance.com/v1/workflows/tasks/{task_id}/stop" \
  -H "Authorization: Bearer app-xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"user": "user-001"}'

注意：task_id 是从 streaming 响应（SSE）的事件流中获取的，不是 workflow_run_id。Chat Message 也有对应的停止端点：POST /v1/chat-messages/{task_id}/stop。

6. 流式响应

6.1 流式传输的工作原理

如果指定 response_mode: "streaming"，响应将以服务器发送事件 (SSE) 格式按顺序返回。

data: {"event": "message", "message_id": "msg-xxx", "answer": "有給", ...}

data: {"event": "message", "message_id": "msg-xxx", "answer": "休暇", ...}

data: {"event": "message", "message_id": "msg-xxx", "answer": "の", ...}

data: {"event": "message_end", "message_id": "msg-xxx", "metadata": {...}}

6.2 SSE 事件类型

活动	描述	时间
`message`	文本块的传递	在生成过程中依次
`message_end`	消息生成完成	当生成完成时
`message_file`	文件输出	文件生成
`tts_message`	音频数据	当 TTS 启用时
`tts_message_end`	音频输出完成	TTS 完成
`message_replace`	消息替换（审核期间）	当内容过滤时
`error`	错误发生	错误

6.3 前端实现示例（JavaScript）

async function sendChatMessage(query, conversationId = "") {
  const response = await fetch("https://your-dify-instance.com/v1/chat-messages", {
    method: "POST",
    headers: {
      "Authorization": "Bearer app-xxxxxxxxxxxxxxxxxxxx",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      inputs: {},
      query: query,
      user: "user-001",
      conversation_id: conversationId,
      response_mode: "streaming",
    }),
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = "";
  let fullAnswer = "";
  let newConversationId = "";

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split("\n");
    buffer = lines.pop() || "";

    for (const line of lines) {
      if (line.startsWith("data: ")) {
        const data = JSON.parse(line.slice(6));

        switch (data.event) {
          case "message":
            fullAnswer += data.answer;
            // UIにリアルタイム表示
            updateUI(fullAnswer);
            newConversationId = data.conversation_id;
            break;

          case "message_end":
            console.log("Token usage:", data.metadata?.usage);
            break;

          case "error":
            console.error("Error:", data.message);
            break;
        }
      }
    }
  }

  return { answer: fullAnswer, conversationId: newConversationId };
}

6.4 后端实现示例（Python）

import requests
import json

DIFY_BASE_URL = "https://your-dify-instance.com"
APP_API_KEY = "app-xxxxxxxxxxxxxxxxxxxx"

def chat_streaming(query: str, user: str, conversation_id: str = ""):
    """ストリーミングモードでチャットメッセージを送信"""
    url = f"{DIFY_BASE_URL}/v1/chat-messages"
    headers = {
        "Authorization": f"Bearer {APP_API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {
        "inputs": {},
        "query": query,
        "user": user,
        "conversation_id": conversation_id,
        "response_mode": "streaming",
    }

    full_answer = ""
    with requests.post(url, headers=headers, json=payload, stream=True) as resp:
        resp.raise_for_status()
        for line in resp.iter_lines():
            if line:
                decoded = line.decode("utf-8")
                if decoded.startswith("data: "):
                    data = json.loads(decoded[6:])
                    event = data.get("event")

                    if event == "message":
                        chunk = data.get("answer", "")
                        full_answer += chunk
                        print(chunk, end="", flush=True)

                    elif event == "message_end":
                        print()  # 改行
                        return {
                            "answer": full_answer,
                            "conversation_id": data.get("conversation_id"),
                            "metadata": data.get("metadata"),
                        }

                    elif event == "error":
                        raise Exception(f"API Error: {data.get('message')}")

    return {"answer": full_answer}


def chat_blocking(query: str, user: str, conversation_id: str = ""):
    """ブロッキングモードでチャットメッセージを送信"""
    url = f"{DIFY_BASE_URL}/v1/chat-messages"
    headers = {
        "Authorization": f"Bearer {APP_API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {
        "inputs": {},
        "query": query,
        "user": user,
        "conversation_id": conversation_id,
        "response_mode": "blocking",
    }

    resp = requests.post(url, headers=headers, json=payload)
    resp.raise_for_status()
    return resp.json()

7. 阻塞与流式传输选择标准

观点	封锁	流媒体
回复格式	完成后一次性全部返回	通过上交所顺序交割
用户体验	仅加载显示	打字动画风格
超时风险	生成长文本时高	低（由于顺序交付）
实施复杂性	低	中（需要 SSE 解析器）
推荐场景	批处理、API协作	聊天UI，实时显示
可被打断	不可能（等待完成）	可以用 `POST /stop` 中断

推荐：始终在面向用户的聊天界面中使用流式传输。如果您需要后端 API 到 API 集成中的完整结果，则阻塞适合。

8. 错误处理

8.1 主要错误代码

HTTP 状态	错误代码	说明	行动
400	`invalid_param`	无效参数	检查请求正文
401	401 `unauthorized`	身份验证错误	检查 API 密钥
403	403 `forbidden`	无访问权限	检查应用程序的公共设置
404	404 `not_found`	资源不存在	检查端点ID
429	429 `rate_limit_exceeded`	超出速率限制	增加重试间隔
500	500 `internal_server_error`	服务器错误	检查日志/重试
400	400 `provider_not_initialize`	LLM 提供商未配置	检查模型提供商配置
400	400 `model_currently_not_support`	当前模型不支持该操作	切换支持的模型
400	400 `completion_request_error`	模型调用错误	检查日志 / 重试
400	400 `provider_quota_exceeded`	提供商配额超限	调整配额或切换提供商

8.2 重试策略

import time
import requests
from requests.exceptions import RequestException

def call_dify_api_with_retry(url, headers, payload, max_retries=3):
    """指数バックオフ付きリトライ"""
    for attempt in range(max_retries):
        try:
            resp = requests.post(url, headers=headers, json=payload, timeout=60)

            if resp.status_code == 429:
                retry_after = int(resp.headers.get("Retry-After", 10))
                print(f"Rate limited. Retrying after {retry_after}s...")
                time.sleep(retry_after)
                continue

            if resp.status_code >= 500:
                wait = 2 ** attempt  # 指数バックオフ: 1, 2, 4秒
                print(f"Server error {resp.status_code}. Retrying in {wait}s...")
                time.sleep(wait)
                continue

            resp.raise_for_status()
            return resp.json()

        except RequestException as e:
            if attempt == max_retries - 1:
                raise
            wait = 2 ** attempt
            print(f"Request failed: {e}. Retrying in {wait}s...")
            time.sleep(wait)

    raise Exception(f"Failed after {max_retries} retries")

9. Webhook 回调

9.1 Workflow的Webhook集成

您可以使用工作流的 HTTP 请求节点将处理结果通知外部系统。

HTTP请求节点配置示例：

method: POST
url: "https://your-system.example.com/webhook/dify-callback"
headers:
  Content-Type: "application/json"
  X-Webhook-Secret: "{{webhook_secret}}"
body:
  type: json
  content: |
    {
      "event": "workflow_completed",
      "workflow_id": "{{workflow_id}}",
      "result": {{workflow_output}},
      "timestamp": "{{current_timestamp}}",
      "status": "success"
    }

9.2 Webhook 接收器实现示例 (Node.js / Express)

const express = require("express");
const crypto = require("crypto");

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

function verifySignature(payload, signature) {
  const expected = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(JSON.stringify(payload))
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

app.post("/webhook/dify-callback", (req, res) => {
  const signature = req.headers["x-webhook-secret"];

  if (signature !== WEBHOOK_SECRET) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  const { event, workflow_id, result, status } = req.body;
  console.log(`Received webhook: ${event} for workflow ${workflow_id}`);

  // ビジネスロジック: 結果をDBに保存、通知送信など
  processWorkflowResult(result, status);

  res.status(200).json({ received: true });
});

function processWorkflowResult(result, status) {
  // 例: Slack通知、DB保存、後続処理のトリガーなど
  console.log("Processing result:", result);
}

app.listen(3000, () => console.log("Webhook server running on port 3000"));

10. 实现模式集合

10.1 LINE Bot 合作

# LINE Bot から Dify Chat API を呼び出すパターン
from flask import Flask, request
from linebot import LineBotApi, WebhookHandler
from linebot.models import MessageEvent, TextMessage, TextSendMessage
import requests

app = Flask(__name__)
line_bot_api = LineBotApi("LINE_CHANNEL_ACCESS_TOKEN")
handler = WebhookHandler("LINE_CHANNEL_SECRET")

DIFY_API_URL = "https://your-dify-instance.com/v1/chat-messages"
DIFY_API_KEY = "app-xxxxxxxxxxxxxxxxxxxx"

# ユーザーごとの会話IDを管理
conversation_store = {}

@app.route("/callback", methods=["POST"])
def callback():
    handler.handle(request.get_data(as_text=True),
                   request.headers["X-Line-Signature"])
    return "OK"

@handler.add(MessageEvent, message=TextMessage)
def handle_message(event):
    user_id = event.source.user_id
    conv_id = conversation_store.get(user_id, "")

    resp = requests.post(
        DIFY_API_URL,
        headers={
            "Authorization": f"Bearer {DIFY_API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "inputs": {},
            "query": event.message.text,
            "user": user_id,
            "conversation_id": conv_id,
            "response_mode": "blocking",
        },
    )
    data = resp.json()

    conversation_store[user_id] = data.get("conversation_id", "")

    line_bot_api.reply_message(
        event.reply_token,
        TextSendMessage(text=data["answer"])
    )

10.2 批处理模式

import csv
import json
import time
import requests

DIFY_API_URL = "https://your-dify-instance.com/v1/workflows/run"
DIFY_API_KEY = "app-xxxxxxxxxxxxxxxxxxxx"

def process_batch(input_csv: str, output_csv: str):
    """CSVファイルの各行に対してWorkflowを実行するバッチ処理"""
    results = []

    with open(input_csv, "r", encoding="utf-8") as f:
        reader = csv.DictReader(f)
        for i, row in enumerate(reader):
            print(f"Processing row {i + 1}: {row.get('title', 'N/A')}")

            resp = requests.post(
                DIFY_API_URL,
                headers={
                    "Authorization": f"Bearer {DIFY_API_KEY}",
                    "Content-Type": "application/json",
                },
                json={
                    "inputs": {
                        "document_text": row["content"],
                        "analysis_type": row.get("type", "要約"),
                    },
                    "user": "batch-processor",
                    "response_mode": "blocking",
                },
            )

            if resp.status_code == 200:
                data = resp.json()
                results.append({
                    "input_title": row.get("title", ""),
                    "output": data["data"]["outputs"].get("final_result", ""),
                    "status": "success",
                    "tokens": data["data"].get("total_tokens", 0),
                })
            else:
                results.append({
                    "input_title": row.get("title", ""),
                    "output": "",
                    "status": f"error: {resp.status_code}",
                    "tokens": 0,
                })

            # レート制限対策: リクエスト間に待機
            time.sleep(1)

    # 結果をCSVに出力
    with open(output_csv, "w", encoding="utf-8", newline="") as f:
        writer = csv.DictWriter(f, fieldnames=["input_title", "output", "status", "tokens"])
        writer.writeheader()
        writer.writerows(results)

    print(f"Batch complete. Results saved to {output_csv}")

11. 安全和运营

11.1 安全检查表

API Key 没有硬编码在源代码中
使用 HTTPS 通信
CORS 设置已正确配置
已建立 API 密钥轮换政策。
已设置速率限制
实施输入验证
错误响应中不泄露内部信息

11.2 监控项目

项目	指标	大约警报阈值
响应时间	P95 延迟	> 30 秒
错误率	5xx 错误百分比	> 5%
代币使用	每日代币消费	预算的 80%
API 调用次数	每小时请求数	速率限制的 80%
对话次数	活跃对话数量	80% 的容量

12. 总结

下面总结了将 Dify API 集成到您的业务系统时需要记住的要点。

观点	要点
端点选择	根据应用程序类型（聊天/完成/工作流程）使用正确的端点
认证	API 密钥通过环境变量进行管理并定期轮换
响应模式	用于用户 UI 的流式传输，用于后端协调的阻塞
错误处理	使用指数退避和适当的回退进行重试
安全	HTTPS、CORS、输入验证、日志监控

API集成的目标不是能够输入curl命令，而是确保Dify应用程序作为实际业务系统的一部分稳定运行。遵循上面列出的实施模式和最佳实践以确保稳健的集成。

部署验收标准：哪些服务必须健康、哪些接口必须通、License 状态确认项

合作伙伴交付时，部署完成不等于验收完成。验收标准必须能回答三个问题：服务是不是都活着、关键链路是不是能通、License 是不是处于有效状态。

这一题虽然公开资料没有直接给出“合作伙伴验收单模板”，但 Enterprise 官方文档已经足以支撑验收标准的最小骨架：一是官方公开列出了核心资源与域名要求，二是公开给出了部署后应可访问的几个关键入口，三是 License 激活与刷新后需要验证生效状态。因此，这篇可以写成“公开资料可确认的最小验收标准”。

一、从公开资料能确认的验收骨架

1. 服务可访问性本身就是验收项

Enterprise 文档已经明确要求配置 console、api、app、upload、enterprise、trigger 等域名，并说明部署后应能访问这些入口。因此，域名与入口可达应被视为验收第一层。

2. 资源与依赖状态应纳入验收

Resources Checklist 已经公开给出 PostgreSQL、Redis、向量库、对象存储等依赖，因此验收不应只看 UI 页面打开，还要确认这些依赖处于正常工作状态。

3. License 生效状态必须单独确认

官方 License 文档明确说明激活或刷新后需重启 enterprise 服务，因此 License 不是“录进去就算完成”，而应验证状态是否真正生效。

二、服务健康项

至少确认：

Web / API / Worker / Enterprise 正常
数据库、Redis、对象存储、向量库正常
Ingress / 域名解析正常

三、接口可用项

登录可用
模型调用可用
知识库上传可用
应用发布后 API 可调用

四、License 确认项

状态有效
生效版本正确
重启后状态保持

五、交付建议

验收不要口头说“没问题”，应形成 checklist 与截图留档。

公开资料线索

note.com

当前暂无特别强的 note.com 直接命中文章，当前更适合以 Enterprise 官方部署与 License 文档为依据。

zenn.dev / 官方文档 / 其他公开页面

Kubernetes - Dify Enterprise Docs | https://enterprise-docs.dify.ai/en-us/deployment/prerequisites/kubernetes
Deployment FAQ - Dify Enterprise Docs | https://enterprise-docs.dify.ai/en-us/deployment/faq/deploying
Resources Checklist - Dify Enterprise Docs | https://enterprise-docs.dify.ai/versions/3-7-x/en-us/deployment/resources-checklist
License Activation - Dify Enterprise Docs | https://enterprise-docs.dify.ai/versions/3-0-x/en-us/deployment/license-activation

这篇当前能从公开资料确认的有效信息

域名 / 入口可达、依赖资源正常、License 生效，是最小验收骨架
公开资料足以支撑“最小验收标准”，但不包含你们内部客户项目特有的验收表格格式

基础功能验证项目：知识库上传 → 检索 → 对话的端到端测试用例

端到端测试的价值在于，确认系统不是“某个页面能打开”，而是从文档进入到回答输出整条链路都可用。

这一题有相对明确的公开支撑。Dify 官方已经公开提供了知识检索测试入口、Question Classifier 节点文档，以及知识库相关说明；同时，公开文章里也已经有围绕 RAG 检索、自动评测和知识管道的实践。因此，这篇可以被写成“交付现场最小可复现测试集”的培训稿。

一、从公开资料能确认的端到端测试骨架

1. 知识库检索测试本身就是官方公开能力

Dify 官方已经提供 Knowledge Test Retrieval 相关能力，这说明“上传后先验证检索，再验证问答”是被产品层认可的测试路径。

2. 端到端验证至少要覆盖三段

对公开资料进行归纳后，可以明确最小链路应覆盖：

文档进入知识库
检索是否命中
最终应用回答是否基于命中内容生成

3. 扩展用例应覆盖复杂文档与错误问题

公开 RAG 文章反复强调，复杂 PDF、参数调整和错误问题处理都会显著影响体验，因此这些都应纳入交付测试。

二、推荐最小用例

上传一份文档
等待索引完成
创建一个绑定知识库的应用
发起一个确定能命中的问题
观察是否引用正确内容作答

三、扩展用例

上传多份文档
上传含表格 PDF
调整 Top-K 与 Rerank
验证错误问题时是否能合理拒答

四、交付建议

培训时可直接给合作伙伴一套标准测试文本和预期结果，方便在现场快速验证。

公开资料线索

note.com

「あるはずの情報が見つからない」── Dify RAGチャットボット開発で踏んだ落とし穴と自動評価システムの構築 | https://note.com/kadinche/n/n87b77918dab9
AIが自ら「検索し直す」。DeepSeek-R1とDifyが作る高度なRAG構築の最前線 | https://note.com/nocode_solutions/n/nbe6c159a5460

zenn.dev / 官方文档 / 其他公开页面

ナレッジ検索テスト | https://docs.dify.ai/ja/use-dify/knowledge/test-retrieval
質問分類器 - Dify Docs | https://docs.dify.ai/ja/use-dify/nodes/question-classifier
【Dify】RAG大全：仕組みと設定を徹底解説 | https://zenn.dev/upgradetech/articles/ac9099a6489abe

这篇当前能从公开资料确认的有效信息

官方已公开提供知识检索测试能力，适合作为验收前最小验证步骤
端到端测试至少应覆盖“上传 → 检索 → 对话”三段链路
复杂 PDF、参数调优和错误问题处理应作为扩展测试项

客户移交文档模板：环境信息记录表、管理员账号交接单、运维联系方式

当前公开资料不足以支撑一篇可靠的、Dify 交付专用的“客户移交文档模板”正文。

这类内容更接近你们内部交付方法、客户成功流程和运维责任边界，公开网络上很难找到足够准确、可直接复用的 Dify 专项模板。

建议你后续补充的内容

请优先补以下内容：

环境信息记录表模板
- 部署方式
- 域名列表
- 集群 / 服务器信息
- 数据库 / Redis / 对象存储 / 向量库信息
- 版本号
- values.yaml / .env 保存位置
管理员账号交接单
- 初始管理员账号
- 密码交接方式
- 是否要求首次登录修改
- MFA / SSO 状态
- License 管理入口说明
运维联系方式模板
- 一线支持联系人
- 升级窗口联系人
- License / 商务联系人
- 故障升级路径
客户确认签收项
- 已收到环境信息
- 已收到账号信息
- 已知升级 / 备份 / 续费责任边界

公开资料线索

当前结论

暂无足够强的公开资料，可支撑 Dify 专项客户移交模板正文。
这一题建议直接由你们内部交付文档补齐。

常见客户问题 Q&A 库：合作伙伴在交付现场最常遇到的 20 个问题与标准回答

当前公开资料不足以支撑一篇可靠的、面向 Dify 交付现场的“20 个常见客户问题与标准回答”正文。

公开网络上可以找到零散排障文章，但很难确认哪些问题是你们交付现场最高频、哪些回答是你们希望统一对外使用的标准话术。因此，这一题更适合由你们内部经验直接补齐。

建议你后续补充的内容

请优先整理以下问题类型，并给出你们内部认可的标准回答：

为什么上传后搜不到内容
为什么回答不稳定
为什么 PDF 解析慢
为什么 Agent 一直调用工具
为什么测试环境可以、生产环境不行
SSO 为什么登录后权限不对
License 刷新后为什么还没生效
为什么升级后某些配置失效
为什么模型调用报错 / 限流
为什么对象存储或向量库异常

公开资料线索

当前结论

公开资料只足以支撑零散问题，不足以形成你们专属的交付现场 Q&A 标准库。
这一题建议直接由你们内部交付、售后和运维团队共同补充。

升级与续费提醒机制：版本更新通知渠道、License 到期前的客户沟通话术

当前公开资料不足以支撑一篇完整的“合作伙伴客户沟通机制”正文，尤其是：

你们实际使用哪些通知渠道
你们内部的升级评估节奏
你们对客户使用什么续费提醒话术
你们如何划分商务、技术支持与客户成功责任

这些都明显更接近内部运营流程，而不是公开产品文档能给出的内容。

建议你后续补充的内容

请优先补以下内容：

版本更新通知机制
- 官方 release 关注方式
- 内部评估节奏
- 客户通知触发条件
License 到期提醒节奏
- 90 / 30 / 7 天提醒规则
- 谁负责发出提醒
- 谁负责跟进续期
客户沟通话术模板
- 版本升级提醒话术
- License 到期提醒话术
- 升级风险说明模板
续期后的验证动作
- 是否需要重启
- 是否需要客户配合确认
- 是否需要截图或留档

公开资料线索

当前结论

公开资料可支持“需要关注 release / License 有效期”这类一般性原则。
但“提醒机制”和“客户话术”本身更适合由你们内部流程与商务实践补齐。

phase-4

本阶段对应原厂技术支持 Premium 内容。

phase-4 公开资料候选索引

说明：以下是与该阶段各主题相关的公开资料候选。优先保留 note.com、zenn.dev、Dify 官方文档、Enterprise 文档与其他日文页面。

phase-4/4-1/01-为什么-Dify-选择-on-premise.md

检索词：Dify on-premise SaaS 企業日本
note 命中：2
站点搜索命中：4

note.com 候选

OpenAI クリスマスまでリリースラッシュ他、最新の生成AIに関するニュース　2024年12月5日（木） | https://note.com/eshimi/n/ndc2591542754
生成ＡＩで漫画を爆速翻訳他、最新の生成AIに関するニュース　2024年12月4日（水） | https://note.com/eshimi/n/ndaf8ee7c772d

zenn.dev / 官方文档 / 其他日文页面

【保存版：Dify導入済の企業向け】n8n導入するべき？Difyとの … | https://zenn.dev/upgradetech/articles/eea37f22313816
DifyなどAI社内活用の試行錯誤の末に辿り着いたのは、Notion … | https://zenn.dev/contrea/articles/acde676ecb7d74
Difyとn8nの違いを徹底解説！AIワークフローツール比較ガイド … | https://zenn.dev/homula_ai_agens/articles/701b2159170b88
記事の一覧 | https://zenn.dev/articles?page=87

phase-4/4-1/02-Provider-抽象层设计.md

检索词：Dify provider model integration architecture
note 命中：6
站点搜索命中：8

note.com 候选

Ollamaが気になる！──「名前は聞く」が止まるまでに押さえること | https://note.com/miccell/n/n6e683c6625ac
The Complete Anatomy of AgentOS: How the AI Agent Operating System Is Rewriting the Rules of Enterprise Computing in 2026 | https://note.com/betaitohuman/n/nf36b85483d60
migration.fm Monthly News / April, 2026 | https://note.com/a_kuratani/n/n1370485c5d01
2026年、AIで勝つ組織の条件——「Build, Don’t Buy.」 | https://note.com/satoshissss/n/nb1db1541c41c

zenn.dev / 官方文档 / 其他日文页面

Model Specs | https://docs.dify.ai/en/develop-plugin/features-and-specs/plugin-types/model-designing-rules
Model API Interface | https://docs.dify.ai/en/develop-plugin/features-and-specs/plugin-types/model-schema
モデルプロバイダー - Dify Docs | https://docs.dify.ai/ja/use-dify/workspace/model-providers
Overview - Dify Docs | https://docs.dify.ai/en/use-dify/workspace/readme
API 基づく開発 - Dify Docs | https://docs.dify.ai/versions/legacy/ja/user-guide/application-publishing/developing-with-apis

phase-4/4-1/03-Knowledge-Base-检索架构.md

检索词：Dify knowledge base rerank hybrid search
note 命中：2
站点搜索命中：8

note.com 候选

【世界一わかりやすい】Dify初心者のためのRAG完全ガイド | https://note.com/ai_app_pro/n/n440e26749bde
【徹底解説】Difyでのナレッジの使い方 | https://note.com/ai_dev_lab/n/n222b025fe3c3

zenn.dev / 官方文档 / 其他日文页面

ハイブリッド検索 | 日本語 | https://legacy-docs.dify.ai/ja-jp/learn-more/extended-reading/retrieval-augment/hybrid-search
Hybrid Search | https://legacy-docs.dify.ai/learn-more/extended-reading/retrieval-augment/hybrid-search
インデックス方法と検索設定を指定 | https://docs.dify.ai/ja/use-dify/knowledge/create-knowledge/setting-indexing-methods
Specify the Index Method and Retrieval Settings | https://docs.dify.ai/en/use-dify/knowledge/create-knowledge/setting-indexing-methods
【Dify】RAG大全：仕組みと設定を徹底解説 | https://zenn.dev/upgradetech/articles/ac9099a6489abe

phase-4/4-1/04-Workflow-节点设计哲学.md

检索词：Dify workflow human in the loop 設計
note 命中：6
站点搜索命中：8

note.com 候选

Human-in-the-Loopの活用事例　Difyでの具体的な運用パターン9選 | https://note.com/nocode_solutions/n/n91655a876f4d
精密アゴニスト薬の設計（次世代GLP-1薬の開発） Precision Agonist (Drug) Design - BIOC 306 - (6) | https://note.com/modern_ferret595/n/n48302ed167b0
AIアプリケーション2026｜Dify・LangGraph・CrewAI・AutoGenで実現する次世代AIシステム | https://note.com/mediafusion_eng/n/n0159807d14fc
【速報】Kimi Claw登場——OpenClawがブラウザで24時間稼働｜5,000スキル・40GBストレージ・月額$39 | https://note.com/yasuda_forceai/n/n50e319f91fb1

zenn.dev / 官方文档 / 其他日文页面

Human-in-the-Loopの概念をDifyに落とし込み、AIの暴走を … | https://zenn.dev/nocodesolutions/articles/df0d883c7d1f79
Human-in-the-Loopの活用事例 Difyでの具体的な運用 … | https://zenn.dev/nocodesolutions/articles/62a03c6770b824
Dify チャットフローを AI が生成する仕組みを AI で作った話 | https://zenn.dev/ryoyoshii/articles/05d2ffe846f518
エージェントは実用的なのか？安定性は？ROIは？ Difyで構築 … | https://zenn.dev/olemi/articles/15d87f87e10463
コントリビューション・フェス参加のためGraphAIを学んでたら … | https://zenn.dev/haratakeshi/scraps/3677528402d5bd

phase-4/4-1/05-Dify-多租户模型.md

检索词：Dify workspace multi tenant
note 命中：1
站点搜索命中：7

note.com 候选

DifyでSEO記事作成を試してみる | https://note.com/kakeyang/n/n862d90c02437

zenn.dev / 官方文档 / 其他日文页面

【お詫び】Dify関連記事の非公開について——ライセンス違反 … | https://zenn.dev/poropi/articles/dify-selfhosted-workspace-apology
Difyのライセンスを見てみる | https://zenn.dev/fujiya228/scraps/887acf52978c16
フロントエンドから読み解くDifyアーキテクチャ | https://zenn.dev/takapom/articles/27ed1389beccb7
Environment Variables | https://docs.dify.ai/en/self-host/configuration/environments
Dify Docs: Introduction | https://docs.dify.ai/en/use-dify/getting-started/introduction

phase-4/4-2/01-企业-AI-应用分层架构.md

检索词：企業AI アーキテクチャレイヤー
note 命中：6
站点搜索命中：8

note.com 候选

企業向け音声AIエージェントにおけるアーキテクチャ設計の技術的比較分析：カスケード型とフューズド型のトレードオフと進化の系譜 | https://note.com/taka_410/n/nfc1e081e9563
野良エージェントが1兆ドルの扉を開く | OpenClawとNVIDIAのエージェンティック転換点 | https://note.com/fabymetal/n/n2a6a34ea9da3
デイリーAI検索備忘録(2026/4/6号) | https://note.com/yasuhitoo/n/nbbaed37c44c8
企業のAIレイヤー所有権は誰に？Glean CEOが語る未来戦略の鍵 | https://note.com/ai_solution/n/n25268654ae73

zenn.dev / 官方文档 / 其他日文页面

メダリオンアーキテクチャ 2.0 と “プラチナレイヤー” を考える | https://zenn.dev/google_cloud_jp/articles/ff74bf18e44f97
「便利だけど怖い」を卒業する – AI Agent認可の3層 … | https://zenn.dev/exwzd/articles/20251224_aiagent_authz_architecture
Encraft #22 「AIプロダクトを支えるアーキテクチャ設計ー理論と … | https://zenn.dev/knowledgework/articles/cbb6d3c3d00424
フクロウと学ぶアーキテクチャ #6-1 ─ 制御プレーン & … | https://zenn.dev/naokky/articles/202512-architecture-aiagent1
企業向けAIチャットボットの設計と実装 | https://zenn.dev/nkktech_global/articles/75ee52779e565c

phase-4/4-2/02-模型选型建议框架.md

检索词：生成AI モデル選定フレームワーク
note 命中：6
站点搜索命中：8

note.com 候选

【生成AIニュース+】『VibeVoice』『Pine AI』『PixelSmile LoRA』『LTX 2.3 Multifunctional』『Another』『ComfyUI-Dynamic-Sigmas』『Particles』『Pretext』『FOSSA』『Hybrid Memory』『Sommelier』『Intern-S1-Pro』『Niryo Nate』『Asimov DIY Kit』 | https://note.com/toshia_fuji/n/n06a492aebae7
デイリーAI検索備忘録(2026/4/10号) | https://note.com/yasuhitoo/n/n8f51d0bda0b9
クラウド法務×Azure技術支援とは何か | https://note.com/yamazaki_cloud/n/nb0235faa4bab
週刊AIニュースPEST編 | https://note.com/yasuhitoo/n/ne402b834173f

zenn.dev / 官方文档 / 其他日文页面

『生成AI』というデカい主語を整理して技術選定する方法 | https://zenn.dev/akari1106/articles/e0a611f9fac69a
LLMチャットUI vs OpenAI API vs フレームワーク5種の選定基準 | https://zenn.dev/epicai_techblog/articles/e4e1a27584e631
2026年版：AIエージェントフレームワークの全体像と選び方 | https://zenn.dev/0h_n0/articles/0b5a30f85cea3a
AI エージェント開発で失敗しないための 10 のデザインパターン | https://zenn.dev/loglass/articles/c7f4499ec8320b
生成AIシステムの6段階の進化／成熟モデルの定義 | https://zenn.dev/ippeisuzuki/articles/d164929bb25ffb

phase-4/4-2/03-知识库规模化设计.md

检索词：RAG 大規模ナレッジベース設計
note 命中：6
站点搜索命中：8

note.com 候选

LLM-wiki：LLMと育てる「一生モノ」のナレッジベース構築術 —— 自動更新される個人Wikiの力 | https://note.com/zenkok/n/n792a9238e980
【2026年】Notion AI×自律型ナレッジベース：全メール・全会議・全思考をAIが自動整理。自分よりも有能な『第2の脳』を構築し、決断を自動化する方法 | https://note.com/am_l/n/n3f5ace5641f1
AIエージェント時代の新常識「ハーネスエンジニアリング」——経営者が知るべき「インフラとサーチライト」の設計思想〜「AI時代の人材開発・組織開発」（310） | https://note.com/take_yoshikawa/n/n72d3bbaa8700
大規模言語モデルのプログラミング能力は1年以上向上していないとの分析、他 2026−03−12 ハッカーニュースまとめ読み | https://note.com/lucid_lynx8370/n/n8f607e0786e5

zenn.dev / 官方文档 / 其他日文页面

【生成AI入門】RAGの基本的な理論 | https://zenn.dev/sun_asterisk/articles/de03f576639ce3
【LLM+RAG】自分自身と会話できるナレッジベースシステムを … | https://zenn.dev/nijigen_plot/articles/personal_knowledge_base
Amazon Bedrockのナレッジベース使ってRAG構築してみた | https://zenn.dev/nbs_tokyo/articles/3fd696f3908e53
【Dify】RAG大全：仕組みと設定を徹底解説 | https://zenn.dev/upgradetech/articles/ac9099a6489abe
RAG精度が劇的に変わるナレッジ管理・ベクトル検索の最適化 … | https://zenn.dev/difymaster/articles/defa930eacd2fe

phase-4/4-2/04-高可用部署架构.md

检索词：Dify 高可用 Kubernetes 構成
note 命中：6
站点搜索命中：4

note.com 候选

【2026年最新版】Azure AZ-900 試験対策問題集（150問）全問解説付き（特典PDF付き） | https://note.com/huge_willet4820/n/nd7dd34e8da27
2026年にクラウドと双璧をなすオンプレAI基盤のリファレンス構成。 | https://note.com/aiojisan2024/n/nfe9e3611209e
2025年現在の Dify の最新機能と、医療という機密性の高い分野に特化したベストプラクティスを盛り込み医療記録特化型 Dify アプリ構築ガイド：多角的・徹底的・最適な詳細と FAQ | https://note.com/clean_broom590/n/nb464a92c8482
クラウド不要！OllamaとDifyで始めるセキュアなAI運用 | https://note.com/unique_lily8381/n/ne376c12fca59

zenn.dev / 官方文档 / 其他日文页面

生成AIアプリ開発ツールDifyをAWS EKSに導入してみた | https://zenn.dev/aki366/articles/0eb696bedf277c
DifyをAWSでセルフホストする際のデータフローとセキュリティ対策 | https://zenn.dev/upgradetech/articles/8b7773dc2de4b3
関西DB勉強会に参加なぅ | https://zenn.dev/awache/articles/643adddbe4f817
Developers Summit 2026 Day2, 3 公開資料・Xアカウント … | https://zenn.dev/h_yoshikawa0724/articles/2026-02-22-developers-summit-2026

phase-4/4-2/05-AI-应用安全边界设计.md

检索词：生成AI セキュリティガバナンスツール呼び出し権限
note 命中：6
站点搜索命中：8

note.com 候选

【完全解説】Claude × Microsoft 365コネクタ全プラン解放｜無料ユーザーもOutlook・SharePoint・OneDriveに直接アクセス可能に | https://note.com/yasuda_forceai/n/n32036bc4d4b8
〖総務省AIセキュリティガイドライン案〗これは「AI活用論」ではなく“AIシステム防御論”である | https://note.com/nice_wren7963/n/ne0c76afd49c5
【第3弾】Claude Code完全ガイド‼️｜Claude Code / Anthropic / AI / エンジニア / 開発効率化 / プログラミング / AIツール / 最新技術 / 自動化 / CLI / ターミナル / ソフトウェア開発 / 業務効率化 / 生産性向上 / DX / 初心者向け / Vibe Coding / エージェント / コーディング / 開発環境/ エンジニア / 非エンジニア | https://note.com/riku_techlab/n/n7a49cafb8070
【完全解説】Slack AIエージェント革命｜30超の新機能でSlackが「仕事のOS」に変わる | https://note.com/yasuda_forceai/n/n9b820c62d0f8

zenn.dev / 官方文档 / 其他日文页面

AIエージェントのガバナンス設計を考える | https://zenn.dev/ryuki_o/articles/a2005ac08ac2e4
Claude Code の権限評価フローを「セキュリティ」だと思っていた | https://zenn.dev/commander/articles/72a907ce68a8c1
Microsoft Agent Governance Toolkit入門 — AIエージェントの … | https://zenn.dev/kai_kou/articles/188-microsoft-agent-governance-toolkit-guide
AIエージェント時代のガバナンス設計 — 禁止から段階的運用 … | https://zenn.dev/miyan/articles/ai-code-agent-governance-design-2026
AIエージェントはなぜルールを守らないのか — 物理的 … | https://zenn.dev/aos_standard/articles/84a3880108d11d

phase-4/4-3/01-企业-AI-落地路线图模板.md

检索词：企業生成AI 導入ロードマップ
note 命中：6
站点搜索命中：8

note.com 候选

AI副業を4月新年度から最速で収益化するロードマップ | https://note.com/torao_aicolumn/n/n1093e3ece835
グラフィックデザイナー向けクリエイティブ生成AIツール入門／なぜ、クライアント企業がノード型ワークフロー構築環境を導入するのか？ | https://note.com/creative_edge/n/n8b8ac1afedc0
【2026年版】中小企業のAI導入ロードマップ｜補助金活用から現場定着まで、月10万円以下で始める具体策 | https://note.com/ai__worker/n/n30f8829b8e1a
【大公開！】内部監査の生成AI・DX活用〜『ツール』から『もう1人の監査人』への進化〜（第２回） | https://note.com/hirotsuchida/n/n68354acc714a

zenn.dev / 官方文档 / 其他日文页面

🚀 生成AI活用スキル0→100ロードマップ | https://zenn.dev/acntechjp/articles/68d3fab5e5df3f
CAIOってなんだ？ - 「なりたい」の前に「何か」を整理した | https://zenn.dev/you_dev_zenn/articles/caio-00-what-is-caio-2026
2026年の企業向け生成AI活用戦略 ─ 営業・企画・開発の業務効率 … | https://zenn.dev/ai_nexus/articles/business-genai-adoption-2026
中小企業AI業務自動化実践ガイド | https://zenn.dev/joinclass/books/sme-ai-automation-guide
チーム開発でAI活用を推進してきた取り組みと今後のビジョン | https://zenn.dev/gvatech_blog/articles/13d87b5dfbcc06

phase-4/4-3/02-AI-投资回报评估框架.md

检索词：生成AI ROI 評価フレームワーク
note 命中：6
站点搜索命中：8

note.com 候选

【生成AIニュース+】『bitnet.cpp』『ACE-Step』『ComfyUI-VideoColorGrading』『FreeMoCap』『LTX2.3-22B_IC-LoRA-Cameraman_v1』『Unsloth Studio Colab』『MIA』『PlayCanvas × Gracia AI 4D』『Token Warping』『PaperRecon』『Falcon Perception』『TriAttention』『Pocket』『UMI』『Bones Studio』 | https://note.com/toshia_fuji/n/n8f414f44b57f
【2026年版】アクセンチュアケース面接対策100選｜フェルミ推定・ビジネスケースの回答プロセスとOK/NG回答を徹底解説 | https://note.com/careercompass_c/n/n11a29b53043c
【生成AIニュース+】『GPT-5.4』『Codex Security』『Stitch』『Antigravity』『Qwen-Image-Layered-Control-V2』『ローカルスケジュールタスク』『Olmo Hybrid』『Kling 3.0 Omni』『Motion Control 3.0 ComfyUI』『Luma Agents』『LTX-2.3-GGUF』『LTX2.3_comfy』『Modular Diffusers』『Viggle V4』『Skills』他沢山 | https://note.com/toshia_fuji/n/nd85944f05f07
ChatGPTからClaude乗り換え1487%急増／OpenAI「Sora」終了でディズニー1600億円契約もとん挫／Gemini「他社AIメモリー転入」機能を提供開始／Claude著作権訴訟2400億円で和解へ／Apple×GoogleでSiri大刷新へ／Google音楽生成AI「Lyria 3 Pro」発表【週刊AIのニュース 2026年3月27日号】 | https://note.com/ainoarukurashi/n/n7847128318e5

zenn.dev / 官方文档 / 其他日文页面

LLMチャットUI vs OpenAI API vs フレームワーク5種の選定基準 | https://zenn.dev/epicai_techblog/articles/e4e1a27584e631
OpenAIの新指標「GDPval」とは？AIの実務能力を測る革新的 … | https://zenn.dev/headwaters/articles/80e67357297275
【第4回金融データ活用チャレンジ】生成AIも“前処理8割” | https://zenn.dev/blue251251/articles/49f3f57d3abc97
AIツールの進化サイクルと学習コストのトレードオフ、および持続 … | https://zenn.dev/myamio/books/ai-induced-cognitive-load/viewer/ai-learning-cost
生成AIシステムの6段階の進化／成熟モデルの定義 | https://zenn.dev/ippeisuzuki/articles/d164929bb25ffb

phase-4/4-3/03-企业-AI-委员会设置建议.md

检索词：企業 AI ガバナンス委員会
note 命中：6
站点搜索命中：8

note.com 候选

青春の「不可解なバランス」と、名門校のガバナンス欠如について | https://note.com/viva_a_h_s/n/na6edb3448579
クラウド法務×Azure技術支援とは何か | https://note.com/yamazaki_cloud/n/nb0235faa4bab
事業を加速させるための攻守の要。マネーフォワード法務が向き合うAIガバナンス | https://note.com/mf_cloud/n/n97be34e82405
人間とAIがバザールに参加しているようなもの | https://note.com/syfan/n/n59b54661bfd0

zenn.dev / 官方文档 / 其他日文页面

経産省AIガバナンスガイドラインを実装する企業向けチェック … | https://zenn.dev/gogoduck/articles/20260324-fn1zpn
企業・大学・官民連携はAIガバナンスをどう実装し始めたか | https://zenn.dev/ghostdrift/articles/98bb4a8e57238c
AIガバナンス 2026年度版 – 最先端研究・制度・実務の到達点 … | https://zenn.dev/ghostdrift/articles/441639ae68f948
国家AI実装戦略プロジェクトを発足しました―― AIガバナンス … | https://zenn.dev/ghostdrift/articles/835e416aea4f96
なぜ日本がAI実装国家を目指すなら、「責任固定インフラ」は … | https://zenn.dev/ghostdrift/articles/7b354531e900a8

phase-4/4-3/04-数据治理与AI合规.md

检索词：日本個人情報保護法生成AI ガイドライン
note 命中：6
站点搜索命中：8

note.com 候选

個人情報保護法の3年ごとの見直しは「クラウド例外」議論に決着をもたらすか | https://note.com/shin_fukuoka/n/n73aded964b63
【Google Cloud / Google Workspaceは医療AIとして実戦投入できるのか？】 3省2ガイドライン・個人情報保護法から読み解く「3つの利用シナリオ」のリアル | https://note.com/nice_wren7963/n/n323e2d757a50
生成AIと著作権——「知らなかった」では済まなくなった2026年の現在 | https://note.com/tsuyosshy/n/n202d6208e276
【挑戦】【資格】4月中に生成AIパスポート受験します！ | https://note.com/prime_snake837/n/n10697d69fce5

zenn.dev / 官方文档 / 其他日文页面

生成AIの法規制と個人情報保護2026：日本AI新法・EU AI Act … | https://zenn.dev/0h_n0/articles/dae805248604f5
生成AI時代の個人データ保護専門用語50と法的フレーム … | https://zenn.dev/0h_n0/articles/f1b476ba139174
【2025年版】生成AI活用に不可欠なセキュリティ対策完全ガイド | https://zenn.dev/headwaters/articles/7f7711b6c6cecc
外部サービスの利用ガイドラインを作ってわかった、エンジニア … | https://zenn.dev/knowledgework/articles/19e7bfba76582f
「生成AIだから機密情報を送るな」は本当に正しい議論なのか | https://zenn.dev/acntechjp/articles/e18a886f9f176e

phase-4/4-3/05-组织能力建设路径.md

检索词：企業生成AI 人材育成パートナー活用
note 命中：6
站点搜索命中：8

note.com 候选

中小企業の生成AI活用：マインドシフトでDXを加速する方法 | https://note.com/77777777777/n/n0a4c99cd6ac5
週刊Work&Techニュース 2026/04/10版: 生成AI利用率が過半数に到達／最強モデル「Claude Mythos」発表ほか | https://note.com/ntakahashi0505/n/n47a2cb9b67d7
AGO MARKETING 吾郷潤｜大企業を飛び出し、地方の中小製造業を生成AIで救う！「現場入り込み型」AIコンサルの全貌 | https://note.com/miraikyoso/n/n792f48940198
「AI活用人材」になるために、実務で生成AIを使おう | https://note.com/hideh_hash_845/n/n609fbc181b9c

zenn.dev / 官方文档 / 其他日文页面

AI時代の人材戦略:生産性を40%向上させる組織づくりの完全 … | https://zenn.dev/headwaters/articles/545fe94fb1a095
AI時代のIT人材生存戦略：次世代の優秀人材像と必須スキル … | https://zenn.dev/renue/articles/2f1ca6ac743456
【2026年最新】生成AIの活用事例30選！明日から使える業務 … | https://zenn.dev/ai_saas_media/articles/36323d3aa4739a
AI導入の鍵は「共創」にあり──大企業500社に聞いたAI … | https://zenn.dev/headwaters/articles/fe9801943b59cc
AIが先生になる？「Claude for Education」 | https://zenn.dev/acntechjp/articles/d4a45f27ad4705

为什么 Dify 选择 On-Premise：数据主权、日本企业合规性和混合云战略

简介

在考虑企业人工智能平台的实施格式时，经常会用“SaaS 或 On-Premise”的二分法来讨论。然而，Dify 的设计理念两者都不是。 Dify 的最大特点是它保持了 SaaS 的便利性，同时提供本地/自托管作为“一流的实施路径”。

在本文中，我们从数据主权、日本特定法规、网络分离要求和混合云策略等角度探讨了 Dify 为何将本地部署置于其产品架构的核心。

1. Dify 的本地交付格式：公开事实

1.1 使用 Docker Compose 进行即时部署

Dify 的官方文档提供了 Docker Compose 作为 Self-Host 的第一步。单个 docker-compose.yml 将运行 API 服务器、worker、Web 前端、PostgreSQL、Redis 和 Weaviate（矢量 DB）。

# Dify Self-Host の最小構成イメージ
services:
  api:
    image: langgenius/dify-api:latest
    environment:
      - DB_HOST=db
      - REDIS_HOST=redis
      - VECTOR_STORE=weaviate
  web:
    image: langgenius/dify-web:latest
  worker:
    image: langgenius/dify-api:latest
    command: celery worker
  db:
    image: postgres:15
  redis:
    image: redis:7
  weaviate:
    image: semitechnologies/weaviate:latest

此配置表明 Dify 正在有意设计一个“不依赖于云供应商托管服务的独立架构”。

1.2 企业 Kubernetes/Helm 部署

企业版提供 Helm Chart 并将以下基础设施控制留给企业：

控制项目	公司责任范围
数据库（PostgreSQL）	连接目的地/备份/加密
Redis	集群配置/持久化设置
对象存储（S3/MinIO）	存储桶策略/加密密钥
矢量数据库	Weaviate / Qdrant / pgvector 选择
入口/TLS	证书管理/WAF合作
许可证	应用企业许可证密钥

这种设计体现了清晰的分离理念：Dify 提供应用层，公司保留对基础设施的控制。

1.3 资源清单的含义

Enterprise Docs 上发布了资源清单，按照 Workspace 数量和并发用户数量列出了 CPU、内存和存储的推荐规格。这是 SaaS 供应商通常不会披露的信息，表明该设计是基于公司基础设施团队将自主执行容量规划的假设。

2. 数据主权：为什么“数据驻留在哪里”至关重要

2.1 企业人工智能处理的数据的性质

AI平台处理的数据与传统SaaS有着根本的不同：

输入知识库的内部文档：工作规则、合同模板、产品规格、客户响应手册
Workflow处理的业务数据：客户信息、交易历史、财务数据
LLM 提示和响应：包含敏感信息及其响应日志的问题。
嵌入向量：允许恢复原始文档的数字表示

graph TB
    subgraph "データ主権の境界"
        A[社内文書] --> B[Embedding 処理]
        B --> C[ベクトルDB]
        A --> D[全文インデックス]
        E[ユーザークエリ] --> F[LLM API]
        F --> G[レスポンスログ]
    end
    
    subgraph "SaaS モデルの場合"
        H[外部クラウド上に全データ]
        style H fill:#f99,stroke:#333
    end
    
    subgraph "On-Premise モデルの場合"
        I[企業ネットワーク内に全データ]
        style I fill:#9f9,stroke:#333
    end

2.2 数据主权问题的典型场景

场景	SaaS 挑战	本地解决方案
合约AI评论	NDA文件在公司外部发布	内网完成
内部常见问题机器人	包括人员和薪资信息	公司管理下的DB
客户交互自动化	个人信息发送给LLM供应商	可以通过代理控制
研发文献检索	专利申请前的技术信息	物理网络分离

3. 日本企业合规性和 On-Premise 的必要性

3.1 遵守个人信息保护法 (APPI)

令和 2 年（2020 年）改正の個人情報保護法（2022 年 4 月施行）将对企业人工智能产生以下直接影响：

第27条（第三者提供の制限）：向第三者（含 AI 平台运营者）提供个人数据时，原则上需事前取得本人同意。
第28条（外国にある第三者への提供の制限）：在海外存储或处理数据时的附加要求（包括对该外国数据保护制度的事前情報提供義務）。
第23条（安全管理措置）：对个人数据实施组织的・人的・物理的・技术的安全管理措施的义务。

⚠️ 诚实补充：选择 On-Premise 不必然意味着规避了第 27 条的“第三者提供“问题——只要 LLM API 调用仍发往外部（OpenAI / Anthropic 等），其本身就构成“第三者提供“，与 Dify 部署形态无关。On-Premise 真正解决的是 (a) 数据落地（不进入云端 SaaS 数据库 / 备份）+ (b) 第 28 条“外国にある第三者“风险（如选用日本国内 region 的 LLM 或本地模型）+ (c) 第 23 条物理 / 网络隔离要求。要彻底规避 LLM API 这条第 27 条路径，需配合本地推理（self-hosted Llama / DeepSeek 等）或国内 region 的 Provider（Azure OpenAI 日本东 / 西、Bedrock 东京 region 等）。

3.2 行业特定法规

工业	法规/指南	为什么需要本地部署
金融	FISC 安全措施标准	系统安装位置/数据中心要求
医疗	医疗信息安全管理GL（3个部门，2个指南）	医疗信息外部存储的严格要求
政府机关	国家统一标准组 (NISC)	根据灵敏度分类的系统隔离要求
制造	每个公司都有自己的安全标准	禁止将技术资料和图纸资料带出公司

3.3 与日本企业的决策过程保持一致

日本大型企业的IT实施具有独特的组织特征：

Ringi系统：需要信息系统部门、法务部门、合规部门依次批准。
部门间权限划分：明确划分各部门可以访问的数据范围
供应商管理：有义务审核分包商的安全管理措施
长期稳定性要求：架构必须能够承受3-5年的运营计划。

On-Premise 降低了审批流程中的最大障碍，因为数据由公司控制。这是因为SaaS所需的“数据处理合同”、“安全管理措施的确认”和“第三方条款适用性的法律安排”将大大简化。

4.网络分离和封闭网络支持

4.1 日本企业典型网络配置

graph LR
    subgraph "社内ネットワーク"
        A[業務端末] --> B[社内プロキシ]
        B --> C[Dify On-Premise]
        C --> D[社内DB / ファイルサーバー]
        C --> E[社内ベクトルDB]
    end
    
    subgraph "DMZ"
        F[リバースプロキシ]
    end
    
    subgraph "外部"
        G[LLM API<br/>OpenAI / Azure / Anthropic]
    end
    
    C -->|"制御されたAPI通信のみ"| F
    F --> G
    
    style C fill:#69b,stroke:#333,color:#fff

许多日本公司认为内部系统不直接连接到互联网，并且仅允许通过代理进行有限通信的外部 API 调用。 Dify 的 On-Premise 允许您配置：

知识库/矢量数据库完全位于公司的封闭网络内
仅LLM API调用通过代理进行外部通信（也可以使用Azure OpenAI服务的私人端点）
用户访问日志和查询日志可以集成到内部 SIEM 中

4.2 支持完全封闭的网络（气隙）

制造设计部门和国防公司可能需要在没有任何互联网连接的情况下运行。 Dify的On-Premise+本地LLM（Ollama/vLLM等）组合也可以满足这个要求：

graph TB
    subgraph "完全閉域網"
        A[Dify On-Premise] --> B[Ollama / vLLM<br/>ローカル LLM]
        A --> C[Weaviate / pgvector<br/>ローカル Vector DB]
        A --> D[PostgreSQL<br/>ローカル DB]
        E[ユーザー端末] --> A
    end
    
    F[インターネット]
    F -.->|"接続なし"| A
    
    style F fill:#f99,stroke:#333

5. 混合云策略：SaaS 与 On-Premise 共存

5.1 分阶段部署模型

日本公司的实际 Dify 实施通常涉及以下步骤：

相	形态学	应用	数据敏感性
第一阶段：PoC	Dify云（SaaS）	技术验证/原型	低（测试数据）
第二阶段：部门试用	Docker Compose 自托管	实际操作有限	中（匿名数据）
第三阶段：生产实施	企业 Kubernetes	全公司部署	高（生产数据）
第四阶段：扩张	混合配置	多区域	混合

5.2 为什么 Dify 的架构能够实现混合性

Dify 的设计具有多项自然支持混合配置的功能：

基于环境变量的配置管理：可以使用环境变量完成数据库连接目的地、存储后端、LLM提供者的切换。
无状态API/Worker：可设计云与本地之间的水平扩展和负载平衡
Provider抽象层：同一个应用程序可以根据环境在Azure OpenAI（封闭网络）和OpenAI API（公共）之间切换
知识库独立性：只需更改矢量DB的连接目的地即可控制知识的放置位置。

6. 本地操作的设计注意事项

6.1 运行负载和权衡

On-Premise 承担“责任”以换取“自由”：

项目	SaaS	本地部署
基础设施管理	供应商	拥有
版本升级	自动	计划实施
可用性设计	供应商 SLA	内部设计
安全补丁	供应商	内部应用
缩放	自动	内部设计
成本结构	按量付费	固定成本+运营人工成本

6.2 推荐的架构模式

graph TB
    subgraph "本番環境 (Kubernetes)"
        direction TB
        LB[Ingress Controller / ALB]
        
        subgraph "Application Layer"
            API1[Dify API Pod x3]
            WEB1[Dify Web Pod x2]
            WK1[Dify Worker Pod x3]
        end
        
        subgraph "Data Layer"
            PG[(PostgreSQL<br/>Primary + Replica)]
            RD[(Redis Sentinel)]
            VDB[(Vector DB<br/>Weaviate Cluster)]
            S3[(Object Storage<br/>MinIO / S3)]
        end
    end
    
    LB --> API1
    LB --> WEB1
    API1 --> PG
    API1 --> RD
    API1 --> VDB
    WK1 --> PG
    WK1 --> RD
    WK1 --> S3

6.3 监控/可观察性

在On-Premise环境中，您需要自行设计以下监控项：

应用程序指标：API 延迟、工作队列长度、错误率
基础设施指标：CPU/内存使用情况、磁盘 I/O、网络带宽
业务指标：活跃用户数量、查询数量、知识库命中率
安全监控：身份验证失败、异常访问模式、数据导出操作

7. 与竞争产品的比较：本地支持的深度

产品	本地兼容	兼容 Kubernetes	封闭网络兼容	开源软件
区分	Docker Compose + Helm	企业掌舵	本地LLM支持	是（阿帕奇 2.0）
浪链	框架（自建）	拥有	可能，但要自建	是的
流动	兼容 Docker	社区掌舵	有限公司	是的
AWS 基岩	仅限 SaaS	不适用	VPC 专用链接	没有
Azure 人工智能工作室	以 SaaS 为中心	AKS 集成	私有端点	没有

Dify 的差异化在于“虽然是 OSS，但也提供 Enterprise Helm，并且包含基于 GUI 的管理界面”。框架类型（LangChain）很灵活，但没有 GUI，云原生类型（Bedrock/Azure）不支持本地部署。

8. 日本市场 On-Premise 的未来展望

8.1 将人工智能治理制度化

从2024年起，日本政府正在加速人工智能治理的讨论。未来，可能会形成以下法规：

澄清人工智能使用的数据位置要求
AI输出的可解释性要求
保存人工智能系统审计追踪的义务

这些更严格的法规将鼓励人工智能平台在本地或私有云中运行。

8.2 本地LLM成熟

随着兼容日语的本地LLM（Llama系列、Qwen系列、国产LLM）性能的提高，在完全封闭的网络中运行Dify正在成为一种实用的选择。 Dify 的 Provider 抽象层旨在以低成本实现这些模型之间的切换。

总结

Dify 将 On-Premise 设计为“一流的部署路径”而不是“附加功能”，原因有以下三个：

确保数据主权：企业人工智能处理的数据是敏感的，必须保留在公司的管理边界内。
符合日本企业的合规要求：与个人信息保护法、行业法规、Ringi系统的一致性
混合云策略的灵活性：提供从 PoC 到生产的分阶段部署路径

内部部署并不是一个“沉重”的选择。相反，它将企业人工智能纳入正式业务流程的先决条件。 Dify 可以说是一个将这个前提融入到其产品架构中的平台。

参考资料

-Deploy Dify with Docker Compose -Kubernetes - Dify Enterprise Docs -Resources Checklist - Dify Enterprise Docs -個人情報保護委員会 - 改正個人情報保護法 -FISC 安全対策基準

Dify 的提供商抽象层设计：我们如何同时支持数十个 LLM 并保持松散耦合

简介

对于企业人工智能平台来说，“使用哪个LLM”并不是一次性的决定。由于成本优化、性能要求的变化、新型号的引入、因法规遵从而导致的供应商变化等，型号切换不断发生。

Dify 的 Provider 抽象层是对这一现实的结构性回答。本文从架构设计的角度阐述了Dify如何抽象LLM Provider，并实现应用层和模型层之间的松耦合。

1.什么是Provider抽象层？

1.1 问题定义

直接调用LLM的应用程序会遇到以下问题：

# 抽象層がない場合の典型的なコード
import openai

# OpenAI に直接依存
response = openai.ChatCompletion.create(
    model="gpt-4",
    messages=[{"role": "user", "content": prompt}],
    temperature=0.7,
)

此实现在以下方面容易受到攻击：

更改模型时需要修改整个应用程序代码
API密钥管理分散在应用程序内
吸收应用端各提供商的API规范差异（参数名称、响应格式）
难以统一处理速率限制、重试和回退

1.2 Dify 解决方案：分离提供者层

Dify 在应用层（Workflow/Agent/Chat）和模型调用层之间放置了一个 Provider 抽象层：

graph TB
    subgraph "Application Layer"
        W[Workflow]
        AG[Agent]
        CH[Chat App]
    end
    
    subgraph "Provider Abstraction Layer"
        direction TB
        MI[Model Interface<br/>統一 API]
        MC[Model Configuration<br/>Workspace レベル管理]
        MR[Model Runtime<br/>実行・リトライ・制御]
    end
    
    subgraph "Model Providers"
        OP[OpenAI]
        AZ[Azure OpenAI]
        AN[Anthropic]
        GG[Google Gemini]
        OL[Ollama / Local]
        CU[Custom Provider]
    end
    
    W --> MI
    AG --> MI
    CH --> MI
    MI --> MC
    MC --> MR
    MR --> OP
    MR --> AZ
    MR --> AN
    MR --> GG
    MR --> OL
    MR --> CU
    
    style MI fill:#69b,stroke:#333,color:#fff

2. 架构细节

2.1 模型提供者注册结构

📖 注：以下 YAML 是 Dify Provider 抽象层的概念模型示意，用于说明设计意图。Dify 1.x 实际的 Plugin Manifest 结构请参考官方仓库：

主清单 manifest.yaml（包含 plugin 元信息、版本、依赖）

工具 / 模型 provider 的具体字段定义见 api/core/plugin/entities/plugin.py 的 PluginDeclaration

Model Runtime 基类位于 api/core/entities/model_entities.py（ProviderEntity、ModelType、ProviderModel），底层依赖 graphon 库

凭证字段实际命名为 credentials_schema（工具 / Provider 通用），ProviderEntity 嵌套字段为 provider_credential_schema.credential_form_schemas

# Provider 抽象的概念模型（不要直接照抄到 plugin manifest）
provider:
  name: "openai"
  label: "OpenAI"
  supported_model_types:
    - llm
    - text-embedding
    - speech2text
    - tts
  credentials_schema:   # 实际字段名（注意是复数）
    - name: api_key
      type: secret
      required: true
    - name: organization_id
      type: string
      required: false
  models:
    - name: "gpt-4o"
      type: llm
      features:
        - function_calling
        - vision
      context_length: 128000
      pricing:
        input: 0.005   # per 1K tokens
        output: 0.015

本设计有以下意图：

设计元素	目的
`supported_model_types`	统一管理同一提供商提供的不同能力（LLM、Embedding、TTS）
`credentials_schema`	定义如何管理每个提供商的 API 密钥并在工作区级别集中管理它们
`features`	应用层可以通过声明函数调用、视觉等能力来判断兼容性
`context_length`	在设计工作流程时将上下文长度公开为元数据并可视化约束
`pricing`	实现成本估算并支持公司的模型选择决策

2.2 模型接口统一

Provider抽象层的核心是能够通过统一的接口调用不同Provider的API：

# Dify の Model Interface 概念モデル
class ModelInterface:
    """全 LLM Provider に共通のインターフェース"""
    
    def invoke(
        self,
        model: str,
        credentials: dict,
        prompt_messages: list[PromptMessage],
        model_parameters: dict,
        tools: list[Tool] | None = None,
        stop: list[str] | None = None,
        stream: bool = False,
        user: str | None = None,
    ) -> LLMResult | Generator[LLMResultChunk]:
        """
        統一的なモデル呼び出しインターフェース。
        プロバイダー固有のパラメータ変換は内部で処理される。
        """
        pass
    
    def get_num_tokens(
        self,
        model: str,
        credentials: dict,
        prompt_messages: list[PromptMessage],
    ) -> int:
        """トークン数の事前計算"""
        pass
    
    def validate_credentials(
        self,
        model: str,
        credentials: dict,
    ) -> None:
        """クレデンシャルの事前検証"""
        pass

2.3 参数映射实际情况

每个提供商的 API 使用的参数名称和格式略有不同。 Provider 抽象层透明地对此进行了转换：

定义统一参数	开放人工智能	人择	Azure 开放人工智能	奥拉玛
`temperature`	`temperature`	`temperature`	`temperature`	`temperature`
`max_tokens`	`max_tokens`	`max_tokens`	`max_tokens`	`num_predict`
`stop`	`stop`	`stop_sequences`	`stop`	`stop`
`tools`	`tools`	`tools`	`tools`	`tools`
`stream`	`stream`	`stream`	`stream`	`stream`
`response_format`	`response_format`	不适用（替代方法）	`response_format`	`format`

3.工作区级模型管理

3.1 为什么是工作区级别？

在 Dify 中，模型提供程序设置是在 工作区基础 上管理的，而不是在应用程序基础上进行管理。这一设计决定有明确的理由：

graph TB
    subgraph "Workspace A（営業部門）"
        APP1[顧客対応 Bot]
        APP2[提案書生成]
        APP3[FAQ 検索]
        
        subgraph "Workspace A の Model Config"
            M1[OpenAI GPT-4o<br/>API Key: ****]
            M2[Azure OpenAI<br/>Endpoint: jpeast]
        end
    end
    
    subgraph "Workspace B（開発部門）"
        APP4[コードレビュー]
        APP5[ドキュメント生成]
        
        subgraph "Workspace B の Model Config"
            M3[Anthropic Claude<br/>API Key: ****]
            M4[Ollama Llama3<br/>Local]
        end
    end
    
    APP1 --> M1
    APP2 --> M2
    APP3 --> M1
    APP4 --> M3
    APP5 --> M4

设计意图	描述
API 密钥集中管理	工作区管理员集中管理 API 密钥，无需将其分发到每个应用程序
成本可视化	了解 Workspace 的代币消耗和成本
部门治理	可用型号可以受部门限制
更高效的模型切换	只需更改工作区设置，它将反映在所有应用程序中

3.2 模型切换用例

企业实际切换模式的典型场景：

成本优化：从 GPT-4o 切换到 GPT-4o-mini（降低成本，同时保证准确性）
监管准备：从外部 API 迁移到本地本地 LLM
性能提升：新机型发布时逐步过渡
故障响应：在特定提供商发生故障时切换到后备目的地
多模型策略：根据任务类型使用最优模型

4. 插件架构：可扩展性设计

4.1 使用插件添加自定义提供程序

Dify 允许您通过插件机制添加不支持开箱即用的模型提供程序：

graph LR
    subgraph "Dify Core"
        PA[Plugin Architecture]
        MR[Model Runtime]
    end
    
    subgraph "Built-in Providers"
        OP[OpenAI]
        AN[Anthropic]
        AZ[Azure]
    end
    
    subgraph "Custom Plugins"
        CP1[社内 LLM Gateway]
        CP2[国産 LLM<br/>ELYZA / PLaMo]
        CP3[vLLM Cluster]
    end
    
    PA --> OP
    PA --> AN
    PA --> AZ
    PA --> CP1
    PA --> CP2
    PA --> CP3
    PA --> MR

4.2 模型设计规则

官方文档中发布的模型设计规则定义了插件开发者必须遵循的接口约定：

# Model Plugin の必須実装項目
model_plugin:
  # 1. Provider 定義
  provider_manifest:
    - プロバイダー名・アイコン・説明
    - サポートするモデルタイプ
    - クレデンシャルスキーマ
  
  # 2. モデル定義
  model_manifest:
    - モデル名・バージョン
    - 能力宣言 (features)
    - パラメータ制約 (context_length, max_tokens)
    - 価格情報（任意）
  
  # 3. Runtime 実装
  runtime:
    - invoke(): 同期/ストリーミング呼び出し
    - get_num_tokens(): トークン計算
    - validate_credentials(): 認証情報検証

通过遵循此约定，您的自定义提供程序将自动与所有 Dify 功能集成，例如工作流节点中的模型选择、代理中的模型规范、知识库中的嵌入模型选择等。

4.3 插件分离带来的稳定性

📖 前提：进程隔离是 Dify 1.0 引入 Plugin Daemon 之后的特性。0.x 版本的 Provider 不是进程隔离的，自定义 Provider 的崩溃可能影响主进程。Enterprise 部署默认启用 Plugin Daemon。

启用 Plugin Daemon 后，插件作为独立进程运行，自定义 Provider 中的错误或故障不会影响 Dify 核心：

建筑特色	效果
进程隔离 (1.0+)	插件崩溃不会蔓延到核心（前提：启用 Plugin Daemon）
版本无关	Plugin和Dify Core可独立更新
资源限制	每个插件的内存和 CPU 都可以受到限制
安全边界	插件凭证与核心凭证分离

5. 设计权衡

5.1 抽象的限制

Provider抽象层吸收了许多差异，但不能使它们全部透明：

差异类型	抽象的可能性	如何应对
基本聊天完成	完全可抽象	统一接口
函数调用	几乎可以抽象	工具定义的统一格式
视觉（图像输入）	条件抽象	带有功能标志的功能声明
上下文长度	作为元数据进行管理	检查应用程序端的约束
速率限制	依赖于提供商	在运行时层重试/排队
JSON 模式	实施情况因提供商而异	部分抽象+回退
多模式（音频/视频）	供应商之间的巨大差异	对每种模型类型的单独支持
微调API	每个提供商完全不同	不抽象

5.2 处理“最小公约数”问题

抽象层的一个典型风险是它们只能提供“最低公分母”API，而无法利用每个提供商的独特功能。 Dify 通过 特征标志 + 模型参数扩展 解决了这个问题：

# Feature フラグによる能力の動的チェック
model_config = get_model_config("gpt-4o")

if "function_calling" in model_config.features:
    # Function Calling 対応のフローを実行
    result = invoke_with_tools(model, tools, prompt)
elif "vision" in model_config.features:
    # Vision 対応のフローを実行
    result = invoke_with_images(model, images, prompt)
else:
    # 基本的な Text Completion のみ
    result = invoke_text(model, prompt)

6. Provider抽象层在企业中的战略价值

6.1 避免供应商锁定

graph TB
    subgraph "ベンダーロックインの比較"
        direction LR
        subgraph "直接統合"
            A1[App] -->|"OpenAI SDK"| B1[OpenAI]
            A1 -.->|"移行コスト: 高"| C1[Anthropic]
        end
        
        subgraph "Dify Provider 抽象層"
            A2[App] --> D2[Provider Layer]
            D2 -->|"設定変更のみ"| B2[OpenAI]
            D2 -->|"設定変更のみ"| C2[Anthropic]
            D2 -->|"設定変更のみ"| E2[Azure]
        end
    end

6.2 多模型策略的实现

有远见的公司正在根据任务类型而不是单一模型采用多模型策略：

任务类型	推荐型号	选择理由
复杂的推理与分析	GPT-4o / Claude Opus	精度要求高
大批量常规加工	GPT-4o-mini / Claude Haiku	成本效益
日本专业任务	国内LLM / Qwen	日本表演
敏感数据处理	奥拉马（本地）	无法向外发送数据
嵌入	文本嵌入-3-小	成本与准确性之间的平衡
图像识别	GPT-4o / Gemini Pro 视觉	多式联运支持

Dify 的 Provider 抽象层允许您为同一工作流中的不同节点指定不同的模型。这使得上述多模型策略可以在工作流设计层面得以实现。

6.3 成本管理和治理

工作区级别的提供商管理自然提供以下治理功能：

使用情况可视化：按工作空间/应用程序/用户跟踪令牌消耗情况
预算控制：设置每个工作区的使用限制
模型使用政策：仅允许在特定工作空间中使用特定模型的限制
审计跟踪：记录哪些用户向哪些模型发送哪些查询

7. 与其他平台的比较

项目	Dify	浪链	亚马逊基岩	Azure 人工智能工作室
抽象层粒度	供应商+模型	连锁/LLM班	API网关	集线器+端点
GUI 中的模型管理	是的	没有	是的	是的
定制供应商	可通过插件添加	Python 类实现	自定义模型导入	自定义端点
工作区单元管理	是的	没有	账户单位	资源组单位
功能标志	以模型单位声明	无（由代码确定）	模型单位	模型单位
开源软件	是的	是的	没有	没有
运营成本	中型（自托管）	低（框架）	高（AWS 计费）	高（Azure 计费）

总结

Dify 的 Provider 抽象层在“支持多模型”的表面特征背后有以下设计理念：

应用层和模型层清晰分离：应用业务逻辑不依赖于模型选择
工作区级统一管理：API密钥管理、成本管理和治理集中于一处
使用插件的扩展性：可以使用相同的接口添加标准不支持的模型。
特征标志的灵活性：每个模型特定特征的抽象和利用

对于企业来说，Provider抽象层的价值不在于可以连接的模型数量，而在于能够选择、切换和使用模型作为业务决策。 Dify 的设计允许在管理屏幕上做出这些决策，而无需更改任何代码。

参考资料

-Model Providers - Dify Docs -Model Designing Rules -Model API Interface (Schema) -Workspace Overview - Dify Docs

知识库搜索架构：向量搜索+全文搜索+Rerank 三层流水线设计理念

简介

RAG（检索增强生成）是一种基本架构模式，用于抑制 LLM 幻觉并根据公司特定知识生成答案。然而，这并不像“引入 RAG 会提高准确性”那么简单。 **如果搜索准确性较低，传递给 LLM 的上下文将不准确，答案质量也会恶化。 **

Dify 的知识库搜索架构使用三层管道：矢量搜索、全文搜索和重新排序。在这篇文章中，我们将以搜索公司文档为例来解释为什么这三层是必要的，以及每层解决什么样的问题。

1.三层管道整体图

graph TB
    Q[ユーザークエリ] --> P[クエリ前処理]
    
    P --> VS[Vector Search<br/>意味的類似性]
    P --> FTS[Full-Text Search<br/>キーワード一致]
    
    VS --> M[Merge<br/>候補統合]
    FTS --> M
    
    M --> RR[Rerank Model<br/>関連度再スコアリング]
    
    RR --> TOP[Top-K 選択]
    TOP --> LLM[LLM<br/>回答生成]
    
    style VS fill:#4a9,stroke:#333,color:#fff
    style FTS fill:#49a,stroke:#333,color:#fff
    style RR fill:#a49,stroke:#333,color:#fff

1.1 为什么单一的搜索方法是不够的

企业文档查询具有以下不同特点：

查询类型	示例	最佳搜索技巧
语义搜索	“退休时需要办理哪些手续？”	矢量搜索
关键词搜索	“ERR-4052 的原因”	全文搜索
混合型	“根据第24条处理个人信息”	混合+重新排名
暧昧的表达	《如何请假》	矢量搜索
技术术语	“FISC 安全措施标准第 9 章”	全文搜索

原则上，用单一的搜索方法很难涵盖所有这些。

2.第一层：向量搜索

2.1 工作原理

矢量搜索将文本转换为高维向量（嵌入）并利用向量空间中的距离计算相似度（例如余弦相似度）：

graph LR
    subgraph "インデックス構築時"
        D1[文書チャンク] --> E1[Embedding Model]
        E1 --> V1[ベクトル<br/>0.12, -0.34, ..., 0.56]
        V1 --> VDB[(Vector DB)]
    end
    
    subgraph "検索時"
        Q[クエリ] --> E2[Embedding Model]
        E2 --> V2[クエリベクトル]
        V2 --> S[類似度計算]
        VDB --> S
        S --> R[Top-K 候補]
    end

2.2 矢量搜索擅长什么

吸收表达差异：确定“退休程序”和“退出公司时要做的事情”的含义相似。
口语问题回答：将自然语言编写的问题与正式文档相匹配
多语言支持：使用多语言嵌入模型，您可以用日语问题搜索英语文档。

2.3 向量搜索的局限性

限制	具体例子	影响
弱精确关键词匹配	即使您搜索“ERR-4052”，顶部也会出现另一个含义相似的错误代码	技术文件的精确度降低
不擅长处理数字和代码	“24条”与“23条”文件高度相似	法律文件的可靠性下降
取决于Embedding模型的质量	日语技术术语可能无法正确矢量化	特定领域文档的准确性降低
短查询的意图估计不稳定	光是“费用”就让人不清楚到底是申请方式、规定还是支付方式	搜索结果的变化

2.4 嵌入模型选择

Dify 支持多种嵌入模型，允许您根据您的用例进行选择：

型号	维数	日本表演	成本	应用场景
文本嵌入-3-小 (OpenAI)	1536	1536好	低	一般内部文件
文本嵌入 3-large (OpenAI)	3072	3072好	中等	当需要高精度时
多语言-e5-大	1024	1024好	免费（本地）	封闭网络/成本导向
Cohere 嵌入-多语言-v3	1024	1024好	中等	多语言混合环境
BGE-M3	1024	1024优秀	免费（本地）	日本强调/封闭网络

3.第二层：全文检索

3.1 工作原理

全文搜索使用 TF-IDF 和 BM25 算法来计算标记化（形态分析）文本的关键字匹配：

graph LR
    subgraph "インデックス構築時"
        D1[文書チャンク] --> T1[トークナイザー<br/>形態素解析]
        T1 --> I1[転置インデックス]
        I1 --> FTI[(全文検索<br/>インデックス)]
    end
    
    subgraph "検索時"
        Q[クエリ] --> T2[トークナイザー]
        T2 --> K[キーワード抽出]
        K --> S[BM25 スコアリング]
        FTI --> S
        S --> R[Top-K 候補]
    end

3.2 全文搜索擅长什么

关键字精确匹配：错误代码、条款号、产品型号、人名精确匹配
搜索技术术语：支持行业特定缩写和内部术语
快速响应：倒排索引快速搜索
可解释性：清楚为什么返回结果（关键字匹配）

3.3 全文搜索的局限性

限制	具体例子	影响
措辞上的弱点	“退休”和“离职”被视为不同的事情	相关文件被忽视
需要处理同义词	“个人电脑”、“个人电脑”、“电脑”	同义词词典的运算负载
日语形态分析的准确性	新词、自造词、片假名分词错误	搜索遗漏
忽略上下文含义	分不清“苹果”是水果还是公司	噪音增加

3.4 日语全文检索的特点

与英语不同，日语的单词之间没有空格，因此词法分析器的质量与搜索准确性直接相关：

入力: 「個人情報保護法に基づくデータ取扱規定」

MeCab/Sudachi の解析結果:
個人情報 / 保護法 / に / 基づく / データ / 取扱 / 規定

N-gram (bi-gram) の場合:
個人 / 人情 / 情報 / 報保 / 保護 / 護法 / 法に / ...

对于公司文档，通常通过在形态分析器中添加内部词典来提高准确性，但 Dify 旨在通过将其与矢量搜索相结合来弥补形态分析的弱点。

4.第三层：重新排序

4.1 为什么需要重新排序？

矢量搜索和全文搜索都有不同的评分逻辑。简单地合并两个结果并不会产生最佳顺序：

graph TB
    subgraph "Rerank なしの問題"
        VS_R[Vector Search 結果<br/>スコア: 0.89, 0.85, 0.82, ...]
        FTS_R[Full-Text Search 結果<br/>スコア: 12.3, 8.7, 6.2, ...]
        
        VS_R --> MERGE[単純マージ]
        FTS_R --> MERGE
        MERGE --> PROB[問題: スコアの尺度が異なる<br/>どちらを優先すべきか不明]
    end
    
    subgraph "Rerank ありの解決"
        CAND[統合候補リスト]
        CAND --> RR[Rerank Model<br/>クエリと各候補の<br/>関連度を直接評価]
        RR --> SORTED[統一スコアで再ソート]
    end
    
    style PROB fill:#f99,stroke:#333
    style SORTED fill:#9f9,stroke:#333

4.2 重新排序模型的工作原理

Rerank 模型使用 Cross-Encoder 直接对查询和文档对的相关性进行评分：

# Rerank の概念モデル
def rerank(query: str, documents: list[str], model: str) -> list[RerankResult]:
    """
    各文書をクエリとの関連度で再スコアリング。
    Cross-Encoder は Bi-Encoder (Embedding) より精度が高いが、
    計算コストが高いため、候補を絞った後に適用する。
    """
    results = []
    for doc in documents:
        # クエリと文書を連結して入力し、関連度スコアを出力
        score = cross_encoder.predict(f"{query} [SEP] {doc}")
        results.append(RerankResult(document=doc, score=score))
    
    return sorted(results, key=lambda x: x.score, reverse=True)

4.3 Rerank解决的问题

问题	通过重新排序解决
矢量/全文分数范围的差异	统一相关性评分重新评估
表面相关但实质无关的文件	精确评估查询的上下文一致性
候选人太多时的噪音	通过仅将顶尖候选人传递给LLM来提高背景质量
长块的部分匹配	评估整个块与查询的相关性

4.4 重新排序模型选项

型号	供应商	日语支持	成本	特点
Cohere 重新排名 v3	连贯	多语言支持	API计费	精度高、安装方便
bge-reranker-v2-m3	bge-reranker-v2-m3	巴爱	多语言支持	免费（本地）
交叉编码器/ms-marco	拥抱脸	主要是英语	免费（本地）	对于英文文件
Jina reranker v2	Jina	多语言支持	API计费	高速

5.混合搜索：三层集成

5.1 Dify 混合搜索设置

Dify 允许您在创建知识库时选择以下搜索方式：

搜索方式	配置	应用场景
矢量搜索	仅矢量搜索	以语义搜索为中心的常见问题
全文搜索	仅全文搜索	技术文档关键字搜索
混合搜索	矢量+全文+重新排名	通用公司文件（推荐）

5.2 混合搜索处理流程详情

sequenceDiagram
    participant U as ユーザー
    participant API as Dify API
    participant VS as Vector Search
    participant FTS as Full-Text Search
    participant RR as Rerank Model
    participant LLM as LLM

    U->>API: クエリ送信
    API->>API: クエリ前処理
    
    par 並列検索
        API->>VS: Embedding + ANN検索
        VS-->>API: Vector候補 (Top-N)
        API->>FTS: トークン化 + BM25検索
        FTS-->>API: Full-Text候補 (Top-N)
    end
    
    API->>API: 候補の統合・重複排除
    API->>RR: 統合候補リスト + クエリ
    RR-->>API: 再ランキング結果
    API->>API: Top-K 選択
    API->>LLM: クエリ + Top-K 文書チャンク
    LLM-->>API: 回答生成
    API-->>U: 回答返却

5.3 权重设置的概念

使用混合搜索，您可以调整矢量搜索和全文搜索之间的权重分配。 Dify 有一个滑块，可以设置为 0.0 到 1.0：

体重设定	矢量：全文	适用场景
1.0 : 0.0	仅矢量	内部FAQ，主要是自由文字查询
0.7 : 0.3	面向矢量	一般内部文件（推荐初始值）
0.5 : 0.5	甚至	当需要混合查询时
0.3 : 0.7	全文	如果有很多型号/代码搜索
0.0 : 1.0	仅全文	错误代码搜索、法规文章搜索

6. 索引设计：搜索准确性的初步阶段

6.1 分块策略

搜索精度很大程度上取决于索引阶段使用的分块方法：

分块方法	说明	优势	缺点
定长除法	分为 500 个代币单位	简单一致	上下文被分割
分离器事业部	按标题/换行符划分	维护文档结构	块大小不均匀
语义分割	语义分割	高品质搜索单元	加工成本高
亲子块	小块搜索，返回父块	平衡搜索准确性和上下文	实施复杂度

Dify 支持多种分块方法，可以根据文档类型进行选择。

6.2 选择索引方法

Dify 提供两种类型的索引方法：

graph TB
    subgraph "高品質モード (Recommended)"
        HQ_D[文書] --> HQ_C[チャンク分割]
        HQ_C --> HQ_E[Embedding Model<br/>ベクトル化]
        HQ_E --> HQ_V[(Vector Index)]
        HQ_C --> HQ_F[(Full-Text Index)]
        HQ_V --> HQ_H{Hybrid Search<br/>+ Rerank}
        HQ_F --> HQ_H
    end
    
    subgraph "経済モード"
        EC_D[文書] --> EC_C[チャンク分割]
        EC_C --> EC_K[キーワードインデックス]
        EC_K --> EC_S{キーワード検索のみ}
    end
    
    style HQ_H fill:#4a9,stroke:#333,color:#fff

高质量模式：构建嵌入+全文索引。提供混合搜索+重新排名。它价格昂贵，但精度很高。
经济模式：仅关键字索引。嵌入模型 API 成本是不必要的，但语义搜索是不可能的。

7. 公司文档搜索准确性的实际考虑

7.1 按文档类型推荐的设置

文件类型	推荐搜索方式	重量	重新排名	原因
公司规定/用工规定	混合动力	0.5:0.5	有效	条款编号和含义搜索均需
技术手册	混合动力	0.3:0.7	已启用	错误代码和参数的关键字搜索很重要
常见问题解答资料	矢量	1.0:0.0	任意	问题的措辞差异很大
合同	混合动力	0.5:0.5	有效	条款编号+法律概念含义搜索
分钟	矢量	0.7:0.3	有效	口语表达很多，意思搜索很有效
API 文档	混合动力	0.3:0.7	已启用	端点名称与参数名称精确匹配

7.2 调整点以提高准确性

graph TB
    subgraph "チューニングの4つのレバー"
        A[1. チャンキング<br/>サイズ・方式の調整] --> E[検索精度]
        B[2. Embedding Model<br/>モデル選択・ファインチューニング] --> E
        C[3. 検索 Weight<br/>Vector vs Full-Text の比率] --> E
        D[4. Rerank<br/>モデル選択・Top-K 設定] --> E
    end
    
    E --> F[LLM への入力品質]
    F --> G[最終回答品質]

调整块大小：太小，上下文会丢失；太大，搜索将变得粗粒度。一般300-500个代币是起点。
嵌入模型的选择：如果主要使用日语文档，请考虑支持多种语言的高质量模型（text-embedding-3-large、BGE-M3）。
权重调整：分析搜索日志并根据用户查询模式进行调整。
Top-K for Rerank：根据 LLM 上下文长度（通常为 3-5 个块）确定重新排名后要传递的块数。

7.3 如何评估搜索准确性

指标	定义	目标值
回忆@K	Top-K 中包含的正确文档的百分比	> 0.85
精度@K	Top-K 中正确文档的百分比	> 0.70
MRR（平均倒数排名）	正确文档排名的平均倒数	> 0.75
NDCG@K	考虑排名的相关性得分	> 0.80

8.三层管道设计理念

8.1 为什么是“三层”：设计原则

Dify 的三层管道基于以下设计原则：

原则	描述
回应不同的询问	语义搜索与关键词搜索相辅相成
准确度逐步提高	广泛收集（Recall）并精确聚焦（Precision）
计算成本优化	通过轻量级搜索缩小候选者范围，并仅对候选者应用大量重新排名
可配置性	可以根据用例调整权重、Top-K 和 Rerank 的 ON/OFF

8.2 “先回忆再精确”模式

三层管道的本质是“首先收集广泛的候选者（高召回率），然后精确缩小范围（高精确度）**”的模式：

舞台	加工	回忆	精密	计算成本
第一阶段	矢量+全文（并行）	高	中等	低到中
第二阶段	重新排名	维护	高	中到高
第三阶段	Top-K精选	维护	最高	无

这种逐渐缩小范围的结果是均衡的搜索结果，既不是“广泛收集但准确性低”，也不是“高度准确但经常错过”。

总结

Dify 的知识库搜索架构结合了三个互补的搜索层来解决企业文档搜索的基本挑战：

矢量搜索：基于语义相似性的搜索，以适应表达式的变化和模糊的用户查询。
全文搜索：根据精确的关键字匹配进行搜索，包括型号、文章编号和技术术语。
重新排名：整合不同的评分方案并精确评估与查询的上下文相关性

这些不仅仅是一堆算法，而是一种分工，旨在响应企业文档搜索中不同类型的查询。通过调整每层的权重、Top-K 和 Rerank 模型的选择，可以根据文档特征和用户查询模式进行优化。

参考资料

-インデックス方法と検索設定を指定 - Dify Docs -ハイブリッド検索 - Dify Legacy Docs -Re-ranking - Dify Legacy Docs -世界一わかりやすい Dify 初心者のための RAG 完全ガイド -徹底解説 Dify でのナレッジの使い方

工作流节点设计理念：可组合性、人机交互、确定性节点与概率性节点并存

简介

Dify的Workflow不仅仅是一个“调用LLM的流程图”。其设计理念的核心是明确区分人工智能可以自主处理的领域和人类必须做出决策的领域，并使它们共存于单一流程中。

本文详细解释了支持 Dify Workflow 节点设计的四个设计原则：可组合性、人机交互 (HITL)、确定性和概率性节点的正确使用以及错误处理模式。

1. Workflow基本架构

1.1 节点和边缘配置

Dify Workflow 表示为有向无环图 (DAG)：

graph LR
    START((Start)) --> A[LLM Node]
    A --> B{IF/ELSE}
    B -->|条件A| C[Knowledge Base]
    B -->|条件B| D[HTTP Request]
    C --> E[LLM Node 2]
    D --> E
    E --> F[Human Review]
    F -->|承認| G[HTTP Request<br/>外部API送信]
    F -->|差し戻し| A
    G --> END((End))

1.2 节点分类系统

Dify的Workflow节点根据其特点可以分为以下几类：

类别	节点类型	输出的性质	执行时间
概率节点	LLM，问题分类器	非确定性（相同输入，不同输出）	中长
确定性节点	IF/ELSE、代码、模板、变量	确定性（相同输入，相同输出）	短
外部联动节点	HTTP 请求、工具	外部依赖	变量
数据节点	知识检索、变量聚合器	取决于搜索结果	中等
人工干预节点	人工输入（待机型）	取决于人的判断	未定义
控制节点	开始、结束、迭代、参数提取器	流量控制	短

2. 可组合性：组合节点的可能性

2.1 设计原则

Dify Workflow 中的可组合性基于以下原则：

每个节点都有独立的输入/输出接口：节点之间唯一的依赖关系就是变量的传递。
无论节点类型如何，连接协议相同：LLM节点和HTTP节点可以采用相同的方式连接
嵌套和引用分离：变量引用是显式的，没有隐式的全局状态

graph TB
    subgraph "コンポーザビリティの原則"
        direction LR
        subgraph "ノード A"
            A_IN[入力変数] --> A_PROC[処理ロジック]
            A_PROC --> A_OUT[出力変数]
        end
        
        subgraph "ノード B"
            B_IN[入力変数] --> B_PROC[処理ロジック]
            B_PROC --> B_OUT[出力変数]
        end
        
        A_OUT -->|"変数参照"| B_IN
    end

2.2 变量范围模型

工作流中的变量遵循以下范围规则：

范围	描述	访问
节点本地	用于节点内部处理	仅在节点内
节点输出	节点处理结果	由下游节点 `{{node_id.output}}` 引用
工作流程输入	Start 节点	中定义的输入参数由`{{start.input_name}}`从所有节点引用
环境变量	工作流程级别常量	从所有节点可见
对话变量	聊天型工作流程中跨对话保留	可以从所有节点引用和更新

通过这种设计，节点只需要知道“自己的输入和引用节点的输出”，而不需要知道整个工作流的状态。这是可组合性的基础。

2.3 迭代节点：迭代的可组合性

Iteration 节点对数组数据重复执行子流程。这使得无法用单个节点表达的复杂处理可以通过可组合的方式实现：

graph TB
    START((Start)) --> SPLIT[Code Node<br/>文書を章ごとに分割]
    SPLIT --> ITER[Iteration Node]
    
    subgraph ITER[Iteration: 各章に対して]
        I_LLM[LLM Node<br/>要約生成]
        I_LLM --> I_QA[LLM Node<br/>QA 生成]
    end
    
    ITER --> AGG[Variable Aggregator<br/>結果統合]
    AGG --> END((End))

3. Human-in-the-Loop (HITL)：以人为本的设计理念

3.1 为何采用人机交互？

人工智能变得越自主，人类控制就变得越重要。这并不矛盾，而是风险管理的基本原则：

graph TB
    subgraph "AI 自律性と人間制御のマトリクス"
        direction TB
        A["低リスク x 高自動化<br/>完全自動処理<br/>例: FAQ 自動回答"]
        B["高リスク x 高自動化<br/>AI ドラフト + 人間承認<br/>例: 契約書レビュー"]
        C["低リスク x 低自動化<br/>手動 + AI アシスト<br/>例: 創造的文書作成"]
        D["高リスク x 低自動化<br/>人間主導 + AI 補助<br/>例: 法務判断"]
    end

3.2 HITL的三种模式

根据公共文档，Dify 工作流程中的人机交互以三种模式运行：

审批模式

人类审查并批准或拒绝人工智能生成的结果：

graph LR
    A[LLM Node<br/>回答ドラフト生成] --> B[Human Input<br/>承認/却下]
    B -->|承認| C[HTTP Request<br/>顧客に送信]
    B -->|却下| D[LLM Node<br/>再生成]
    D --> B

适用场景：

自动为客户生成电子邮件后发送前确认
合同条款人工智能审核结果的法律确认
主管批准批准文件草案

####修正模式

人类可以直接编辑AI生成的结果：

graph LR
    A[LLM Node<br/>レポート生成] --> B[Human Input<br/>内容修正可能]
    B --> C[Template Node<br/>フォーマット適用]
    C --> D[HTTP Request<br/>レポート保存]

适用场景：

更正了人工智能生成的报告中的数字和表达式
调整翻译结果的细微差别
修正技术文件中的术语

升级模式

如果人工智能的置信度较低，则自动升级为人类：

graph TB
    A[LLM Node<br/>問い合わせ分類] --> B{IF/ELSE<br/>確信度チェック}
    B -->|確信度 > 0.8| C[自動回答]
    B -->|確信度 <= 0.8| D[Human Input<br/>担当者対応]
    D --> E[回答送信]
    C --> E

适用场景：

自动客户支持响应/升级判断
根据OCR识别结果的可靠性进行人工验证
自动/手动分类投诉

3.3 HITL 设计注意事项

注意事项	说明	建议行动
超时	没有收到人类响应时该怎么办	设置默认行为（升级或保留）
并行处理	当多个审批队列同时发生时	审批队列管理和优先级设置
审计追踪	谁批准/修改了什么以及何时	操作日志持久化
权限管理	控制具有审批权限的用户	与工作区角色设置链接
服务水平协议	管理审批等待时间	配置警报通知

4.确定性节点和随机性节点并存

4.1 为什么这种区别很重要？

设计工作流时要认识到的最重要的一点是，输出的可预测性因节点而异：

节点类型	输出属性	测试方法	错误处理
确定性（代码，IF/ELSE）	相同的输入，相同的输出	可进行单元测试	已修复错误
随机（LLM）	相同输入有不同输出的可能性	需要统计评估	提示/参数调整

如果不了解这种区别，就会出现以下问题：

后续处理无法准确解析LLM节点的输出（格式不稳定）
它在测试期间有效，但在生产期间出现不同的输出（缺乏再现性）
无法确定错误原因是LLM 输出还是逻辑。

4.2 确定性节点的作用

确定性节点为工作流提供可预测性和可控性：

# Code ノードの例：LLM 出力の正規化
def main(llm_output: str) -> dict:
    """
    LLM の確率的な出力を、確定的な構造に変換する。
    これにより、後続ノードは安定したデータ形式に依存できる。
    """
    import json
    import re
    
    # JSON ブロックの抽出（LLM が余分なテキストを付加する場合への対応）
    json_match = re.search(r'\{[\s\S]*\}', llm_output)
    if json_match:
        try:
            data = json.loads(json_match.group())
            return {
                "status": "success",
                "category": data.get("category", "unknown"),
                "confidence": float(data.get("confidence", 0)),
                "summary": data.get("summary", "")
            }
        except (json.JSONDecodeError, ValueError):
            pass
    
    return {
        "status": "parse_error",
        "category": "unknown",
        "confidence": 0.0,
        "summary": llm_output[:200]
    }

4.3 随机节点和确定性节点的合作模式

graph TB
    subgraph "推奨パターン: 確率 then 確定 then 分岐"
        A[LLM Node<br/>確率的: テキスト生成] --> B[Code Node<br/>確定的: 出力パース]
        B --> C{IF/ELSE<br/>確定的: 条件分岐}
        C -->|正常| D[次の処理]
        C -->|パースエラー| E[エラー処理]
    end
    
    subgraph "アンチパターン: 確率の連鎖"
        X[LLM Node 1] --> Y[LLM Node 2<br/>前段の出力形式に依存]
        Y --> Z[LLM Node 3<br/>さらに不安定な入力]
    end
    
    style A fill:#f96,stroke:#333,color:#fff
    style B fill:#69b,stroke:#333,color:#fff
    style C fill:#69b,stroke:#333,color:#fff
    style X fill:#f96,stroke:#333,color:#fff
    style Y fill:#f96,stroke:#333,color:#fff
    style Z fill:#f96,stroke:#333,color:#fff

设计原则：始终将代码（确定性）节点放置在LLM（概率性）节点之后，以规范化输出。这可以防止随机输出不稳定在整个 Workflow中传播。

5. 错误处理模式

5.1 工作流程中的错误类型

错误类型	来源	示例	对应图案
模型错误	LLM节点	速率限制、超时和错误输出	重试/回退
外部 API 错误	HTTP 请求	连接超时，5xx 错误	重试/备用端点
数据错误	知识检索	0 条搜索结果，数据格式无效	默认值/升级
逻辑错误	代码 / IF/ELSE	类型不匹配，NULL 引用	错误修复（在设计时修复）
人工输入超时	人工输入	审批人未回复	升级/自动批准

5.2 重试模式

graph TB
    A[LLM Node] -->|成功| B[次のノード]
    A -->|エラー| C{リトライ回数<br/>< 上限?}
    C -->|Yes| D[待機<br/>指数バックオフ]
    D --> A
    C -->|No| E{フォールバック<br/>モデルあり?}
    E -->|Yes| F[代替 LLM Node<br/>別モデルで実行]
    F --> B
    E -->|No| G[エラー終了<br/>/ エスカレーション]

5.3 后备模式

与 Provider 抽象层结合，模型级回退是可能的：

graph LR
    subgraph "フォールバックチェーン"
        P1[GPT-4o<br/>Primary] -->|エラー| P2[Claude Sonnet<br/>Secondary]
        P2 -->|エラー| P3[GPT-4o-mini<br/>Tertiary]
        P3 -->|エラー| ERR[エラー処理]
    end

5.4 优雅降级

服务持续但质量逐渐下降而不是完全失败的模式：

舞台	状态	回应
正常	所有节点工作正常	优质答案
轻微恶化	无法重新排名	仅使用矢量搜索回答（准确性略有下降）
中度恶化	知识库无法搜索	仅使用LLM内部知识回答（带注释）
严重恶化	初级LLM不可能	用后备模型回答
服务中断	所有型号均不可用	升级为人类

6. 工作流程设计最佳实践

6.1 节点设计原则

原理	说明	示例
单一责任	1 个节点 = 1 个责任	不要把“分类+总结”塞进一个LLM
概率输出的即时归一化	将代码节点紧接在 LLM	之后JSON解析验证
故障安全	在每条路径上放置错误处理	使用 IF/ELSE 设计错误分支
可观察性	记录中间结果	将重要的节点输出保留为变量
幂等性	使用相同输入重新运行时没有副作用	确保外部API调用的幂等性

6.2 实用工作流程模板

####客户询问自动回复

graph TB
    START((Start<br/>問い合わせ受信)) --> CLASS[LLM Node<br/>問い合わせ分類]
    CLASS --> PARSE[Code Node<br/>分類結果パース]
    PARSE --> ROUTE{IF/ELSE<br/>カテゴリ判定}
    
    ROUTE -->|FAQ| KB[Knowledge Retrieval<br/>FAQ検索]
    ROUTE -->|技術問題| TECH[Knowledge Retrieval<br/>技術文書検索]
    ROUTE -->|クレーム| HUMAN[Human Input<br/>担当者対応]
    
    KB --> ANS[LLM Node<br/>回答生成]
    TECH --> ANS
    
    ANS --> CONF{IF/ELSE<br/>確信度チェック}
    CONF -->|高| SEND[HTTP Request<br/>回答送信]
    CONF -->|低| REVIEW[Human Input<br/>回答確認]
    REVIEW -->|承認| SEND
    REVIEW -->|修正| ANS
    
    HUMAN --> SEND
    SEND --> END((End))

6.3 反模式

反模式	问题	改进思路
LLM链	随机节点链使输出不稳定	通过
整体LLM	一位LLM有多重责任	将任务拆分到单独的节点
忽略错误	不要设计错误路径	在所有分支上放置错误处理
过度自动化	自动执行高风险操作	使用 HITL 节点设置检查点
硬编码	在提示中嵌入固定值	使用变量和环境变量

7. 日本企业的工作流程设计注意事项

7.1 与 Ringi 流程集成

日本企业特有的Ringi系统自然对应着HITL节点：

graph TB
    A[AI ドラフト生成] --> B[Human Input<br/>起案者確認]
    B --> C[Human Input<br/>課長承認]
    C --> D{IF/ELSE<br/>金額判定}
    D -->|100万円以上| E[Human Input<br/>部長承認]
    D -->|100万円未満| F[処理実行]
    E --> F

7.2 审计跟踪要求

日本企业合规性要求保留人工智能生成的内容和人工批准的记录：

记录项目	需保留的数据	预计保留期限
AI生成日志	提示、模型名称、生成结果、时间戳	5-10年
人类判断日志	审批人ID、判断详情、时间戳	5-10年
外部API调用	请求/响应、端点	3-5年
错误日志	错误类型、发生时间、影响范围	1-3年

7.3 分阶段实施策略

相	自动化水平	HITL 部署	风险管理
第一阶段	AI打稿+人工验证全案	所有节点上的 HITL	最小化风险/建立信任
第二阶段	自动（高置信度）+人工确认（低置信度）	有条件的 HITL	效率与安全的平衡
第三阶段	大多数情况下是自动+人工干预（仅在例外情况下）升级式HITL	需要高效率和监控系统

8. 工作流节点设计的未来展望

8.1 与代理节点合并

Dify 正在进行 Workflow 节点和 Agent 功能的整合，预计会有以下演变：

代理作为节点：将代理作为节点嵌入到工作流中以实现自主任务执行
动态路由：LLM 动态决定工作流程的分支（超越传统 IF/ELSE 的灵活性）
多代理协作：多个代理在工作流程中协作解决问题

8.2 更高级的错误处理

自动恢复：当发生错误时，LLM分析错误原因并自动尝试修复。
学习回退：从过去的错误模式中学习最佳回退策略
主动检查：人工智能在运行节点之前预先验证输入数据的有效性

总结

Dify Workflow 的节点设计理念可以概括为四大支柱：

可组合性：每个节点都有独立的输入/输出接口，可以自由组合。变量作用域使节点之间的依赖关系保持明确且最小化。
人在环：人工智能自主与人类控制共存。可以根据风险级别使用批准、纠正和升级三种模式来设计人为干预。
使用确定性和概率性节点：立即用Code（确定性）节点对LLM（概率性）的输出进行归一化，以确保整个 Workflow的可预测性。
错误处理：通过多层错误处理（包括重试、回退、优雅降级和升级）实现生产环境的稳健性。

一个成熟的工作流并不是自动化比例很高，而是有一个清晰的边界设计，“哪里自动化，哪里部署人力，哪里放置错误处理”。 Dify 的节点设计理念提供了一个框架，允许您在 GUI 上直观地设计边界。

参考资料

-Human-in-the-Loop の概念を Dify に落とし込み、AI の暴走を防ぐ -Human-in-the-Loop の活用事例 Dify での具体的な運用パターン9選 -Human-in-the-Loop の活用事例 Dify での具体的な運用パターン

Dify 的多租户模型：Workspace 隔离的粒度、权限继承关系、设计取舍

当前公开资料不足以支撑一篇可靠的、可直接定性为“Dify 官方多租户模型设计说明”的正文。

虽然公开资料里能看到 Workspace、Team Members、Environment Variables、部分前端架构观察，但这些信息还不足以严谨说明：

Workspace 隔离到底是产品级还是企业治理级的最终边界
权限继承关系在 Enterprise 中的完整设计
多租户场景下哪些能力可以共享、哪些必须隔离
设计取舍背后的官方产品决策逻辑

因此，这一题不适合继续硬写成方法论正文，建议先留空，占位等你后续补内部资料或原厂视角信息。

建议你后续补充的内容

请优先补以下内容：

Workspace 隔离粒度说明
- 应用
- 知识库
- 工具授权
- 成员与角色
权限继承关系图
- 平台管理员
- 工作区管理员
- 应用维护者
- 普通成员
共享与隔离策略
- 哪些模型配置可平台共享
- 哪些数据必须工作区隔离
- 哪些插件或工具应按工作区授权
设计取舍说明
- 为什么采用当前隔离边界
- 为什么不做更强 / 更弱隔离
- 多租户与企业治理之间的关系

公开资料线索

当前结论

公开资料只足以说明 Dify 存在 Workspace、成员和配置分层。
但不足以支撑一篇严谨的“多租户模型官方设计稿”。
这一题建议等你补原厂或内部资料后再写。

企业AI应用的分层架构设计

以“LLM+聊天UI”的方式引入企业人工智能的时代已经结束。为了平衡生产环境中的可靠性、可扩展性和治理，基于清晰层分离的架构设计至关重要。本文提出了一个四层模型：基础设施层、平台层、应用层和表示层，并解释了 Dify 定位在哪一层以及如何设计各层之间的集成模式。

整体架构概览

graph TB
    subgraph PL["プレゼンテーション層（ユーザー層）"]
        WEB["Web UI / チャット"]
        MOBILE["モバイルアプリ"]
        INTERNAL["社内ポータル連携"]
        API_GW["API Gateway"]
    end

    subgraph AL["アプリケーション層"]
        APP1["契約レビュー Assistant"]
        APP2["社内 FAQ Bot"]
        APP3["稟議ドラフト生成"]
        APP4["製造品質分析"]
        APP5["文書処理パイプライン"]
    end

    subgraph PLAT["プラットフォーム層 ← Dify"]
        MODEL["モデル管理・ルーティング"]
        KB["Knowledge Base"]
        WF["Workflow エンジン"]
        AGT["Agent フレームワーク"]
        GOV["権限・ログ・監査"]
        TOOL["Tool / Plugin 管理"]
    end

    subgraph INFRA["インフラストラクチャ層"]
        K8S["Kubernetes / コンテナ基盤"]
        DB["PostgreSQL / RDS"]
        REDIS["Redis / ElastiCache"]
        S3["S3 / オブジェクトストレージ"]
        VDB["ベクトルDB（Weaviate / Qdrant）"]
        NET["ネットワーク / Ingress / WAF"]
    end

    PL --> AL
    AL --> PLAT
    PLAT --> INFRA

为什么我们需要分层架构

职责分离原则

企业人工智能基础设施涉及各种各样的利益相关者。

利益相关者	兴趣	对应层
基础设施团队 (SRE)	可用性、扩展性和成本	基础设施层
人工智能平台团队	模型管理、RAG 质量、治理	平台层
业务拓展团队	业务逻辑、用户体验	应用层
最终用户/外部系统	使用方便，响应速度快	表示层

如果不分层，模型变更将波及到基础设施配置，业务应用修改将与整个平台的发布周期捆绑在一起。有一个金融行业大公司的案例，LLM版本更新触发了全公司系统测试，因为这种分离不充分。

日本企业特定的考虑因素

数据主权：遵守个人信息保护法和金融服务机构指南。通过分离模型推理层和数据存储层，可以定位数据跨界问题。
多供应商策略：与日本公司常见的SI划分系统兼容。可以将A公司的基础设施、B公司的平台运营以及内部应用程序开发分开。
逐步实施：从PoC到生产逐层提高成熟度。

基础设施层设计指南

组件和推荐配置

组件	开发/验证环境	生产环境（中型）	生产环境（大规模）
库伯内特	单节点/Docker 撰写	3+ 个工作节点	5 个以上工作节点，多可用区
PostgreSQL	单实例	RDS 多可用区	极光 PostgreSQL
Redis	单实例	ElastiCache（副本）	Redis哨兵/集群
对象存储	本地卷	S3	S3 + CloudFront
矢量数据库	Weaviate单	韦维特集群	Qdrant 分布式 / pgvector
网络	节点端口	ALB + 入口	ALB + WAF + 私有链接

###基础设施层设计原则

无状态/有状态分离：Dify 的 API Server 和 Workers 被设计为无状态，使得水平扩展变得容易。最好将有状态数据存储（PostgreSQL、Redis、向量数据库）委托给托管服务。
资源预留：使用 NodePool 分离 GPU 节点（如果您内部托管模型推理）和 CPU 节点
秘密管理：使用 Kubernetes Secrets 或 HashiCorp Vault 集中管理 API 密钥和数据库凭证

平台层设计指南–Dify定位

Dify 覆盖的领域

Dify 位于企业人工智能应用基础的平台层。具体来说，它提供了以下功能。

graph LR
    subgraph DifyPlatform["Dify プラットフォーム層"]
        direction TB
        MP["Model Provider 管理<br/>OpenAI / Azure / Anthropic / 国産LLM"]
        KB2["Knowledge Base<br/>ベクトル検索 / 全文検索 / Hybrid"]
        WF2["Workflow Designer<br/>条件分岐 / ループ / 外部API呼出"]
        AG2["Agent<br/>Tool 呼び出し / ReAct / Function Calling"]
        PERM["Workspace 権限管理<br/>メンバー / ロール / API キー"]
        LOG["ログ・可観測性<br/>実行履歴 / トークン使用量"]
    end

###平台层向应用层提供的接口

Dify 通过以下方式向上层应用程序层公开功能。

接口	应用	典型使用场景
休息 API	来自应用程序的调用	来自内部系统的聊天机器人/完成调用
网络钩子	事件驱动的协作	向 Slack / Teams 发送工作流程完成通知
嵌入小部件	网页嵌入	嵌入内部门户的聊天 UI
工作流程作为 API	将复杂的处理管道转换为API	系列文件导入→分类→汇总→通知

平台层设计注意事项

模型路由策略：不是对所有应用程序使用相同的模型，而是根据任务特征在 GPT-4o / Claude / 轻量级模型之间切换。 Dify 模型提供程序设置允许基于每个工作空间进行控制
知识库分而治之：按部门/业务领域划分知识库，并限制每个应用程序的引用（详细信息请参阅“知识库可扩展设计”）
治理政策：设置令牌使用限制、模型访问审批流程以及管理提示模板

应用层设计指南

###应用模式分类

图案	特点	Dify中的实现方法	行业实例
互动助手	与用户自然语言对话	聊天机器人应用程序 + 知识库	财务：内部查询机器人
文档处理管道	大文档量的批处理	工作流程（HTTP + LLM 节点链接）	制造：质量报告自动摘要
决策支持	多方信息分析与建议	代理+工具（数据库搜索/API调用）	零售：需求预测报告生成
代码生成/审查	软件开发支持	完成应用+自定义提示	IT：代码审查支持
多式联运处理	图像/PDF/音频理解	工作流程+视觉模型	保险：定损单据图像分析

应用层与其他层的边界

应用层应该具备什么：

业务逻辑（审批流程、通知规则、输出格式）
用户认证/授权（SSO联动、API密钥管理）
特定业务的前处理和后处理

应用层不应该有的东西：

直接模型调用（通过平台层）
直接访问Vector DB（使用知识库API）
基础设施配置管理

表示层设计指南

连接模式

graph LR
    U1["エンドユーザー"] --> WEB2["Dify Web UI"]
    U2["社内ユーザー"] --> PORTAL["社内ポータル<br/>（iframe / API）"]
    U3["モバイルユーザー"] --> MAPP["モバイルアプリ<br/>（REST API）"]
    U4["外部システム"] --> APIGW["API Gateway<br/>（認証 + レート制限）"]
    
    WEB2 --> DIFY["Dify Platform"]
    PORTAL --> DIFY
    MAPP --> DIFY
    APIGW --> DIFY

日本企业的典型整合目的地

整合目的地	连接方式	笔记
微软团队	Bot 框架 + Dify API	需要与 Azure AD 进行 SSO 集成
松弛	Slack 应用程序 + Webhook	企业网格需要安全审查
立即服务	REST API 集成	工单创建/更新流程设计
SAP	RFC/BAPI → 中间 API → Dify	需要数据转换层
通通	Webhook + REST API	定制JS API调用

层间集成模式

模式 1：同步 API 调用

最简单的模式。如果响应时间落在 SLA 范围内，则适用。

ユーザー → API Gateway → Dify REST API → LLM → 応答返却

预计延迟：1-10秒（取决于型号提示长度）

模式 2：异步工作流程

适用于长期加工和批量加工。使用 Dify Workflow 进行排队。

外部トリガー → Dify Workflow API → 処理実行 → Webhook 通知 → 結果格納

模式 3：事件驱动的协作

使用文档注册/更新作为触发器自动更新知识库。

文書管理システム → Webhook → Dify Knowledge Base API → 自動インデックス更新

反模式

以下架构决策很可能会导致企业运营出现问题。

反模式	问题	推荐方法
单一人工智能应用程序	模型变化波及各处	层层分离+API抽象
每个部门都建立自己的LLM基础设施	成本增加和治理的不可能性	建立通用平台层
跳过平台层直接调用LLM	没有审核日志，提示难以管理	通过 Dify 标准化模型访问
基础设施层与应用层紧耦合	扩展困难和迁移成本增加	利用托管服务 + IaC

总结

企业人工智能应用的分层架构不仅仅是一个概念组织；这是一项实用的设计政策，可以明确团队之间的职责划分并将变更的影响本地化。通过将 Dify 定位在平台层，基础设施团队可以专注于基础设施，业务团队可以专注于业务逻辑，实现整个 AI 平台的治理和可扩展性。

特别是对于日本大型企业来说，它与SI合作伙伴的共享结构和分阶段引入流程高度兼容，是在利用现有IT治理体系的同时加速人工智能应用的现实方法。

参考资料

Dify官方文档：Overview
Dify企业部署指南：Kubernetes
Dify Helm 图表：Advanced Configuration
Dify API开发指南：API ベースの開発

模型选择框架：根据任务特征优化模型策略

企业中的模型选择是由任务特征、成本、延迟和质量的平衡决定的，而不是由基准排名决定的。本文提出了一个实用的选择框架，包括按任务类型进行模型映射、成本/性能权衡以及日语支持注意事项。

模型选择的基本原则

为什么“选择最强模型”失败

许多 PoC 将 GPT-4 类的顶级模型应用于所有任务。但在生产环境中，会出现以下问题。

问题	影响	示例
成本爆炸	每月超过数百万日元	将 GPT-4o 应用到全公司范围内的 FAQ Bot 每月成本为 400 万日元
延迟增加	用户放弃	对于分类任务来说 3-5 秒已经过多了
品质过剩	投资回报率下降	是/否决策不需要高级推理
单点故障	所有应用程序均已停止	特定提供商的失败会影响整个公司

Dify 的多模型架构

Dify 使用 Model Provider 机制来管理和切换同一平台上的多个模型。

graph TB
    subgraph Apps["アプリケーション"]
        A1["契約レビュー"]
        A2["FAQ Bot"]
        A3["文書分類"]
        A4["画像解析"]
    end

    subgraph DifyRouter["Dify Model Provider ルーティング"]
        MP1["OpenAI<br/>GPT-4o / GPT-4o-mini"]
        MP2["Anthropic<br/>Claude Sonnet / Haiku"]
        MP3["Azure OpenAI<br/>（日本リージョン）"]
        MP4["Google<br/>Gemini Pro / Flash"]
        MP5["国産 LLM<br/>（オンプレミス）"]
        EMB["Embedding モデル<br/>text-embedding-3-large"]
        RR["Reranker<br/>Cohere Rerank"]
    end

    A1 --> MP2
    A2 --> MP1
    A3 --> MP1
    A4 --> MP4
    A1 --> EMB
    A2 --> EMB
    A1 --> RR

按任务类型划分的模型选择矩阵

选择决策轴

graph LR
    TASK["タスク特性"] --> QUALITY["品質要求"]
    TASK --> LATENCY["レイテンシ要求"]
    TASK --> COST["コスト感度"]
    TASK --> LANG["日本語品質"]
    TASK --> SEC["セキュリティ要件"]
    
    QUALITY --> MODEL["モデル選定"]
    LATENCY --> MODEL
    COST --> MODEL
    LANG --> MODEL
    SEC --> MODEL

类型 1：文本生成（高质量）

输出质量至关重要的任务，例如合同审查、报告生成和长摘要。

评价轴	重要性	笔记
表达质量/准确性	最高	幻觉率直接影响生意
长上下文	高	合同10-50页
结构化输出	高	稳定的 JSON/Markdown 输出
日本品质	最佳	敬语/作为商业文件的适当性
延迟	中等	很多情况下，小于10秒是可以接受的

推荐型号配置：

型号	适用场景	优势
Claude Sonnet 4	合同审查、长文本分析	长文本上下文、指令可遵循性、日语品质
GPT-4o	报告生成、总结	结构化输出的多功能性、稳定性
Gemini2.5 Pro	超长文本处理	100万个代币上下文

类型 2：文本生成（快速且低成本）

响应速度和成本效率很重要的任务，例如常见问题解答、样板生成和重写。

评价轴	重要性	笔记
延迟	最佳	1-2 秒内
成本	最高	需要大量通话
品质	中等	预设回复就足够了

推荐型号配置：

型号	适用场景	成本比（与 GPT-4o 相比）
GPT-4o-迷你	常见问题解答，标准回复	大约。 1/30
Claude Haiku 3.5	轻量级文本处理	大约 1/25
Gemini2.0闪存	快速响应	大约。 1/20

###类型3：分类/判断

输出有限且稳定性至关重要的任务，例如文档分类、情感分析和路由决策。

评价轴	重要性	笔记
输出稳定性	最高	相同输入相同输出
成本	高	经常需要大批量处理
延迟	高	避免管道瓶颈
品质	中等	类别数量有限

推荐型号配置：

型号	适用场景	笔记
GPT-4o-迷你	一般分类	温度=0时稳定输出
Claude Haiku 3.5	日语文本分类	对日语背景有很好的了解
微调模型	分类精度要求高	使用内部数据进行培训

Dify Workflow 中的分类模式：

入力テキスト → LLM（分類）→ 条件分岐 → 各カテゴリ別処理

通过与Workflow的条件分支节点结合，可以根据分类结果自动进行后续处理。

类型 4：RAG（搜索扩展生成）

与知识库集成的问答。基本的三层结构是Embedding / Reranker / Generation Model。

组件	角色	推荐型号
嵌入	文本到矢量转换	text-embedding-3-large (OpenAI)，多语言-e5-large
重新排序	重新排名搜索结果	Cohere 重新排名，bge-reranker-v2-m3
生成模型	答案生成	根据任务质量选择（见类型1/2）

日本 RAG 注释：

日语文本高度依赖于嵌入模型的多语言质量。
text-embedding-3-large 具有良好的日语性能，但如果需要领域专业化，请考虑微调 multilingual-e5-large
Reranker 极大地提高了搜索准确性。需要包含超过 100,000 篇文章的知识库

类型 5：多式联运

涉及非文本输入的任务，例如图像识别、PDF 解析和绘图阅读。

输入类型	推荐型号	适用场景
照片/图像	GPT-4o、Gemini 2.5 Pro	损害评估、现场照片分析
PDF / 文档图像	Claude Sonnet 4	文本提取/合同摘要 PDF
图纸/蓝图	Gemini2.5 Pro	制造业设计图分析
表格数据	GPT-4o	阅读财务报表

类型6：代理（工具调用）

在调用多个外部工具的同时执行多步推理的任务。函数调用的稳定性是关键。

评价轴	重要性	笔记
函数调用准确度	最高	错误的工具调用直接导致业务问题
推理能力	高	多步骤规划+执行
成本	中等	与对话轮数成正比

推荐型号配置：

型号	适用场景	优势
Claude Sonnet 4	复杂代理	工具使用精度和可靠性
GPT-4o	通用代理	函数调用生态系统成熟度

成本、延迟和质量之间的权衡

成本比较（估计，截至 2026 年 4 月）

型号	输入（$/1M 代币）	产出（$/1M 代币）	延迟指南	质量范围
GPT-4o	2.50 美元	10.00 美元	2-5 秒	高
GPT-4o-迷你	0.15 美元	0.60 美元	0.5-2秒	中等
Claude Sonnet 4	$3.00	15.00 美元	2-5 秒	高
Claude Haiku 3.5	0.80 美元	4.00 美元	0.5-2秒	中高
Gemini2.5 Pro	1.25 美元	10.00 美元	2-5 秒	高
Gemini2.0闪存	0.10 美元	0.40 美元	0.3-1秒	中等

*价格是根据每个提供商公布的费用估算的。根据实际合同条款而有所不同。

每月成本模拟

估算典型内部人工智能应用程序集的成本：

应用程序	每月请求	型号	预计月费
内部常见问题机器人	50,000	GPT-4o-迷你	大约。 150 美元
合同审查	2,000	Claude Sonnet 4	大约。 600 美元
文档分类管道	100,000	GPT-4o-迷你	大约。 100 美元
管理报告生成	500	500 GPT-4o	大约。 250 美元
总计			大约 1,100 美元/月

将 GPT-4o 应用于所有任务时，与每月约 12,000 美元相比，成本节省约 90%。

日本模型注意事项

###日语成绩评价分

评价项目	确认方法	注意事项
敬语的恰当性	商业电子邮件生成测试	如何使用敬语和谦语
术语准确性	行业特定文档摘要测试	金融、法律和制造词汇
长句的一致性	10页以上文档处理测试	维护上下文并遵循指示
专有名词的处理	公司名称和产品名称的处理测试	存在不必要的翻译和转换
结构化输出	JSON/CSV 生成测试	包括日语在内的结构化数据的稳定性

数据位置要求

需求级别	对策	应用行业实例
日本地区必填	Azure OpenAI（日本东部）	金融、政府机关
国内通讯路线	通过 API + VPN / 私人链接	医疗、国防相关
需要本地部署	国内LLM/OSS模式自托管	高度保密的制造

Azure OpenAI 的日本东部地区已成为需要遵守金融厅准则的金融机构事实上的标准选择。

模型选择的决策流程

flowchart TD
    START["タスク定義"] --> Q1{"セキュリティ要件<br/>オンプレ必須？"}
    Q1 -->|Yes| OSS["OSS / 国産モデル<br/>自社ホスト"]
    Q1 -->|No| Q2{"タスク複雑度"}
    
    Q2 -->|"高（推論・分析）"| Q3{"コスト感度"}
    Q2 -->|"中（生成・要約）"| MID["GPT-4o / Claude Sonnet"]
    Q2 -->|"低（分類・判定）"| LIGHT["GPT-4o-mini / Haiku"]
    
    Q3 -->|低| PREMIUM["Claude Sonnet 4 / GPT-4o"]
    Q3 -->|高| BALANCED["Gemini 2.5 Pro / Claude Sonnet"]
    
    MID --> Q4{"日本語品質<br/>最重要？"}
    Q4 -->|Yes| JP["Claude Sonnet 4<br/>（日本語品質に定評）"]
    Q4 -->|No| GEN["GPT-4o<br/>（汎用性重視）"]

使用 Dify 进行模型切换操作

按工作区进行模型管理

Dify Enterprise 允许您限制每个工作区可用的模型。推荐的操作模式如下。

工作空间	使用	权限模型	原因
用于开发和验证	PoC，快速发展	所有型号	对比验证
生产（标准）	一般商业应用	GPT-4o-mini，俳句	成本管理
生产（高品质）	合同/法律/管理	GPT-4o，Claude Sonnet	质量保证
生产（安全）	敏感数据处理	Azure OpenAI（日本）	数据位置

更改模型时的影响管理

模型变更（版本升级、提供商切换）对应用质量有直接影响。建议采用以下流程。

验证环境中的回归测试：使用代表性输入/输出对检查质量
逐步推出：作为金丝雀版本应用于部分用户
指标监控：监控令牌使用情况、响应质量得分和错误率
回滚程序：您可以使用 Dify 的 Model Provider 设置立即切换

总结

模型选择不应仅基于技术性能比较，还应基于任务特性、成本、延迟、安全性和日语质量五个轴进行综合判断。通过利用 Dify 的多模型架构，可以为每个任务分配最佳模型，并实现在保持质量的同时降低成本高达 90% 的配置。

重要的是不要让模型选择成为一次性决策，而是建立一个持续评估和审查的操作流程。鉴于LLM的发展速度，我们建议每季度重新评估一次。

参考资料

Dify 模型提供商设置：モデルプロバイダー
整理一代AI技术评选：zenn.dev 記事
LLM框架选择标准：zenn.dev 記事

知识库可扩展设计：超10万个文档稳定运行的架构

当知识库的文档数量超过10万条时，问题从“能否上传？”转变为“搜索质量能否保持？”和“运营能否持续？”本文将基于Dify的功能体系，阐述大规模知识库的划分策略、优化嵌入管道、索引管理以及保证搜索性能的方法。

规模扩大会带来什么变化？

文档大小的变化和问题

规模	典型用例	主要挑战
约 1,000 件商品	部门常见问题解答、内部规定	很少有问题。可使用默认设置
1,000~10,000 件	产品手册、技术文件	搜索准确性降低，块设计的重要性增加
10,000~100,000 件	全公司知识整合、合同组	需要分区策略，索引更新性能问题
10万例~	跨多个业务部门的客户响应历史记录	需要全面的架构设计

大规模运营中出现的问题

graph TD
    SCALE["ドキュメント規模拡大"] --> P1["検索精度低下<br/>関連性の低い結果が増加"]
    SCALE --> P2["インデックス更新遅延<br/>新規文書の反映に時間"]
    SCALE --> P3["ベクトルDB 負荷増大<br/>メモリ・ストレージ逼迫"]
    SCALE --> P4["運用複雑化<br/>版管理・権限管理が困難"]
    SCALE --> P5["コスト増大<br/>Embedding API 呼び出し費用"]
    
    P1 --> S1["Hybrid 検索 + Rerank"]
    P2 --> S2["差分インデックス更新"]
    P3 --> S3["ベクトルDB スケーリング"]
    P4 --> S4["分割戦略 + メタデータ管理"]
    P5 --> S5["Embedding パイプライン最適化"]

分区策略（知识库分区）

分部基本方针

“将公司所有文档放在一个知识库中”的做法在规模较小时有效，但当数量超过10万时就失效了。需要根据目的确定划分轴并设计知识库。

分割轴比较

分度轴	应用场景	优势	缺点
按部门	部门具体业务知识	权限管理方便，搜索范围有限	交叉搜索困难
按域名	产品组、服务组	高度专业化的搜索成为可能	需要就域定义达成一致
按文件类型	合同、手册、会议记录	轻松优化分块策略	弱于交叉问题
按安全级别划分	按灵敏度分类	清晰的访问控制	分布在同一部门内
按时间轴	按年/季度	轻松档案管理	最新/过去交叉搜索

推荐：混合分体式

在实际操作中，多轴组合比单轴更有效。

graph TB
    subgraph Org["全社 Knowledge Base アーキテクチャ"]
        subgraph Finance["金融事業部"]
            F1["KB: 契約書<br/>（機密・高）"]
            F2["KB: 商品マニュアル<br/>（機密・中）"]
            F3["KB: 顧客 FAQ<br/>（機密・低）"]
        end
        subgraph Mfg["製造事業部"]
            M1["KB: 品質規格<br/>（機密・高）"]
            M2["KB: 作業手順書<br/>（機密・中）"]
            M3["KB: 技術ナレッジ<br/>（機密・低）"]
        end
        subgraph Common["全社共通"]
            C1["KB: 社内規程"]
            C2["KB: IT ヘルプデスク"]
            C3["KB: 人事・総務 FAQ"]
        end
    end

Dify 中的拆分实现

Dify 允许您通过以下方式划分和管理您的知识库。

工作空间划分：为每个部门划分独立的工作空间，并在每个工作空间内创建多个知识库。
应用级引用控制：显式指定每个应用程序引用的知识库。防止不必要的知识库搜索
通过API动态选择：使用工作流中的条件分支根据输入分类结果切换参考知识库。

块设计优化

按文档类型划分的分块策略

块大小和重叠设置与搜索质量直接相关。需要根据文档类型进行优化。

文件类型	推荐块大小	重叠	原因
常见问题解答（问答格式）	300-500 代币	50 个代币	大小适合一大块问答
技术手册	500-800 代币	100 个代币	章节中的语义分组
合同	800-1200 代币	150 个代币	将条款放在上下文中
分钟	400-600 代币	80 个代币	发言单位组
代码文档	600-1000 代币	100 个代币	功能/类单元

块质量评估指标

指标	目标值	测量方法
搜索命中率 (Recall@5)	90% 或以上	评估题集命中率（100 题）
搜索准确率（精度@5）	70% 或以上	前 5 个相关块的百分比
答案准确度	85% 或以上	手动评估 LLM 生成的答案

嵌入管道优化

大规模嵌入处理的架构

当使用嵌入处理超过 100,000 个文档时，需要解决以下问题。

graph LR
    subgraph Input["入力"]
        DOC["文書群<br/>100K+ 件"]
    end
    
    subgraph Pipeline["Embedding パイプライン"]
        PRE["前処理<br/>テキスト抽出・クレンジング"]
        CHUNK["チャンク分割<br/>文書タイプ別ルール"]
        BATCH["バッチ Embedding<br/>並列処理"]
        IDX["インデックス登録<br/>ベクトルDB"]
    end
    
    subgraph Optimize["最適化ポイント"]
        O1["差分処理<br/>変更分のみ再Embedding"]
        O2["バッチサイズ調整<br/>API レート制限対応"]
        O3["非同期処理<br/>業務時間外実行"]
    end
    
    DOC --> PRE --> CHUNK --> BATCH --> IDX
    O1 -.-> BATCH
    O2 -.-> BATCH
    O3 -.-> BATCH

初始加载和差异更新

加工类型	目标	推荐方法	预计所需时间（100,000 项）
首次满载	所有文件	批量嵌入，每晚执行	8-24小时（取决于型号和并行度）
每日差异更新	新的/更新的文档	Webhook 触发器或常规批处理	几分钟到几十分钟
定期重建	所有索引	每月/每季度，更改嵌入模型时	8-24 小时
紧急后处理	检测出质量问题	手动触发	取决于目标金额

嵌入成本估算

嵌入模型	价格（$/100 万代币）	100,000 个物品的初始成本（平均 1000 个代币/物品）
文本嵌入-3-小	0.02 美元	约 2 美元
文本嵌入 3 大	0.13 美元	约 13 美元
multilingual-e5-large（自托管）	仅 GPU 成本	初期投资+运营成本

分块后的 token 总数大约是原始文档的 1.1-1.3 倍（重叠）。尽管与 LLM 推理成本相比，嵌入成本本身很小，但频繁的重建会累积起来。

索引管理

Dify索引方法

Dify 提供了以下几种索引方式，您可以根据自己的使用情况进行选择。

指数法	特点	推荐情况
高品质模式	嵌入+矢量搜索	标准推荐。语义搜索成为可能
经济模式	基于关键词	成本导向，精准术语搜索
问答环节	索引为问答对	常见问题解答、客户支持

###大规模操作的索引管理规则

管理项目	推荐规则	原因
添加元数据	为所有文档添加来源、日期、部门、文档类型	过滤搜索、溯源
版本管理	更新时先删除旧版本再注册新版本	防止由于重复块而导致搜索质量下降
定期库存	每季度识别并删除无效文档	防止索引膨胀
质量监控	每月进行搜索质量评估测试	及早发现老化恶化

搜索性能优化

利用混合搜索

在大型知识库中，仅靠矢量搜索通常是不够的。利用 Dify 提供的混合搜索（矢量搜索+全文搜索）。

搜索方式	优势	弱点	应用场景
矢量搜索	语义相似度	缺乏专有名词和型号	概念性问题
全文检索	精确匹配、部分匹配	容易受到表达变化的影响	型号搜索、准确术语
混合搜索	结合两者的优势	需要调整设置	大KB标准
混合+重新排名	最高精度	成本和延迟增加	质量至关重要的情况

重新排序的效果

Reranker 重新评估前 N 个搜索结果并按相关性顺序对它们进行排序。对于大规模知识库来说效果显着。

条件	无需重新排序 (Recall@5)	通过重新排名（Recall@5）	改善率
10,000 KB	85%	90%	+5%
100,000 KB	70%	85%	+15%
100 万KB	55%	78%	+23%

*以上是基于一般 RAG 基准的指南。实际数字因数据特征而异。

搜索性能调整

参数	默认	大知识库推荐	描述
前 K（首次搜索）	5	10-20	10-20重新排名增加先前候选人的数量
前K名（最终结果）	3-5	3-5 3-5	3-5传递给 LLM 的块数
分数门槛	无	0.5-0.7	排除低分结果
重新排名	关闭	上	大 KB 所需

通过查询预处理进行优化

通过预处理用户输入查询可以显着提高搜索质量。以下模式可以使用 Dify Workflow 来实现。

graph LR
    Q["ユーザー質問"] --> CLASS["LLM: 質問分類<br/>（どの KB を検索すべきか）"]
    CLASS --> REWRITE["LLM: クエリ書き換え<br/>（検索に最適化した表現）"]
    REWRITE --> SEARCH["Hybrid 検索<br/>+ Rerank"]
    SEARCH --> GEN["LLM: 回答生成"]
    GEN --> ANS["回答"]

查询重写示例：

原始查询	重写后	效果
“去年的销售情况怎么样？”	《2025年度销售报告》	让歧义表达更加具体
《A先生的案子》	“客户A最新续约状态”	使隐性知识显性化
“那本手册”	《产品X操作手册最新版》	指示代词解析

矢量数据库缩放

矢量数据库选择标准

矢量数据库	100,000 件商品	100 万件商品	1000 万件商品	特点
Weaviate	好	好	集群推荐	Dify默认兼容，过滤功能齐全
Qdrant	好	好	分布式模式	高性能、内存高效
pgvector	好	注意	不推荐	PostgreSQL集成，适合中小型
Milvus	好	好	好	大规模专业化、分布式原生

尺码指南

参数	计算公式	预计 100,000 件
矢量存储	项目数 x 维度数 x 4 字节 x 块放大率	大约。 30-50 GB（1536 个维度）
内存	矢量存储 x 1.5-2.0	大约。 45-100 GB
中央处理器	与同时搜索的数量成正比	4-8 个 vCPU
IOPS	取决于索引更新频率	1000-3000 IOPS

块乘数：假设每个文档平均有 3-10 个块

大规模知识库的运行结构

###推荐操作流程

流程	频率	责任	内容
文件导入	每日/根据需要	内容管理员	注册新文档，添加元数据
质量检测	每月	人工智能平台团队	使用评估问题集搜索质量测量
指数盘点	季刊	内容管理员+AI团队	删除无效文档，审查分块策略
矢量数据库监控	不断	上一篇：内存使用率、查询延迟、错误率
嵌入模型评估	半年	AI平台团队	与新模型的质量比较、迁移决策

要监控的指标

指标	门槛	警报条件
搜索延迟 (P95)	< 500 毫秒	连续超过3分钟
矢量数据库内存使用情况	< 80%	超过80%
嵌入API错误率	< 1%	5 分钟内超过 1%
搜索命中率（定期测试）	> 85%	环比下降5%以上

总结

运营一个超过10万条的知识库不仅仅是文件上传的扩展，而是整个搜索架构的设计问题。通过系统地设计分区策略、块优化、嵌入管道设计、使用混合搜索+重新排序和矢量数据库扩展，即使在大规模情况下也可以保持稳定的搜索质量。

特别是在日本企业，跨部门的知识整合需要与严格的安全和权限管理并存，分区策略的初步设计决定了整体的成败。建议从PoC阶段就制定划分政策，制定分阶段规模化的计划。

参考资料

修改索引方法和搜索设置：公式ドキュメント
Dify 混合搜索：ハイブリッド検索
Dify RAG 描述：RAG大全

高可用部署架构：生产运营参考设计

随着 Dify 从 PoC 转向生产，高可用性 (HA) 成为一项要求，而不是一种选择。本文系统阐述了企业生产环境所需的高可用部署架构，包括应用层多副本配置、数据库HA、Redis Sentinel、对象存储、矢量DB集群、监控系统、灾难对策等。

整体架构概览

graph TB
    subgraph LB["ロードバランサー層"]
        ALB["ALB / NLB / Nginx Ingress"]
        WAF["WAF"]
    end

    subgraph APP["アプリケーション層（Kubernetes）"]
        API1["API Server<br/>Replica x3"]
        WEB1["Web Server<br/>Replica x2"]
        WORKER1["Worker<br/>Replica x3"]
        SANDBOX1["Sandbox<br/>Replica x2"]
    end

    subgraph DATA["データ層"]
        subgraph PG["PostgreSQL HA"]
            PG_P["Primary"]
            PG_S1["Standby 1"]
            PG_S2["Standby 2"]
        end
        subgraph RD["Redis HA"]
            RD_M["Master"]
            RD_R1["Replica 1"]
            RD_R2["Replica 2"]
            RD_S["Sentinel x3"]
        end
        S3_["S3 / MinIO<br/>（オブジェクトストレージ）"]
        subgraph VDB["ベクトルDB HA"]
            VDB1["Node 1"]
            VDB2["Node 2"]
            VDB3["Node 3"]
        end
    end

    subgraph MON["監視・可観測性"]
        PROM["Prometheus"]
        GRAF["Grafana"]
        ALERT["AlertManager"]
        LOG["Loki / EFK"]
    end

    ALB --> API1
    ALB --> WEB1
    API1 --> PG_P
    API1 --> RD_M
    API1 --> S3_
    API1 --> VDB1
    WORKER1 --> PG_P
    WORKER1 --> RD_M
    WORKER1 --> S3_
    WORKER1 --> VDB1
    PROM --> APP
    PROM --> DATA

修改组件配置和 HA 要求

每个组件的角色和可用性要求

组件	角色	无状态/有状态	建议的副本数量	停电影响
API服务器	REST API 处理、应用程序执行	无国籍	3+	所有 API 停止响应
网络服务器	前端交付	无国籍	2+	用户界面无法访问
工人	异步任务处理（Embedding等）	无国籍	3+	停止后台处理
沙盒	代码执行环境	无国籍	2+	代码节点无法执行
PostgreSQL	元数据、用户和应用程序设置	有状态	主用 + 备用 x2	完整功能下
Redis	会话、缓存、队列	有状态	主 + 副本 x2	响应延迟、任务队列停顿
对象存储	文件和文档存储	有状态	托管推荐	没有文件访问权限
矢量数据库	嵌入索引	有状态	3 节点集群	知识库不可搜索

应用层HA设计

Kubernetes 部署配置

API Server部署设计要点：

副本：3或更多，RollingUpdate策略（maxUnavailable：1，maxSurge：1）
podAntiAffinity：使用 topology.kubernetes.io/zone 作为密钥的 AZ 分布式放置
资源：请求（CPU：1，内存：2Gi）/限制（CPU：2，内存：4Gi）
健康检查：使用readinessProbe（30秒后启动，每10秒一次）、livenessProbe（60秒后启动，每30秒一次）监控/health端点

扩展策略

组件	缩放方法	触发条件	上限指南
API服务器	HPA（CPU/内存）	CPU 超过 70%	10 个复制品
网络服务器	HPA（CPU）	CPU 超过 60%	5 个复制品
工人	HPA（队列长度）	等待任务100+	10 个副本
沙盒	HPA（CPU）	CPU 超过 70%	5 个复制品

Pod 中断预算

在PodDisruptionBudget中设置minAvailable: 2，即使在维护或节点故障期间也能维持最小数量的副本。

数据层HA设计

PostgreSQL 高可用性

PostgreSQL 是存储 Dify 所有元数据的最重要组件。

配置模式	特点	推荐环境
AWS RDS 多可用区	托管、自动故障转移	AWS 环境
极光 PostgreSQL	高可用性、只读副本	大规模 AWS 环境
云 SQL 高可用	区域管理	GCP 环境
帕特罗尼 + PostgreSQL	OSS、Kubernetes 原生	本地/多云

推荐配置（适用于AWS）：

graph LR
    subgraph AZ1["AZ-a"]
        PGP["PostgreSQL Primary<br/>db.r6g.xlarge"]
    end
    subgraph AZ2["AZ-c"]
        PGS["PostgreSQL Standby<br/>db.r6g.xlarge"]
    end
    
    PGP -->|"同期レプリケーション"| PGS
    PGP -->|"自動バックアップ"| S3B["S3<br/>バックアップ"]

设计要点：

自动故障转移 RTO：60-120 秒（对于 RDS 多可用区）
备份保留期限：最短7天，建议35天
时间点恢复：5 分钟间隔
连接池：建议引入PgBouncer（管理API Server连接数）

Redis 高可用性

Redis 用于会话管理、缓存和任务队列 (Celery)。

配置模式	特点	故障转移时间
Redis哨兵	自动故障转移，3+ Sentinel	10-30 秒
Redis集群	分片+副本	10-30 秒
AWS ElastiCache（集群模式）	托管、多可用区	秒 - 30 秒

Redis Sentinel配置示例：

graph TB
    subgraph Sentinels["Sentinel クラスタ"]
        S1["Sentinel 1"]
        S2["Sentinel 2"]
        S3["Sentinel 3"]
    end
    
    subgraph RedisNodes["Redis ノード"]
        RM["Master<br/>r6g.large"]
        RR1["Replica 1<br/>r6g.large"]
        RR2["Replica 2<br/>r6g.large"]
    end
    
    S1 ---|監視| RM
    S2 ---|監視| RM
    S3 ---|監視| RM
    RM -->|レプリケーション| RR1
    RM -->|レプリケーション| RR2

设计要点：

法定人数至少由 3 个哨兵（奇数）组成
最大内存策略：推荐 allkeys-lru
内存大小：活动会话数 x 平均会话大小 + 缓存 + 任务队列

对象存储

配置模式	耐用性	可用性	推荐环境
AWS S3	AWS S3 99.999999999%	99.99%	AWS环境（标配推荐）
地面站	99.999999999%	99.95%+	GCP 环境
Azure Blob 存储	99.999999999%	99.9%+	Azure 环境
MinIO（分布式模式）	依赖配置	依赖配置	本地

托管对象存储本质上具有高可用性，因此您只需要注意应用程序端的连接设置（重试、超时）即可。

矢量数据库高可用性

矢量数据库	高可用性配置	复制	推荐节点数
Weaviate	多节点集群	自动复制	3+
Qdrant	分布式模式	基于 Raft 的共识	3+
Milvus	分布式架构	段复制	3+
pgvector	取决于 PostgreSQL HA	PostgreSQL 复制	与 PostgreSQL 同居

网络层设计

入口/负载均衡器配置

graph TB
    INTERNET["インターネット / 社内ネットワーク"] --> WAF2["WAF<br/>（AWS WAF / ModSecurity）"]
    WAF2 --> ALB2["Application Load Balancer<br/>（Multi-AZ）"]
    ALB2 --> ING["Kubernetes Ingress Controller<br/>（Nginx / ALB Ingress）"]
    
    ING --> SVC_API["Service: dify-api"]
    ING --> SVC_WEB["Service: dify-web"]
    
    SVC_API --> POD_API1["API Pod 1"]
    SVC_API --> POD_API2["API Pod 2"]
    SVC_API --> POD_API3["API Pod 3"]

设计要点：

TLS 终止由 ALB / Ingress Controller 执行
WebSocket 支持（用于流响应）：扩展 Ingress Controller 超时设置
速率限制：在WAF或Ingress级别设置
IP白名单：仅限内网访问（企业标准）

尺码指南

按规模推荐配置

组件	小型（约 50 个用户）	中（50-500 个用户）	大型（500+ 用户）
Kubernetes 工作节点	3 x m6i.大	5 x m6i.x大	8+ x m6i.2x大
API 服务器副本	2	3	5+
工人复制品	2	3	5+
PostgreSQL	db.r6g.large	db.r6g.xlarge	db.r6g.2xlarge
Redis	缓存.r6g.large	缓存.r6g.xlarge	cache.r6g.xlarge（集群）
矢量数据库	3 个 4vCPU/16GB	3 个 8vCPU/32GB	5 个 8vCPU/64GB
对象存储	S3标准	S3标准	S3 标准 + CloudFront

预计每月费用（AWS，东京区域）

组件	小	中等	大
Kubernetes（EKS + EC2）	800 美元	2,500 美元	6,000 美元以上
PostgreSQL (RDS)	300 美元	600 美元	1,200 美元
Redis（ElastiCache）	200 美元	400 美元	800 美元
S3	10 美元	50 美元	200 美元
矢量数据库（EC2）	500 美元	1,200 美元	3,000 美元
ALB+WAF	100 美元	200 美元	400 美元
总计	1,900 美元	$4,950	$11,600+

*不包括LLM API使用费。实际成本将根据使用模式的不同而有很大差异。

监控/可观察性

监控堆栈配置

层	工具	监控
基础设施	普罗米修斯 + Grafana	CPU、内存、磁盘、网络
库伯内特	kube 状态指标	Pod、部署、节点状态
应用	普罗米修斯（自定义指标）	API 延迟、错误率、队列长度
数据库	CloudWatch / pg_stat	查询性能、连接数、复制延迟
日志	Loki / EFK 堆栈	应用日志、错误日志、审核日志
追踪	Jaeger/X 射线	请求追踪、瓶颈识别

重要警报设置

警报名称	状况	严重性	回应
API响应延迟	P95 > 10秒持续5分钟	警告	考虑横向扩展
API 错误率增加	5xx > 1% 持续 3 分钟	关键	立即调查
PostgreSQL 复制延迟	> 30 秒	关键	数据库团队通知
Redis内存使用率	> 85%	警告	内存扩展或缓存TTL回顾
工作队列保留	等待任务> 500	警告	工作人员横向扩展
矢量数据库延迟	P95 > 1 秒	警告	索引优化
Pod CrashLoopBackOff	5分钟内重启3次	关键	检查日志，调查根本原因
磁盘使用情况	> 80%	警告	产能扩张

灾难响应（DR）设计

RPO/RTO 设计指南和 DR 配置模式

根据行业具体的RPO/RTO需求选择容灾配置。金融行业要求RPO<1分钟/RTO<15分钟，并要求热备或更高。在制造业中，RPO/RTO 都在 1 小时内，而对于零售和内部工具，4-24 小时是一般准则。

图案	恢复点目标	RTO	成本	配置
备份与恢复	几个小时	几个小时	低	定期备份→S3→恢复到其他区域
指示灯	几分钟	30分钟-1小时	中等	始终将数据库副本保留在灾难恢复区域
温暖待机	分钟	15 分钟	中高	DR 区域中减少的配置始终可用
主动-主动	零	零	高	两个区域同时运行，基于DNS的路由

备份策略

目标	备份方法	频率	保留期限	储存地点
PostgreSQL	自动快照+WAL	每日+连续	35 天	S3跨区
Redis	RDB 快照	每 6 小时	7 天	S3
对象存储	S3跨区域复制	实时	无限期	异域S3
矢量数据库	快照	每日	14 天	S3
Kubernetes 配置	GitOps（ArgoCD / Flux）	每次提交	Git 历史	Git 存储库

灾难恢复培训

灾害对策仅靠设计是不够的；定期培训至关重要。我们建议您每月执行一次备份恢复测试和混沌工程（Pod/节点故障模拟），每季度执行一次 DB/Redis 故障转移测试，每六个月执行一次灾难恢复区域切换的端到端测试。

部署管道

建议使用基于 GitOps (ArgoCD/Flux) 的部署流程。 Git Push → CI 管道（测试 + 镜像构建）→ 容器注册表 → ArgoCD 差异检测 → 暂存自动部署 → 批准 → 生产在滚动更新流程中，N-1 个副本始终通过设置 maxUnavailable: 1 / maxSurge: 1 来继续处理请求。如果出现问题，可以立即使用kubectl rollout undo进行回滚。

总结

Dify的高可用部署架构并不止于应用层的多重复制。需要对各层进行系统设计，包括PostgreSQL、Redis、对象存储、矢量DB数据层HA、网络层冗余、监控/警报系统、灾难对策等。日本金融机构和制造业要求与现有的灾难恢复标准和审计要求保持一致，因此我们建议您明确您的非功能性需求，并根据您自己的环境调整本文中的参考架构。就成本和风险平衡而言，从中等规模的配置开始生产并随着使用量的增加逐渐扩展是最现实的方法。

参考资料

Dify 企业资源清单：公式ドキュメント
Dify Kubernetes 部署：公式ドキュメント
ACK最佳实践：Alibaba Cloud Blog

AI 应用的安全边界设计：输入过滤、输出审查、工具调用权限控制的完整方案

当前公开资料不足以支撑一篇可靠的、可直接定性为“Dify 专项完整安全边界方案”的正文。

虽然公开网络上可以找到很多关于 AI Agent 治理、输入注入风险、权限控制和输出审查的通用文章，但这些资料大多是通用方法论，无法严谨证明：

Dify 官方当前对输入过滤、输出审查、工具调用权限的完整产品边界
哪些安全控制属于平台原生能力，哪些需要外围系统补齐
企业级部署时推荐的正式安全控制分层
官方对安全审计、权限最小化和工具写权限控制的完整设计取舍

因此，这一题不适合继续硬写成“完整方案稿”，建议先留空，占位等你后续补内部资料、原厂视角或安全方案文档。

建议你后续补充的内容

请优先补以下内容：

输入侧控制
- prompt injection 防护策略
- 文件上传限制与恶意文件处理
- 敏感信息检测与脱敏
输出侧控制
- 高风险回答拦截
- 敏感词 / 合规词审查
- 人类在环审核触发条件
工具调用权限控制
- 哪些工具可读 / 可写
- 谁能配置工具
- 哪些写操作必须人工确认
审计与治理
- 调用日志保留范围
- 责任追踪方式
- 安全事件升级流程

公开资料线索

当前结论

通用 AI 安全治理公开资料很多，但不足以形成 Dify 专项“完整安全边界方案”。
这一题建议等你补内部安全规范、原厂说明或企业级部署经验后再写。

企业AI实施路线图模板：阶段0（PoC）→阶段1（试点）→阶段2（规模）→阶段3（优化）

决定人工智能实施成败的不是模型的准确性，而是“在组织中实施何时以及实施哪些能力”的路线图设计。

简介：为什么需要路线图

从2024年到2026年，日本企业对生成式人工智能的引入正在迅速扩大。然而，经济产业省的研究和各咨询公司的报告一再表明，概念验证（PoC）尚未达到全面生产的情况仍然很多。这就是所谓的“PoC死亡”。

问题的本质在于缺乏组织准备，而不是技术挑战。人工智能的实施不仅仅是一个工具的引入，而是一个逐步发展业务流程、治理结构、人力资源技能和数据基础设施的计划。为此需要一个定义每个阶段的里程碑和 KPI 的路线图。

本文根据日本企业的组织结构、决策流程和预算周期提出了一个四步路线图模板。该框架本身被设计为独立于平台，尽管它主要用于 Dify 等低代码 AI 平台。

大图：4 相配置

graph LR
    P0["Phase 0<br/>PoC<br/>1-2ヶ月"] --> P1["Phase 1<br/>パイロット<br/>3-6ヶ月"]
    P1 --> P2["Phase 2<br/>スケール<br/>6-12ヶ月"]
    P2 --> P3["Phase 3<br/>最適化<br/>継続的"]
    
    style P0 fill:#e8f4fd,stroke:#1976d2
    style P1 fill:#e8f5e9,stroke:#388e3c
    style P2 fill:#fff3e0,stroke:#f57c00
    style P3 fill:#fce4ec,stroke:#c62828

阶段	预计时间段	目标	主要交付成果
阶段 0	1-2个月	技术可行性验证	PoC报告、技术选型政策
第一阶段	3-6个月	商业价值展示、运营知识积累	试点评估报告、操作规则v1
第二阶段	6-12 个月	部署到多个部门和基础设施开发	平台运营基础设施、治理结构
第三阶段	连续	持续改进和内部生产	CoE体系的建立和改进周期

第 0 阶段：PoC（概念验证）— 1-2 个月

目的

验证技术上是否可以以最低的成本实现。制定业务案例假设并建立证据以获得管理层的批准。

实施细节

项目	详情
用例选择	根据业务影响 x 可行性矩阵选择 1-2 个案例
技术验证	LLM精度评估、Dify工作流程原型构建
数据准备	目标作业样本数据收集、质量初步评估
成本估算	大概的 API 成本、基础设施成本和人员成本
风险评估	个人信息保护法兼容性及幻觉风险的初步评估

里程碑和关键绩效指标

里程碑	关键绩效指标	标准值
完成原型	构建一个工作演示	验证目标用例中的操作
精度评估完成	答案准确率（手动评估）	第一阶段过渡决策达到 70% 或更高
成本估算完成	每月运行成本估算	在管理层能够批准的范围内
提交PoC报告	向管理层报告和批准	实施通过/不通过决定

清单

确保赞助商（军官级）
PoC团队的构成（2-3人）
目标业务部门合作协议
LLM提供商的选择（OpenAI / Anthropic / Azure OpenAI /国内LLM）
与安全部门初步协商（是否可以对外发送数据）
根据个人信息保护法初步实施影响评估

第 1 阶段：试点 — 3-6 个月

目的

在实际商业环境中运行人工智能并定量展示商业价值。同时，确定运营问题并制定规模所需的系统和规则。

实施细节

项目	详情
试点部门遴选	1-2个变革愿望高的部门（20-50人）
生产环境建设	Dify生产环境搭建、SSO配合
运营规则制定	使用指南、提示管理规定、升级流程
教育培训	试点用户实践培训（约2个半天）
效果测量	基线获取→实施后定量/定性评估

组织架构（试点）

graph TD
    SP["スポンサー<br/>（CxO / 事業部長）"] --> PM["プロジェクトマネージャー"]
    PM --> TECH["技術リード<br/>（AI/IT部門）"]
    PM --> BIZ["業務リード<br/>（パイロット部門）"]
    PM --> GOV["ガバナンス担当<br/>（法務/コンプライアンス）"]
    TECH --> DEV["開発チーム<br/>2-3名"]
    BIZ --> USER["パイロットユーザー<br/>20-50名"]

制定操作规则要点

1.使用指南

日本企业尤其需要明确以下几点：

可以输入的数据范围（个人信息和机密信息的处理）
人工智能输出的强制人工审查范围
可以和不能使用AI的任务分类
向公司外部提供输出结果的规则（需要披露是由AI生成的）

2.及时管理

在 Dify 上集中管理部门范围的提示模板
版本控制和变更历史记录
组织内高效提示共享机制

3.事件响应

出现幻觉时升级流程
处理意外输出个人信息的程序
服务失败时的业务连续性计划（BCP）

里程碑和关键绩效指标

里程碑	关键绩效指标	标准值
试点开始	环境搭建完成，培训实施	按计划开始
基线的获取	引进前经营指标记录	量化目标业务的处理时间和质量
中期评估（截至 2 个月）	使用率 (WAU)	超过60%的试点用户
效率提升	目标操作的处理时间减少率	减少30%以上
品质提升	错误率/返工率	改善 20% 或更多
用户满意度	NPS 或调查分数	70%+ 正面评价
最终评估报告	向管理层提出的第二阶段过渡建议	投资回报率的量化呈现

日本企业的具体考虑因素

与审批流程保持一致：提前检查第二阶段过渡审批所需审批流程的格式和审批流程
年度预算周期：大多数日本公司的年度预算从四月开始。为了确保第二阶段的预算，最迟在12月底之前向管理层报告试点结果。
与工会协商：如果人工智能业务转型影响就业，可能需要劳资协商。
回应 AI 事業者ガイドライン：根据経済産業省 / 総務省共同发布的「AI 事業者ガイドライン（第 1.0 版）」（2024 年 4 月公表）进行风险评估。参考链接：METI AI 事業者ガイドライン

第 2 阶段：规模化 — 6-12 个月

目的

将试点中验证的价值横向部署到多个部门和多个用例。同时，建立组织治理架构和AI平台基础。

实施细节

项目	详情
横向部署方案	基于部门优先级矩阵的部署计划
平台基础设施	多租户支持、API 网关、监控基础设施
知识管理	RAG知识库集成管理及更新操作流程
权限/访问管理	部门权限设计、数据分离、审计日志
治理结构	成立AI推进委员会并制定全公司使用规则
人力资源开发	全公司开展AI素养培训，培训部门AI推广人员

平台架构（Dify 使用示例）

graph TB
    subgraph "ユーザーレイヤー"
        U1["営業部門"]
        U2["人事部門"]
        U3["法務部門"]
        U4["カスタマーサポート"]
    end
    
    subgraph "アプリケーションレイヤー（Dify）"
        A1["営業提案書生成"]
        A2["採用FAQ Bot"]
        A3["契約書レビュー"]
        A4["問い合わせ自動応答"]
    end
    
    subgraph "共通基盤レイヤー"
        GW["API ゲートウェイ"]
        KB["ナレッジベース管理"]
        MON["監視・ログ基盤"]
        AUTH["認証・認可（SSO）"]
    end
    
    subgraph "LLM レイヤー"
        L1["GPT-4o"]
        L2["Claude"]
        L3["国産 LLM"]
    end
    
    U1 --> A1
    U2 --> A2
    U3 --> A3
    U4 --> A4
    A1 & A2 & A3 & A4 --> GW
    GW --> KB
    GW --> MON
    GW --> AUTH
    GW --> L1 & L2 & L3

构建治理体系

成立人工智能推进委员会（AI CoE：卓越中心）

角色	职责	职责
委员会主席	首席技术官/首席数据官	全公司AI战略决策
技术主管	AI/IT 部门经理	平台运营、技术标准制定
风险管理	法律/合规部门	法规遵从、使用法规管理
数据管理	数据治理	数据质量管理、隐私保护
业务推广	负责各部门AI推广	发现用例，在部门内推广
人力资源开发	人力资源与培训部	AI素养培训、技能测评

公司范围内的法规待制定：

AI使用政策——全公司通用的使用规则和禁令
数据处理规定——可输入人工智能的数据的分类和限制
质量控制标准 — AI输出审核流程和质量标准
事件响应程序 — 人工智能相关事件的报告和响应流程
供应商管理标准 — LLM 供应商选择和评估标准

知识库管理的最佳实践

规模化阶段最大的挑战是保持 RAG 知识库的质量。

管理项目	操作规则
更新频率	季度库存+按需更新
质量标准	进行过时检查和准确性审查
访问控制	按部门划分知识，保密级别设置
元数据	创建日期、更新日期、负责人以及保密级别分配
删除规则	超过一年未更新的文档自动提醒

里程碑和关键绩效指标

里程碑	关键绩效指标	标准值
部署的部门数量	使用人工智能的部门数量	占整个公司 50% 或以上
用户数量	MAU（每月活跃用户）	40%以上的目标用户
用例数量	生产申请数量	10 个或更多
成本效益	每个用例的开发时间	与试点相比减少 50%
治理成熟度	全公司规章制定率	全部 5 项已完成
投资回报率	投资回报率	每年节省的成本超过投资

第三阶段：优化和自主运营——持续

目的

将人工智能的使用作为组织 DNA 的一部分，并运行持续改进周期，同时最大限度地减少外部依赖。

实施细节

项目	详情
促进内部生产	培养内部人工智能工程师并组织快速的工程能力
持续改进	基于使用数据分析的应用改进，自主发现新用例
应对技术演进	新车型、新功能的评估和引进决策流程
成本优化	LLM成本持续优化（模型选择、缓存、微调）
构建生态系统	与外部合作伙伴协作并分享行业内最佳实践

持续改进循环

graph LR
    M["計測<br/>Measure"] --> A["分析<br/>Analyze"]
    A --> I["改善<br/>Improve"]
    I --> D["展開<br/>Deploy"]
    D --> M
    
    style M fill:#e3f2fd
    style A fill:#f3e5f5
    style I fill:#e8f5e9
    style D fill:#fff8e1

具体改进措施：

分析应用使用率低的原因并进行改进或废除
根据用户反馈及时优化
新LLM模型的基准评估（每季度）
审查成本结构（减少不必要的 API 调用、缓存的使用）
保持知识库的新鲜度并提高质量

日本企业实用指南

与预算周期的联系

许多日本公司使用 4 月至 3 月的会计年度。使路线图与预算周期保持一致对于平滑审批流程至关重要。

时间	行动
四月至六月（第一季度）	第 0 阶段实施，PoC 预算（1-300 万日元）由部门自行决定
七月至九月（第二季度）	第一阶段开始，第二阶段费用包含在明年的预算请求中
十月至十二月（第三季度）	第一阶段中期评估，提交明年预算批准
一月至三月（第四季度）	一期最终评估、二期详细规划制定
下一财年四月 -	第二阶段开始（正式确定为年度预算）

批准文件中包含的要素

为获得管理层批准，批准文件应包括以下内容：

商业案例：定量效果预测（处理时间减少XX%，成本减少XX万日元）
风险评估：安全、合规、运营风险及对策
投资计划：3年展望初始成本+运行成本
系统规划：所需人员和角色、利用外部合作伙伴的政策
退出标准：明确阶段过渡的通过/不通过标准

监管合规清单

法规/指南	措施	响应阶段
个人信息保护法	使用目的的明确、向第三方提供的限制、安全管理措施	阶段 0
AI 操作员指南	风险评估、透明度和人力监控	第一阶段
著作权法（人工智能相关修订动态）	学习数据的权利处理、生成产品的版权安排	第一阶段
行业特定法规	金融（FISC）、医疗（厚生劳动省GL）等	1-2 阶段
欧盟人工智能法案（海外扩张时）	根据风险分类应对、域外适用确认	第二阶段

总结：使用路线图的 3 个原则

1.一步步培养你的能力

引入AI不是“引入工具”，而是“构建组织能力”。在每个阶段均衡地构建技术、人力资源和治理能力，才是防止PoC死亡的最佳途径。

2.明确定义通过/不通过

提前定义每个阶段的过渡标准，并根据定量的 KPI 而不是直观的判断来做出决策。退出标准也应明确。

3.让日本公司的决策周期成为您的朋友

年度预算/审批过程不被视为一种约束，而是一种逐步引入的节奏。通过上半年执行0-1阶段并在下半年确保明年的预算，您可以稳步扩大业务规模。

该模板是一个通用框架，假设引入 Dify 等低代码 AI 平台。应根据您组织的规模、行业特征和现有 IT 基础设施对其进行定制。

AI投资回报率（ROI）评估框架：从成本结构可视化到投资回收期计算

AI ROI评估的目的是定量显示“业务改善了多少”，而不是“是否引入了”。

简介：为什么AI ROI评估很难

日本企业的高层在考虑引入生成式人工智能时最大的担忧是“如何向管理层解释投资回报”。与传统IT投资不同，人工智能投资具有以下特点：

有效性是渐进的：人工智能引入后并不会立即展现出100%的有效性，而是随着学习数据的积累和用户的熟练程度而逐渐提高其有效性。
可变成本：即用即付 API 成本与使用量成正比，因此很难将其作为固定成本进行预算。
效果归因不明确：很难区分人工智能支持的业务改进有多少是由于人工智能的效果，有多少是由于其他因素。
高定性效果：很多效果很难量化，比如提高员工满意度、组织知识、加快决策速度等。

本文考虑到这些问题，提出了一个与日本企业的预算周期和审批文化相兼容的实用投资回报率评估框架。

框架总体结构

graph TB
    subgraph "コスト（投資）"
        C1["インフラコスト"]
        C2["モデル API コスト"]
        C3["人件費"]
        C4["間接コスト"]
    end
    
    subgraph "ベネフィット（効果）"
        B1["時間削減効果"]
        B2["コスト削減効果"]
        B3["品質向上効果"]
        B4["売上貢献効果"]
    end
    
    subgraph "評価指標"
        R1["ROI（投資利益率）"]
        R2["回収期間"]
        R3["NPV（正味現在価値）"]
    end
    
    C1 & C2 & C3 & C4 --> R1
    B1 & B2 & B3 & B4 --> R1
    R1 --> R2
    R1 --> R3

第 1 章：可视化成本结构

引入AI的成本不仅仅是API使用费。为了准确计算投资回报率，必须了解整体情况，包括隐藏成本。

1.1 成本类别列表

类别	项目	费用表	大致范围（每年）
基础设施	云基础设施（Dify 托管）	固定+可变	1.2-600万日元
	矢量数据库（用于 RAG）	固定	600,000 至 2,400,000 日元
	网络安全	固定	600,000-1,800,000日元
模型 API	LLM API使用费（GPT-4o、Claude等）	变化	1.2-1200万日元
	嵌入 API	变化	120,000-600,000日元
人员成本	AI工程师（全职/兼职）	固定	6-1500万日元/人
	项目经理	固定	4-800万日元（按工时计算）
	业务部门合作工时	固定	100万至300万日元（按比例工时）
间接成本	培训/教育费用	临时+固定	500,000-2,000,000日元
	咨询/外部支持	临时	3-2000万日元
	运行维护	固定	基础设施成本的 15-20%
	治理体系运行	固定	100万～300万日元

1.2 如何估算API成本

API 成本是可变成本，准确的估算需要使用情况预测。使用下面的模板进行计算。

API成本估算模板：

月間 API コスト = Σ（ユースケースごとのコスト）

ユースケースごとのコスト計算：
  = 月間リクエスト数
    × 平均入力トークン数 × 入力単価
    + 月間リクエスト数
    × 平均出力トークン数 × 出力単価

估算示例：内部常见问题解答机器人（RAG 基础）

参数	价值
每月请求数量	3,000次（100人×1.5次/天×20个工作日）
平均输入标记（提示+上下文）	2,000 个代币
平均输出代币	500 代币
型号	GPT-4o（输入：2.50 美元/100 万代币，输出：10.00 美元/100 万代币）
每月费用	15.0 美元 + 15.0 美元 = 约 30 美元（约 4,500 日元）

注意：以上仅是 API 成本。实际上，加上基础设施成本和人员成本，总成本通常是 API 成本的 10-50 倍。

1.3 成本的时间序列变化

人工智能实施成本因阶段而异。虽然初始投资很大，但每个用例的成本随着规模的扩大而降低。

相	主要成本结构	预计月费
阶段 0（PoC）	人员成本（验证工时）、API成本小	50万至150万日元
第一阶段（试点）	环境搭建、培训、API费用、外部支持	1.5-400万日元
第 2 阶段（规模）	平台基础设施、人员成本扩张、API成本增加	4-1000万日元
第 3 阶段（优化）	专注运维，API成本优化	2-600万日元

第 2 章：量化收益

2.1 效果的四类

人工智能实施效果分为以下四类，每一类采用不同的量化方法。

	易于量化	难以量化
高影响力	减少人工成本和处理时间	增加销售额并加快决策速度
影响	降低错误率	客户满意，知识积累

2.2 时间缩短效果

最容易量化、向管理层解释能力最强的指标。

计算公式：

年間時間削減効果（金額）
  = 対象業務の月間処理件数
    × 1件あたりの時間短縮（分）
    × 12ヶ月
    × 時間単価（円/分）

量化模板：

使用案例	每月处理的案件数量	节省时间/案例	每年节省的时间	货币换算（时薪3,500日元）
内部常见问题解答	500 件	15 分钟	1,500 小时	525万日元
分钟创作	100 件	30 分钟	600 小时	210万日元
提案草案	50 件	60 分钟	600 小时	210万日元
合同审查	200 件	20 分钟	800 小时	280万日元
总计			3,500 小时	1225万日元

重要：减少工作时间与“减少员工人数”不同。在日本企业，节省下来的时间应该被解释为“重新分配给更高附加值的任务”。这一点是《林吉修》中讨论的特别重要的一点。

2.3 成本降低效果

计算直接节省的成本。

减价项目	计算方法	计算示例
降低外包成本	减少件数×单价	翻译外包：每月20件×3万日元=每年720万日元
加班费减免	减少时间×加班单价	每月 100 小时 × 3,000 日元 = 每年 360 万日元
降低纸张和印刷成本	通过无纸化减少	每年 500-100,000 日元
工具集成	废除/整合现有工具	每年100万至300万日元

2.4 质量提升效果

质量的提高间接导致成本降低和销售贡献。

量化思路：

质量指标	测量方法	货币兑换逻辑
错误率降低	引入前后错误数对比	每个错误的返工成本 x 减少数量
提高初始解析率	客户支持FCR比较	每次升级的成本 × 减少的次数
响应质量均等化	质量分数标准差比较	投诉率降低，避免损失金额
达标率	漏检次数对比	每次违规的风险成本×减少次数

2.5 销售贡献效应

虽然它最难量化，但对管理的吸引力最大。仔细分析因果关系是必要的。

效果项目	计算方法
潜在客户获取量增加	AI聊天机器人询问量增加×CVR×平均订单单价
提高提案速度	通过缩短提案交付周期提高订单率 × 项目数量 × 平均单价
提高客户满意度	预计为 NPS 改善 → 客户流失率降低 → LTV 改善
新业务创造	利用人工智能销售新服务（中长期评估）

第 3 章：投资回报率计算和投资回收期

3.1 基本ROI计算公式

ROI（%） = （年間ベネフィット合計 - 年間コスト合計）÷ 年間コスト合計 × 100

回収期間（月） = 初期投資額 ÷ 月間ネットベネフィット

3.2 计算模拟

案例研究：拥有 500 名员工的制造公司

我们假设 Dify 将用于实现以下四个用例。

成本（3年）：

项目	第一年	第二年	第三年
基础设施成本	360万日元	360万日元	360万日元
API成本	180万日元	360万日元	480万日元
人员成本（2名AI团队成员）	1800万日元	1800万日元	1800万日元
外部咨询	800万日元	200万日元	00,000 日元
培训费用	200万日元	100万日元	50万日元
运行维护	100万日元	200万日元	200万日元
年度总计	3440万日元	3020万日元	2890万日元

福利（3年）：

效果项目	第一年	第二年	第三年
时间缩短效果	500万日元	1200万日元	1800万日元
降低外包成本	200万日元	500万日元	720万日元
误差减少效果	100万日元	300万日元	500万日元
销售贡献（间接）	0,000 日元	3,000,000日元	8,000,000日元
年度总计	800万日元	2300万日元	3820万日元

投资回报率趋势：

年度	成本	效益	年度投资回报率	累计投资回报率
第一年	3440万日元	800万日元	-76.7%	-76.7%
第二年	3020万日元	2300万日元	-23.8%	-41.1%
第三年	2890万日元	3820万日元	+32.2%	-4.6%
3 年总计	9350万日元	6920万日元		-26.0%

在此情况下，第三年实现单年盈利，预计累计投资回报约为3.5年**。

3.3 敏感性分析

投资回报率根据先决条件的不同而有很大差异。在向管理层报告时，应呈现三种情景：乐观、标准和悲观。

场景	假设	3 年累计投资回报率	投资回收期
乐观	使用率80%，效果最大	+15%	2.5 年
标准	使用率50%，效果中等	-26%	3.5 年
悲观	使用率30%，效果有限	-55%	超过 5 年

影响投资回报率的关键变量：

使用率（采用）：最大的影响因素。如果利用率低的话，就没有效果。
用例数量：扩展时添加用例的速度
API成本波动：考虑到LLM价格的下降趋势
人员成本：内部生产与外包之间的平衡

第 4 章：基线设置和测量过程

4.1 基线采集的重要性

为了准确计算投资回报率，在引入人工智能之前获得基线至关重要。 “不知怎的，事情已经好转了”将不会通过批准请求。

4.2 基线采集模板

测量项目	测量方法	测量周期	录音格式
业务处理时间	时间戳记录或采样	介绍前1个月	平均值、中值、P95
错误率	质量检查记录	介绍前3个月	每月错误数/已处理案件总数
外包费用	会计数据	过去 12 个月	每月金额趋势
客户满意度	调查/NPS	实施前的最新值	分数和回复数量
员工工作时间	考勤数据	过去 6 个月	加班时间趋势

第 5 章：与日本公司的预算周期保持一致

5.1 预算保障策略

以下是针对日本企业预算周期量身定制的ROI解释策略。

时间	预算活动	投资回报率说明点
四月至六月	财年初期，部门预算执行	PoC 从小规模开始，部门可自由支配预算
七月至九月	上半年业绩中期确认	根据中期试点结果准备明年的预算申请
十月至十一月	请求明年的预算	提交包含定量投资回报率估算的提案
十二月至一月	预算评估与调整	提出敏感性分析的三种情景并解释风险对冲措施
二月至三月	明年预算敲定	二期预算正式确定

5.2 管理层强调的要点

日本企业高管在做出人工智能投资决策时往往强调的几点：

要点	对应ROI解释
最大限度降低风险	通过分阶段投资限制风险
竞争对手动向	同行业其他公司AI实施实例及效果图展示
对员工的影响	解释为“转向增值工作”而非“减少工作”
安全	澄清数据处理政策和安全管理措施
遵守法律法规	与个人信息保护法和人工智能商业准则的兼容性
可持续发展	呈现持续改进周期而非暂时效果

第6章：ROI评估的陷阱和对策

6.1 常见的高估

高估模式	对策
将 PoC 的积极结果推断为全公司部署的效果	缩放时利用率降低的因素（通常为 50-60%）
计算方式：时间减少=人员减少	具体定义创建的时间将在何处重新分配
仅使用 API 成本计算成本	基于TCO进行评估，包括人员成本和间接成本
使用最新最便宜的API单价计算	由于使用量增加预计成本会增加

6.2 常见的低估

低估模式	对策
完全忽略质量影响	使用代理指标量化质量改进和满意度改进
未计的知识积累效应	通过构建组织知识来预期长期生产力的提高
学习曲线效应未体现	从第二年开始，效果不断增加被纳入模型中
不考虑连锁反应（部署到其他部门）	反映出规模带来的边际成本递减

总结：ROI 评估的 5 个原则

1.没有基线就没有投资回报率

实施前业务指标的定量记录是所有投资回报率评估的起点。

2.根据 TCO（总拥有成本）进行评估

全局决策，不仅包括API成本，还包括人员成本、间接成本和机会成本。

3.保守地估计影响并切合实际地估计成本

不仅要呈现乐观场景，还要呈现三种场景：标准场景和悲观场景，以赢得管理层的信任。

4.定量和定性地解释

不仅要适当地表述可量化的效果，还要表述定性的效果，例如提高组织能力和降低风险。

5.适应日本企业的决策文化

考虑到年度预算周期、审批流程和建立共识文化的投资回报率沟通设计将决定最终的投资批准。

该框架被设计为通用人工智能投资回报率评估框架。请根据Dify等特定平台的成本结构定制参数，并应用于您自己的评估。

企业 AI 委员会设置建议：谁负责 AI 战略、谁负责技术、谁负责合规的职责划分

企业 AI 项目最怕“大家都参与，但没人真正负责”。因此，建立跨职能治理机制非常重要。

这篇内容可以保留，因为公开资料已经足够支撑一个“公开版治理角色建议稿”。围绕 AI governance、企业实施指南、CAIO 讨论和跨职能治理的日文文章，已经足够说明：AI 在企业内部不会只是技术部门的事，至少需要战略、技术、合规与业务四类角色共同参与。

一、从公开资料能确认的治理前提

1. AI 治理天然是跨职能议题

公开治理文章已经明确指出，AI 导入不仅涉及系统与模型，还涉及风险、制度、合规、组织责任与业务优先级，因此不可能只靠单一部门推动。

2. “委员会”本质上是职责协调机制

无论叫委员会、治理小组还是 steering committee，公开资料共同指向的是：必须有一个横跨业务、技术与合规的协调结构。

3. 角色清晰比组织名称更重要

公开资料虽然不一定都用同样命名，但普遍都能抽象出几类核心角色：战略负责人、技术负责人、合规负责人、业务负责人。

二、战略负责人

通常由业务高层或数字化负责人承担，负责方向与资源。

三、技术负责人

负责平台选型、架构、安全与实施路线。

四、合规负责人

负责数据治理、法规审查、风险边界与审计要求。

五、业务负责人

负责场景优先级、效果评估与组织推广。

六、结语

AI 委员会的本质不是多开会，而是把战略、技术、合规和业务四条线真正拉到一起。

公开资料线索

note.com

事業を加速させるための攻守の要。マネーフォワード法務が向き合うAIガバナンス | https://note.com/mf_cloud/n/n97be34e82405

zenn.dev / 官方文档 / 其他公开页面

経産省AIガバナンスガイドラインを実装する企業向けチェック … | https://zenn.dev/gogoduck/articles/20260324-fn1zpn
AIガバナンス 2026年度版 – 最先端研究・制度・実務の到達点 … | https://zenn.dev/ghostdrift/articles/441639ae68f948
CAIOってなんだ？ - 「なりたい」の前に「何か」を整理した | https://zenn.dev/you_dev_zenn/articles/caio-00-what-is-caio-2026

这篇当前能从公开资料确认的有效信息

企业 AI 治理天然需要跨职能结构
战略、技术、合规与业务四类角色是公开资料可支撑的基本抽象
这篇可保留为公开资料版治理角色建议稿

数据治理与 AI 合规：日本个人信息保护法（改正個人情報保護法）对 AI 应用的约束点

AI 应用一旦接触个人信息，就会落入数据治理与合规讨论范围。在日本语境下，改正個人情報保護法是一个必须被考虑的框架。

这篇内容可以保留，但应明确它属于“公开资料版合规提醒稿”，而不是正式法务意见书。原因是公开资料已经足够支撑几个关键判断：个人信息、第三方提供、跨境处理、日志与知识库数据流，都应纳入 AI 合规边界；但如果要写到法条适用细节、正式合规结论和法律意见层，仍需要更强的法务资料或内部审阅。

一、从公开资料能确认的合规前提

1. 日本语境下，AI 合规首先是数据流问题

公开法律与治理文章已经反复强调，真正该先问的不是“这条法怎么背”，而是：数据从哪里来、到哪里去、是否出域、是否进入第三方模型或服务。

2. 个人信息保护法会直接影响知识库与日志设计

只要企业把真实文档、用户提问、客服记录、内部制度、审批内容送进知识库或模型调用链，就会出现个人信息、用途限制、第三方提供和委托处理等问题。

3. 公开资料足以支撑原则，但不足以替代正式法律意见

这一点需要写清楚：当前公开资料足够支撑产品治理层的建议，但如果要形成正式法务咨询稿，还需要更严谨的法条引用和法律审阅。

二、企业最该先关注的不是法条背诵，而是数据流

收集了什么个人信息
用于什么目的
是否超出原始使用目的
是否向第三方提供
是否跨境处理

三、对 AI 应用的直接影响

知识库是否混入个人信息
日志中是否保留敏感问答
模型调用时数据是否出域
工具调用是否访问到超权限数据

四、建议动作

先做数据分级
再做场景分级
高敏感场景优先 on-premise 或更强控制路径
建立日志保留与脱敏规则

五、需要你后续补充的部分

如果你希望这篇更像法务咨询稿，后续建议补充日本法条引用、第三方提供、匿名加工信息、委托处理等更正式的章节。当前版本先保留为产品治理视角草稿。

公开资料线索

note.com

個人情報保護法の3年ごとの見直しは「クラウド例外」議論に決着をもたらすか | https://note.com/shin_fukuoka/n/n73aded964b63
【Google Cloud / Google Workspaceは医療AIとして実戦投入できるのか？】 3省2ガイドライン・個人情報保護法から読み解く「3つの利用シナリオ」のリアル | https://note.com/nice_wren7963/n/n323e2d757a50

zenn.dev / 官方文档 / 其他公开页面

生成AIの法規制と個人情報保護2026：日本AI新法・EU AI Act … | https://zenn.dev/0h_n0/articles/dae805248604f5
生成AI時代の個人データ保護専門用語50と法的フレーム … | https://zenn.dev/0h_n0/articles/f1b476ba139174
外部サービスの利用ガイドラインを作ってわかった、エンジニア … | https://zenn.dev/knowledgework/articles/19e7bfba76582f

这篇当前能从公开资料确认的有效信息

AI 合规在日本语境下首先应从数据流和个人信息处理边界入手
知识库、日志、模型调用和外部工具都会触发合规讨论
这篇可保留为公开资料版合规提醒稿，但不能替代正式法务意见

组织能力建设路径：内部 AI 人才培养计划 vs 依赖合作伙伴的边界与过渡策略

企业 AI 落地到一定阶段后，核心问题会从“能不能做”转向“谁来持续做”。

这篇内容可以保留，因为公开资料已经足够支撑一个“公开版组织能力建设稿”。无论是中小企业导入 AI、组织共创、人才战略还是伙伴协同的公开讨论，都在反复指向同一个问题：企业最终必须从“外部带着做”过渡到“内部能持续做”。

平台部署
首批场景建设
交付方法论导入

三、内部团队应逐步接手的能力

提示词与知识库维护
应用运营
数据与反馈分析
新场景复制

四、过渡策略

建议采用“三阶段接手”方式：

合作伙伴主导，内部旁听
合作伙伴共建，内部开始维护部分场景
内部主导，合作伙伴转支持与专项咨询

AGO MARKETING 吾郷潤｜大企業を飛び出し、地方の中小製造業を生成AIで救う！「現場入り込み型」AIコンサルの全貌 | https://note.com/miraikyoso/n/n792f48940198

zenn.dev / 官方文档 / 其他公开页面

AI時代の人材戦略:生産性を40%向上させる組織づくりの完全 … | https://zenn.dev/headwaters/articles/545fe94fb1a095
AI導入の鍵は「共創」にあり──大企業500社に聞いたAI … | https://zenn.dev/headwaters/articles/fe9801943b59cc

这篇当前能从公开资料确认的有效信息

早期依赖合作伙伴推进 AI 导入是公开资料可支撑的正常路径
企业要真正进入自主运营，必须逐步把能力从外部转移到内部
这篇可保留为公开资料版组织能力建设稿

内容进度总览

总文章数

L1 完稿

L2 文章数

L3 文章数

L4 文章数

📅 最后更新：2026-05-03（by @Mini）

状态说明：完稿内容完整可发布 · 初稿有框架和内容但需补充 · 审核中等待 review · 待写仅有标题

第1层 · 公开渠道 Public

#	标题	状态	行数
1-1 Dify 产品认知类
1	Dify 是什么	完稿	94
2	Dify Cloud vs Enterprise	完稿	112
3	Dify 支持哪些 LLM	完稿	119
4	Dify 核心概念	完稿	162
5	Dify Workflow vs n8n/Zapier	完稿	163
1-2 场景案例类
6	企业内部 FAQ 机器人	完稿	252
7	合同审查助手	完稿	273
8	Workflow 自动化日报生成	完稿	294
9	Agent 调用外部工具 — 天气查询	完稿	255
10	日本企业常见 AI 需求场景盘点	完稿	227
1-3 技术观察类
11	MCP 是什么	完稿	205
12	RAG 的核心问题	完稿	261
13	提示词工程的误区	完稿	230
14	AI Agent 的局限性	完稿	263
15	on-premise 部署 AI 应用的必要性	完稿	237

第2层 · Dify协会 Members Only

#	标题	状态	行数	备注
2-1 深度 Use Case
16	制造业设备故障排查机器人	审核中	308
17	法务合同比对 Workflow	审核中	327
18	社内稟議自动草稿生成	审核中	336
19	多语言客服 Agent	审核中	343
20	HR 入职文件处理流水线	审核中	323
21	[LangGenius 社内事例] IDE 里自助查生产数据：Ops Smart Assistant	待写	81	LangGenius 内部 case
2-2 踩坑记录与解法
22	知识库检索结果不相关	审核中	273
23	Workflow 节点超时频繁	审核中	297
24	同一问题每次回答不一致	审核中	320
25	大文件上传失败	审核中	325
26	Agent 工具调用陷入死循环	审核中	327
2-3 Dify Enterprise 部署最佳实践
27	生产环境 vs 测试环境	审核中	328
28	Helm Chart values 关键参数	审核中	314
29	多租户权限设计	审核中	325
30	License 管理实务	审核中	329
31	升级版本注意事项	审核中	325

第3层 · 合作伙伴培训 Partners

#	标题	状态	行数	备注
3-1 部署技术培训
32	Docker Compose 部署全流程	审核中	545
33	Helm Chart 部署全流程	审核中	707
34	License 激活与验证	待写	59	需内部补数据
35	基础运维操作手册	待写	58	需内部补错误码表
36	SSO 集成配置	待写	54	需内部补 IdP 映射
3-2 App 搭建培训
37	知识库三种构建方式	审核中	334
38	提示词设计规范	审核中	378
39	Workflow 节点类型与组合模式	审核中	444
40	Agent 工具定义规范	审核中	447
41	API 集成对接指南	审核中	692
3-3 交付检查清单
42	部署验收标准	待写	56
43	基础功能验证项目	待写	55	需内部补测试用例
44	客户移交文档模板	待写	41	需大量内部补充
45	常见客户问题 QA 库	待写	34	需内部交付团队输入
46	升级与续费提醒机制	待写	40	需内部流程文档

第4层 · 原厂技术支持 Premium

#	标题	状态	行数
4-1 产品设计理念
47	为什么 Dify 选择 on-premise	审核中	315
48	Provider 抽象层设计	审核中	416
49	Knowledge Base 检索架构	审核中	397
50	Workflow 节点设计哲学	审核中	426
51	Dify 多租户模型	待写	45
4-2 架构建议
52	企业 AI 应用分层架构	初稿	222
53	模型选型建议框架	审核中	274
54	知识库规模化设计	审核中	275
55	高可用部署架构	审核中	303
56	AI 应用安全边界设计	待写	42
4-3 AI 治理咨询
57	企业 AI 落地路线图模板	审核中	338
58	AI 投资回报评估框架	审核中	340
59	企业 AI 委员会设置建议	待写	52
60	数据治理与 AI 合规	待写	59
61	组织能力建设路径	待写	56

Dify 主题定向筛选（基于前100篇）

说明：按你的5个主题做定向筛选；优先高赞，同时保留长尾高相关（点赞<20）。

1-1 Dify 产品认知类

Likes	Long-tail	Title	URL
7	是	【ノーコードでAIアプリが作れる】Difyとは何か？特徴・できること・料金まで徹底解説	https://note.com/super_phlox114/n/nba7104ad1f71
7	是	プログラミングなしでAIエージェントを作れる。GitHubスター13万の「Dify」がすごい	https://note.com/a_utomation/n/n708fc4391b59
26	否	Difyで話題の「16タイプ診断」を作ってみた！チャットフローで作るコンサルBotのすすめ	https://note.com/weel_media/n/nd8fe23b955d8

Cloud vs Enterprise / 部署模式

Likes	Long-tail	Title	URL
7	是	【ノーコードでAIアプリが作れる】Difyとは何か？特徴・できること・料金まで徹底解説	https://note.com/super_phlox114/n/nba7104ad1f71
16	是	【2026年最新】企業におけるAI基盤ツールの選び方	https://note.com/masayukitanaka/n/n075a86e683f3
7	是	プログラミングなしでAIエージェントを作れる。GitHubスター13万の「Dify」がすごい	https://note.com/a_utomation/n/n708fc4391b59

LLM 接入（OpenAI/Claude/Gemini/Ollama）

Likes	Long-tail	Title	URL
6	是	GPTs・Claude Projects・Difyで「自分専用AI」を作る方法	https://note.com/maruking777/n/ndd3f06832c54
5	是	進化の最前線を掴む実践ガイド：Gemini、Dify、AIエージェントが拓くビジネス変革	https://note.com/kandoinspirefact/n/nc79bd58037ed
7	是	プログラミングなしでAIエージェントを作れる。GitHubスター13万の「Dify」がすごい	https://note.com/a_utomation/n/n708fc4391b59

核心概念（Chatbot/Agent/Workflow/Knowledge）

Likes	Long-tail	Title	URL
4	是	LLMチャットボット開発 - Difyで実現した問い合わせ対応の自動化	https://note.com/super_aster627/n/n739518ab21db
8	是	「あるはずの情報が見つからない」── Dify RAGチャットボット開発で踏んだ落とし穴と自動評価システムの構築	https://note.com/kadinche/n/n87b77918dab9
26	否	Difyで話題の「16タイプ診断」を作ってみた！チャットフローで作るコンサルBotのすすめ	https://note.com/weel_media/n/nd8fe23b955d8

Workflow vs n8n / Zapier

Likes	Long-tail	Title	URL
17	是	【2026年3月版】AIワークフロー自動化ツールを徹底比較してみた！　Dify vs n8n vs Make vs Jinba	https://note.com/kazu_t/n/nfcdb0fd1aa2c
7	是	n8nとDifyどっちを使う？ノーコードAI自動化ツール徹底比較	https://note.com/thesaurus1/n/n545fbf130862
193	否	実はClaude Codeで、DifyやZapierのような「自動化ワークフロー」もつくれる	https://note.com/kajiken0630/n/ne3f5b9161bd5

全量抓取文件

phase-1/curated-fulltext/01.json ← https://note.com/super_phlox114/n/nba7104ad1f71
phase-1/curated-fulltext/02.json ← https://note.com/a_utomation/n/n708fc4391b59
phase-1/curated-fulltext/03.json ← https://note.com/weel_media/n/nd8fe23b955d8
phase-1/curated-fulltext/04.json ← https://note.com/masayukitanaka/n/n075a86e683f3
phase-1/curated-fulltext/05.json ← https://note.com/maruking777/n/ndd3f06832c54
phase-1/curated-fulltext/06.json ← https://note.com/kandoinspirefact/n/nc79bd58037ed
phase-1/curated-fulltext/07.json ← https://note.com/super_aster627/n/n739518ab21db
phase-1/curated-fulltext/08.json ← https://note.com/kadinche/n/n87b77918dab9
phase-1/curated-fulltext/09.json ← https://note.com/kazu_t/n/nfcdb0fd1aa2c
phase-1/curated-fulltext/10.json ← https://note.com/thesaurus1/n/n545fbf130862
phase-1/curated-fulltext/11.json ← https://note.com/kajiken0630/n/ne3f5b9161bd5

Keyboard shortcuts

MKC — Dify Japan 内容体系