为什么只靠 Prompt 一定会翻车
模型生成输出是 token 级别的概率采样。你写了「只输出 JSON 数组」,模型在绝大多数情况下会遵守,但它不会真的「理解」这条规则,只是在训练数据里见过足够多的类似模式。遇到下面这 3 类情况时,程序随时会报错:
模型习惯性回应确认语,JSON.parse 从第一个字符就会直接报错。
要求 line 为正整数,模型却输出 lineNumber 或字符串,静态类型假设失效。
数组生成到一半达到 token 上限,末尾缺少 ]},整段 JSON 无效。
这三类问题靠反复微调 Prompt 无法根治。更稳妥的工程架构是两道防线:Prompt 层降低偏离概率,代码层在偏离发生时有能力检测、提取、校验或重试。缺了任何一道,应用都很脆弱。
通过系统提示词、示例或服务端 output_config.format,把格式约束尽可能前移。
用 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 用法
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;
}