JSON 合法也可能出错,让模型读懂自己的报错
Instructor 用 Pydantic 校验 LLM 输出,失败就带着错误信息重问,OpenAI、Anthropic 和 Ollama 都适用。
要点速览
- Instructor 用 Pydantic 定义 schema,校验 LLM 输出,校验失败时自动带着错误信息重问。
- 它支持多家提供商(OpenAI、Anthropic、Google、Mistral、Ollama、Cohere 等),适合需要适配各家客户技术栈的 FDE。
- OpenAI 原生 Structured Outputs 在 API 层面保证输出符合 schema。Instructor 是不依赖提供商的安全网,但替代不了好的 schema 设计。
OpenAI 的 Structured Outputs 文档里有一句话值得细读:JSON 模式和 Structured Outputs 都保证输出是合法 JSON,但只有 Structured Outputs 保证输出符合 schema。也就是说,一段能顺利解析的 JSON 字符串,照样可能缺字段、类型不对,或者在本该填金额的地方放了一个毫无意义的日期。
做演示时,这几乎无关紧要。可对于把 LLM 接入客户生产系统的前线部署工程师(FDE)来说,这类故障偏偏在凌晨两点冒出来,卡在一个长批处理任务的半路,而且出在一家你没得选的模型提供商身上。
客户很少让你选。一家用 OpenAI,另一家用 Anthropic,第三家因为数据不能出公司,在内网里通过 Ollama 跑开源模型。你需要一种在这些技术栈上都能用的 schema 约束手段。Instructor 支持的提供商列表很长,正好对上这个问题。
Pydantic 写契约,Instructor 来执行
按 Pydantic 自己文档的说法,它是 Python 里使用最广的数据校验库,校验核心用 Rust 编写。这里更重要的是:Pydantic 模型可以导出 JSON Schema,直接传给 LLM API,意思就是“严格按这个结构返回”。
Instructor 由 Jason Liu 编写,建立在这一基础之上。它的主页把自己描述为一个从任意 LLM 中提取结构化数据的工具,提供类型安全、校验和自动重试。README 里有一句话概括了它的工作方式:校验失败时,会带着错误信息自动重试。
关键在“带着错误信息”。Instructor 不是一直调用、直到碰巧成功。它会把 Pydantic 抛出的错误发回给模型,就像代码评审者退回 pull request 时附上具体意见,而不是一拒了之。模型知道自己错在哪里,不必从头再猜一遍。
把客户的规则写成代码
假设你在为一家物流公司做项目,任务是读取订单邮件,再把订单推送进仓储系统。与其写一大段提示词,叮嘱“记得返回 JSON,记得 quantity 是整数”,不如直接用 Pydantic 声明契约:
from pydantic import BaseModel, Field, field_validator
class OrderLine(BaseModel):
sku: str = Field(description="客户商品目录中的商品编码")
quantity: int = Field(gt=0)
unit: str
class Order(BaseModel):
customer_code: str
lines: list[OrderLine]
requested_date: str
@field_validator("customer_code")
@classmethod
def must_be_known(cls, v: str) -> str:
if not v.startswith("KH-"):
raise ValueError("customer_code 必须以 KH- 开头")
return v
(字段描述的意思是“按客户商品目录给出的商品编码”,错误信息提示“customer_code 必须以 KH- 开头”,其中 KH 是越南语中“客户”一词的缩写。)
把这个 Order 模型连同邮件正文交给 Instructor。如果模型把 quantity 返回成字符串“两箱”,或者给出一个没有前缀的 customer_code,Pydantic 会捕获错误,Instructor 把错误打包后再问一次。最终你拿到的是一个带类型的 Order 对象,IDE 可以自动补全,代码里不再需要 json.loads 和 try/except。
有意思的是 must_be_known 这个校验器。它编码的是客户的业务知识,而不是模型的知识;你把它放进了纠错循环,却没有为此重新训练模型。
这正是 Instructor 适合 FDE 工作的原因。每个客户都有自己的规则,Pydantic 让你把这些规则写进代码,而不是写进提示词的措辞里。
重试是保险,不是魔法
每次重问都是一次额外的 API 调用,意味着更高的延迟和成本;而校验器只能拦住你写进去的那些问题。一个满是 str 字段的宽松 schema 会顺利通过 Instructor,一次重问都不会触发,哪怕里面的数据毫无意义。输出质量依然取决于 schema 质量。
如果客户只用 OpenAI,先试原生 Structured Outputs,因为它在 API 层面保证输出符合 schema,而不是事后纠错。Instructor 的优势在别处:它能在 OpenAI、Anthropic、Google、Vertex AI、Mistral、Ollama、llama-cpp-python、Cohere 和 LiteLLM 上运行,一套代码可以跟着你从一个客户换到下一个客户。
Instructor(先校验,再重问)
- 支持多家提供商,包括通过 Ollama 运行的开源模型
- 可为每个客户的业务规则编写自定义 Pydantic 校验器
- 每次重试都是一次额外的 API 调用
OpenAI Structured Outputs(原生)
- 在 API 层面保证输出符合 schema
- 凡是 schema 能描述的内容,都不需要纠错循环
- 只有客户使用 OpenAI 时才可用
先学 Pydantic,再学 Instructor
安装只需 pip install instructor,项目采用 MIT 许可证,工具本身不是门槛。门槛在于,大多数开发者把 Pydantic 当作数据模板,而在这里它是一门规格语言:Field(description=...) 是提示词,gt=0 是约束,field_validator 是业务规则。
多练习编写这样的模型:它生成的 JSON Schema 能让一个陌生人准确明白你要什么。
求职时,如果岗位描述提到从 LLM 中提取结构化数据,就把这段经验放在简历靠前的位置。描述要具体,例如:“将一条抽取数据管道从纯提示词迁移到带业务校验器的 Pydantic schema,通过 Instructor 在两家不同的提供商上运行”。
语言模型还会继续出错。你的工作不是指望它们答对,而是写出足够严密的契约,让每个错误在触及客户数据之前都被发现并纠正。
这篇文章对你有帮助吗?
感谢你的反馈!