AI Agent Guide 交互版
第一阶段 · LLM 工程基础 含 3 个交互实验台 · 涵盖 Zod Schema、原生约束与重试流水线

Prompt 工程实战:结构化输出与结果校验

上一章讲了如何用 Prompt 要求模型「只输出 JSON」。这个方向没问题,但有一个根本性的限制:Prompt 是概率约束,不是确定性保障。面对真实生产环境,你需要用代码层构建检测、修复与重试防线。

30 秒版 · 只记这 3 句 实验台模拟模型典型翻车模式
  1. 01 只靠 Prompt 要求 JSON 一定会翻车,必须有 Schema 校验兜底。
  2. 02 用 Zod 定义唯一 Schema,同时拿到 TS 类型、校验和字段级报错。
  3. 03 output_config.format 先确认端点兼容性,不兼容就切 Tool Use。

为什么只靠 Prompt 一定会翻车

模型生成输出是 token 级别的概率采样。你写了「只输出 JSON 数组」,模型在绝大多数情况下会遵守,但它不会真的「理解」这条规则,只是在训练数据里见过足够多的类似模式。遇到下面这 3 类情况时,程序随时会报错:

偏离 01 · 前置确认
输出前加了一句废话

模型习惯性回应确认语,JSON.parse 从第一个字符就会直接报错。

好的,以下是评审结果: ```json {"summary":"..."} ```
偏离 02 · 字段飘移
字段名或类型偷偷变了

要求 line 为正整数,模型却输出 lineNumber 或字符串,静态类型假设失效。

{"line_number": 12, "score": 120}
偏离 03 · 截断未闭合
长输出触发 max_tokens

数组生成到一半达到 token 上限,末尾缺少 ]},整段 JSON 无效。

