大模型应用开发 / 系统课时

生成结构化 JSON

生成结构化 JSON

学习目标

完成本课后,你将能够:

  • 区分普通 JSON 模式与 JSON Schema 约束
  • 通过原生 API 的 format 字段限制输出结构
  • 在程序中解析并验证模型结果
  • 处理截断、额外字段和类型错误

为什么提示词不足以保证 JSON

只在提示词中写“请返回 JSON”仍可能出现 Markdown 围栏、解释文字、缺少字段或类型错误。结构化输出把格式要求作为请求参数传给模型,并在应用端继续验证,适合抽取、分类、表单填充和接口参数生成。

JSON 模式与 Schema

两种常见方式:

  • format: "json":要求返回合法 JSON,但不限定具体字段。
  • format: { ...JSON Schema... }:限制对象属性、类型和必填字段。

Schema 能提高一致性,但不能证明字段内容在业务上正确。例如 confidence 是数字,也可能超出允许范围,应用仍需校验。

使用 JSON 模式

执行:

bash
curl --fail --silent --show-error http://localhost:11434/api/generate   -H "Content-Type: application/json"   -d '{
    "model": "gemma3:1b",
    "prompt": "提取主题和三个关键词。文本:Ollama 可在本地运行大模型。",
    "format": "json",
    "stream": false,
    "options": {
      "temperature": 0
    }
  }'

预期响应结构:

json
{
  "model": "gemma3:1b",
  "response": "{\"<KEY>\": \"<VALUE>\"}",
  "done": true
}

原生 generate 的结构化内容位于 response 字符串中,需要再次执行 JSON 解析。

使用 JSON Schema

执行:

bash
curl --fail --silent --show-error http://localhost:11434/api/generate   -H "Content-Type: application/json"   -d '{
    "model": "gemma3:1b",
    "prompt": "分析文本:Ollama 可在本地运行大模型。只返回符合 Schema 的结果。",
    "format": {
      "type": "object",
      "properties": {
        "topic": {"type": "string"},
        "keywords": {
          "type": "array",
          "items": {"type": "string"},
          "minItems": 3,
          "maxItems": 3
        }
      },
      "required": ["topic", "keywords"],
      "additionalProperties": false
    },
    "stream": false,
    "options": {
      "temperature": 0
    }
  }'

预期的 response 内容结构:

json
{
  "topic": "<TOPIC>",
  "keywords": ["<KEYWORD_1>", "<KEYWORD_2>", "<KEYWORD_3>"]
}

Python 解析与校验

安装校验库:

bash
python -m pip install jsonschema

预期输出:

text
Successfully installed jsonschema-<VERSION> ...

保存为 structured_output.py:

python
import json
import urllib.request
from jsonschema import validate

schema = {
    "type": "object",
    "properties": {
        "topic": {"type": "string", "minLength": 1},
        "keywords": {
            "type": "array",
            "items": {"type": "string", "minLength": 1},
            "minItems": 3,
            "maxItems": 3,
        },
    },
    "required": ["topic", "keywords"],
    "additionalProperties": False,
}

payload = {
    "model": "gemma3:1b",
    "prompt": (
        "分析文本:Ollama 可在本地运行大模型。"
        "只返回符合给定 Schema 的 JSON。"
    ),
    "format": schema,
    "stream": False,
    "options": {"temperature": 0},
}

request = urllib.request.Request(
    "http://localhost:11434/api/generate",
    data=json.dumps(payload).encode("utf-8"),
    headers={"Content-Type": "application/json"},
)

with urllib.request.urlopen(request, timeout=180) as response:
    envelope = json.load(response)

data = json.loads(envelope["response"])
validate(instance=data, schema=schema)

print(json.dumps(data, ensure_ascii=False, indent=2))

运行:

bash
python structured_output.py

预期输出结构:

json
{
  "topic": "<TOPIC>",
  "keywords": [
    "<KEYWORD_1>",
    "<KEYWORD_2>",
    "<KEYWORD_3>"
  ]
}

可靠性技巧

  • Schema 字段名称要清晰。
  • 提示词中重复要求只输出结构,不添加说明。
  • 温度设为 0 提高稳定性。
  • 限制 additionalProperties。
  • 为字符串、数组和数字设置范围。
  • 给足 num_predict,避免 JSON 被截断。
  • 解析失败时记录原始文本,但日志需要脱敏。
  • 重试次数应有限,不能无限调用。

结构正确不等于语义正确

应用还应验证:

  • 枚举值是否在业务集合中
  • 数字是否在允许范围
  • 日期是否真实有效
  • ID 是否存在
  • 字段之间是否矛盾
  • 内容是否来自允许的数据源

模型适合提出结构化候选,最终业务决策仍由确定性代码完成。

本课练习

练习 1:抽取联系人信息

任务目标:设计严格 Schema。输入或初始条件:准备包含姓名、邮箱和电话的文本。实现要求:要求模型抽取并验证格式。验收条件:缺失字段有明确可空规则,额外字段被禁止。

练习 2:测试截断

任务目标:识别不完整 JSON。输入或初始条件:使用较复杂 Schema。

实现要求:降低 num_predict 触发截断。验收条件:程序捕获解析失败而不是使用残缺结果。

练习 3:增加语义校验

任务目标:区分 Schema 与业务规则。输入或初始条件:模型输出金额和币种。实现要求:增加金额范围与币种白名单。验收条件:结构合法但业务非法的数据会被拒绝。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

生成结构化 JSON

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通