大模型应用开发 / 系统课时
生成结构化 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 与业务规则。输入或初始条件:模型输出金额和币种。实现要求:增加金额范围与币种白名单。验收条件:结构合法但业务非法的数据会被拒绝。
按自己的节奏,确认真正理解。