Dify实战：JSON Schema精准控制AI输出，构建可靠LLM应用工作流

1. 项目概述：为什么我们需要关注 Dify 中的 JSON Schema？

如果你正在使用 Dify 构建 AI 应用，或者对 LLM 应用开发感兴趣，那么“如何让 AI 准确地理解并输出你想要的复杂数据结构”这个问题，你一定绕不开。Dify 作为一个低代码的 LLM 应用开发平台，其核心能力之一就是通过“提示词编排”和“工作流”来定义 AI 的行为。而 JSON Schema，正是实现这一精准控制的关键“契约”。

简单来说，JSON Schema 就像一份给 AI 的“产品规格说明书”。你告诉 AI：“我需要你生成一个用户信息，它必须包含姓名（字符串）、年龄（整数，且大于0）、邮箱（符合邮箱格式的字符串）”。如果没有这份“说明书”，AI 可能会自由发挥，给你返回一段纯文本描述，或者一个结构混乱、字段缺失的 JSON，你的后续程序根本无法解析。在 Dify 的上下文中，无论是用于定义“文本生成”节点的结构化输出，还是作为“代码执行”节点的输入参数验证，亦或是构建一个多步骤工作流时在不同节点间传递数据，JSON Schema 都扮演着确保数据格式正确、流程顺畅运行的核心角色。

我见过不少开发者，初期只是简单地在提示词里写“请用 JSON 格式回复”，结果被不稳定的输出格式折腾得够呛。直到开始系统使用 JSON Schema，才真正体会到什么叫“可控”和“可靠”。这份指南，就是把我自己从踩坑到熟练使用 JSON Schema 的经验，结合 Dify 平台的具体特性，为你梳理出一套从标准理解到实战上手的完整路径。无论你是想确保聊天机器人返回规整的订单信息，还是想让工作流中的数据处理环节坚如磐石，这里的内容都能给你直接的帮助。

2. JSON Schema 核心标准快速解读

在深入 Dify 的具体操作之前，我们必须先统一“语言”。JSON Schema 本身是一个国际标准（最新常用版本是 Draft-7 和 2019-09），它用 JSON 格式来定义和验证 JSON 数据。在 Dify 中，我们主要利用其核心部分来约束 LLM 的输出或验证输入。

2.1 基础类型与约束：构建数据模型的砖瓦

JSON Schema 的基石是数据类型。你需要像定义数据库字段一样，明确每个字段的“类型”。

1. string(字符串)：最常用的类型。除了声明类型，你还可以施加约束：

   • maxLength/minLength：控制字符串长度。比如用户昵称要求 2-20 个字符：{"type": "string", "minLength": 2, "maxLength": 20}
   • pattern：使用正则表达式验证格式。这是确保数据质量的利器。例如，验证手机号（简单示例）：{"type": "string", "pattern": "^1[3-9]\\d{9}$"}。在 Dify 中，这能有效防止 LLM 编造一个不合规的手机号。
   • format：内置格式校验，如email、uri、date-time。对于邮箱字段，直接使用{"type": "string", "format": "email"}比单纯用正则更可靠、语义也更清晰。

2. number/integer(数字/整数)：用于所有数值型数据。

   • minimum/maximum：定义数值范围。例如年龄：{"type": "integer", "minimum": 0, "maximum": 150}。
   • exclusiveMinimum/exclusiveMaximum：定义开区间范围（不包含边界值）。
   • 一个常见误区：价格、评分等字段应使用number（允许小数），而数量、ID等应使用integer。

3. boolean(布尔值)：简单的true或false。定义时只需{"type": "boolean"}。

4. array(数组)：用于定义列表。关键在于定义其items的 schema。

   • items: 描述数组中每个元素必须符合的 schema。例如，一个字符串标签数组：{"type": "array", "items": {"type": "string"}}。
   • minItems/maxItems: 控制数组长度。这在定义“最多上传5张图片的ID列表”时非常有用。

5. object(对象)：这是构建复杂结构的主体。核心属性是properties和required。

   • properties: 一个对象，其键是属性名，值是该属性对应的 JSON Schema。
   • required: 一个数组，列出必须存在的属性名。这是实战中极易出错的地方：一个字段在properties中定义了，但如果没有列入required，LLM 可能会“偷懒”不输出它。

2.2 结构组合与复用：让 Schema 模块化、可维护

当数据结构变复杂时，我们需要更高级的组合方式。

