提示中的 JSON Schema
约束输出结构。
提示中的 JSON Schema 是 CoddyKit 上的免费 AI Prompt Engineering 课时。 这是第 2 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 AI Prompt Engineering 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 AI Prompt Engineering 课程共包含 4 节课。
模式即输出契约
JSON 模式以声明式方式描述有效输出的形状：类型、必需键、值约束和嵌套关系。将其传递给结构化输出 API 时，它会成为硬性契约；将其嵌入提示时，它会成为强有力的指导。
掌握模式编写是结构化生成的核心技能。
严格标志改变一切
在严格模式下，提供方要求每个属性都列在 required 中，并且 additionalProperties 必须为 false。可选字段要通过与 null 组成联合类型来表达，而不是省略字段。
{
'type': 'object',
'properties': {
'name': {'type': 'string'},
'nickname': {'type': ['string', 'null']}
},
'required': ['name', 'nickname'],
'additionalProperties': False
}约束标量值
请将验证放入模式中，而不是放在后处理中：
enum用于固定选项。minimum/maximum用于数值范围。pattern用于通过正则表达式验证字符串。format用于提供date-time或email等格式提示。
{
'rating': {'type': 'integer', 'minimum': 1, 'maximum': 5},
'sku': {'type': 'string', 'pattern': '^[A-Z]{3}-[0-9]{4}$'},
'created': {'type': 'string', 'format': 'date-time'}
}数组与元组
对同质数组使用 items，并添加 minItems/maxItems 以限制长度。对于按位置排列的元组，请通过 prefixItems 提供一个模式数组。
{
'tags': {
'type': 'array',
'items': {'type': 'string'},
'minItems': 1,
'maxItems': 5
}
}使用 oneOf 的带判别标记联合类型
使用 oneOf 加上判别字段来表示多态结果。模型会选择恰好一个分支，而您的反序列化器则根据该标记进行切换。
{
'oneOf': [
{'type': 'object', 'properties': {
'kind': {'const': 'email'},
'address': {'type': 'string', 'format': 'email'}},
'required': ['kind', 'address']},
{'type': 'object', 'properties': {
'kind': {'const': 'phone'},
'number': {'type': 'string'}},
'required': ['kind', 'number']}
]
}从类型生成模式
手动编写模式容易出错。请从类型化模型派生模式，这样模式与代码就不会相互偏离。
from pydantic import BaseModel
class Invoice(BaseModel):
total: float
currency: str
paid: bool
schema = Invoice.model_json_schema()
# pass schema directly to response_format描述也是提示
模式中的每个 description 都会被模型读取。请利用它们来引导语义，而不只是记录字段。
例如，像“ISO-3166 二字母国家代码，大写”这样的描述，能够实质性地提高字段准确率。请将描述视为嵌入契约中的微型提示。
{
'country': {
'type': 'string',
'description': 'ISO-3166 alpha-2 code, uppercase, e.g. US, TR, DE'
}
}将模式嵌入提示
当提供方不支持原生结构化输出时，请将模式嵌入提示中，并要求输出符合该模式。将其与一个单独的上下文示例以及明确的仅限 JSON，不要附带文字指令结合使用。
SYSTEM = (
'You output ONLY JSON matching this schema. No markdown, no commentary.\n'
'Schema:\n' + json.dumps(schema) + '\n'
'If a value is unknown, use null.'
)避免模式膨胀
过深或分支过多的模式会使模型困惑，并增加令牌成本。建议如下：
- 保持嵌套层次较浅；尽可能进行扁平化。
- 优先使用枚举，而不是自由文本。
- 将庞大模式拆分为多个目标明确的调用。
- 某些提供方会限制嵌套深度和属性总数；请检查相关限制。
引用与复用
使用 $defs 和 $ref 复用子模式（例如，在账单和配送中使用的 Address）。请注意，某些严格模式会限制递归深度，因此在依赖自引用之前，请先确认是否支持。
{
'$defs': {
'Address': {'type': 'object', 'properties': {
'city': {'type': 'string'}}, 'required': ['city'],
'additionalProperties': False}
},
'type': 'object',
'properties': {
'billing': {'$ref': '#/$defs/Address'},
'shipping': {'$ref': '#/$defs/Address'}
},
'required': ['billing', 'shipping'],
'additionalProperties': False
}验证模式本身 validate
有一类隐蔽的错误：出问题的可能是模式，而不是输出。在持续集成中，针对 JSON 模式元模式对模式进行静态检查并 validate；在发布前，还要让一个示例对象通过验证器完成往返验证。
import jsonschema
jsonschema.Draft202012Validator.check_schema(schema)
# also: validate a known-good sample
jsonschema.validate(sample_obj, schema)快速检查
在提供方的严格 JSON 模式下，可选字段应如何正确表达？
回顾
现在您已经能够编写精确的模式：
- 严格模式要求所有属性必需，并禁用 additionalProperties。
- 使用枚举、范围、模式和格式约束来限制标量值。
- 使用带判别标记的 oneOf 表示多态。
- 从类型化模型生成模式，并将描述视为微型提示。
- 在持续集成中验证模式本身。
接下来：将模式应用于工具调用和函数调用。
用 AI 导师学习 AI Prompt Engineering — 免费
在浏览器中编写并运行真实代码，获得全天候 AI 导师的即时帮助，并在网页或应用中继续学习。
- 课程
- 53
- 课程
- 199
常见问题解答
「提示中的 JSON Schema」课时是免费的吗？
是的 — 「提示中的 JSON Schema」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 AI Prompt Engineering 课程的其余内容，请升级到 CoddyKit PRO。 AI Prompt Engineering 课程共包含 4 节课。
「提示中的 JSON Schema」这节课中我会学到什么？
约束输出结构。 你通过在浏览器中直接运行的动手代码来练习 AI Prompt Engineering，全天候 AI 导师会在你学习这节课的过程中回答你的问题。
学习 AI Prompt Engineering 需要有经验吗？
无需任何先前经验。CoddyKit 上的 AI Prompt Engineering 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 2 节课，共 4 节。
「提示中的 JSON Schema」课时需要多长时间？
大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。
我能在这节 AI Prompt Engineering 课中编写并运行代码吗？
能。每节 AI Prompt Engineering 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。