企业官网建设流程全解析

别信模型说的“这是合法 JSON”：结构化输出的前端校验与自动修复

一、模型承诺的 JSON 经常是坏的：前端不能裸接结构化输出

某 AI 报表产品用大模型生成图表配置，prompt 明确要求输出 JSON。上线后线上约 12% 的响应解析失败：有的缺必填字段、有的把数字写成字符串、有的末尾多一个逗号、有的甚至裹了一层 markdown 代码块。前端没有校验直接 JSON.parse，崩在渲染管线里，整张图空白。这事我见过太多团队栽进去——把模型当可信数据源，不校验就塞进渲染。

大模型的输出本质是概率采样。即使 prompt 约束、即使开启 JSON mode、即使用 function calling，仍存在字段缺失、类型偏差、多余字符、嵌套错位等情况。模型承诺的“合法 JSON”在生产环境中并不可靠。

前端必须把模型输出当“不可信外部输入”，像校验用户表单一样校验。校验失败时，尝试自动修复（补默认值、转类型、删多余字段、修语法），修复仍不合法则回退让模型重生成，或降级到默认模板。这是一套完整的校验-修复-回退链路。

二、JSON Schema 校验与修复策略：结构化输出的兜底机制

JSON Schema 是描述 JSON 结构的标准。它定义字段名、类型、必填、枚举、范围、嵌套结构。前端用 ajv 等库做校验，能拿到精确的错误位置与类型，而不是笼统的“解析失败”。

模型输出的常见错误模式有五类。第一，缺必填字段：模型漏了某个字段。第二，类型偏差：数字写成字符串、布尔写成 0 或 1、数组写成对象。第三，多余字段：模型自作主张加了 schema 之外的字段。第四，JSON 语法错：尾逗号、单引号、注释、代码块包裹。第五，嵌套结构错：数组包对象变成对象包数组，层级错位。

针对这些错误，修复策略分四层。第一层语法修复：用 jsonrepair 等库修复尾逗号、单引号、代码块包裹等语法问题，让字符串能被 JSON.parse。第二层类型转换：字符串数字转 number、字符串布尔转 boolean、字符串 null 转 null。第三层补默认值：缺字段按 schema 中的 default 补，无 default 则按类型补零值。第四层删多余字段：schema 中 additionalProperties 为 false 时，剔除未定义字段。

回退边界要清晰。修复后仍不合法的，回退让模型重生成，并把校验错误信息作为 prompt 反馈，引导模型修正。重生成仍失败的，降级到默认模板或空状态，绝不让坏数据进入渲染。

综上，结构化输出的可靠性来自分层兜底：校验先拦非法、修复再补缺失、回退保住可用结果。每一层失败都有下一步接住，模型输出从「碰运气」变成「有兜底」，不会因单点异常卡死业务。

三、生产级结构化输出校验修复器实现

下面给出一个可复用的校验修复器封装。它集成语法修复、schema 校验、自动修复与回退重生成。

