一句话定义:Instructor 是一个 Python 库(开源的轻量封装),它把你的 Pydantic 模型当作“模板”交给大语言模型(LLM),要求模型按这个结构返回 JSON,再自动校验、转成强类型对象;一旦不合格,就带着错误原因让模型重新填写。
它怎么工作
流程其实只有三步:
1. 下单:读取 Pydantic 类的字段定义,转成 JSON Schema,随请求一起发给模型(通常借助模型厂商的 function calling / tool use 或 JSON 输出能力)。
2. 验货:拿回文本后,交给 Pydantic 做类型校验——age 是不是整数、email 格式对不对、必填字段有没有缺。
3. 返工:校验失败时,Instructor 不会直接把异常抛给调用方,而是把 Pydantic 报出的 ValidationError 文本连同原始请求再发回给模型,让它“看着错误改一遍”,循环若干次(重试次数可配置),直到通过或到上限。
打个比方:这就像去政务大厅办事。窗口(Instructor)递给你一张固定表格(Pydantic 模型),你(模型)填完交回;窗口不会因为你把日期写成“三月五号”就轰你走,而是圈出那一栏写“请填 YYYY-MM-DD”,让你现场改。改对了才盖章收件。真正有价值的不是那张表,而是这个当场纠错的回路。
和相邻概念的区别
| 概念 | 负责什么 | 与 Instructor 的关系 |
|---|---|---|
| Pydantic | 定义数据结构 + 校验 | 被当作“目标模板”使用 |
| Function calling / tool use | 模型侧“调哪个函数、参数是什么”的能力 | Instructor 借用它把 schema 递进去 |
| JSON mode | 只保证输出是合法 JSON | 不保证字段名对、类型对;Instructor 在其上再加校验与重试 |
手写正则 / json.loads | 事后切割字符串 | 一次解析失败就中断,没有修复机会 |
| LangChain 的 output parser 等 | 同类“结构化输出”封装 | 思路相通,细节与生态各异 |
对从业者的意义
它把“调模型”从“祈祷返回的字符串能解析”变成“调用一个带类型签名的函数”:IDE 有补全,字段有类型,出错有日志。常见用途是信息抽取(从简历、发票、邮件里抽字段)、分类打标、让 Agent 的中间步骤输出可被程序消费的结构。好处是把不确定性收拢在一处——你只需要关心最终模型对象对不对,而不用到处写 try/except。
对普通人的意义
你用的很多“AI 自动填工单”“AI 自动归类客服消息”功能,背后往往就是这套模板 + 纠错的模式。它也提示了一个更普遍的道理:模型不可能不出错,工程上的关键是出错之后有没有反馈通道,而不是指望一次就对。具体支持哪些模型后端、重试默认值是多少,以官方文档为准。