1. $defs/definitions(定义复用)：这是保持 Schema 简洁、避免重复的“神器”。你可以在 Schema 顶部定义一些通用的子模式，然后在多处引用。

   { "$defs": { "address": { "type": "object", "properties": { "street": {"type": "string"}, "city": {"type": "string"} }, "required": ["street", "city"] } }, "type": "object", "properties": { "homeAddress": {"$ref": "#/$defs/address"}, "workAddress": {"$ref": "#/$defs/address"} } }

   这样，修改地址结构只需改一处$defs.address。

2. allOf,anyOf,oneOf(逻辑组合)：

   • allOf：所有子模式都必须满足（相当于逻辑与）。常用于合并多个约束或继承。
   • anyOf：至少满足一个子模式（逻辑或）。例如，一个字段可以是字符串或数字：{"anyOf": [{"type": "string"}, {"type": "number"}]}。
   • oneOf：必须恰好满足一个子模式。这在定义“类型枚举”时有用，但让 LLM 理解有时会有歧义，需谨慎使用。

实操心得：对于 LLM 输出约束，优先使用清晰、简单的结构。过度复杂的oneOf或深层嵌套，可能会增加 LLM 的解析负担，导致输出不稳定。$ref复用是提升可维护性的最佳实践，务必掌握。

3. 在 Dify 中应用 JSON Schema 的三大实战场景

理解了标准，我们来看 Dify 这个“战场”上，JSON Schema 具体在哪儿发挥作用。主要有三个核心场景，每个场景的侧重点略有不同。

3.1 场景一：约束文本生成节点的结构化输出

这是 JSON Schema 在 Dify 中最经典、最高频的应用。在“文本生成”节点（或类似的大模型调用节点）的配置中，你可以找到“结构化输出”或“Response Schema”的配置项。

• 核心作用：直接引导 LLM 按照你定义的 JSON 格式生成内容，而不是自由格式的文本。
• 操作路径：在 Dify 工作流编辑器中，选中你的 LLM 节点 -> 在右侧配置面板找到“高级设置”或“输出设置” -> 启用“结构化输出” -> 将编写好的 JSON Schema 粘贴进去。
• 示例：生成产品描述假设我们需要 AI 为电商产品生成描述，并要求返回固定结构以便前端直接渲染：

  { "type": "object", "properties": { "product_name": { "type": "string", "description": "产品的正式名称" }, "key_features": { "type": "array", "description": "核心卖点列表", "items": {"type": "string"}, "minItems": 3, "maxItems": 5 }, "price_range": { "type": "string", "description": "价格区间描述，如'100-200元'", "pattern": "^\\d+-\\d+元$" }, "is_in_stock": { "type": "boolean", "description": "当前是否有库存" } }, "required": ["product_name", "key_features", "price_range", "is_in_stock"] }

• 注意事项：
  1. 善用description：Schema 中每个字段的description属性至关重要！LLM 会仔细阅读这些描述来理解字段含义。描述应清晰、无歧义，甚至可以包含示例。
  2. required字段必填：务必仔细核对required数组，遗漏关键字段会导致输出不完整。
  3. 复杂度权衡：Schema 不是越复杂越好。过于复杂的嵌套和约束可能会降低 LLM 输出的准确率。先从简单的必需字段开始，逐步增加。

3.2 场景二：定义代码执行节点的输入参数

在 Dify 工作流中，“代码执行”节点（或“Python 代码”节点）允许你运行自定义脚本。为了安全、可控地向脚本传递参数，JSON Schema 可以用来定义和验证输入。

