跳到正文

字段级验证

字段级验证允许您为数据模型中的单个字段创建特定规则。本指南展示了如何在 Instructor 中使用字段级验证。

什么是字段级验证？

Instructor 中的字段级验证使用 Pydantic 的验证功能来

  1. 使用自定义规则检查单个字段
  2. 转换字段值（例如格式化或清理数据）
  3. 对特定字段应用业务规则
  4. 在值无效时提供清晰的反馈

验证在处理模型时进行，如果验证失败，Instructor 将使用更好的指令重试。

基本字段验证

您可以使用 Pydantic 的 Field 约束应用简单验证

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

client = instructor.from_openai(OpenAI())

class User(BaseModel):
    name: str = Field(..., min_length=2, description="User's full name")
    age: int = Field(..., ge=18, le=120, description="User's age in years")
    email: str = Field(
        ..., 
        pattern=r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$",
        description="Valid email address"
    )

有关更多详细信息，请参阅字段概念页面。

自定义字段验证器

对于更复杂的规则，使用 field_validator 装饰器

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

client = instructor.from_openai(OpenAI())

class Product(BaseModel):
    name: str
    sku: str
    price: float

    @field_validator('name')
    @classmethod
    def validate_name(cls, v):
        if len(v.strip()) < 3:
            raise ValueError("Product name must be at least 3 characters long")
        return v.strip().title()  # Clean up and format

    @field_validator('sku')
    @classmethod
    def validate_sku(cls, v):
        pattern = r'^[A-Z]{3}-\d{4}$'
        if not re.match(pattern, v):
            raise ValueError("SKU must be in format XXX-0000 (3 uppercase letters, dash, 4 digits)")
        return v

联合验证多个字段

有时一个字段的有效性取决于其他字段。为此使用 model_validator

from pydantic import BaseModel, model_validator
import instructor
from openai import OpenAI
from datetime import date

client = instructor.from_openai(OpenAI())

class Reservation(BaseModel):
    check_in: date
    check_out: date
    room_type: str
    guests: int

    @model_validator(mode='after')
    def validate_dates(self):
        if self.check_out <= self.check_in:
            raise ValueError("Check-out date must be after check-in date")

        if self.room_type == "Standard" and self.guests > 2:
            raise ValueError("Standard rooms can only fit 2 guests")

        return self

如何处理验证错误

当验证失败时，Instructor 添加错误详细信息以帮助 AI 解决问题

The following errors occurred during validation:
- product_sku: Product not found
- quantity: Quantity must be at least 1

Please fix these errors and ensure the response is valid.

最佳实践

  1. 顺序很重要：验证器按照定义顺序运行
  2. 清晰的消息：编写具体的错误消息
  3. 先清理：在验证之前处理数据清理
  4. 尽早验证：在模型级验证之前检查字段
  5. 明智地转换：字段验证器既可以检查也可以更改值

下一步