Instructor 简单对象提取模式用 Pydantic 定义 Schema把非结构化文本转为类型安全的结构化对象【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor本文是 Instructor 官方学习路线docs/learning/patterns的第一篇实战指南讲解其最基础也是最核心的模式——简单对象提取Simple Object Extraction用一个 PydanticBaseModel定义要提取什么再通过client.create(..., response_modelPerson)让 LLM 直接把非结构化文本转化为类型安全的 Python 对象。读完本文你将掌握 Instructor 的对象提取核心用法、字段描述增强、缺失字段处理、Pydantic 业务规则校验、嵌套对象提取以及用Maybe模式优雅应对文本中根本没有目标数据的真实场景为后续列表提取与嵌套结构学习打下基础。基本对象提取最小可运行示例Instructor 的核心思路非常简单Schema 即 Prompt。你不需要手写冗长的 prompt 去描述 JSON 结构只需定义一个 Pydantic 模型Instructor 会把模型的结构与字段定义注入到请求中让模型严格按此结构输出。from pydantic import BaseModel import instructor # Define your LLM extraction schema class Person(BaseModel): name: str age: int occupation: str # Extract structured data from LLM client instructor.from_provider(openai/gpt-5-nano) person client.create( modelgpt-5.4-mini, # Works with GPT-4, Claude, Gemini messages[ {role: user, content: John Smith is a 35-year-old software engineer.} ], response_modelPerson # Type-safe LLM extraction ) print(fName: {person.name}) print(fAge: {person.age}) print(fOccupation: {person.occupation})上述过程可以用下图直观理解左边是定义的模型Schema右边是模型被 LLM 填充后的提取结果中间一次create调用完成了定义 → 提取的转换┌───────────────┐ ┌───────────────┐ │ Define Model │ │ Extracted │ │ name: str │ Extract │ name: John │ │ age: int │ ───────── │ age: 35 │ │ occupation: str│ │ occupation: │ └───────────────┘ │ software... │ └───────────────┘这段代码与仓库中的官方示例 examples/simple-extraction/user.py 一脉相承。该示例演示了instructor.from_openai(OpenAI())的经典写法并用user.model_dump_json(indent2)输出提取结果{ age: 25, name: Jason, role: null }可以看到返回的不是一串裸 JSON 字符串而是一个已经通过 Pydantic 校验的UserDetail实例可以直接访问.age、.name等属性。理解 from_provider 与 create两条核心 API 的底层行为上面的示例用到了 Instructor 的两个核心入口它们的底层实现在仓库中均有明确对应instructor.from_provider(...)定义于 instructor/v2/auto_client.py。它接受形如provider/model-name的模型字符串例如openai/gpt-4、anthropic/claude-3-sonnet、google/gemini-pro自动完成三件事按/拆分 provider 与 model 名、校验 provider 是否受支持、实例化对应厂商 SDK 客户端并包装成 Instructor 客户端。它还支持async_clientTrue返回异步客户端以及cache传入缓存适配器如AutoCache、RedisCache开启透明的响应缓存。这是 v2 统一接口的一部分相关演进可参考 docs/blog/posts/announcing-unified-provider-interface.md。client.create(...)定义于 instructor/v2/core/client.py。签名中两个关键默认值与提取质量直接相关max_retries3校验失败后自动重试最多 3 次可通过Retrying对象精细控制与strictTrue默认开启严格结构化模式。messages参数既可以是标准消息列表也可以直接传一个字符串内部会被归一化为[{role: user, content: ...}]格式见 instructor/v2/core/client.py 中的_normalize_messages。如果不想使用from_provider也可以沿用 v1 时代的经典写法client instructor.from_openai(OpenAI())然后通过client.chat.completions.create(..., response_model...)调用这与 examples/simple-extraction/user.py 中的用法完全一致。用 Field 描述增强提取准确率LLM 的提取准确性高度依赖字段语义是否清晰。字段名title可能有歧义但完整书名的描述不会。Instructor 会把Field(description...)的内容作为提示信息注入到请求的 Schema 中因此字段描述就是给 LLM 的额外指令from pydantic import BaseModel, Field class Book(BaseModel): title: str Field(descriptionThe full title of the book) author: str Field(descriptionThe authors full name) publication_year: int Field(descriptionThe year the book was published)字段描述本质上是面向 LLM 的 Prompt描述写得越精确模型越不容易把作者名、出版社或出版年份张冠李戴。这也是 Instructor 文档中反复强调的减少结构化输出错误的最廉价手段。更系统的字段用法可以参考 docs/concepts/fields.md 与 docs/concepts/validation.md。用 Optional 优雅处理缺失信息真实世界里的文本往往信息不完整——一段人物介绍可能没有电话号码一条产品描述可能不含库存状态。如果把这些字段声明为必填strLLM 会强行编造一个值来满足 Schema这恰恰是结构化提取最需要避免的幻觉。正确做法是把可能缺失的字段声明为可选from typing import Optional from pydantic import BaseModel class MovieReview(BaseModel): title: str director: Optional[str] None # Optional field rating: floatOptional[str] None意味着提取到该字段时使用提取值没有提取到时回退为None而不是触发校验失败。这让整个提取流程在面对不完整、有噪声的输入时依然稳健。官方示例 examples/simple-extraction/user.py 中的UserDetail模型正是这么设计的class UserDetail(BaseModel): age: int name: str role: Optional[str] Field(defaultNone)对比两次调用可以看到Optional字段的两种结局输入Jason is 25 years old时role为null输入Jason is a 25 years old scientist时role被正确提取为scientist。用 Pydantic 对 LLM 输出做业务规则校验Pydantic 的价值不止于结构化更在于正确性。你可以直接在模型字段上声明业务约束Instructor 在拿到 LLM 输出后会先跑一遍 Pydantic 校验不满足规则就触发重试这正是max_retries3的用武之地from pydantic import BaseModel, Field class Product(BaseModel): name: str price: float Field(gt0, descriptionThe product price in USD) in_stock: bool这里Field(gt0)声明了价格必须大于 0的约束。若 LLM 输出了price: -5或price: 0Pydantic 会抛出ValidationErrorInstructor 捕获后带着错误信息重新请求模型修正输出直到校验通过或耗尽重试次数。除了gtPydantic 还支持ge、lt、le、min_length、max_length、pattern等约束字段级与模型级校验器field_validator/model_validator的完整用法可以继续阅读 docs/learning/patterns/field_validation.md 和 docs/learning/validation/custom_validators.md。生产级示例嵌套对象提取真实业务很少只提取一层字段。下面的完整示例展示如何用嵌套 Pydantic 模型做多层级提取——ContactInfo内嵌一个可选的Address对象LLM 需要一次性把联系人信息和地址信息全部解析出来Instructor 会按照嵌套 Schema 完成整棵对象树的构建与校验from pydantic import BaseModel from typing import Optional class Address(BaseModel): street: str city: str state: str zip_code: str class ContactInfo(BaseModel): name: str email: str phone: Optional[str] None address: Optional[Address] None # Extract structured data client instructor.from_provider(openai/gpt-5-nano) contact client.create( modelgpt-5.4-mini, messages[ {role: user, content: Contact information: Name: Sarah Johnson Email: sarah.jexample.com Phone: (555) 123-4567 Address: 123 Main St, Boston, MA 02108 } ], response_modelContactInfo ) print(fName: {contact.name}) print(fEmail: {contact.email})嵌套提取是列表提取、知识图谱等复杂模式的基石——更深入的多层结构设计可参考 docs/learning/patterns/nested_structure.md。进阶用 Maybe 模式处理根本提取不到的场景Optional解决的是某字段缺失但当整条输入都不包含目标数据时例如把User not found传给一个提取用户信息的函数普通 Pydantic 模型仍会强迫 LLM 编造一个结果。官方示例 examples/simple-extraction/user.py 就展示了这一现象——输入User not found时模型竟编造出了{age: 25, name: John Doe, role: null}这样的假数据。仓库为此提供了Maybe包装器实现于 instructor/v2/dsl/maybe.py。它通过create_model动态生成一个包装模型在原模型基础上追加三个字段result提取到的结果或None、error是否失败默认False、message失败原因并实现__bool__方法使包装对象可直接用作布尔判断。官方配套示例见 examples/simple-extraction/maybe_user.pyMaybeUser instructor.Maybe(UserDetail) user get_user_detail(User not found) print(user.model_dump_json(indent2)) { user: null, error: true, message: User not found } if not user: print(Detected error)对比普通模式与Maybe模式语义完全不同普通模式在无数据时会幻觉出假对象Maybe模式则诚实地返回resultnull、errortrue和原因message让调用方可以明确区分成功提取到空值与根本无数据可提取。关于该模式的更多用法与error/message字段说明可参考 docs/concepts/maybe.md。常见应用场景简单对象提取模式几乎可以套用到所有一段文本 → 一个结构化对象的需求上联系人信息抽取从邮件签名、名片文本、对话记录中提取姓名、邮箱、电话即上文ContactInfo示例的用途商品信息结构化把散乱的产品描述解析为名称、价格、库存等字段用于构建商品目录事件信息提取从活动通知或会议纪要中抽取日期、地点、与会人等实体识别与结构化识别文本中的人物、地点、组织等实体并整理成统一结构。继续你的 Instructor 学习路线简单对象提取是 Instructor 结构化输出的第一块基石掌握后建议按以下顺序继续深入列表提取教程从一条消息中提取多个对象List[T]与包装模型两种方式嵌套结构处理复杂的分层数据字段校验与业务规则为 LLM 输出实现完整的业务规则校验。另外docs/learning/getting_started 目录下的安装与环境配置、响应模型response models入门以及 docs/concepts/models.md 对response_model的底层机制说明都可以作为本模式的补充阅读。把以上模式吃透你就能用 Instructor 构建出可靠的结构化输出应用。【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考