用Instructor实现Agent结构化数据输出

可视化演示

展示Instructor将LLM文本输出转化为结构化Python对象的全流程：Schema定义、模型调用、JSON解析、验证重试，以及Agent工具间的类型安全数据传递。

结构化输出概述

想象一家后厨：主厨（大模型）最讨厌填表格。你问他“这个客户什么情况”，他能眉飞色舞讲一大段，里面确实有姓名、有年龄、有爱好，但全都藏在流水账里。后厨的记账系统不认流水账，它只认小票上的固定栏目。Agent 世界也一样：Agent 调用工具（查数据库、发邮件、建工单）时，工具接口需要的是 name、age、order_id 这样的类型化参数，而不是一段口语。

过去大家靠手写正则、json.loads 从模型输出里“抠”字段，字段一多、说法一杂就崩，这正是所谓的“非结构化困境”。要让 Agent 真正自动化，就必须把大模型的自由文本“翻译”成严格的数据结构——这就是结构化需求。Instructor 就是为解决这个痛点而生的 Python 库。

它轻量地封装了大模型客户端（OpenAI、Anthropic 等），核心用法只有一招：调用时传入 response_model——一个 Pydantic 模型。Instructor 会自动把模型输出校验、纠错、解析成 Python 对象，开发者拿到的永远是对象而不是字符串。它的核心价值，是把“让模型输出合规数据”从手工作坊变成标准化流水线。

回到餐厅：主厨还是那个洒脱的主厨，但有了小票系统，后厨再也不用靠喊。你向 Agent 要数据，拿到的一定是规规整整的对象。

Pydantic模型定义

小票模板是整个系统的灵魂。印小票的模板必须严谨：哪栏填姓名、哪栏填数量、哪栏允许空白——全部定死，主厨才不会自由发挥。Instructor 的“小票模板”就是 Pydantic 模型：一个继承自 BaseModel 的类声明了输出结构的全部规则。

用法很直观：写字段名和类型即可。每个字段的 Field(description=...) 还会作为 schema 描述喂给大模型，相当于在模板旁边印一行小字“此栏填写客户姓名”，引导模型理解语义。字段的类型验证（str、int、list[str] 等）由 Pydantic 严格把关：类型不匹配立刻报 ValidationError，为后续重试提供依据。

Pydantic 还支持默认值和嵌套模型。有默认值的字段，模型偶尔漏填也能兜住，不用整单作废；嵌套模型用来表达“地址包含省、市、街道”这类复合结构，让输出对象具备真正的层次感。这些特性共同决定了“哪些字段必须填、填错会怎样”。

模板越严谨，返工越少。这也是为什么优秀的 Agent 工程总是把“数据结构设计”放在写提示词之前——小票印得清楚，主厨才不容易填错。

模式匹配机制

同一张小票，传单方式可以不同：老练的服务员可以口头报给后厨（函数调用），求稳时也可以塞一张书面单（JSON 模式）。Instructor 会根据“后厨设备”——也就是大模型的能力——自动选择传单方式。

以 OpenAI 系模型为例，它们原生支持函数调用（tool calling）。Instructor 会把 Pydantic 模型编译成工具的 parameters schema，模型生成时以“工具参数”的形式返回对象，输出天然就是结构化 JSON，准确率最高。这就是函数调用机制的威力：模型不是在“写散文”，而是在“填参数”。

如果底层模型不支持工具调用（部分开源模型、较旧版本），Instructor 就退回 JSON 模式：把 JSON Schema 写进提示词，要求模型输出符合该 Schema 的 JSON 文本，再交给 json.loads + Pydantic 解析。两条路走哪条基本不用开发者操心，Instructor 自动判断、自动兜底。

就像一个熟练的服务员知道什么时候该口头传单、什么时候该写书面单，Instructor 把这条“判断”也替你做了。

验证与重试

小票填好不等于合格。传菜员发现“年龄”栏写了个“十八岁”，不会直接认了，而是把单子端回厨房：“这栏要填数字！”Instructor 的重试机制就是这个流程的自动化。

一次生成的完整链路是：模型输出 → Pydantic 校验 → 失败则把 ValidationError 的详细错误信息（哪个字段错、期望什么类型）拼进对话上下文 → 再让模型生成一次，如此循环，直到通过或达到 max_retries 上限。因为错误信息足够具体，模型第二次通常就能改对——这不是盲试，而是“带着点评改作业”。