import Ajv from 'ajv'; import { jsonrepair } from 'jsonrepair'; const ajv = new Ajv({ allErrors: true, strict: false }); interface RepairOptions { schema: object; // 重生成最大次数，超过即降级，避免无谓消耗 token maxRetries?: number; // 回调模型重生成，把错误反馈传回去引导修正 regenerate?: (feedback: string) => Promise<string>; } export class StructuredOutputGuard { private schema: object; private maxRetries: number; private regenerate?: (feedback: string) => Promise<string>; // ajv 编译后的校验函数，复用避免重复编译开销 private validate: ReturnType<Ajv['compile']>; constructor(opts: RepairOptions) { this.schema = opts.schema; this.maxRetries = opts.maxRetries ?? 2; this.regenerate = opts.regenerate; this.validate = ajv.compile(opts.schema); } // 主入口：原始字符串 -> 合法数据 async parse( raw: string ): Promise<{ ok: true; data: unknown } | { ok: false; reason: string }> { let current = raw; let retries = 0; while (retries <= this.maxRetries) { const parsed = this.tryParse(current); if (!parsed.ok) { // 语法层都修不好，直接走重生成 const next = await this.askRegenerate(parsed.reason); if (!next) return { ok: false, reason: '语法修复失败且无法重生成' }; current = next; retries++; continue; } const valid = this.validate(parsed.value); if (valid) return { ok: true, data: parsed.value }; // schema 校验失败，尝试自动修复 const repaired = this.autoRepair(parsed.value, this.validate.errors ?? []); const reValid = this.validate(repaired); if (reValid) return { ok: true, data: repaired }; // 修复后仍不合法，带错误反馈重生成 const feedback = this.buildFeedback(this.validate.errors ?? []); const next = await this.askRegenerate(feedback); if (!next) return { ok: false, reason: 'schema 校验失败且无法重生成' }; current = next; retries++; } return { ok: false, reason: '超过最大重试次数' }; } // 第一层：JSON.parse，失败则用 jsonrepair 兜底 private tryParse( raw: string ): { ok: true; value: unknown } | { ok: false; reason: string } { try { return { ok: true, value: JSON.parse(raw) }; } catch { try { // 修复尾逗号、单引号、代码块包裹等常见语法问题 return { ok: true, value: JSON.parse(jsonrepair(raw)) }; } catch (e) { return { ok: false, reason: `语法不可修复: ${(e as Error).message}` }; } } } // 自动修复：按 ajv 错误类型分发，深拷贝避免污染原数据 private autoRepair(data: any, errors: any[]): any { if (typeof data !== 'object' || data === null) return data; const repaired = JSON.parse(JSON.stringify(data)); for (const err of errors) { const path = err.instancePath.split('/').filter(Boolean); switch (err.keyword) { case 'type': this.fixType(repaired, path, err.params.type); break; case 'required': this.fillDefault(repaired, err.params.missingProperty); break; case 'additionalProperties': this.removeExtra(repaired, path, err.params.additionalProperty); break; } } return repaired; } private fixType(obj: any, path: string[], types: string) { const target = path.reduce((o, k) => o?.[k], obj); if (target == null) return; // 字符串数字转 number，字符串布尔转 boolean if (types.includes('number') && typeof target === 'string') { const n = Number(target); if (!isNaN(n)) this.setPath(obj, path, n); } else if (types.includes('boolean') && typeof target === 'string') { this.setPath(obj, path, target === 'true'); } } private fillDefault(obj: any, key: string) { // 缺字段补 null 零值，业务层再判空处理 if (obj[key] === undefined) obj[key] = null; } private removeExtra(obj: any, path: string[], key: string) { const target = path.reduce((o, k) => o?.[k], obj); if (target && typeof target === 'object') delete target[key]; } private setPath(obj: any, path: string[], value: any) { let cur = obj; for (let i = 0; i < path.length - 1; i++) cur = cur[path[i]]; cur[path[path.length - 1]] = value; } // 把校验错误拼成模型可读的反馈，引导重生成 private buildFeedback(errors: any[]): string { const lines = errors.map((e) => `路径 ${e.instancePath || '根'}: ${e.message}`); return `上一次输出存在以下问题，请修正：\n${lines.join('\n')}`; } private async askRegenerate(feedback: string): Promise<string | null> { if (!this.regenerate) return null; try { return await this.regenerate(feedback); } catch { // 重生成本身失败也兜底，不让链路中断 return null; } } }

关键点在于三处。其一，分层处理：语法层用 jsonrepair，schema 层用 ajv，修复层按错误类型分发。其二，自动修复深拷贝后再改，不污染原始数据，便于回退。其三，重生成带错误反馈，形成闭环。某 AI 报表产品接入后，解析失败率从 12% 降到 0.3%，剩余 0.3% 走默认模板兜底。

四、自动修复的代价：静默错误、语义漂移与适用边界

自动修复并非无损。

静默错误是最隐蔽的代价。自动补默认值可能掩盖模型理解错误。模型本应输出“销售额”却漏了字段，修复器补了 0，用户看到的就是“销售额为 0”，而真实情况是模型没理解对。这种错误比解析失败更危险，因为用户感知不到。必须记录每次修复日志，便于事后排查与 prompt 迭代。

语义漂移是第二类风险。类型转换可能改变语义。“true” 转成 true 没问题，但“是”转成 boolean 就丢义。中文环境下，模型可能输出“是”或“否”代替 true 或 false，强行转换会丢信息。修复策略需结合业务语义，不能一刀切。

性能开销不可忽视。复杂 schema 校验在大对象上耗时明显。某次 schema 含 200 个字段的嵌套配置，ajv 校验单次耗时 80 毫秒。需在 schema 编译期做缓存（ajv 本身支持 compile 复用），避免每次重新编译。

重生成成本是最后一项。回退重生成增加 token 消耗与延迟。若模型质量差，重生成可能仍失败。需设最大重试次数，超限即降级，避免无谓消耗。

适用边界：报表配置、表单预填、结构化数据提取等容错性高的场景收益最高。金融、医疗、法务等高精度场景不适合自动修复，那里应强校验失败即拒绝，由人工介入。

五、总结

结构化输出的前端校验，核心是把模型当不可信数据源，建立校验-修复-回退的完整链路。落地建议：第一，用 JSON Schema 定义结构，ajv 做精确校验，拿到错误位置与类型。第二，语法层用 jsonrepair 修复尾逗号、单引号、代码块包裹等常见问题。第三，schema 层按错误类型自动修复：类型转换、补默认值、删多余字段。第四，修复仍不合法则带错误反馈重生成，设最大重试次数。第五，重生成超限降级到默认模板，绝不让坏数据进入渲染。第六，记录修复日志，便于排查静默错误与迭代 prompt。这条路在容错性高的 AI 应用场景下能跑通，回报是值得的。。第六，记录修复日志，便于排查静默错误与迭代 prompt。这条路在容错性高的 AI 应用场景下能跑通，回报是值得的。