• 核心作用：作为代码节点的输入“接口文档”，确保传入的参数类型、格式正确，避免代码运行时因参数错误而崩溃。
• 操作路径：编辑“代码执行”节点 -> 在“输入”或“变量”设置部分，选择“JSON Schema”模式 -> 定义 Schema。
• 示例：定义一个图片处理脚本的输入

  { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri", "description": "待处理图片的公开访问URL" }, "operation": { "type": "string", "description": "要执行的操作", "enum": ["resize", "crop", "grayscale", "watermark"] }, "width": { "type": "integer", "description": "调整后的宽度（像素），仅在operation为resize或crop时需要", "minimum": 1 }, "height": { "type": "integer", "description": "调整后的高度（像素）", "minimum": 1 } }, "required": ["image_url", "operation"], "dependentRequired": { "width": ["operation"], "height": ["operation"] } }

• 注意事项：
  1. 使用enum限定选项：对于操作类型、状态等有限集合，使用enum列表比单纯的字符串约束更精确。
  2. 条件依赖：如上例，width和height字段仅在operation为特定值时才需要。JSON Schema 的dependentRequired可以处理这种简单条件逻辑。更复杂的条件可能需要结合 Dify 的“条件判断”节点在流程中实现。
  3. 防御性编程：即使有 Schema 验证，代码内部也应对参数进行二次检查和默认值处理，因为 Schema 主要验证类型和格式，不验证业务逻辑（如图片 URL 是否真正可达）。

3.3 场景三：作为工作流中节点间传递的数据契约

当你的工作流包含多个节点时（如：文本生成 -> 代码处理 -> 数据库存储），JSON Schema 可以定义每个节点输出数据的格式，从而成为节点间通信的“契约”。

• 核心作用：确保上游节点的输出符合下游节点的输入预期，使得复杂工作流能够可靠地串联起来。
• 实现方式：这更多是一种设计和约定。你可以为某个节点的输出“文档化”一个 Schema，并确保后续使用该输出的节点（通过变量引用）按照此 Schema 的结构来访问数据。
• 示例：一个内容创作与发布流水线
  1. 节点A（创意生成）：输出 Schema 定义了一篇文章的草稿结构{title, outline, sections: [...]}。
  2. 节点B（SEO优化）：接收节点A的输出，并期望sections是一个对象数组。节点B的代码就可以安全地遍历sections。
  3. 节点C（格式转换）：接收节点B优化后的数据，将其转换为特定平台（如微信公众号）所需的 HTML 格式。它依赖title和sections字段的存在。
• 注意事项：
  1. 契约先行：在设计工作流时，先定义好关键节点间的数据接口（Schema），再开发具体功能。
  2. 版本管理：如果 Schema 发生变更，需要同步检查所有依赖该数据格式的节点，避免工作流断裂。在团队协作中，这点尤为重要。
  3. 使用变量预览：Dify 工作流调试时，充分利用“运行”后查看每个节点输出的变量详情功能，直观地验证实际数据是否符合你心中的“Schema契约”。

4. 从零到一：在 Dify 工作流中配置 JSON Schema 的完整流程

让我们以一个实际的例子，串联起整个配置过程。目标是构建一个“智能客服工单生成”工作流：用户描述问题，AI 自动提取关键信息并生成结构化工单。

4.1 第一步：定义目标数据结构（Schema 设计）

首先，脱离平台，用纸笔或文本编辑器明确我们要什么数据。这是最关键的一步。

工单需要包含：

• ticket_id(自动生成，字符串)
• user_query(用户原始问题，字符串)
• problem_summary(问题摘要，字符串)
• category(问题分类，枚举值)
• priority(紧急程度，枚举值)
• related_products(涉及产品列表，字符串数组，可选)
• extract_contact(从对话中提取的联系方式，对象，可选)

据此，编写出 JSON Schema：

{ "$schema": "https://json-schema.org/draft-07/schema#", "title": "Customer Support Ticket", "description": "Schema for structured customer support ticket generated by AI", "type": "object", "properties": { "ticket_id": { "type": "string", "description": "Auto-generated unique ticket ID, format: TKT-YYYYMMDD-XXXXX", "pattern": "^TKT-\\d{8}-[A-Z0-9]{5}$" }, "user_query": { "type": "string", "description": "The original question or description from the user" }, "problem_summary": { "type": "string", "description": "Concise summary of the core problem, extracted from user_query", "minLength": 10, "maxLength": 200 }, "category": { "type": "string", "description": "The category of the problem", "enum": ["billing", "technical", "account", "feature_request", "other"] }, "priority": { "type": "string", "description": "Urgency level of the ticket", "enum": ["low", "medium", "high", "critical"] }, "related_products": { "type": "array", "description": "List of product names mentioned in the query, if any", "items": {"type": "string"}, "default": [] }, "extract_contact": { "type": "object", "description": "Contact information extracted from the conversation", "properties": { "email": {"type": "string", "format": "email"}, "phone": {"type": "string", "pattern": "^\\+?[1-9]\\d{1,14}$"} } } }, "required": ["ticket_id", "user_query", "problem_summary", "category", "priority"] }

4.2 第二步：在 Dify 工作流中配置 LLM 节点

1. 创建工作流：在 Dify 控制台新建一个工作流。
2. 添加起始节点：通常是一个“对话输入”或“文本输入”节点，用于接收用户问题。将其输出变量命名为user_input。
3. 添加 LLM 节点：从节点库拖入一个“文本生成”节点（如连接到 GPT-4 等模型）。
4. 连接节点：将起始节点的输出连接到 LLM 节点的输入。
5. 编写提示词：在 LLM 节点的提示词编辑器中，结合我们定义的 Schema 来编写系统提示词和用户提示词。
   • 系统提示词（关键）：

     你是一个智能客服工单分类与摘要生成助手。请严格根据用户描述，提取信息并生成一个结构化的 JSON 工单。 你必须遵循以下 JSON Schema 定义的结构和字段要求： [将上面定义的完整 JSON Schema 粘贴到这里] 注意：`ticket_id` 字段请按格式生成，示例：TKT-20231027-ABC12。`category` 和 `priority` 必须从给定的枚举值中选择。如果用户未提及产品，`related_products` 返回空数组。只有明确提到联系方式时才填充 `extract_contact` 对象。 你的响应必须是且仅是一个合法的 JSON 对象，不要有任何额外的解释、标记或文本。

   • 用户提示词：用户问题：{{user_input}}
6. 启用结构化输出：在 LLM 节点的“高级设置”中，找到“结构化输出”或“响应格式”选项。将我们之前定义的 JSON Schema 完整地粘贴到配置框中。这一步是直接告诉 Dify 平台和底层模型 API，需要按此 Schema 约束输出。

4.3 第三步：测试、调试与迭代

1. 首次运行测试：点击工作流的“运行”按钮，在预览区输入一个测试问题，例如：“我的账户无法登录了，邮箱是 [e-mail]，我用的主要是‘旗舰版’产品，非常着急！”
2. 检查输出：查看 LLM 节点的输出变量。理想情况下，你会得到一个完美的 JSON：

   { "ticket_id": "TKT-20231027-DF8G7", "user_query": "我的账户无法登录了...", "problem_summary": "用户报告账户无法登录，使用邮箱注册，涉及旗舰版产品，情绪焦急。", "category": "account", "priority": "high", "related_products": ["旗舰版"], "extract_contact": { "email": "[e-mail]" } }

3. 常见问题与调试：
   • 问题：输出不是纯 JSON，包含了“json ...”这样的 Markdown 代码块标记。
   • 解决：在系统提示词中再次强调“响应必须是且仅是一个合法的 JSON 对象，不要有任何额外的解释、标记或文本”。同时，检查 Dify 的模型配置，某些模型可能需要更明确的指令。
   • 问题：缺少required字段，或枚举字段的值不在列表中。
   • 解决：首先检查 Schema 中required数组是否遗漏。其次，检查enum列表是否覆盖了所有可能情况。可以在提示词的description里更详细地解释每个枚举值的适用场景。
   • 问题：pattern格式校验失败（如ticket_id格式不对）。
   • 解决：在提示词中为有复杂格式的字段提供更清晰的示例。例如：“ticket_id格式必须严格为TKT-年月日-五位随机码，年月日如20231027，随机码如AB123”。
4. 迭代优化：根据测试结果，反复调整提示词（特别是系统提示词中对 Schema 各字段的解释）和 Schema 本身（比如放宽某些pattern，或调整enum）。这是一个“提示词工程”与“Schema 设计”相互磨合的过程。

4.4 第四步：连接后续节点，实现完整流程

LLM 节点输出结构化数据后，你就可以像使用普通变量一样，在工作流中引用这些字段。

1. 添加后续处理节点：
   • 条件判断节点：根据priority字段的值（如“critical”），决定是否触发短信告警。
   • 代码执行节点：将生成的工单 JSON 写入数据库。在代码中，你可以直接通过input.ticket_id,input.category等方式安全地访问数据，因为 Schema 已经保证了它们的存在和类型。
   • HTTP 请求节点：将工单数据POST到外部工单系统（如 Jira, Zendesk）的 API。
2. 引用变量：在后续节点的配置中，使用 Dify 的变量语法{{node_id.output.field_name}}来引用数据。例如，引用问题摘要：{{llm_node_1.output.problem_summary}}。

5. 高级技巧与避坑指南

掌握了基础流程后，下面这些从实战中总结的经验，能帮你把 JSON Schema 用得更加得心应手，并避开那些常见的“坑”。

5.1 提示词与 Schema 的协同优化术

Schema 定义了“结构”，提示词解释了“语义”。两者必须紧密配合。

• 技巧一：在提示词中“翻译”Schema。不要只是把冰冷的 Schema 扔给 AI。用自然语言在提示词里重新描述一遍关键约束，特别是enum和pattern。
  • 差：“请遵循此 Schema。”
  • 优：“请生成一个工单。紧急程度（priority）只能是 ‘low‘, ‘medium‘, ‘high‘, ‘critical‘ 中的一个，请根据用户描述的紧急程度判断。问题分类（category）只能是 ‘billing‘（账单问题）, ‘technical‘（技术故障）, ‘account‘（账户问题）, ‘feature_request‘（功能建议）, ‘other‘（其他）中的一个。”
• 技巧二：提供少量示例（Few-Shot）。在系统提示词中，给出1-2个符合 Schema 的完整 JSON 示例。这对于复杂结构或特殊格式要求的字段效果极佳。
• 技巧三：明确处理缺失信息的策略。对于可选字段（不在required中），在提示词里说明什么情况下该填充，什么情况下留空或给默认值。例如：“如果用户对话中没有提及任何具体产品名称，则related_products字段应设置为空数组[]。”

5.2 复杂嵌套结构的处理策略

当需要定义深层嵌套的 JSON 时（例如，一个包含多项技能、每项技能又有多个熟练度标签的用户简历），直接编写一个巨大的 Schema 会难以维护。

• 策略：使用$defs分而治之。如前所述，将重复或复杂的子结构定义在$defs中。
• 策略：分步生成。对于极其复杂的结构，考虑设计多步工作流。第一步，让 LLM 生成一个顶层概要；第二步，根据概要，再调用另一个 LLM 节点（配置更细粒度的 Schema）去生成某个子部分。这能降低单次生成的复杂度，提高成功率。

5.3 性能与稳定性调优

• 控制 Schema 体积：过大的 Schema（几十KB）可能会增加模型的 Token 消耗，略微影响速度和成本。保持简洁，移除不必要的description（如果提示词中已说明清楚）。
• 选择兼容性好的模型：并非所有模型对 JSON Schema 的支持度都一样。OpenAI 的 GPT-4、GPT-3.5-Turbo 对此支持非常好。使用其他模型时，需要更详细的测试。在 Dify 的模型配置中，确保开启了相应的“JSON 模式”或“结构化输出”功能开关。
• 设置合理的重试与回退：在 Dify 工作流设置中，可以为节点配置“失败重试”策略。如果因为偶发的模型输出格式错误导致节点失败，自动重试一次可能会解决问题。同时，可以设计一个简单的格式校验（代码节点）作为后续节点，一旦发现 JSON 解析失败，就触发一个降级处理流程（如记录日志并转人工）。

5.4 常见错误排查清单

当你遇到输出不符合预期时，可以按此清单逐一排查：

问题现象	可能原因	解决方案
输出包含额外文本（如```json）	提示词未强调“仅输出JSON”，或模型习惯性添加标记。	1. 在系统提示词开头和结尾强调。2. 尝试在提示词模板中指定Response Format: JSON ONLY。
缺少某个字段	1. 该字段未列入required。2. 模型不理解该字段含义。	1. 检查并添加至required数组。2. 在字段description和提示词中用更直白的语言解释。
字段值不符合enum列表	模型选择了列表外的值。	1. 检查enum列表是否完整。2. 在提示词中明确列出并解释每个选项。3. 提供示例。
字段值不符合pattern	模型生成的格式有误。	1. 在字段description中提供明确的格式示例。2. 如果格式非常复杂，考虑放宽约束（如先用正则做粗略验证，后续用代码节点精细清洗）。
输出为null或空对象	Schema 可能过于复杂或矛盾，导致模型无法生成。	1. 简化 Schema，移除不必要的嵌套和组合逻辑（如oneOf）。2. 分步生成复杂数据。
Dify 节点报“输出格式错误”	Dify 后端验证 Schema 失败。	1. 首先检查你粘贴的 JSON Schema 本身是否是合法的 JSON（可用在线 JSON 校验工具）。2. 检查是否使用了 Dify 不支持的 Schema 特性（如过于新潮的关键字）。

最后，我个人最深刻的体会是：把 JSON Schema 当作与 AI 模型和下游系统签订的“精确合同”。设计 Schema 的过程，就是厘清你真正需要什么数据的过程。在 Dify 中投入时间精心设计 Schema 和配套提示词，虽然前期会多花些功夫，但换来的是整个 AI 工作流输出稳定性的巨大提升和后续集成的顺畅，这笔投资绝对划算。刚开始可以从最简单的两个必需字段开始，跑通流程，建立信心，然后再逐步增加复杂度和约束，这样迭代起来会更顺畅。