AI Engineering Academy · 课时

Instructor：使用 Pydantic 进行类型化提取

使用 instructor 库修改 OpenAI 客户端，使其自动重试，并根据您的 Pydantic 模式验证响应，直到提取成功。

第 1 / 4 课13 个步骤

Instructor：使用 Pydantic 进行类型化提取 是 CoddyKit 上的免费 AI Engineering Academy 课时。这是第 1 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 AI Engineering Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 AI Engineering Academy 课程共包含 4 节课。

什么是提取库？

提取库是 OpenAI 客户端的轻量封装，可让结构化提取更加可靠。它不会让您只能寄希望于模型返回有效 JSON，而是会强制执行您的Pydantic 模式，并在验证失败时自动重试。这样，您无需自行编写自定义解析和重试逻辑。

安装提取库

只需一条 pip 命令即可安装提取库。它需要 pydantic v2 和 openai SDK。安装完成后，使用 instructor.patch() 修补 OpenAI 客户端，即可获得增强版客户端；该客户端支持在每次调用中使用 response_model 参数。

pip install instructor openai pydantic

修补 OpenAI 客户端

提取库通过修补标准 OpenAI 客户端来工作。调用 instructor.from_openai(client) 会返回一个新客户端，其中每次 chat.completions.create 调用都接受 response_model 关键字参数。底层 API 调用完全相同——提取库只是在其上添加了模式约束。

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI())

定义您的 Pydantic 模式

将您希望模型返回的数据结构定义为 Pydantic BaseModel。字段名称、类型和文档字符串会自动转换为发送给模型的 JSON Schema。请使用清晰、描述性强的字段名称，以便模型理解应填充哪些内容。为业务规则添加验证器。

from pydantic import BaseModel, Field
from typing import Optional

class PersonExtract(BaseModel):
    name: str = Field(description='Full name of the person')
    age: Optional[int] = Field(None, description='Age in years if mentioned')
    email: Optional[str] = Field(None, description='Email address if present')
    company: Optional[str] = Field(None, description='Company or employer')

发起提取调用

将您的 Pydantic 模型类作为 response_model 传递给修补后的客户端。提取库会在幕后构造工具调用，模型填充各个字段，然后提取库将结果反序列化为带类型的 Python 对象。对于返回的数据，您可以获得完整的 IDE 自动补全和类型安全支持。

result = client.chat.completions.create(
    model='gpt-4o-mini',
    response_model=PersonExtract,
    messages=[
        {'role': 'user', 'content': 'Alice Smith, 34, works at Acme Corp. Email: alice@acme.com'}
    ]
)
print(result.name)   # Alice Smith
print(result.email)  # alice@acme.com

验证失败时自动重试

如果模型返回的数据未通过 Pydantic 验证，提取库会自动将验证错误发送回模型，并要求模型修正其响应。您可以通过 max_retries 参数配置最大重试次数。这种自我修复循环无需额外代码，就能消除大多数偶发的提取失败。

import instructor
from openai import OpenAI
from pydantic import BaseModel, field_validator

client = instructor.from_openai(OpenAI())

class Product(BaseModel):
    name: str
    price_usd: float

    @field_validator('price_usd')
    @classmethod
    def must_be_positive(cls, v):
        if v <= 0:
            raise ValueError('Price must be positive')
        return v

result = client.chat.completions.create(
    model='gpt-4o-mini',
    response_model=Product,
    max_retries=3,
    messages=[{'role': 'user', 'content': 'Widget costs $12.99'}]
)

使用嵌套模型处理复杂结构

提取库可以无缝处理嵌套的 Pydantic 模型。您可以定义包含列表、可选子对象和带判别字段联合类型的深层嵌套模式。模型会接收完整的 JSON Schema，并且必须填充所有必需字段，因此非常适合提取发票或简历等包含多个部分的结构化对象。

from pydantic import BaseModel
from typing import List

class LineItem(BaseModel):
    description: str
    quantity: int
    unit_price: float

class Invoice(BaseModel):
    vendor: str
    invoice_number: str
    total_amount: float
    line_items: List[LineItem]

