理解响应模型¶

响应模型是 Instructor 功能的核心。它们定义了你想要提取的数据结构并提供验证规则。本指南解释了如何为各种用例创建不同类型的响应模型。

基本模型¶

让我们从一个之前看过的简单模型开始

from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int

这定义了一个包含两个必填字段的模型：name（字符串）和 age（整数）。

添加字段元数据¶

你可以使用 Field 类为字段添加元数据

from pydantic import BaseModel, Field

class WeatherForecast(BaseModel):
    """Weather forecast for a specific location"""

    temperature: float = Field(
        description="Current temperature in Celsius"
    )
    condition: str = Field(
        description="Weather condition (sunny, cloudy, rainy, etc.)"
    )
    humidity: int = Field(
        description="Humidity percentage from 0-100"
    )

字段描述有助于大型语言模型（LLM）理解每个字段需要提取的信息。

字段验证¶

你可以添加验证规则以确保提取的数据符合你的要求

from pydantic import BaseModel, Field

class Product(BaseModel):
    name: str = Field(min_length=3)
    price: float = Field(gt=0)  # greater than 0
    quantity: int = Field(ge=0)  # greater than or equal to 0
    description: str = Field(max_length=500)

常见的验证参数包括： - min_length/max_length：用于字符串 - ge/gt/le/lt：用于数字（大于/小于或等于/大于） - pattern：用于正则表达式匹配

有关验证的更多信息，请参阅字段验证和验证基础指南。

嵌套模型¶

你可以使用嵌套模型创建复杂的数据结构

from pydantic import BaseModel, Field
from typing import List, Optional

class Address(BaseModel):
    street: str
    city: str
    state: Optional[str] = None
    country: str

class User(BaseModel):
    name: str
    age: int
    addresses: List[Address]

这允许你提取分层数据结构。更多示例请查看简单嵌套结构指南。

使用枚举¶

当你你想将字段限制在一组特定值时，枚举很有用

from enum import Enum
from pydantic import BaseModel

class UserType(str, Enum):
    ADMIN = "admin"
    REGULAR = "regular"
    GUEST = "guest"

class User(BaseModel):
    name: str
    user_type: UserType

可选字段¶

对于源文本中可能不存在的字段

from typing import Optional
from pydantic import BaseModel

class Contact(BaseModel):
    name: str
    email: str
    phone: Optional[str] = None
    address: Optional[str] = None

有关使用可选字段的更多信息，请参阅可选字段指南。

列表和数组¶

用于提取多个相同类型的项目

from typing import List
from pydantic import BaseModel

class BlogPost(BaseModel):
    title: str
    content: str
    tags: List[str]

有关使用列表的更多信息，请参阅列表提取指南。

在 Instructor 中使用你的模型¶

定义好模型后，你就可以用它进行提取

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI())

forecast = client.chat.completions.create(
    model="gpt-3.5-turbo",
    response_model=WeatherForecast,
    messages=[
        {"role": "user", "content": "What's the weather in New York today?"}
    ]
)

print(forecast.model_dump_json(indent=2))

模型文档¶

你可以使用文档字符串和字段描述为你的模型添加文档

from pydantic import BaseModel, Field

class Investment(BaseModel):
    """Represents an investment opportunity with risk and return details."""

    name: str = Field(description="Name of the investment")
    amount: float = Field(description="Investment amount in USD")
    expected_return: float = Field(description="Expected annual return percentage")
    risk_level: str = Field(description="Risk level (low, medium, high)")

这个文档既有助于大型语言模型（LLM）理解要提取什么，也使你的代码更易于维护。

使用验证器进行高级验证¶

对于更复杂的验证规则，你可以使用验证器方法

from pydantic import BaseModel, Field, field_validator
from datetime import date

class Reservation(BaseModel):
    check_in: date
    check_out: date
    guests: int = Field(ge=1)

    @field_validator("check_out")
    def check_dates(cls, v, values):
        if "check_in" in values.data and v <= values.data["check_in"]:
            raise ValueError("check_out must be after check_in")
        return v

有关更高级的验证技术，请查看自定义验证器指南。

下一步¶

在下一节中，学习关于客户端设置，了解如何配置不同的 LLM 提供商并理解各种操作模式。