---

name: llm-structured-output description: > 使用 response_format、tool_use 和 schema 约束解码，从 OpenAI、Anthropic 和 Google API 获取可靠的 JSON、枚举和类型化对象。 risk: safe source: community date_added: "2026-03-12"

LLM 结构化输出

本技能的作用

从 LLM API 响应中提取类型化、经过验证的数据，而非解析自由文本。本技能涵盖三种主要方法：OpenAI 的 response_format 配合 JSON Schema、Anthropic 的 tool_use 块用于结构化提取，以及 Google Gemini 的 responseSchema。你将了解每种方法何时有效、何时失效，以及如何围绕每个生产系统都会遇到的 schema 验证失败构建重试逻辑。

何时使用本技能

• 用户需要从 LLM 响应中提取结构化数据（JSON 对象、数组、枚举）
• 用户正在构建 LLM 输出直接馈入代码的管道（数据库写入、API 调用、UI 渲染）
• 用户询问 OpenAI 中的 response_format、json_mode、json_object 或 json_schema
• 用户询问使用 Anthropic 的 tool_use 或 tool_result 块进行数据提取（非实际工具执行）
• 用户询问 openai npm 包中的 Zod schema 配合 zodResponseFormat()
• 用户需要使用 instructor、marvin 或手动验证将 LLM 输出解析为 Pydantic 模型
• 用户从 LLM 响应中获得格式错误的 JSON、缺失字段或错误类型，需要修复
• 用户询问本地模型中的受控生成、约束解码或基于语法的采样

不要在以下情况使用本技能：

• 用户需要自由格式文本生成（摘要、文章、聊天）
• 用户询问用于表单验证或 API 输入验证的 Zod（请改用 zod-validation-expert）
• 用户需要提示工程以提高文本质量（非结构）
• 用户想要调用真实的外部工具/API（本技能涵盖将 tool_use 作为结构化输出技巧使用，而非实际工具编排）

核心工作流

1. 确定目标 schema。询问用户需要提取哪些字段。定义每个字段的类型、是否必需或可选，以及适用的有效枚举值。没有具体 schema 不要继续。

2. 选择适合提供商的方法：

   • OpenAI (gpt-4o, gpt-4o-mini)： 使用 response_format: { type: "json_schema", json_schema: { ... } }。这启用了通过约束解码保证 schema 一致性的结构化输出。
   • Anthropic (Claude)： 定义一个以目标 schema 作为 input_schema 的单一工具，并设置 tool_choice: { type: "tool", name: "extract_data" }。Claude 在 tool_use 内容块中返回结构化数据。
   • Google (Gemini)： 使用 generationConfig.responseSchema 配合 JSON Schema 对象，并设置 responseMimeType: "application/json"。
   • 本地模型 (llama.cpp, vLLM)： 使用 GBNF 语法或 --json-schema 标志在 token 级别进行约束解码。

3. 用用户的语言编写 schema 定义。对于 Python，定义 Pydantic BaseModel。对于 TypeScript，定义 Zod schema 并用 zodResponseFormat() 转换。对于原始 API 调用，直接编写 JSON Schema。

4. 在 schema 中包含字段级描述。每个字段都应有一个 description 字符串，告诉模型该放什么内容。模型将这些描述用作隐式提示指令——描述为 "用户情感为正面、负面或中性" 的字段比没有上下文的裸 sentiment: str 产生更好的结果。

5. 设置系统提示以强化结构。告诉模型它的工作是数据提取，而非对话。示例："你是一个数据提取系统。分析输入并返回请求的字段。不要在 JSON 结构之外包含解释。"

6. 如果使用 OpenAI 的 json_schema 模式，在 schema 定义中设置 "strict": true。这激活约束解码，模型只能输出符合 schema 的 token。没有 strict: true，模型仍可能产生无效 JSON。

7. 如果使用 Anthropic 的 tool_use 方法，从 response.content 中找到 type == "tool_use" 的块并读取其 input 字段来提取结构化数据。不要解析文本块——结构化数据仅存在于 tool_use 块中。

8. 在应用代码中对照 schema 验证响应。即使使用约束解码，在将数据传递到下游之前也要用 Pydantic 的 model_validate() 或 Zod 的 .parse() 进行验证。这能捕获 schema 一致性本身无法防止的语义问题（空字符串、超范围数字）。

9. 为验证失败构建重试循环。当验证失败时，将原始输入加上失败的输出和验证错误发送回模型，附带指令如 "你之前的输出验证失败：{error}。请修复输出。" 重试上限为 3 次。