result = client.chat.completions.create(
    model='gpt-4o',
    response_model=Invoice,
    messages=[{'role': 'user', 'content': invoice_text}]
)

流式提取部分结果

对于大型提取任务，提取库支持通过 instructor.Partial[YourModel] 进行部分流式传输。模型生成令牌时，您会实时收到已部分填充的模型实例。这对于在界面中显示进度，或在字段到达后立即处理字段很有用，无需等待完整响应。

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI())

for partial in client.chat.completions.create_partial(
    model='gpt-4o-mini',
    response_model=PersonExtract,
    messages=[{'role': 'user', 'content': long_text}]
):
    print(partial.name, partial.email)

提取对象列表

当您需要从单个文档中提取多个实体时，请将模型包装在 List[YourModel] 中。提取库会处理 JSON 数组模式，并将每个元素反序列化为带类型的 Python 对象。这种模式非常适合提取文章中提到的所有人员、对账单中的所有交易，或合同中的所有日期。

from pydantic import BaseModel
from typing import List

class Mention(BaseModel):
    entity: str
    entity_type: str  # PERSON, ORG, DATE, LOCATION
    context: str

result = client.chat.completions.create(
    model='gpt-4o-mini',
    response_model=List[Mention],
    messages=[{'role': 'user', 'content': article_text}]
)
for mention in result:
    print(f'{mention.entity} ({mention.entity_type})')

为提取选择合适的模型

并非所有提取任务都需要 GPT-4o。对于少于 10 个字段的简单扁平模式，gpt-4o-mini 能以十分之一的成本生成几乎相同的结果。对于复杂的嵌套模式、较长的文档，或重视召回率的场景，请使用 GPT-4o。在为生产环境选择模型之前，务必使用真实数据样本进行基准测试。

# Cost comparison for 1000 extractions
# GPT-4o-mini: ~$0.002 per call = $2.00 total
# GPT-4o: ~$0.015 per call = $15.00 total
# Test both on 50 samples and compare F1 score
# before committing to the expensive model

记录和调试提取过程

提取库提供了用于可观测性的 hooks 系统。注册 on_completion 回调，以记录每次提取的原始 API 响应、令牌用量和重试次数。这有助于您找出失败最多的文档类型，并据此调整模式或提示。

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI())

@client.on('completion:response')
def log_usage(response):
    usage = response.usage
    print(f'Tokens: {usage.prompt_tokens}+{usage.completion_tokens}')

result = client.chat.completions.create(
    model='gpt-4o-mini',
    response_model=PersonExtract,
    messages=[{'role': 'user', 'content': text}]
)

快速检查

测试您对使用带类型提取的提取库的理解。

在交互式课程中回答

课程回顾

在本课中，您学到了：提取库会修补 OpenAI 客户端，使其接受能够强制执行 Pydantic 模式的 response_model 参数；验证失败时自动重试，无需手动处理错误即可让提取更加稳健；嵌套模型和列表提取则可以将复杂的多实体文档解析为带完整类型信息的 Python 对象。接下来，我们将处理提取模式中的部分数据和缺失数据。

免费开始

用 AI 导师学习 Python — 免费

在浏览器中编写并运行真实代码，获得全天候 AI 导师的即时帮助，并在网页或应用中继续学习。

课程: 30
课程: 120

免费开始学习查看完整课程

常见问题解答

「Instructor：使用 Pydantic 进行类型化提取」课时是免费的吗？

是的 — 「Instructor：使用 Pydantic 进行类型化提取」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 AI Engineering Academy 课程的其余内容，请升级到 CoddyKit PRO。 AI Engineering Academy 课程共包含 4 节课。

「Instructor：使用 Pydantic 进行类型化提取」这节课中我会学到什么？

使用 instructor 库修改 OpenAI 客户端，使其自动重试，并根据您的 Pydantic 模式验证响应，直到提取成功。你通过在浏览器中直接运行的动手代码来练习 AI Engineering Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 AI Engineering Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 AI Engineering Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 1 节课，共 4 节。

「Instructor：使用 Pydantic 进行类型化提取」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 AI Engineering Academy 课中编写并运行代码吗？

能。每节 AI Engineering Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 AI Engineering Academy