Back to Details

llm-structured-output

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

LLM Structured Output

LLM 结构化输出

Build structured-output flows that are predictable enough for software to trust.
构建足够可预测、能被软件信任的结构化输出流程。

Use This Skill For

适用场景

  • JSON or typed-object output from a model
  • Data extraction pipelines
  • Function or tool argument generation
  • Prompt contracts that feed downstream automation
  • Validation and retry strategies for malformed model output
  • 模型生成的JSON或类型化对象输出
  • 数据提取流水线
  • 函数或工具参数生成
  • 为下游自动化提供支持的提示词契约
  • 针对格式错误的模型输出的验证与重试策略

Workflow

工作流程

1. Start With the Consumer

1. 从消费者需求出发

  • Identify exactly what the downstream system needs
  • Define required fields, optional fields, enums, and limits
  • Keep the schema as small as possible
  • 明确识别下游系统的具体需求
  • 定义必填字段、可选字段、枚举类型（enums）和限制条件
  • 尽可能简化Schema

2. Make the Contract Explicit

2. 明确契约规则

  • Provide the model with the expected structure
  • State field meanings and constraints clearly
  • Prefer deterministic formats over prose-plus-JSON hybrids
  • If a field is free-form, bound it with type, length, or examples
  • 向模型提供预期的输出结构
  • 清晰说明字段含义和约束条件
  • 优先选择确定性格式，而非 prose-plus-JSON 混合格式
  • 如果字段为自由格式，需通过类型、长度或示例进行约束

3. Validate Everything

3. 全面验证

  • Parse strictly
  • Reject unknown or malformed shapes when correctness matters
  • Validate enums, ranges, array sizes, and nested objects
  • Treat structured output as untrusted input until validated
  • 严格解析输出
  • 当正确性至关重要时，拒绝未知或格式错误的输出结构
  • 验证枚举类型、取值范围、数组大小和嵌套对象
  • 在验证通过前，将结构化输出视为不可信输入

4. Design Recovery Paths

4. 设计恢复路径

  • Retry with the validation error when the output is close
  • Fall back to a smaller schema if the original is too complex
  • Log invalid outputs for inspection
  • Avoid silent coercion that hides model mistakes
  • 当输出接近要求时，结合验证错误信息进行重试
  • 如果原始Schema过于复杂， fallback 到更简化的Schema
  • 记录无效输出以供检查
  • 避免使用会隐藏模型错误的静默强制转换

5. Optimize for Reliability

5. 优化可靠性

  • Break large tasks into smaller structured steps
  • Separate reasoning from final machine-readable output when needed
  • Prefer schemas with stable keys and low ambiguity
  • Remove optional fields that are not actually useful
  • 将大型任务拆分为更小的结构化步骤
  • 必要时将推理过程与最终的机器可读输出分离
  • 优先选择键稳定、歧义性低的Schema
  • 删除并非真正有用的可选字段

Rules

规则

  • Do not ask for markdown fences around JSON unless the consumer needs them
  • Do not mix human-facing commentary into machine-facing payloads
  • Prefer enums over natural-language categories
  • Prefer arrays of objects over encoded strings
  • Make nullability intentional, not accidental
  • 除非消费者需要，否则不要要求在JSON周围添加markdown围栏
  • 不要将面向人类的注释混入面向机器的有效载荷中
  • 优先使用枚举类型（enums）而非自然语言分类
  • 优先使用对象数组而非编码字符串
  • 明确设置可空性，避免意外情况

Common Failure Modes

常见失败模式

  • Schema too broad for the task
  • Required fields that the model cannot infer
  • Free-text values that should be enums
  • Nested output with no examples or constraints
  • Parsers that accept bad data and fail later in the pipeline
  • Schema与任务需求过于宽泛
  • 模型无法推断的必填字段
  • 应使用枚举类型却采用自由文本的值
  • 无示例或约束的嵌套输出
  • 接受不良数据并在流水线后期才失败的解析器

Output

输出成果

When using this skill, produce:
  • The target schema or shape
  • The prompt contract for generating it
  • The validation and retry plan
  • Any reliability risks or edge cases
使用此技能时，需产出：
  • 目标Schema或输出结构
  • 用于生成该结构的提示词契约
  • 验证与重试方案
  • 任何可靠性风险或边缘情况