1. 项目概述为什么我们需要让 LLM 输出结构化 JSON如果你最近在折腾大语言模型不管是 OpenAI 的 GPT 系列还是 Claude、DeepSeek 这些后起之秀肯定都遇到过这样的场景你问模型“帮我查一下北京明天的天气”它可能会给你一段非常“人性化”的回答比如“北京明天天气晴朗最高温度25度最低温度15度风力2-3级建议穿薄外套。” 读起来很舒服对吧但如果你是一个开发者想把这段信息塞进你自己的天气 App 里或者存到数据库里麻烦就来了。你得写一堆复杂的正则表达式或者 NLP 解析代码去从这段自由文本里抠出“城市”、“日期”、“最高温”、“最低温”、“风力”、“建议”这些字段。这个过程不仅繁琐而且极其脆弱——模型换一种说法你的解析代码可能就崩了。这就是“Prompt 工程让 LLM 输出结构化 JSON”要解决的核心痛点。我们不再满足于让 LLM 当一个“聊天高手”而是希望它能成为一个“合格的 API 接口”输出机器和程序都能轻松理解、稳定处理的数据格式。JSON作为现代 Web 开发和数据交换的“世界语”自然成了首选。想象一下你直接告诉模型“请以 JSON 格式返回北京明天的天气信息包含 city, date, max_temp, min_temp, wind, suggestion 字段。” 然后你得到的就是一个干干净净的{city: 北京, date: 2023-10-27, max_temp: 25, ...}。后端代码直接用JSON.parse()就能处理前端直接data.max_temp就能渲染省去了中间所有“猜谜”和“清洗”的步骤。这个需求在构建 AI Agent、自动化工作流、数据提取、内容生成等场景下变得尤为关键。比如你想让 LLM 从一篇新闻里提取公司名、股价、涨跌幅或者从用户反馈中分类情感并提取关键问题结构化输出是串联起 LLM 能力与你现有业务系统的唯一桥梁。没有它LLM 就只是一个聪明的玩具有了它LLM 才能真正成为你生产流水线上的一个可靠“零件”。接下来我们就深入拆解如何通过 Prompt 工程这门手艺把 LLM 这匹“天马行空”的野马驯化成能产出规整 JSON 的“良驹”。2. 核心思路与方案选型从“祈祷”到“约束”早期让 LLM 输出 JSON基本靠“祈祷”。你会在 Prompt 里写上“请输出 JSON”然后期待模型心情好能给你一个正确的格式。结果往往是有时对了有时多了个逗号有时键名用了中文引号有时干脆在 JSON 外面又包裹了一段解释文字。这种不确定性在开发中是致命的。所以我们的核心思路要从“请求”转变为“约束”。不是请求模型“能不能输出 JSON”而是通过 Prompt 的巧妙设计给模型戴上“紧箍咒”让它必须在指定的框架内回答问题。目前主流且有效的方法可以归纳为三类它们各有优劣适用场景也不同。2.1 方法一基础指令约束法这是最直接的方法即在你的系统指令System Prompt或用户问题中明确、详细地描述你期望的 JSON 结构。具体操作示例你是一个智能天气助手。请始终以 JSON 格式回复。 JSON 必须包含以下字段 - city: 字符串城市名称。 - date: 字符串日期格式为 YYYY-MM-DD。 - condition: 字符串天气状况如“晴”、“多云”、“雨”。 - temperature: 对象包含 max整数最高温和 min整数最低温。 - wind: 字符串风力描述。 请确保输出是纯 JSON不要有任何额外的解释或标记。 用户问题北京明天天气怎么样优点简单直观不需要任何额外工具或库直接修改 Prompt 即可。通用性强适用于几乎所有支持文本输入的 LLM。快速验证对于简单的结构这种方法足够有效。缺点与坑点约束力弱模型仍然可能“忘记”格式或者在 JSON 前后添加文本。你需要非常强硬和重复的指令。结构复杂时乏力当 JSON 结构嵌套很深或者需要定义枚举值比如 condition 只能是“晴、阴、雨、雪”中的一种时纯文本描述会变得冗长且容易产生歧义。无运行时验证输出后你仍然需要写代码去校验这个 JSON 是否真的符合你定义的 schema数据模式是否有缺少的字段或类型错误。实操心得在使用基础指令法时一个非常有效的小技巧是“示例驱动”。与其用文字描述不如直接给一个完整的例子。在 Prompt 里加上“例如正确的输出应该像这样{\city\: \上海\, \date\: \2023-10-28\, ...}”。LLM 非常擅长模仿看到一个具体例子它遵循格式的准确率会大幅提升。2.2 方法二函数调用Function Calling与工具使用这是 OpenAI 等主流 API 提供的高级功能。你不再要求模型“输出 JSON”而是定义一系列“函数”或“工具”描述这些函数的参数一个符合 JSON Schema 的复杂对象。然后模型在理解用户意图后会决定是否调用以及调用哪个函数并自动生成一个符合你预定义 Schema 的、填充好参数的 JSON 对象。工作流程开发者定义函数比如get_weather(city: string, date: string)。在 API 调用时将这些函数描述包括名称、描述、参数 JSON Schema传给模型。模型回复中会包含一个特殊字段如tool_calls其中就包含了它想要调用的函数名和已经结构化好的参数 JSON。你的代码解析这个tool_calls直接拿到一个保证格式正确的 JSON然后去执行真正的函数如查询天气数据库。优点格式绝对可靠输出的 JSON 严格遵循你定义的 JSON Schema极大减少了格式错误。意图识别模型会先判断用户问题是否匹配某个函数实现了“意图分类信息提取”一步到位。生态友好与 LangChain、LlamaIndex 等框架集成度极高是构建复杂 Agent 的基石。缺点平台绑定严重依赖模型提供商是否支持此功能OpenAI、Anthropic Claude 等支持。概念复杂需要理解 JSON Schema 和函数调用的整个流程学习成本较高。不适用于纯文本模型对于某些开源或本地部署的模型可能不支持此特性。2.3 方法三外部 Schema 强制验证以 Zod 为代表这是目前社区里最受推崇、也最“工程化”的方法。它结合了前两者的优点像基础指令法一样通用又像函数调用一样提供强约束和验证。核心是使用一个外部库如Zod来定义数据模式Schema然后将这个 Schema 的文本描述或特定格式的指令插入到 Prompt 中引导模型输出符合该 Schema 的 JSON。最后用同一个 Zod Schema 去解析和验证模型的输出。为什么是 Zod在提供的热词里出现了VeeValidate Zod Shadcn这正说明了 Zod 在前端生态的火爆。Zod 是一个 TypeScript/JavaScript 的 schema 声明和验证库。它的定义方式非常直观import { z } from zod; const WeatherSchema z.object({ city: z.string(), date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/), // 用正则约束日期格式 condition: z.enum([晴, 多云, 阴, 雨, 雪]), temperature: z.object({ max: z.number().int(), min: z.number().int() }), wind: z.string() });这个WeatherSchema不仅能在运行时验证数据其本身也是一个清晰、无歧义的结构描述。我们可以把这段Schema 的定义文本或转换后的自然语言描述放进 Prompt告诉模型“请按照以下 Zod Schema 的定义输出 JSON”。优点强类型约束能定义字段类型、字符串格式如日期、邮箱、枚举值、数值范围等约束力远超纯文本描述。前后端一致同一个 Schema 既用于生成 Prompt又用于验证输出保证了解析的一致性避免了“说一套做一套”。开发体验好配合 TypeScript能得到完美的类型提示和类型安全。相对通用虽然需要一些 Prompt 技巧但理论上适用于任何能理解文本指令的 LLM。缺点Prompt 可能很长复杂的 Schema 转换成文本描述后会消耗大量 Token增加成本并可能影响模型对主要问题的注意力。需要后处理你仍然需要写代码去捕获模型输出并用 Zod 去解析WeatherSchema.parse(modelOutput)解析失败意味着模型“不听话”你需要处理错误。方案选型总结对于快速原型或简单需求基础指令法足够。对于构建在 OpenAI 等平台上的生产级应用函数调用是最稳健的选择。而如果你追求极致的类型安全、跨模型兼容性或者你的技术栈就在 TypeScript/JavaScript 领域那么Zod 驱动的方法是目前最优雅和强大的解决方案。下文我们将重点深入这种最具普适性和工程价值的方法。3. 实操详解用 Zod 驯服 LLM 输出让我们从一个具体的例子出发手把手实现用 Zod 约束 LLM 输出结构化 JSON 的全流程。假设我们要构建一个“会议纪要生成器”用户输入一段会议录音的文字稿我们需要 LLM 提取出结构化信息。3.1 第一步定义你的 Zod Schema这是最关键的一步你需要精确地定义你希望得到什么。这本身就是一次很好的需求梳理。import { z } from zod; // 定义会议纪要的 Schema const MeetingMinutesSchema z.object({ // 会议主题字符串必填 topic: z.string().describe(会议的核心主题或名称), // 会议日期字符串需符合YYYY-MM-DD格式 date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).describe(会议发生的日期), // 参会者列表是由字符串组成的数组至少1人 attendees: z.array(z.string()).min(1).describe(参会人员姓名列表), // 关键决议是一个对象数组每个决议有内容和负责人 keyDecisions: z.array( z.object({ content: z.string().describe(决议的具体内容), owner: z.string().describe(该决议的负责人姓名), deadline: z.string().optional().describe(截止日期YYYY-MM-DD格式可选) // 可选字段 }) ).describe(会议达成的关键决议事项), // 待办事项也是一个对象数组 actionItems: z.array( z.object({ task: z.string().describe(具体的待办任务描述), assignee: z.string().describe(任务负责人), dueDate: z.string().describe(截止日期YYYY-MM-DD格式) }) ).optional().describe(会后需要跟进的待办事项可选), // 整个待办数组是可选的 // 总结字符串 summary: z.string().describe(对会议的整体总结) }); // 从这个Schema推导出TypeScript类型后续可以直接使用实现类型安全 type MeetingMinutes z.infertypeof MeetingMinutesSchema;你看通过 Zod我们不仅定义了字段名和类型string,number,array,object还增加了丰富的约束.regex()用于格式校验.min()规定数组长度.optional()表示可选字段.describe()为字段添加描述这些描述在后续生成 Prompt 时非常有用。这个 Schema 就是我们和 LLM 之间的“契约”。3.2 第二步将 Schema 转换为模型能理解的 Prompt我们不能直接把 TypeScript 代码扔给 LLM。我们需要把 Schema “翻译”成清晰、无歧义的自然语言指令。有几种策略策略A直接描述法适合简单Schema将 Zod 的describe()内容和结构用文字写出来。请从提供的会议记录中提取信息并严格按照以下JSON格式输出 { “topic”: “会议主题字符串”, “date”: “会议日期格式必须为YYYY-MM-DD”, “attendees”: [“参会人1姓名”, “参会人2姓名”, ...], // 至少一人 “keyDecisions”: [ { “content”: “决议内容”, “owner”: “负责人姓名”, “deadline”: “截止日期(YYYY-MM-DD)可选” } // ... 更多决议 ], “actionItems”: [ // 这个字段是可选的如果没有待办则设为空数组 [] { “task”: “任务描述”, “assignee”: “负责人”, “dueDate”: “截止日期(YYYY-MM-DD)” } ], “summary”: “会议总结字符串” } 请确保输出是纯JSON不要有任何其他文字。策略B结构化描述法推荐更清晰你的任务是生成结构化的会议纪要JSON。输出必须包含以下字段 1. topic (字符串): 会议的核心主题。 2. date (字符串): 会议日期格式YYYY-MM-DD。 3. attendees (字符串数组): 所有参会者姓名列表。至少有一个。 4. keyDecisions (对象数组): 关键决议列表。每个对象包含 - content (字符串): 决议内容。 - owner (字符串): 决议负责人。 - deadline (字符串可选): 截止日期格式YYYY-MM-DD。 5. actionItems (对象数组可选): 待办事项列表。如果无可设为空数组[]。每个对象包含 - task (字符串): 任务描述。 - assignee (字符串): 任务负责人。 - dueDate (字符串): 截止日期格式YYYY-MM-DD。 6. summary (字符串): 会议整体总结。 请确保输出是有效的、纯净的JSON字符串不要有任何Markdown标记或额外解释。策略C利用 Zod 的describe自动生成进阶你可以写一个小函数遍历 Zod Schema自动提取字段名、类型、描述和约束生成类似策略B的文本。这在大规模应用时非常有用能保证 Prompt 和 Schema 的绝对同步。3.3 第三步组装完整 Prompt 并调用模型现在我们将指令和用户的具体输入结合起来。以下是一个使用 OpenAI API 的示例import OpenAI from openai; const openai new OpenAI({ apiKey: your-api-key }); // 这是我们的“系统指令”定义了AI的角色和输出格式要求 const systemPrompt 你是一个专业的会议纪要助理。你的唯一任务是根据用户提供的会议记录文本提取信息并生成一个高度结构化的JSON摘要。 请严格遵循以下数据结构输出 { “topic”: “会议主题”, “date”: “YYYY-MM-DD”, “attendees”: [“姓名1”, “姓名2”], “keyDecisions”: [ {“content”: “...”, “owner”: “...”, “deadline”: “...”} ], “actionItems”: [ {“task”: “...”, “assignee”: “...”, “dueDate”: “...”} ], // 可选 “summary”: “...” } 输出必须是纯净的、可直接被JSON.parse()解析的JSON字符串不要有任何额外前缀、后缀或解释性文字。; // 用户的输入会议记录 const userInput 2023年10月26日我们召开了第三季度产品评审会。参会的有张三、李四、王五。主要讨论了“智慧办公”项目下一步计划。决定由李四负责在11月15日前完成市场调研报告。王五需要在11月10日前准备好技术架构图。大家一致认为当前进度符合预期下个月重点推进试点客户落地。; async function getStructuredMinutes() { const completion await openai.chat.completions.create({ model: gpt-4-turbo-preview, // 使用支持JSON Mode的模型更好 messages: [ { role: system, content: systemPrompt }, { role: user, content: userInput } ], temperature: 0.1, // 降低“创造力”让输出更确定、更遵循格式 // response_format: { type: json_object }, // 如果模型支持JSON Mode强烈建议开启 }); const rawOutput completion.choices[0].message.content; console.log(模型原始输出, rawOutput); return rawOutput; }关键参数解析temperature: 设为较低值如0.1-0.3能显著减少模型在格式上的“自由发挥”使其更专注于遵循指令。response_format: { type: json_object }: 这是 OpenAI 提供的“JSON 模式”。当开启时模型会强制以合法的 JSON 对象开始生成极大提高了输出 JSON 的格式正确率。这是目前最简单粗暴且有效的官方方案。务必在支持的模型上使用。3.4 第四步用 Zod 验证并解析输出模型输出后我们不能盲目相信它。用我们之前定义的 Zod Schema 进行验证是最安全的一步。import { MeetingMinutesSchema } from ./schema; // 导入之前定义的Schema async function parseAndValidate(output) { try { // 1. 尝试解析JSON。模型可能在JSON外包裹了json 标记需要处理。 let jsonString output.trim(); // 处理常见的Markdown代码块包裹 if (jsonString.startsWith(json)) { jsonString jsonString.slice(7, -3).trim(); } else if (jsonString.startsWith()) { jsonString jsonString.slice(3, -3).trim(); } const parsedJson JSON.parse(jsonString); // 2. 使用Zod Schema进行验证和类型转换 const validatedData MeetingMinutesSchema.parse(parsedJson); console.log(验证成功结构化数据, validatedData); // 现在 validatedData 的类型就是 MeetingMinutes可以安全使用了 return validatedData; } catch (error) { if (error instanceof SyntaxError) { console.error(JSON解析失败模型输出格式错误, output); // 这里可以加入重试逻辑或者用更简单的Prompt让模型修正 } else if (error instanceof z.ZodError) { console.error(数据验证失败字段不符合Schema, error.errors); // ZodError会详细告诉你哪个字段、出了什么问题非常利于调试 // 例如[ { code: invalid_type, expected: string, received: number, path: [temperature, max], ... } ] } else { console.error(未知错误, error); } throw error; // 或者返回一个错误状态让上游处理 } } // 主流程 async function main() { const rawOutput await getStructuredMinutes(); const structuredData await parseAndValidate(rawOutput); // 接下来你可以将 structuredData 存入数据库、发送到前端或进行下一步处理 }通过这四步我们建立了一个从需求定义Zod Schema到指令生成Prompt再到输出验证Zod Parse的完整、健壮的流水线。即使模型偶尔“抽风”我们也能在验证环节及时发现并通过错误信息精准定位问题而不是让脏数据流入下游系统。4. 高级技巧与避坑指南掌握了基本流程后下面这些实战中总结的技巧和坑点能帮你把这件事做得更稳、更高效。4.1 技巧一使用“JSON Mode”并理解其局限如前所述OpenAI 的response_format: { type: json_object }是一个神器。但它有两个重要限制系统指令中必须明确提示官方文档强调当使用 JSON Mode 时你的系统指令System Prompt里必须包含“输出 JSON”之类的字眼否则 API 可能会报错。它不验证内容只保证格式JSON Mode 只强制模型以{开头生成一个合法的 JSON 对象。至于里面的字段名、类型是否符合你的要求它不管。所以Zod 的后端验证依然是必不可少的。不要以为开了 JSON Mode 就高枕无忧。4.2 技巧二处理复杂嵌套与数组不确定性LLM 在生成数组时有时会多生成有时会少生成。在 Schema 中使用.min(1)、.max(5)或.length(3)可以给出数量上的约束并在 Prompt 中说明。对于可能不存在的数据如我们的actionItems将其定义为.optional()或在 Prompt 中明确“如果没有请设为空数组[]或null”这比让模型完全忽略这个字段更可控。对于深层嵌套对象在 Prompt 中展示一个完整的、正确的示例比千言万语的描述都管用。这就是“少说教多示范”的 Prompt 哲学。4.3 技巧三为模型提供“思考框架”——Chain of Thought对于逻辑复杂的信息提取可以引导模型先“思考”再输出 JSON。这能提升准确率。请按照以下步骤处理会议记录 1. 首先通读全文确定会议核心主题和日期。 2. 其次找出所有提到的人名作为参会者。 3. 然后识别所有包含“决定”、“同意”、“计划”等关键词的句子提取为决议。 4. 接着找出所有包含“负责”、“跟进”、“完成”和日期的任务提取为待办事项。 5. 最后用一句话总结会议核心成果。 完成以上思考后请将结果填入下面的JSON结构中 {...你的JSON Schema描述...}这种“分步思考”的指令尤其适合处理冗长、杂乱的非结构化文本。4.4 避坑一Token 成本与上下文长度复杂的 Zod Schema 转换成文本描述后可能会很长。一个包含几十个字段的 Schema 描述可能就会占用上千个 Token。这会增加API调用成本输入 Token 是要收费的。挤占有效上下文留给会议记录本身的分析空间就少了。可能导致模型“失焦”指令太复杂模型可能无法完全吸收。解决方案精简 Schema 描述只保留最关键的约束如格式、枚举字段类型string/number可以省略模型通常能推断。将 Schema 放在 System Prompt 中对于多轮对话System Prompt 通常只计算一次比放在每轮 User Prompt 中更经济。考虑使用函数调用如果模型支持函数调用的参数 Schema 是以一种更高效的方式传递给模型的。4.5 避坑二模型“幻觉”与字段填充LLM 可能会生成 Schema 中要求的字段但内容却是它“编造”的。例如会议记录里根本没提日期但你的 Schema 要求date字段模型可能会自己猜一个日期填进去。解决方案在 Prompt 中强调“仅基于提供文本”明确指令“请仅基于提供的会议记录提取信息如果文本中没有明确提及则将对应字段设为null或空字符串”。在 Schema 中合理使用.optional()和.nullable()对于可能不存在的关键信息不要强制要求允许它为null。后处理与人工审核对于关键业务数据建立人工审核流程或设计交叉验证机制。4.6 避坑三错误处理与重试策略网络可能超时API 可能限流热词中提到的error code: 429模型输出可能无效。你的代码必须有健壮的错误处理。重试策略示例async function robustLLMCall(prompt, maxRetries 3) { for (let i 0; i maxRetries; i) { try { const result await callLLMAPI(prompt); // 你的调用函数 const validated await parseAndValidate(result); return validated; // 成功则返回 } catch (error) { if (error.status 429) { // 遇到限流 const delay Math.pow(2, i) * 1000 Math.random() * 1000; // 指数退避 console.warn(Rate limited. Retrying after ${delay}ms...); await sleep(delay); continue; } else if (error instanceof z.ZodError) { // 数据验证失败 console.error(Attempt ${i 1}: Schema validation failed., error.errors); if (i maxRetries - 1) throw error; // 最后一次重试也失败则抛出 // 可以尝试微调Prompt后重试例如增加“请严格检查格式”的警告 } else { throw error; // 其他错误直接抛出 } } } }5. 常见问题排查与实战案例即使按照最佳实践操作在实际开发中你还是会遇到各种稀奇古怪的问题。下面这个表格整理了一些典型问题及其排查思路和解决方案。问题现象可能原因排查步骤与解决方案输出不是纯JSON带有额外文本1. Prompt 指令不够强硬。2. 未使用 JSON Mode。3. 模型在“解释”它的输出。1. 在 System Prompt 开头和结尾都强调“输出纯 JSON不要任何其他文字”。2. 启用response_format: { type: json_object }。3. 在 Prompt 中明确说“不要解释直接输出 JSON”。4. 在解析前编写预处理函数去除常见的包裹标记如 json。JSON解析失败SyntaxError1. 输出包含非法字符或格式错误如末尾多逗号。2. 模型输出了非 JSON 文本。1. 使用JSON.parse()前先用try...catch包裹。2. 尝试使用更严格的 JSON 解析库或先进行简单清洗。3. 降低temperature参数值如设为0.1。4. 考虑换用更新、在结构化输出上表现更好的模型如 gpt-4-turbo。Zod验证失败字段类型错误1. 模型将数字生成了字符串如“25”或反之。2. 日期格式不符合正则约束。1. 在 Prompt 中明确类型如“max_temp是一个整数”。2. 在 Zod Schema 中对于可能是字符串的数字使用.transform(val parseInt(val, 10))进行转换或使用.coerce.number()。3. 对于日期提供更明确的格式示例或考虑在后期处理中转换。Zod验证失败缺少必需字段1. 模型忽略了某个字段。2. 输入文本中确实没有该信息。1. 在 Prompt 中将该字段标记为“必需”。2. 检查该字段在示例中是否清晰展示。3. 如果信息可能缺失将该字段改为.optional()。数组内容为空或数量不对1. 模型对“哪些内容属于数组”判断不准。2. 输入文本中相关条目模糊。1. 在 Prompt 中定义更清晰的数组元素识别规则如“所有以‘任务’开头的句子”。2. 使用 Chain of Thought 技巧让模型先列出所有候选再组装。3. 接受数组的不确定性在业务逻辑层处理空数组情况。处理长文本时效果变差1. 复杂 Schema 描述消耗了大量上下文窗口。2. 模型对长距离依赖关系处理能力下降。1.分而治之先将长文本按主题分割Chunk对每部分提取结构化信息再合并。2.摘要优先先让模型对长文本做一个摘要再基于摘要提取结构化信息。3. 使用支持更长上下文的模型如 Claude 200K GPT-4 128K。API返回429速率限制错误请求频率超过 API 限制。1.实现指数退避重试这是必须的如delay (2^重试次数)秒 随机抖动。2. 监控你的 Token 消耗和请求频率。3. 如果是批量作业在请求间加入人工延迟。实战案例从客户邮件中提取支持工单信息假设我们需要从杂乱的客户邮件中自动创建工单。我们定义 Zod Schema 包含customer_name,email,product,issue_description,urgency高/中/低。我们发现模型经常把urgency填错。问题定位Prompt 里只写了“紧急程度”模型对“高/中/低”的理解不一致。解决方案在 Prompt 中提供明确映射“根据邮件语气判断紧急程度包含‘立刻’、‘无法使用’、‘严重’等词视为‘高’包含‘希望尽快’、‘有问题’等词视为‘中’其他视为‘低’。” 同时在 Zod Schema 中使用z.enum([高, 中, 低])进行严格约束。这样指令清晰后端验证也严格准确率得到显著提升。这个过程本质上是一个与模型不断“对齐”的迭代过程。你需要根据验证错误ZodError反馈不断微调你的 Prompt 和 Schema直到达到稳定可用的状态。记住Prompt Engineering 不是一蹴而就的魔法而是结合了清晰的需求分析、严谨的工程约束和持续测试调试的精细手艺。