用概率来看这件事：假设模型单次生成完全合法的概率是 p，那么重试 n 次后，最终成功率会显著提升。正是这个简单的概率逻辑，让“碰运气”变成了“稳成功”。

不过要提醒：每退一次单，都要重新付一次“烹饪成本”（token）。重试不是无限免单，如何设置上限，是工程实践要解决的问题。

Agent数据流转

真正的餐厅后厨有很多工位：切配、掌勺、装盘……每个工位之间传递的，都是同一格式的小票。Agent 架构也一样：工具 A 的结果要喂给工具 B，中间传的如果是自由文本，下游根本不知道该怎么读。

让每个 Agent 步骤的输出都经过 Instructor 结构化，工具之间传递的就是类型化对象：切配工位（解析工具）产出结构体，掌勺工位（生成工具）直接读字段。多步对话时，上一步的结构化结果还能存进状态，作为下一步的上下文——这就是“字段补全 + 类型校验”在流程编排中的真正价值。

状态管理也因结构化而简化：对象比字符串更容易存储、比对、回滚。Agent 的每一步都带着一张标准小票进入下一工位，任何一步出了问题，都能精确定位是哪个字段、哪个环节，而不是在一大段文本里大海捞针。

后厨的协作本质就是“标准信息在工位间流动”。Agent 有了结构化输出，工具之间的协作才真正靠得住。

工程实践要点

小票系统上线前，餐厅还要定几条规矩：面没了可以写“售罄”，但不能让小票作废；传菜员复查不过的单子，最多退回两次。这些在 AI 工程里就是“输出兜底”和“重试上限”。

具体做法上：给非关键字段设置默认值，模型漏填也能拿到可用对象；max_retries 一般设 2~3 次，既保成功率又控延迟；字段描述写清楚，减少模型因歧义导致的无效重试。测试策略上，把历史上校验失败的输入收集成回归集，每次改提示词都跑一遍，防止“修好一个坑、踩塌一座桥”。

性能优化与成本控制是一体两面：每一次调用、每一次重试，都是真金白银的 token 消耗。用轻量模型做简单字段抽取、精简 description 减少输入长度，都是立竿见影的省钱手段。

就像后厨 SOP 决定餐厅能否稳定营业，这些工程细节决定了 Agent 能不能从 Demo 走到生产环境。

AI 应用场景

Python 演示

from pydantic import BaseModel, Field, ValidationError  class UserProfile(BaseModel):    name: str = Field(description="user name")    age: int = Field(description="user age, non-negative int")    city: str = Field(default="Unknown", description="user city")    tags: list[str] = Field(default_factory=list, description="interest tags")  def mock_llm(text: str, attempt: int) -> dict:    # 模拟大模型自由输出, 前两次返回类型不合法的数据    if attempt == 0:        return {"name": "Alice", "age": "twenty eight"}   # age 是字符串, 类型错    if attempt == 1:        return {"name": 12345, "age": 28, "city": "HZ"}   # name 是整数, 类型错    return {"name": "Alice", "age": 28, "city": "HZ", "tags": ["AI", "dance"]}  def extract_profile(text: str, max_retries: int = 3) -> UserProfile:    last_error = None    for attempt in range(max_retries + 1):        data = mock_llm(text, attempt)        try:            profile = UserProfile(**data)            print("attempt {} ok: {}".format(attempt + 1, profile))            return profile        except ValidationError as e:            last_error = e            print("attempt {} failed: {}".format(attempt + 1, e))    raise last_error  if __name__ == "__main__":    raw_text = "Alice is 28 years old and lives in Hangzhou."    profile = extract_profile(raw_text)    print("name: {}, age: {}, city: {}".format(profile.name, profile.age, profile.city))

1. class UserProfile(BaseModel):声明一个 Pydantic 模型，等于先画好一张“点单小票”
2. age: int = Field(description=...)字段类型约束 + 给模型看的填写说明
3. city: str = Field(default="Unknown", ...)默认值兜底，漏填也不作废
4. def mock_llm(text, attempt)模拟大模型自由发挥，前两次故意返回类型错误的数据
5. UserProfile(**data)把数据转成对象，像质检员按小票逐栏核对
6. except ValidationError as e:捕获不合格结果，记录错误详情
7. for attempt in range(max_retries + 1)重试循环，最多首次 + n 次重试

常见误区

面试题