> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 修复结构化 JSON 响应

> 恢复接近有效的结构化 JSON 输出，无需放宽架构或手动重试格式错误的响应。

如果应用需要严格的 JSON，而模型偶尔返回的内容几乎有效却仍会导致解析器报错，请使用此方案。

## 1. 从结构化响应契约开始

只有请求本身已要求结构化输出时，响应修复才有用。

适用场景：

* `response_format.type = "json_object"`
* JSON Schema 风格的输出
* 多个调用方共用的稳定对象结构

不要对开放式文本请求启用修复。

## 2. 在合适的层级启用插件

可以在以下三个位置启用 `response-healing`：

1. 工作区默认插件策略
2. 预设插件配置
3. 请求中的 `plugins`

优先级如下：

1. 工作区
2. 预设
3. 请求

如果某个工作流始终要求结构化 JSON，请使用预设默认值。

## 3. 限定模型输出

请求的输出结构越明确，修复效果越好。

建议：

* 返回一个对象，避免输出多个无关的数据块
* 明确列出必需键
* 尽可能使用确定性 temperature
* 不要要求模型在 JSON 负载之外添加解释文字

## 4. 了解响应修复的能力与限制

当前修复流程是确定性的，仅适用于非流式请求。流式请求会完全跳过响应修复。

它可以修复：

* JSON 外层的 Markdown 代码围栏
* 尾随逗号
* 可以安全补齐的闭合符
* 其他部分仍可恢复的对象中未加引号的键

如果需要更严格的策略，请使用 `strict` 模式。该模式只会从代码围栏或周围文本中提取已有效的 JSON，不会执行范围更广的语法修复。

如果请求使用 JSON Schema 风格输出，修复流程还会在重写之前验证恢复后的负载。当前验证器涵盖一些常见约束，包括：

* 必需键
* 基本标量类型和容器类型
* 枚举值和 const 值
* 数组边界和 `uniqueItems`
* 字符串长度、正则表达式，以及 `email`、`uri`、`uuid`、`date-time` 等常见格式
* 数值边界和 `multipleOf`
* 对象属性数量限制以及 `additionalProperties: false`

它不会：

* 补造缺失的语义字段
* 猜测业务值
* 将任意文本改写成有效数据

## 5. 确认插件确实运行

修复运行时，请求详情中应包含插件执行信息。

检查：

* 插件 ID
* 是否尝试了转换
* 负载是否发生变化
* 响应无法恢复时的失败原因
* 如果预期修复生效，确认请求是否为非流式

如果看不到插件，请确认请求、预设或工作区策略确实启用了它。

## 6. 区分解析器问题与内容问题

如果修复没有帮助，请判断失败属于哪一类：

1. JSON 格式错误，但结构仍接近预期
2. JSON 符合架构，但字段内容不正确
3. 返回的是普通文本而不是 JSON
4. 令牌上限太低，导致输出被截断

只有第 1 类适合使用响应修复。

## 7. 逐步推出

1. 在一个结构化输出稳定的预设中启用修复
2. 查看日志中的插件执行元数据
3. 确认恢复后的负载符合预期架构
4. 日志表现正常后，再推广到类似预设

## 8. 选择合适的模式

* 如果工作流需要有限的语法清理，例如删除尾随逗号或为未加引号的键补上引号，请使用 `safe`。
* 如果工作流只应在移除外层包装后接受原本就有效的 JSON，请使用 `strict`。
* 检查请求详情以确认实际运行的模式。

## 相关指南

* [在预设中使用响应缓存](./response-caching-with-presets.mdx)
* [推出预设并调试路由](./preset-rollout-and-routing-debug.mdx)
* [TypeScript Agent SDK](../sdk-reference/typescript/agent-sdk.mdx)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.