解决 Gemini JSON 输出截断的三档递进路径从自检到兜底一次讲清【免费下载链接】generative-aiSample code and notebooks for Generative AI on Google Cloud, with Gemini Enterprise Agent Platform项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai在 generative-ai 示例项目中用 Gemini SDK 批量导出商品数据凌晨跑完日志里飘出 400 多条JSONDecodeError——每条响应体都在数组中间戛然而止末尾没有闭合括号解析器全线翻车。这类 JSON 截断看着是模型没写完其实是 token 预算和输出模式两个问题叠加。本文按自检 → 归因 → 三档修复 → 兜底的顺序展开你能带走三档递进式修复方案外加一份上线前检查清单。快速自检你是否踩中了截断挑一条失败请求看原始响应文本不是加工后的字符串逐条对照下面的信号答是记一分是响应末尾停在数组或字符串中间缺少闭合的}或]是数组元素数量与 prompt 里要求的数量不一致要 100 条只回来 63 条是响应的finish_reason字段为MAX_TOKENS是JSON 后面跟了一段模型自己的解释性文字或 markdown 代码围栏解析器卡住是函数调用场景下function_calls[0].args缺少 schema 声明的字段或嵌套对象只剩一半是同样的请求重跑时好时坏每次截断的位置都不一样得 3 分以上基本可以锁定是 JSON 截断低于 2 分先怀疑自己的解析代码别急着怪模型。归因token 预算与自由文本是两大元凶输出上限token 预算用尽后直接硬切Gemini 单次调用有输出 token 上限因模型而异具体数值以官方文档为准。当生成内容超过预算时模型是直接截断而不是报错——所以客户端拿到的是一段看起来正常的文本只是 JSON 恰好不完整。如果你还顺手把max_output_tokens调小过等于把上限又收紧了一档触发概率更高。非结构化输出自由文本不承诺结构完整性默认自由文本模式下模型把 JSON 当成普通文字来写可能夹带说明文字、漏掉长数组中的元素、多打一个逗号。输出越长结构出错和超预算的概率同步上升两者互相放大——这就是数据量一大就截断的直接原因。正常响应截断响应{items: [a, b], total: 2}{items: [a, bfunction_calls[0].args字段齐全args只剩一半缺required字段分档修复按数据量选档轻档调大输出上限适用数据量略超默认上限时判断标准需要导出的 JSON 只比默认输出上限略多——几百个元素、几 KB 以内。此时不用改架构把预算顶到模型上限即可配合temperature0压低随机性。下面这段只演示调上限 降随机性两个关键参数response client.models.generate_content( modelgemini-2.0-flash, contents把所有商品的价格导出为 JSON 数组, configGenerateContentConfig( max_output_tokens8192, # 顶到模型上限 temperature0, ), )这档是止血手段数据量一旦真正超过模型最大输出 token参数调到多大都没用上限的具体值以官方文档为准。如果数据量涨到几千条或者 JSON 里有深层嵌套单靠调参数已经不稳了再往上走一档。中档强制结构化输出适用需要保证 schema 合规时思路从让模型写 JSON换成让模型填函数参数。模型被FunctionDeclaration的 schema 约束只能产出符合声明结构的参数输出不再经过text字段而是直接落在function_calls[0].args里由 SDK 解析——解释性文字、代码围栏这些自由发挥就没有落脚点了。仓库里 forced_function_calling.ipynb 用ANY模式强制调用search_arxiv的完整写法可以直接套用把函数名换成你的输出结构即可。下面是强制结构化调用的核心配置output_json是声明目标结构的FunctionDeclarationconfig GenerateContentConfig( temperature0, tools[Tool(function_declarations[output_json])], tool_configToolConfig( function_calling_configFunctionCallingConfig( modeFunctionCallingConfigMode.ANY, allowed_function_names[output_json], ) ), ) json_data response.function_calls[0].args这档解决的是格式完整解决不了体量数据本身超过单次输出预算时截断会在参数层面照样发生。要导出的如果是数千条记录的超大数组即使每次调用都结构合法单次也装不下只能上最重的一档。重档分片生成再合并适用数据量超过单次输出上限时把大 JSON 拆成多个小片逐片调用生成每片校验通过后再合并。关键是让每个分片复用中档的 schema——每片单独都是结构完整的 JSON 片段合并后自然就是完整 JSON。下面是分片循环骨架structured_config即中档那份配置result [] for i in range(0, total, chunk_size): chunk client.models.generate_content( modelgemini-2.0-flash, contentsf生成第 {i} 到 {i chunk_size - 1} 条数据只返回 JSON 数组, configstructured_config, # 每片都走强制结构化 ) result.extend(json.loads(chunk.text))⚠️ 这档的代价是调用次数和延迟成倍增加小数据量别交这个成本chunk_size要按单次输出预算反推设大了会重新触发截断。大多数场景从中档起步就够强制结构化输出先把格式问题锁死数据量控制在单次输出上限内即可不必一上来就分片。兜底上线前 4 道防御档位选得再好截断也是概率事件解析层必须有防御别把稳定性押在模型这次没截断上每次响应先过json.loads捕获JSONDecodeError后保留原始文本落盘、打日志走降级路径不要静默返回空数据解析失败自动重试 1~2 次重试时换更保守的参数更小chunk_size或更低max_output_tokens仍失败则转人工检查finish_reason值为MAX_TOKENS说明是上限截断直接走分片通道别盲目重发同一请求把JSON 解析失败率做成监控指标并配告警阈值例如 1%指标抬升通常意味着数据量长大了该换档了凌晨那 400 条日志不用逐条救先把导出链路切到强制结构化输出解析层加好失败回退剩下偶尔撞上限的请求交给分片生成即可。函数调用更多模式——嵌套结构、并行调用——可以参考仓库里的 intro_function_calling.ipynb 和 function_calling_data_structures.ipynb。【免费下载链接】generative-aiSample code and notebooks for Generative AI on Google Cloud, with Gemini Enterprise Agent Platform项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 解决 Gemini JSON 输出截断的三档递进路径：从自检到兜底一次讲清
解决 Gemini JSON 输出截断的三档递进路径从自检到兜底一次讲清【免费下载链接】generative-aiSample code and notebooks for Generative AI on Google Cloud, with Gemini Enterprise Agent Platform项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai在 generative-ai 示例项目中用 Gemini SDK 批量导出商品数据凌晨跑完日志里飘出 400 多条JSONDecodeError——每条响应体都在数组中间戛然而止末尾没有闭合括号解析器全线翻车。这类 JSON 截断看着是模型没写完其实是 token 预算和输出模式两个问题叠加。本文按自检 → 归因 → 三档修复 → 兜底的顺序展开你能带走三档递进式修复方案外加一份上线前检查清单。快速自检你是否踩中了截断挑一条失败请求看原始响应文本不是加工后的字符串逐条对照下面的信号答是记一分是响应末尾停在数组或字符串中间缺少闭合的}或]是数组元素数量与 prompt 里要求的数量不一致要 100 条只回来 63 条是响应的finish_reason字段为MAX_TOKENS是JSON 后面跟了一段模型自己的解释性文字或 markdown 代码围栏解析器卡住是函数调用场景下function_calls[0].args缺少 schema 声明的字段或嵌套对象只剩一半是同样的请求重跑时好时坏每次截断的位置都不一样得 3 分以上基本可以锁定是 JSON 截断低于 2 分先怀疑自己的解析代码别急着怪模型。归因token 预算与自由文本是两大元凶输出上限token 预算用尽后直接硬切Gemini 单次调用有输出 token 上限因模型而异具体数值以官方文档为准。当生成内容超过预算时模型是直接截断而不是报错——所以客户端拿到的是一段看起来正常的文本只是 JSON 恰好不完整。如果你还顺手把max_output_tokens调小过等于把上限又收紧了一档触发概率更高。非结构化输出自由文本不承诺结构完整性默认自由文本模式下模型把 JSON 当成普通文字来写可能夹带说明文字、漏掉长数组中的元素、多打一个逗号。输出越长结构出错和超预算的概率同步上升两者互相放大——这就是数据量一大就截断的直接原因。正常响应截断响应{items: [a, b], total: 2}{items: [a, bfunction_calls[0].args字段齐全args只剩一半缺required字段分档修复按数据量选档轻档调大输出上限适用数据量略超默认上限时判断标准需要导出的 JSON 只比默认输出上限略多——几百个元素、几 KB 以内。此时不用改架构把预算顶到模型上限即可配合temperature0压低随机性。下面这段只演示调上限 降随机性两个关键参数response client.models.generate_content( modelgemini-2.0-flash, contents把所有商品的价格导出为 JSON 数组, configGenerateContentConfig( max_output_tokens8192, # 顶到模型上限 temperature0, ), )这档是止血手段数据量一旦真正超过模型最大输出 token参数调到多大都没用上限的具体值以官方文档为准。如果数据量涨到几千条或者 JSON 里有深层嵌套单靠调参数已经不稳了再往上走一档。中档强制结构化输出适用需要保证 schema 合规时思路从让模型写 JSON换成让模型填函数参数。模型被FunctionDeclaration的 schema 约束只能产出符合声明结构的参数输出不再经过text字段而是直接落在function_calls[0].args里由 SDK 解析——解释性文字、代码围栏这些自由发挥就没有落脚点了。仓库里 forced_function_calling.ipynb 用ANY模式强制调用search_arxiv的完整写法可以直接套用把函数名换成你的输出结构即可。下面是强制结构化调用的核心配置output_json是声明目标结构的FunctionDeclarationconfig GenerateContentConfig( temperature0, tools[Tool(function_declarations[output_json])], tool_configToolConfig( function_calling_configFunctionCallingConfig( modeFunctionCallingConfigMode.ANY, allowed_function_names[output_json], ) ), ) json_data response.function_calls[0].args这档解决的是格式完整解决不了体量数据本身超过单次输出预算时截断会在参数层面照样发生。要导出的如果是数千条记录的超大数组即使每次调用都结构合法单次也装不下只能上最重的一档。重档分片生成再合并适用数据量超过单次输出上限时把大 JSON 拆成多个小片逐片调用生成每片校验通过后再合并。关键是让每个分片复用中档的 schema——每片单独都是结构完整的 JSON 片段合并后自然就是完整 JSON。下面是分片循环骨架structured_config即中档那份配置result [] for i in range(0, total, chunk_size): chunk client.models.generate_content( modelgemini-2.0-flash, contentsf生成第 {i} 到 {i chunk_size - 1} 条数据只返回 JSON 数组, configstructured_config, # 每片都走强制结构化 ) result.extend(json.loads(chunk.text))⚠️ 这档的代价是调用次数和延迟成倍增加小数据量别交这个成本chunk_size要按单次输出预算反推设大了会重新触发截断。大多数场景从中档起步就够强制结构化输出先把格式问题锁死数据量控制在单次输出上限内即可不必一上来就分片。兜底上线前 4 道防御档位选得再好截断也是概率事件解析层必须有防御别把稳定性押在模型这次没截断上每次响应先过json.loads捕获JSONDecodeError后保留原始文本落盘、打日志走降级路径不要静默返回空数据解析失败自动重试 1~2 次重试时换更保守的参数更小chunk_size或更低max_output_tokens仍失败则转人工检查finish_reason值为MAX_TOKENS说明是上限截断直接走分片通道别盲目重发同一请求把JSON 解析失败率做成监控指标并配告警阈值例如 1%指标抬升通常意味着数据量长大了该换档了凌晨那 400 条日志不用逐条救先把导出链路切到强制结构化输出解析层加好失败回退剩下偶尔撞上限的请求交给分片生成即可。函数调用更多模式——嵌套结构、并行调用——可以参考仓库里的 intro_function_calling.ipynb 和 function_calling_data_structures.ipynb。【免费下载链接】generative-aiSample code and notebooks for Generative AI on Google Cloud, with Gemini Enterprise Agent Platform项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考