FDE Times 数据在招 FDE 职位 881▼8 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 55在招公司 185支持远程 25%美国薪资中位数 $201k招聘最多 Databricks 98
ENVI

前线部署工程师(FDE)的专业媒体

工具

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 设计。
循环示意图:LLM 返回 JSON,由 Pydantic 校验。如果不符合 schema,Instructor 把错误发回给模型并重试,回到第一步;如果有效,结果以带类型的 Order 对象输出。每次重试都多一次 API 调用。
Instructor 不是反复调用直到碰巧成功:Pydantic 的错误会发回给模型,让它知道错在哪里。代价是每轮循环都会增加延迟和成本。

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 在两家不同的提供商上运行”。

语言模型还会继续出错。你的工作不是指望它们答对,而是写出足够严密的契约,让每个错误在触及客户数据之前都被发现并纠正。

这篇文章对你有帮助吗?

4 个信源
路线图上的下一篇 · 阶段 3: AI 应用MCP 公开服务器破万,FDE 对接客户系统的方式变了协议已归 Linux Foundation 旗下基金,写一个服务器即可把客户数据库或 ERP 开放给多个主流 AI 应用。