知序
返回
保存草稿
发布
H1
H2
H3
1
2
3
Excalidraw 图
AI 写作
AI 优化
目录
输入内容后显示目录
Markdown
# 结构化输出与 Function Calling 工程化 > 导读:本文从"我已经在 Prompt 里写了'请返回 JSON',为什么线上还是天天解析失败?"这个实际开发中的疑问出发,把"让模型返回 JSON 为什么不可靠、三种实现路径怎么选、JSON Schema 怎么设计、解析与校验如何工程化、Function Calling 的完整流程与安全边界、流式场景下的结构化输出怎么办"逐项讲透,最后给出可运行示例与踩坑清单。适合需要把大模型(LLM,Large Language Model,大语言模型)输出接入业务逻辑、做"模型 → 代码"数据管道的 Java / Python 后端与算法工程师。 ## 一、先建立全局认知 ### Q:为什么"让模型返回 JSON"本质上不可靠? A:结论先行——**大模型是概率生成器(逐个 token 采样),它生成的是"看起来像 JSON 的文本",而不是"结构化的数据";只要有一个字符错位、多一个逗号、少一个引号,整段就解析失败。** 这不是模型"不听话",而是生成机制决定的必然现象。 要真正理解这件事,先看模型是怎么"写"JSON 的:  *图:逐 token 预测:模型如何拼出这段 JSON* ```text 你想要的:{"name":"张三","age":30} 模型实际做的事:预测下一个 token "{" ← 概率最高的开头 "\"name\"" ← 接着预测 ":" ← 接着预测 "\"张三\"" "," "\"age\"" ":" "30" ← 也可能预测出 "30岁" / "三十" / "thirty" "}" ← 也可能忘了闭合,或补个尾随逗号 ``` 每一次采样都带随机性,链条越长出错概率越高。于是你会看到这些"格式漂移"的典型症状: | 症状 | 表现 | 根因 | |---|---|---| | 包裹说明文字 | `好的,结果是:{...}` | 模型把 JSON 当普通文本,前后加了解释 | | Markdown 代码块 | ` ```json {...} ``` ` | 训练数据里 JSON 常被代码块包裹 | | 尾随逗号 / 单引号 | `{"a":1,}` / `{'a':1}` | 非法但在聊天语境里"看起来对" | | 字段名漂移 | 你写 `user_name`,它给 `userName` | 没有强约束,模型按语义"合理"发明 | | 类型不稳 | 数字给成字符串 `"30"` | 语义上都是"30",模型不区分类型 | | 截断 | 少一个 `}` | 撞到 `max_tokens` 上限,`finish_reason=length` | | 空值风格不一 | `null` / `""` / `"无"` / 直接省略 | 无 schema 约束时的自由发挥 | 所以,"在 Prompt 里加一句'请只返回 JSON'"只是**降低**了出错率,远没有**消除**它。工程上必须把"结构约束"从"文字请求"升级为"协议约束",并把"解析失败"当作**一等公民异常**来设计重试与兜底。 **一个必须记住的原则**:无论用哪种方式拿到结构化数据,**模型输出永远是不可信输入**,必须当作"外部用户输入"来校验,绝不直接反序列化成对象后就信任它。 ### Q:三种实现路径是什么?能力与可靠性怎么对比? A:结论先行——**Prompt 约束只是"请求"、JSON Mode 只保证"是合法 JSON"、Structured Outputs / Function Calling 才能"按 schema 约束";按可靠性从低到高选,业务越是强一致,越要往后两种靠。** 三种(严格说是四类)路径的定位: | 路径 | 机制 | 保证合法 JSON | 保证符合 schema | 稳定性 | 往返成本 | 典型场景 | |---|---|---|---|---|---|---| | Prompt 约束 | 在提示里要求格式 + 给示例 | 否 | 否 | 最低 | 无 | 快速验证、兜底、对结构要求低 | | JSON Mode | 服务端约束输出为合法 JSON(如 `response_format: {"type":"json_object"}`) | 是(供应商支持时) | 否 | 中 | 无 | 只要"合法 JSON"、字段简单 | | Structured Outputs | 按 JSON Schema 约束(如 `response_format: {"type":"json_schema",...}`,`strict`) | 是 | 是(受支持子集内) | 高 | 无 | 字段固定、强一致的数据管道 | | Function Calling / Tool Use | 模型输出 `tool_calls`,参数按函数 schema 生成 | 是 | 是(`strict` 时) | 高 | 多一次往返 | 需要执行动作、参数即结构 | 几点关键取舍: - **JSON Mode 只保证"是 JSON",不保证"字段对"**。它解决了"多一个逗号、前后加话"的问题,但字段名、类型、嵌套结构仍可能漂移。部分供应商的 JSON Mode 还要求提示里出现"JSON"字样,**具体约束需结合版本确认**。 - **Structured Outputs 用 JSON Schema 约束解码过程**,理论上能保证结构与 schema 一致,但只支持 JSON Schema 的一个**子集**,且对 schema 写法有硬性要求(见下一节),而且**支持它的模型与供应商是有限的,需结合版本确认**。 - **Function Calling 更适合"要调工具"的场景**,它把"结构"表达成"函数参数"。如果只是想要一段结构化数据、并不需要调用外部函数,用 Structured Outputs 往往更直接。 - 三者不是互斥的:可以用 **Prompt 约束兜底 + JSON Mode 保证合法性 + 本地 schema 校验**组合,在供应商能力不足时也能拿到一个可用的稳定版本。 ## 二、理解核心机制:Schema 设计与校验 ### Q:三种约束方式在请求里分别怎么写? A:结论先行——**它们其实是"同一个接口、换不同参数":Prompt 约束靠提示词,JSON Mode 靠 `response_format` 的类型开关,Structured Outputs 靠 `response_format` 里的 JSON Schema,Function Calling 则把结构放进 `tools`。** 因此你可以逐步升级约束强度而不动调用链路。以下字段名以 OpenAI 兼容接口为例,**其他供应商的字段名与限制可能不同,需结合版本确认**。 Prompt 约束(只靠提示词,无协议保证): ```text 你是信息抽取器。只输出一个 JSON 对象,不要任何解释、不要 Markdown 代码块。 字段定义: order_id string 订单号,原样返回 amount string 金额,两位小数的十进制字符串 currency "CNY" | "USD" | "EUR" ``` JSON Mode(保证"是合法 JSON"): ```json { "model": "your-model", "messages": [ {"role": "user", "content": "从下面文本抽取订单信息,输出 JSON:...文本..."} ], "response_format": {"type": "json_object"} } ``` 注意两点:部分供应商要求提示词里**必须出现 "JSON" 字样**,否则直接报错;JSON Mode **只保证 JSON 合法,不保证字段符合你的定义**。 Structured Outputs(按 JSON Schema 约束): ```json { "model": "your-model", "messages": [{"role": "user", "content": "从下面文本抽取订单信息:...文本..."}], "response_format": { "type": "json_schema", "json_schema": { "name": "order_draft", "strict": true, "schema": { "type": "object", "additionalProperties": false, "required": ["order_id", "amount", "currency"], "properties": { "order_id": {"type": "string"}, "amount": {"type": "string"}, "currency": {"type": "string", "enum": ["CNY", "USD", "EUR"]} } } } } } ``` Function Calling 把同一份 schema 放进 `tools[].function.parameters`(见第三节示例)。三条路可以叠加:**Prompt 约束 + JSON Mode 保合法性 + 本地 schema 校验**,是在供应商能力不足时最务实的一档。 ### Q:JSON Schema 怎么设计?常见坑有哪些? A:结论先行——**Schema 要"窄而明确":字段少、类型固定、枚举穷举、避免深层嵌套、ID 与金额用字符串;要清楚 strict 模式对 `required` 与 `additionalProperties` 的硬要求,否则模型不会按你想的约束。** 先看一份"踩坑版"和"修正版"的对比: ```json // ❌ 踩坑版:可选字段、裸 number、中文键、深层嵌套 { "type": "object", "properties": { "订单信息": { "type": "object", "properties": { "金额": {"type": "number"}, "用户": {"type": "object", "properties": {"备注": {"type": "string"}}} } } } } ``` ```json // ✅ 修正版:ASCII 键、金额与 ID 用 string、枚举穷举、嵌套扁平化 { "type": "object", "additionalProperties": false, "required": ["order_id", "amount", "currency", "status"], "properties": { "order_id": {"type": "string", "description": "订单号,原样返回,不要改造"}, "amount": {"type": "string", "description": "金额的十进制字符串,如 \"12.50\""}, "currency": {"type": "string", "enum": ["CNY", "USD", "EUR"]}, "status": {"type": "string", "enum": ["pending", "paid", "cancelled"]}, "remark": {"type": ["string", "null"]} } } ``` 逐个坑说明: 1. **可选字段**:strict 模式通常要求**所有字段都放进 `required`**,"可选"要用**可空类型**(`["string","null"]`)表达,而不是"不写进 required"。这是新手最常踩的一条,**具体要求需结合所用供应商版本确认**。 2. **`additionalProperties: false`**:strict 模式一般要求对象上显式声明它,否则模型可以自由加字段。加上它,等于堵死字段漂移。 3. **枚举**:能用枚举就别用自由字符串。`status` 用 `enum` 后,模型不会给你编出 `"已支付"` 这种没定义的值;但仍要**在本地按未知枚举兜底**(见下文 Jackson 处理)。 4. **数字精度**:ID、金额、时间戳这类**不要用 `number` / `integer`**。JSON 数字在不同语言反序列化时可能丢精度(如超长整数、浮点尾数),而且模型可能把 `12.50` 写成 `12.5` 或 `"12.50"`。**统一用 `string` 承载,本地再按 `BigDecimal` / 字符串解析**。 5. **中文键**:JSON 本身支持 UTF-8,中文**值**没问题,但中文**键**会带来映射麻烦、工具兼容问题和模型抄写错误。**键一律用 ASCII 蛇形命名**,中文放进 `description`。 6. **嵌套**:嵌套越深,模型出错面越大、模型对深层结构的遵循度越差。**优先扁平化**,不得已再用一层嵌套,并给每一层都设 `required` + `additionalProperties: false`。 7. **描述(description)**:schema 里的 `description` 是给模型的"字段说明书",要写清"取什么、什么格式、原样还是改写"。它直接影响抽取质量,值得认真写。 8. **不要用 `oneOf` / 复杂条件**:strict 模式对 JSON Schema 的支持是子集,`oneOf`、条件关键字等不一定支持,**需结合版本确认**,能用 `enum` 和可空类型解决的不要上复杂组合。 ### Q:什么是 schema 收敛?什么时候需要它? A:结论先行——**schema 收敛是指:当模型输出结构长期不稳定时,通过"缩小字段范围、明确枚举、补示例与描述、限制自由度、固定模型版本"等手段,把输出结构逐步收敛到一个稳定、可长期依赖的 schema。** 它解决的是"模型总在边缘情况上给你惊喜"。 出现这些信号,就该做收敛了:解析失败率长期偏高;同一个字段名时而 `user_id` 时而 `userId`;枚举总是多出未定义值;嵌套层级时深时浅;换个输入就换一套字段。 收敛手段按成本递增: | 手段 | 做法 | 效果 | |---|---|---| | 缩小 schema | 字段越少越好,能拆成多次抽取就拆 | 出错面直接变小 | | 明确枚举 | 所有离散值用 `enum` 穷举 | 消灭自由发挥 | | 给示例 | 提示里放 1~2 组"输入 → 正确 JSON" | 明显提升遵循度 | | 补描述 | 每个字段写清"取什么、什么格式、原样还是改写" | 减少语义歧义 | | 固定模型版本 | 不用"最新",锁定具体版本 | 防止升级漂移 | | 升级约束 | 从 Prompt 约束升到 JSON Mode / Structured Outputs | 协议级兜底 | 关键取舍:**收敛的目标是"少而稳",不是"全而美"。** 一个只有 4 个必填字段的 schema,远比一个 20 字段、一半可选、三层嵌套的 schema 稳定。宁可分多次抽取、在服务端组合结果,也不要把所有字段塞进一次调用——**字段每多一个,模型犯错的面就大一分**。 ### Q:拿到输出后,解析与校验怎么工程化? A:结论先行——**解析要"宽容但不将就":先用宽容模式尽量把脏 JSON 修出来,再用严格校验判定是否可用;不可用就带着错误信息重试,重试仍失败再降级。** 校验分两层:结构校验(能否反序列化)与业务校验(值是否合理)。 一个稳健的处理管线: ```text 模型原始输出 │ ├─ 1. 清洗:剥掉 ```json 代码块、去掉前后说明文字、截取第一个 { 到最后一个 } │ ├─ 2. 宽容解析:允许单引号、无引号键、尾随逗号(仅用于"救回来",不作为常态) │ ├─ 3. 结构校验:反序列化为 DTO + Bean Validation(必填、范围、枚举) │ ├─ 4. 业务校验:金额是否为正、状态流转是否合法、ID 是否存在 │ └─ 任一步失败 → 携带"原始输出 + 具体错误"重试(最多 N 次) ↓ 仍失败 降级:返回固定结构 / 转人工 / 抛业务异常 ``` **Java 侧的宽容解析**(Jackson 提供了若干"宽容"开关,仅用于 try-repair,不要全局开启): ```java // 场景:模型偶尔返回单引号或尾随逗号,用宽容 ObjectMapper 尝试救回 ObjectMapper lenient = JsonMapper.builder() .enable(JsonReadFeature.ALLOW_SINGLE_QUOTES) .enable(JsonReadFeature.ALLOW_UNQUOTED_FIELD_NAMES) .enable(JsonReadFeature.ALLOW_TRAILING_COMMA) .build(); public Optional<OrderDraft> tryParse(String raw) { String cleaned = stripCodeFence(raw); // 去掉 ```json ... ``` try { return Optional.of(lenient.readValue(cleaned, OrderDraft.class)); } catch (Exception e) { log.warn("parse failed: {}", e.getMessage()); // 不要把原始输出全量打进日志(可能含隐私) return Optional.empty(); } } ``` **Java 侧的结构校验**(Jackson + Bean Validation): ```java // DTO:字段名与 schema 对齐;枚举提供 unknown 兜底 public class OrderDraft { @JsonProperty("order_id") @NotBlank @Size(max = 64) private String orderId; @JsonProperty("amount") @NotBlank @Pattern(regexp = "^-?\\d+(\\.\\d{1,2})?$") // 金额必须是十进制字符串 private String amount; @JsonProperty("currency") @NotNull @JsonEnumDefaultValue // 未知枚举值落为 UNKNOWN private Currency currency; @JsonProperty("status") @NotNull @JsonEnumDefaultValue private OrderStatus status; // getter / setter 省略 } ``` 配合校验器使用: ```java // 场景:结构合法 + 业务规则都过了,才允许进入后续流程 private static final Validator VALIDATOR = Validation.buildDefaultValidatorFactory().getValidator(); public OrderDraft validateOrThrow(OrderDraft dto, String rawModelOutput) { Set<ConstraintViolation<OrderDraft>> errors = VALIDATOR.validate(dto); if (!errors.isEmpty()) { String msg = errors.stream() .map(v -> v.getPropertyPath() + ":" + v.getMessage()) .collect(Collectors.joining("; ")); throw new SchemaValidationException(msg, rawModelOutput); // 携带原文供重试 } // 再叠加业务校验:金额>0、状态白名单、ID 存在性等 return dto; } ``` 几条容易被忽略的细节: - **`@JsonEnumDefaultValue` 需要开启 `DeserializationFeature.READ_UNKNOWN_ENUM_VALUES_USING_DEFAULT_VALUE`**,否则未知枚举值仍会抛异常;且默认值的枚举常量命名要有约定(如 `UNKNOWN`)。 - **未知字段策略**:Spring Boot 自动配置的 `ObjectMapper` 默认关闭 `FAIL_ON_UNKNOWN_PROPERTIES`,而**裸 Jackson 默认为开启**。这意味着**同一份 DTO 在 Spring 里能反序列化、脱离 Spring 跑单测却抛异常**。要么统一配置,要么在 DTO 上用 `@JsonIgnoreProperties(ignoreUnknown = true)` 明确表态。 - **宽容解析是"救济手段"不是"常态"**:如果宽容解析的命中率很高,说明上游结构约束没做好,应该回去收紧 schema,而不是长期依赖修复。 - **修复(repair)策略**:修复分两类——**本地规则修复**(剥代码块、去尾逗号、转义引号)和**模型修复**(把原始输出 + 错误信息再发一轮让模型自己改)。本地修复快而免费,模型修复准而贵,建议"先本地、后模型、最多 1~2 次"。 - **重试要带错误上下文**:只把原 prompt 再发一遍,模型大概率还是错;把"你上次的输出违反了 X,请修正"一并给它,成功率明显更高。 ## 三、Function Calling 完整流程 ### Q:Function Calling 的完整流程是什么?幂等、超时、权限要注意什么? A:结论先行——**Function Calling 是"两次(或多次)模型调用 + 本地执行"的闭环:模型返回 `tool_calls`(只有意向和参数,不会真的执行)→ 本地校验参数后执行 → 把结果作为 `tool` 消息回填 → 再次调用模型得到最终回答。** 它不是"模型帮你调函数",执行权和风险始终在你这边。 完整流程:  *图:Function Calling 两次请求的完整往返* ```text 第 1 次请求:messages + tools(函数定义) │ ▼ 模型返回:finish_reason = "tool_calls" message.tool_calls = [ { id:"call_1", type:"function", function:{ name:"get_weather", arguments:"{\"city\":\"上海\"}" } } ] │ ← 注意:arguments 是"字符串形式的 JSON",不是对象 ▼ 本地:参数校验 → 执行函数 → 得到结果 │ ▼ 第 2 次请求:把 assistant(tool_calls) 与 tool(结果) 一起追加进 messages │ ▼ 模型返回:最终自然语言回答(finish_reason="stop") ``` 工具定义(示意): ```json { "tools": [{ "type": "function", "function": { "name": "get_weather", "description": "查询指定城市的当前天气", "strict": true, "parameters": { "type": "object", "additionalProperties": false, "required": ["city"], "properties": { "city": {"type": "string", "description": "城市名,如 上海"} } } } }], "tool_choice": "auto" } ``` 回填结果时的消息结构(关键:`tool_call_id` 必须与发起调用时的 `id` 一一对应): ```json [ {"role": "user", "content": "上海今天天气怎么样?"}, {"role": "assistant", "content": null, "tool_calls": [{"id": "call_1", "type": "function", "function": {"name": "get_weather", "arguments": "{\"city\":\"上海\"}"}}]}, {"role": "tool", "tool_call_id": "call_1", "content": "{\"temp\":26,\"desc\":\"多云\"}"} ] ``` Java 侧的本地执行骨架: ```java // 场景:模型请求调用工具 → 本地按白名单派发 → 回填结果 public List<ToolResult> executeToolCalls(List<ToolCall> calls, CallContext ctx) { List<ToolResult> results = new ArrayList<>(); for (ToolCall call : calls) { String name = call.getFunction().getName(); try { ToolHandler handler = registry.get(name); // 只允许注册过的工具 if (handler == null) { results.add(ToolResult.error(call.getId(), "unknown tool: " + name)); continue; } if (!ctx.hasPermission(handler.requiredScope())) { // 权限边界 results.add(ToolResult.error(call.getId(), "permission denied")); continue; } JsonNode args = objectMapper.readTree(call.getFunction().getArguments()); handler.validateArgs(args); // 参数不可信,必须校验 Object out = idempotent(call.getId(), () -> handler.execute(args, ctx)); results.add(ToolResult.ok(call.getId(), objectMapper.writeValueAsString(out))); } catch (Exception e) { results.add(ToolResult.error(call.getId(), "execution failed")); // 用错误文本回填,让模型继续 } } return results; } ``` **三条安全与可靠性纪律:** 1. **幂等(Idempotency)**:模型可能对同一意图重复发起同名调用(尤其在多轮里)。以 `tool_call_id` 作为执行去重键,对写操作再叠加业务幂等键(如订单号 + 操作类型),保证重复执行不产生重复副作用。 2. **超时(Timeout)**:工具执行要有独立超时,且**总耗时 = 模型 N 次往返 + 工具 M 次执行**,容易超过一个普通接口的预算。工具超时后要返回**可解释的错误文本**给模型(让它决定继续还是放弃),而不是直接抛出堆栈。 3. **权限(Permission)**:**工具是一个真实的安全边界**。必须做工具白名单、参数校验、最小权限(工具只能访问它该访问的资源)、以及敏感操作二次确认/人工审批。绝不允许"模型给什么参数就执行什么"——SQL 拼接、文件路径、外部 URL 都是典型注入面。 ### Q:工具(函数)本身怎么设计才好用? A:结论先行——**函数名要语义明确、描述要写清"何时调用",参数 schema 要窄而必填,返回结果要短且结构化;工具数量不是越多越好,越少越精越稳。** - **函数名**:动宾结构、下划线命名,如 `get_weather`、`create_order`,别用 `func1` / `do_stuff` 这类无信息量的名字。 - **description**:它是写给模型看的"说明书",必须回答"这个工具做什么、什么时候该用、什么时候不该用"。**模型选错工具,八成是描述没写清楚**,而不是模型笨。 - **parameters**:与数据 schema 相同的纪律——必填、枚举穷举、ID 与金额用字符串;`strict: true` 时同样要求 `additionalProperties: false` 与全量 `required`。 - **返回结果**:回填给模型的工具结果应**短小、结构化、无冗余**,只含模型决策所需信息。不要把整张数据库行塞回去——既费 token 又稀释重点。 - **数量控制**:一次暴露的工具越少,模型选错的概率越低;工具很多时按场景拆分工具集,而不是一股脑全塞进 `tools`。 - **错误也回填**:工具执行失败时,把"简短可读的错误原因"作为 `tool` 消息回填,让模型有机会换工具或给出解释,而不是直接中断整个流程。 ### Q:流式场景下的结构化输出怎么做? A:结论先行——**流式下你拿到的是"越来越长的 JSON 片段",在完整之前它不是合法 JSON,不能边收边 `readValue` 除非用增量解析器。** 两种务实策略:**要么等收完再解析(最稳),要么明确只对"支持增量解析的字段"做实时展示。** 流式结构化输出的核心难点是"不完整": ```text chunk1: {"order_id":"A chunk2: 123","amount":"1 chunk3: 2.50","status":"pa chunk4: id"} ``` 在 chunk1 到达时,这不是合法 JSON,任何严格解析器都会失败。应对方式: 1. **缓冲 + 收尾解析(推荐默认)**:把增量片段累积到 `StringBuilder`,收到 `[DONE]` 或 `finish_reason` 后再统一解析与校验。**稳定性最高,代价是失去"逐字段实时展示"**。绝大多数场景这就够了。 2. **增量解析(需要实时展示时)**:维护一个"部分的 JSON"解析器,能在流式过程中尽量抽出已经闭合的字段。实现上有两条路:一是引入支持流式/部分解析的库;二是把结构简化(例如让模型先只输出一个正在生成的字符串字段),降低实时解析难度。**需结合所选库与供应商对结构化流式的支持情况确认。** 3. **结构化与展示分流**:让模型同时产出"给人看的自然语言"和"给机器用的 JSON"两段(或分两次调用),展示走流式、结构化走收尾解析,避免为一个场景牺牲另一个。 一个缓冲收尾的实现骨架: ```java // 场景:流式接收结构化 JSON,累积完成后再解析校验 public Mono<OrderDraft> streamToObject(String prompt) { StringBuilder buffer = new StringBuilder(); return llmClient.stream(prompt) .doOnNext(buffer::append) .then(Mono.fromCallable(() -> { String raw = stripCodeFence(buffer.toString()); OrderDraft dto = lenient.readValue(raw, OrderDraft.class); return validateOrThrow(dto, raw); })); } ``` 要点:**流式的 `finish_reason` 与结束标记要和结构化校验联动**——如果是 `length` 截断,多半 JSON 不完整,此时应判断为"需要重试/调大 `max_tokens`",而不是当成普通解析失败。另外,**流式 UI 上不要过早渲染"半截 JSON"**,否则用户会看到跳变的乱码,体验反而更差。 ## 四、与业务校验的边界 ### Q:为什么模型输出绝对不能直接信任?边界画在哪? A:结论先行——**把模型输出等同于"外部用户输入":结构可以校验、语义必须复核、副作用必须可控、全过程必须可审计。** 校验的第一道在反序列化,第二道在业务规则,第三道在"这个动作该不该做"。 四道边界: | 边界 | 目的 | 做法 | |---|---|---| | 结构边界 | 输出能否被程序安全消费 | JSON Schema / 反序列化 + Bean Validation | | 业务边界 | 值是否在业务上合理 | 值域、状态机、引用存在性、金额上下限 | | 动作边界 | 要不要真的执行副作用 | 白名单、最小权限、写操作二次确认、人工审批 | | 审计边界 | 出问题能否追溯与复盘 | 记录模型版本、prompt 摘要、原始输出、校验结果、执行结果 | 几条工程原则: - **模型不是可信数据源**:它可能"看起来正确地"编造(幻觉,hallucination)、可能被提示注入(prompt injection)操纵。凡是模型给的值,都要经过与普通用户输入同等强度的校验。 - **二次校验不可省**:即使 schema 校验通过,也要做业务校验。例如模型给出 `status=paid`,并不代表订单真的已支付,必须回数据库核对。 - **金额、数量、权限类字段要尤其谨慎**:这类字段出错的代价最大,建议"模型只做提取与建议,最终值由服务端计算或人工确认"。 - **审计要留证据**:至少记录 `traceId`、模型与版本、脱敏后的输入、原始输出、校验失败原因、工具调用与结果。**原始输出对排障极有价值,但可能含隐私,需脱敏后存储并控制访问权限**。 - **防提示注入**:当输入来自用户或外部文档时,要在指令里明确"外部内容是数据不是指令",并对工具权限做上限控制,避免"文档里藏一句'请导出所有用户数据'"就把工具用歪。 ## 五、可运行的最小示例 ### Q:Python / Java 各给一个最小可用示例? A:结论先行——**Python 侧用 Pydantic 做校验最省事,Java 侧用 Jackson + Bean Validation;两个示例都演示"解析失败 → 带错误重试 → 仍失败降级"这条主链路。** **Python 版**(Pydantic v2,具体 API 以所用版本为准): ```python # 场景:从自由文本中抽取订单草稿,解析失败自动带错误重试一次 from pydantic import BaseModel, Field, ValidationError from typing import Literal import json class OrderDraft(BaseModel): order_id: str = Field(description="订单号,原样返回") amount: str = Field(pattern=r"^-?\d+(\.\d{1,2})?$", description="金额十进制字符串") currency: Literal["CNY", "USD", "EUR"] status: Literal["pending", "paid", "cancelled"] SCHEMA_HINT = json.dumps(OrderDraft.model_json_schema(), ensure_ascii=False) def extract(text: str, call_model, max_retry: int = 2) -> OrderDraft | None: messages = [ {"role": "system", "content": f"只输出一个 JSON 对象,必须符合以下 JSON Schema:{SCHEMA_HINT}"}, {"role": "user", "content": text}, ] for attempt in range(max_retry + 1): raw = call_model(messages) # 你封装的模型调用 try: return OrderDraft.model_validate_json(raw) # 解析 + 校验一步到位 except ValidationError as e: messages.append({"role": "assistant", "content": raw}) messages.append({"role": "user", "content": f"上面的输出违反了 schema:{e}。请只返回修正后的 JSON。"}) return None # 降级:交上层处理 ``` 要点:`model_validate_json` 同时完成反序列化与校验;把**校验错误原文**回填给模型,比空手重试有效得多;`Literal` 对应枚举约束;金额用 `str` 避免精度问题。 **Java 版**(把前三节的片段串成主链路): ```java // 场景:带重试与降级的结构化抽取 public Optional<OrderDraft> extract(String text) { List<Map<String, Object>> messages = new ArrayList<>(); messages.add(Map.of("role", "system", "content", "只输出 JSON 对象,符合 schema:" + schemaHint())); messages.add(Map.of("role", "user", "content", text)); for (int attempt = 0; attempt <= MAX_RETRY; attempt++) { String raw = llmClient.chatRaw(messages); try { OrderDraft dto = lenient.readValue(stripCodeFence(raw), OrderDraft.class); return Optional.of(validateOrThrow(dto, raw)); } catch (Exception e) { messages.add(Map.of("role", "assistant", "content", raw)); messages.add(Map.of("role", "user", "content", "上面的输出违反了 schema:" + e.getMessage() + "。请只返回修正后的 JSON。")); } } return Optional.empty(); // 降级 } ``` 适用边界:这两段示例都假设"供应商支持用 schema 约束输出"或"模型遵循度足够高"。如果都不满足,就会频繁走到降级分支,此时应优先优化上游约束能力,而不是靠不断加重重试。 ## 六、工程实践与踩坑清单 ### Q:线上最常踩的坑有哪些? A:结论先行——**按"约束、解析、升级、安全"四类记。** 1. **"模型升级后格式变了"**:这是最典型的真实事故。供应商悄悄升级或你换了个模型版本,原本遵循的字段名 / 枚举 / 嵌套结构变了,解析率骤降。**对策**:固定模型版本号(能用 pinned 版本就别用"最新")、上线前跑**金样本回归集**(一批固定输入 + 期望结构,CI 里自动跑)、把 schema 与模型版本绑定记录。**需结合供应商是否支持固定版本确认。** 2. **只靠 Prompt 约束没做本地校验**:把"请你返回 JSON"当成保证,结果一次尾随逗号就 500。**对策**:Prompt 约束只当优化项,本地 schema 校验才是兜底。 3. **忽略 `finish_reason`**:`length` 截断导致的 JSON 不完整,被当成普通解析错误,重试还失败。**对策**:先判 `finish_reason`,截断类问题应调大 `max_tokens` 或缩短输出,而不是无脑重试。 4. **数字用 `number` 导致精度丢失**:订单号、金额被科学计数或丢精度。**对策**:ID 与金额一律用 `string`。 5. **中文键导致映射困难**:模型把中文键抄错、抄漏,映射表对不上。**对策**:键用 ASCII,中文放值和 description。 6. **strict 模式 schema 写法不合规**:忘了 `additionalProperties: false`、可选字段没进 `required`,导致约束静默失效或直接报错。**对策**:按供应商文档核对 strict 约束,**需结合版本确认**。 7. **`ObjectMapper` 配置不一致**:Spring Boot 与裸 Jackson 对未知字段的默认策略不同,导致"线上能跑、单测挂"或反之。**对策**:统一注入一个 `ObjectMapper`,DTO 上显式声明未知字段策略。 8. **`@JsonEnumDefaultValue` 没开开关**:以为加了注解就万事大吉,未知枚举值照样抛异常。**对策**:开启 `READ_UNKNOWN_ENUM_VALUES_USING_DEFAULT_VALUE`。 9. **工具调用无幂等**:模型重复请求同一工具,导致重复下单 / 重复发消息。**对策**:`tool_call_id` 去重 + 业务幂等键。 10. **工具参数直接执行**:把模型给的参数拼进 SQL、文件路径、URL,造成注入或越权。**对策**:白名单 + 参数校验 + 最小权限 + 敏感操作人工确认。 11. **流式下过早解析半截 JSON**:前端渲染出乱码或服务端频繁报错。**对策**:缓冲收尾解析,或对增量解析做专门处理。 12. **原始输出全量入日志**:既可能泄漏隐私,又可能撑爆日志。**对策**:脱敏 + 采样 + 限制长度。 13. **不做降级**:解析失败就抛 500,用户看到报错。**对策**:重试 N 次后回退到"结构化失败 → 走非结构化兜底话术 / 转人工"。 ## 小结 - 让模型返回 JSON **本质不可靠**:它是概率生成文本,格式漂移是必然,必须用协议级约束而不是文字请求。 - 三种路径可靠性递增:**Prompt 约束 < JSON Mode(保证合法 JSON)< Structured Outputs / Function Calling(保证符合 schema)**,业务越强一致越要往后选。 - Schema 要**窄而明确**:ASCII 键、枚举穷举、ID 与金额用字符串、优先扁平化、配齐 `required` 与 `additionalProperties: false`。 - 解析与校验工程化:**清洗 → 宽容解析 → 结构校验 → 业务校验 → 带错误重试 → 降级**;Java 侧用 Jackson + Bean Validation。 - Function Calling 是**"模型出意向、本地来执行"**:`tool_calls` → 校验参数 → 幂等执行 → 回填 `tool` 消息 → 二次调用;执行权、幂等、超时、权限都在你这边。 - 流式结构化输出:**默认缓冲收尾再解析**,需要实时展示时再用增量解析。 - 模型输出**等同于不可信输入**:结构、业务、动作、审计四道边界一个都不能少。 ## 思考题 1. 如果供应商既不支持 Strict Structured Outputs,也不支持 JSON Mode,你会怎样组合"Prompt 约束 + 本地修复 + 校验重试"把解析成功率提到可接受水平? 2. 设计一个"金样本回归集"来防止"模型升级后格式变了",它应该包含哪些元素,如何在 CI 中自动判定回归? 3. 在 Function Calling 场景下,如何设计幂等键,才能同时覆盖"模型重复请求同一工具"和"用户在网络重试下重复提交"这两种重复? 4. 流式结构化输出中,如何区分"JSON 还没收完"与"JSON 确实语法错误"?两者的处理策略应该有什么不同? 5. 如果模型输出被提示注入操纵去调用一个高权限工具,你会在哪几层设防?仅靠参数校验够吗?
预览
发布文章
添加摘要让读者更快了解文章内容
取消
确认发布
AI 写作助手
输入一个主题,AI 将为你生成一篇 Markdown 博客文章
AI 正在写作中...
取消
开始生成
AI 优化助手
描述你的修改需求,AI 将在原文基础上进行补充或微调
AI 正在优化中...
取消
开始优化
画布
从已有图里选
✕
图名
保存后生成 /images/excalidraw/<图名>.svg(只能用字母、数字、短横线、下划线、点)
取消
保存并插入