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 的基石是数据类型。你需要像定义数据库字段一样明确每个字段的“类型”。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}比单纯用正则更可靠、语义也更清晰。number/integer(数字/整数)用于所有数值型数据。minimum/maximum定义数值范围。例如年龄{type: integer, minimum: 0, maximum: 150}。exclusiveMinimum/exclusiveMaximum定义开区间范围不包含边界值。一个常见误区价格、评分等字段应使用number允许小数而数量、ID等应使用integer。boolean(布尔值)简单的true或false。定义时只需{type: boolean}。array(数组)用于定义列表。关键在于定义其items的 schema。items: 描述数组中每个元素必须符合的 schema。例如一个字符串标签数组{type: array, items: {type: string}}。minItems/maxItems: 控制数组长度。这在定义“最多上传5张图片的ID列表”时非常有用。object(对象)这是构建复杂结构的主体。核心属性是properties和required。properties: 一个对象其键是属性名值是该属性对应的 JSON Schema。required: 一个数组列出必须存在的属性名。这是实战中极易出错的地方一个字段在properties中定义了但如果没有列入requiredLLM 可能会“偷懒”不输出它。2.2 结构组合与复用让 Schema 模块化、可维护当数据结构变复杂时我们需要更高级的组合方式。$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。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] }注意事项善用descriptionSchema 中每个字段的description属性至关重要LLM 会仔细阅读这些描述来理解字段含义。描述应清晰、无歧义甚至可以包含示例。required字段必填务必仔细核对required数组遗漏关键字段会导致输出不完整。复杂度权衡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] } }注意事项使用enum限定选项对于操作类型、状态等有限集合使用enum列表比单纯的字符串约束更精确。条件依赖如上例width和height字段仅在operation为特定值时才需要。JSON Schema 的dependentRequired可以处理这种简单条件逻辑。更复杂的条件可能需要结合 Dify 的“条件判断”节点在流程中实现。防御性编程即使有 Schema 验证代码内部也应对参数进行二次检查和默认值处理因为 Schema 主要验证类型和格式不验证业务逻辑如图片 URL 是否真正可达。3.3 场景三作为工作流中节点间传递的数据契约当你的工作流包含多个节点时如文本生成 - 代码处理 - 数据库存储JSON Schema 可以定义每个节点输出数据的格式从而成为节点间通信的“契约”。核心作用确保上游节点的输出符合下游节点的输入预期使得复杂工作流能够可靠地串联起来。实现方式这更多是一种设计和约定。你可以为某个节点的输出“文档化”一个 Schema并确保后续使用该输出的节点通过变量引用按照此 Schema 的结构来访问数据。示例一个内容创作与发布流水线节点A创意生成输出 Schema 定义了一篇文章的草稿结构{title, outline, sections: [...]}。节点BSEO优化接收节点A的输出并期望sections是一个对象数组。节点B的代码就可以安全地遍历sections。节点C格式转换接收节点B优化后的数据将其转换为特定平台如微信公众号所需的 HTML 格式。它依赖title和sections字段的存在。注意事项契约先行在设计工作流时先定义好关键节点间的数据接口Schema再开发具体功能。版本管理如果 Schema 发生变更需要同步检查所有依赖该数据格式的节点避免工作流断裂。在团队协作中这点尤为重要。使用变量预览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 节点创建工作流在 Dify 控制台新建一个工作流。添加起始节点通常是一个“对话输入”或“文本输入”节点用于接收用户问题。将其输出变量命名为user_input。添加 LLM 节点从节点库拖入一个“文本生成”节点如连接到 GPT-4 等模型。连接节点将起始节点的输出连接到 LLM 节点的输入。编写提示词在 LLM 节点的提示词编辑器中结合我们定义的 Schema 来编写系统提示词和用户提示词。系统提示词关键你是一个智能客服工单分类与摘要生成助手。请严格根据用户描述提取信息并生成一个结构化的 JSON 工单。 你必须遵循以下 JSON Schema 定义的结构和字段要求 [将上面定义的完整 JSON Schema 粘贴到这里] 注意ticket_id 字段请按格式生成示例TKT-20231027-ABC12。category 和 priority 必须从给定的枚举值中选择。如果用户未提及产品related_products 返回空数组。只有明确提到联系方式时才填充 extract_contact 对象。 你的响应必须是且仅是一个合法的 JSON 对象不要有任何额外的解释、标记或文本。用户提示词用户问题{{user_input}}启用结构化输出在 LLM 节点的“高级设置”中找到“结构化输出”或“响应格式”选项。将我们之前定义的 JSON Schema 完整地粘贴到配置框中。这一步是直接告诉 Dify 平台和底层模型 API需要按此 Schema 约束输出。4.3 第三步测试、调试与迭代首次运行测试点击工作流的“运行”按钮在预览区输入一个测试问题例如“我的账户无法登录了邮箱是 userexample.com我用的主要是‘旗舰版’产品非常着急”检查输出查看 LLM 节点的输出变量。理想情况下你会得到一个完美的 JSON{ ticket_id: TKT-20231027-DF8G7, user_query: 我的账户无法登录了..., problem_summary: 用户报告账户无法登录使用邮箱注册涉及旗舰版产品情绪焦急。, category: account, priority: high, related_products: [旗舰版], extract_contact: { email: userexample.com } }常见问题与调试问题输出不是纯 JSON包含了“json ...”这样的 Markdown 代码块标记。解决在系统提示词中再次强调“响应必须是且仅是一个合法的 JSON 对象不要有任何额外的解释、标记或文本”。同时检查 Dify 的模型配置某些模型可能需要更明确的指令。问题缺少required字段或枚举字段的值不在列表中。解决首先检查 Schema 中required数组是否遗漏。其次检查enum列表是否覆盖了所有可能情况。可以在提示词的description里更详细地解释每个枚举值的适用场景。问题pattern格式校验失败如ticket_id格式不对。解决在提示词中为有复杂格式的字段提供更清晰的示例。例如“ticket_id格式必须严格为TKT-年月日-五位随机码年月日如20231027随机码如AB123”。迭代优化根据测试结果反复调整提示词特别是系统提示词中对 Schema 各字段的解释和 Schema 本身比如放宽某些pattern或调整enum。这是一个“提示词工程”与“Schema 设计”相互磨合的过程。4.4 第四步连接后续节点实现完整流程LLM 节点输出结构化数据后你就可以像使用普通变量一样在工作流中引用这些字段。添加后续处理节点条件判断节点根据priority字段的值如“critical”决定是否触发短信告警。代码执行节点将生成的工单 JSON 写入数据库。在代码中你可以直接通过input.ticket_id,input.category等方式安全地访问数据因为 Schema 已经保证了它们的存在和类型。HTTP 请求节点将工单数据POST到外部工单系统如 Jira, Zendesk的 API。引用变量在后续节点的配置中使用 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 工作流输出稳定性的巨大提升和后续集成的顺畅这笔投资绝对划算。刚开始可以从最简单的两个必需字段开始跑通流程建立信心然后再逐步增加复杂度和约束这样迭代起来会更顺畅。