# JSON 合法也可能出错，让模型读懂自己的报错

> Instructor 用 Pydantic 校验 LLM 输出，失败就带着错误信息重问，OpenAI、Anthropic 和 Ollama 都适用。

原文: https://fdetimes.net/zh/tools/instructor-pydantic-llm-schema-validation/

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 声明契约：

```python
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 上运行，一套代码可以跟着你从一个客户换到下一个客户。

## 先学 Pydantic，再学 Instructor

安装只需 `pip install instructor`，项目采用 MIT 许可证，工具本身不是门槛。门槛在于，大多数开发者把 Pydantic 当作数据模板，而在这里它是一门规格语言：`Field(description=...)` 是提示词，`gt=0` 是约束，`field_validator` 是业务规则。

多练习编写这样的模型：它生成的 JSON Schema 能让一个陌生人准确明白你要什么。

求职时，如果岗位描述提到从 LLM 中提取结构化数据，就把这段经验放在简历靠前的位置。描述要具体，例如：“将一条抽取数据管道从纯提示词迁移到带业务校验器的 Pydantic schema，通过 Instructor 在两家不同的提供商上运行”。

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

**本周动手试试:**

- 找一个你目前用纯提示词处理的抽取任务，改写成至少包含一个 field_validator 的 Pydantic 模型，通过 Instructor 运行，并统计模型被重问了几次。
- 对这个模型调用 .model_json_schema()，仔细阅读生成的 JSON Schema。这就是 LLM 看到的内容：字段描述够清楚吗？
- 如果客户使用 OpenAI，用原生 Structured Outputs 跑同一个 schema，比较它与 Instructor 重试方式的可靠性。

## 信源

- [Instructor - Multi-Language Library for Structured LLM Outputs | Python, TypeScript, Go, Ruby - Instructor](https://python.useinstructor.com/)

- [Instructor: Structured Outputs for LLMs (567-labs/instructor)](https://github.com/567-labs/instructor)

- [Pydantic Validation](https://pydantic.dev/docs/validation/latest/get-started/)

- [Structured model outputs](https://developers.openai.com/api/docs/guides/structured-outputs)