{"issues":[{"type":"bug","line":49

这三类问题靠反复微调 Prompt 无法根治。更稳妥的工程架构是两道防线:Prompt 层降低偏离概率,代码层在偏离发生时有能力检测、提取、校验或重试。缺了任何一道,应用都很脆弱。

第一道防线 · Prompt / 原生约束
降低格式偏离的概率

通过系统提示词、示例或服务端 output_config.format,把格式约束尽可能前移。

→
第二道防线 · 代码层 Schema 校验
确定性地拦截、修复与重试

用 extractJson() + JSON.parse() + Zod safeParse() 把不稳定文本拉回类型安全。

先把期望格式说清楚:Zod Schema

写任何校验或重试逻辑之前,先用代码把「期望的输出格式」表达出来。在 TypeScript 里最合适的是 Zod:用一份 Schema 同时得到 TypeScript 类型、运行时校验与清晰的字段级报错。生产代码里优先使用 safeParse() 而不是 parse(),因为你永远不知道模型下一轮会返回什么。

Zod 方法 用途 示例
z.object({}) 定义对象结构与必填字段 z.object({ summary: z.string() })
z.enum([...]) 限定字符串只能取枚举值之一 z.enum(["bug", "style", "performance", "security"])
z.number().int().positive() 约束整数且大于 0 用于代码行号 line,防止负数或小数
z.optional() / z.catch() 允许字段缺失,或校验失败时降级为默认值 z.array(ReviewIssue).catch([])
查看 ReviewResult Schema 定义与 safeParse 用法
review-schema.ts
import { z } from "zod";

const ReviewIssue = z.object({
  type: z.enum(["bug", "style", "performance", "security"]),
  line: z.number().int().positive(),
  message: z.string().min(1),
  suggestion: z.string().optional(),
});

const ReviewResult = z.object({
  summary: z.string(),
  issues: z.array(ReviewIssue),
  score: z.number().min(0).max(100),
});

type ReviewResult = z.infer<typeof ReviewResult>;

// 生产代码优先用 safeParse(),失败时不抛异常而是返回结构化 issues
const parsed = ReviewResult.safeParse(rawOutput);
if (!parsed.success) {
  console.error("解析失败:", parsed.error.issues);
} else {
  const result: ReviewResult = parsed.data;
}
交互实验台 01 · 代码层防线透视

JSON 提取、语法解析与 Zod Schema 双层校验

选择典型模型偏离样本或直接编辑左侧原始输出,观察 extractJson → JSON.parse → safeParse 三步如何逐层拦截。

故障预设:
模型原始输出(可自由编辑测试) 0 字符
1. extractJson(raw) 正则提取 —
2. JSON.parse(jsonStr) 语法解析 —
3. ReviewResult.safeParse() 类型校验 —

进阶能力:output_config.format 与兼容端点真相

前面讲的 Zod 校验是在模型输出之后做检查。在支持原生结构化输出的模型服务里,你还可以通过 Anthropic SDK 的 client.messages.parse() 传入 output_config.format,把 JSON Schema 直接提交给服务端(Anthropic Structured Outputs 文档)。

工程上记住一个优先级:如果模型服务原生支持严格的 response format,优先使用它;手动解析和重试是兼容端点不支持时的通用兜底。但这里有一个关键坑点:兼容 Anthropic API,不等于支持 Anthropic 的所有高级参数。

以阿里云百炼 Anthropic 兼容端点为例,官方文档明确区分了模型行为:DeepSeek、GLM 等部分模型会严格遵守 JSON Schema;而 Qwen 会退化为普通 JSON 模式,只保证返回合法 JSON,Schema 的字段约束默认不生效。另外,DeepSeek 官方 Anthropic 兼容端点文档写明 output_config 只支持 effort 参数。

兼容端点接入原则
不要因为请求没有报 400 错误就以为服务端执行了 Schema 约束。只要涉及多模型切换或兼容端点,本地仍须保留 Zod 校验与重试逻辑。
查看完整示例:bailian-output-format.ts 与 parseOutput() 重试封装
structured-output-sync.ts(参数随实验台 02 实时联动)
import Anthropic from "@anthropic-ai/sdk";
import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod";

const client = new Anthropic();
const MODEL = process.env.MODEL ?? "qwen-plus";

// 1. 原生 output_config.format(服务端支持严格 Schema 时首选)
const response = await client.messages.parse({
  model: MODEL,
  max_tokens: 2048,
  messages: [{ role: "user", content: `请评审以下代码:\n${code}` }],
  output_config: {
    format: zodOutputFormat(ReviewResult),
  },
});

// 2. 万能兜底:手动提取 + Zod 校验 + 重试(兼容任意文本模型)
const result = await parseOutput(
  [{ role: "user", content: `评审代码:${code}` }],
  ReviewResult,
  { maxRetries: 2, withFeedback: true }
);

完整可运行源码:bailian-output-format.ts · parse-with-retry.ts

交互实验台 02 · 端点差异与重试流水线

兼容端点行为模拟与带错误反馈重试

先做一次直觉预测,再切换不同模型服务与重试策略,观察 parseOutput() 如何把 Zod 报错喂回模型完成自愈。

先猜再看 通过百炼 Anthropic 兼容端点调用 qwen-plus 并传入 output_config.format,若模型漏掉必填字段 score,会发生什么?
模型服务与端点能力
本地重试策略(同步更新上方代码)

流式 JSON 消费与 Tool Use 备选方案

面对长文件评审时,等全部内容生成完再返回会让用户盯着空白屏。Anthropic SDK 支持在 messages.stream() 中同时传入 output_config.format:流式过程中把文本片段实时推给前端,流结束后再从 stream.finalMessage() 读取校验好的 parsed_output。

注意一个关键边界:parsed_output 仍然是在整条流结束后才产出的。如果你的业务必须「模型每发现一条问题,前端立刻渲染出一张可交互卡片」,那么可以考虑 NDJSON(Newline Delimited JSON),即让模型每行输出一个独立 JSON 对象,前端按换行符切分并逐行 JSON.parse()。不过 NDJSON 对提示词更敏感,只建议作为逐条消费场景的备选协议。

此外,在原生结构化输出普及之前,工程上广泛使用 Tool Use / Function Calling 承载结构化结果(Anthropic Define Tools · OpenAI Structured Outputs):定义一个虚拟工具 submit_review,用 tool_choice 强制模型调用它,再从 tool_use.input 取出结构化参数交由 Zod 校验。这套模式在 Agent 章节中依然是核心机制。

查看流式 output_config.format 与 Tool Use 强制调用示例
streaming-and-tool-use.ts
// 方案 A:流式 output_config.format(用户看过程,代码拿最终 parsed_output)
const stream = client.messages.stream({
  model: MODEL,
  max_tokens: 2048,
  messages: [{ role: "user", content: prompt }],
  output_config: { format: zodOutputFormat(ReviewResult) },
});

stream.on("text", (text) => process.stdout.write(text));
const message = await stream.finalMessage();
const finalResult = message.parsed_output;

// 方案 B:Tool Use 虚拟工具承载结构化结果
const res = await client.messages.create({
  model: MODEL,
  max_tokens: 2048,
  tools: [{
    name: "submit_review",
    description: "提交代码评审结果",
    input_schema: { type: "object", properties: { /* ... */ }, required: ["summary", "issues", "score"] },
  }],
  tool_choice: { type: "tool", name: "submit_review" },
  messages: [{ role: "user", content: `评审代码:${code}` }],
});
const toolUse = res.content.find((c) => c.type === "tool_use");
if (toolUse?.type === "tool_use") {
  const checked = ReviewResult.parse(toolUse.input);
}

流式完整源码:bailian-streaming-output-format.ts

交互实验台 03 · 流式消费对比

整体 JSON 流式等待 vs NDJSON 逐行即时渲染

点击开始流式传输,直观对比两种协议在 token 到达过程中的前端消费时机差异(模拟流式输出)。

原始 Token 流(SSE text delta) 就绪
点击「▶ 开始流式传输」观察 token 到达过程...
parsed_output 对象消费状态 0 条已解析
等待数据流...

选哪条路:工程决策矩阵

实际选型时,不需要在所有项目里强行使用同一种方案,按模型服务能力与业务消费形态做判断即可:

业务与模型场景 推荐方案 关键原因
模型服务严格支持 output_config.format / response_format 原生结构化输出 格式约束前移到服务端,首轮成功率最高
模型不支持原生格式约束,但支持 Tool Use Tool Use + Zod 校验 利用 tool_choice 强制填参,兼容 Agent 工具链
服务只保证合法 JSON,或需要跨多模型迁移 JSON 提取 + Zod + 带反馈重试 最可迁移的通用兜底防线
长输出,用户需要看过程、代码只需最终对象 流式 output_config.format 兼顾交互体验与最终 parsed_output 类型安全
数组输出,前端必须每生成一条就渲染一条 NDJSON 逐行解析 唯一能做到无等待逐条消费对象的轻量协议

当输出格式的确定性问题通过「原生约束 + 代码校验 + 反馈重试」解决之后,决定生成质量上限的下一个瓶颈就会转移到输入侧:你喂给模型的上下文里到底该放什么、不该放什么,以及多轮对话如何避免窗口失控。这就是下一章 Context Engineering 要解决的问题。