跳到内容

重试机制

Instructor 中的重试机制通过给 LLM 另一次机会生成有效响应来处理验证失败。本指南解释了重试的工作原理以及如何根据您的用例对其进行自定义。

重试如何工作

当验证失败时，Instructor 会

  1. 捕获验证错误
  2. 将它们格式化为反馈
  3. 将反馈添加到提示词上下文中
  4. 要求 LLM 利用这些新信息再次尝试

这创建了一个反馈循环，帮助 LLM 修正其输出，直到生成有效响应。

基本重试示例

这是一个展示重试功能的简单示例

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

# Initialize the client with max_retries
client = instructor.from_openai(
    OpenAI(),
    max_retries=2  # Will try up to 3 times (initial + 2 retries)
)

class Product(BaseModel):
    name: str
    price: float = Field(..., gt=0)

    @field_validator('name')
    @classmethod
    def validate_name(cls, v):
        if len(v) < 3:
            raise ValueError("Product name must be at least 3 characters")
        return v

# This will automatically retry if validation fails
response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[
        {"role": "user", "content": "Product: Pen, Price: -5"}
    ],
    response_model=Product
)

在此示例中，初始响应很可能会验证失败，因为：- 价格是负数（违反了 gt=0 约束）- Instructor 将自动使用关于这些问题的反馈进行重试

有关 max_retries 配置的更多详细信息，请参阅重试概念页面。

自定义重试行为

您可以在初始化 Instructor 客户端时自定义重试行为

import instructor
from openai import OpenAI

# Customize retry behavior
client = instructor.from_openai(
    OpenAI(),
    max_retries=3,                   # Maximum number of retries
    retry_if_parsing_fails=True,     # Retry on JSON parsing failures
    throw_error=True                 # Throw an error if all retries fail
)

重试配置选项

选项 描述 默认值
max_retries 最大重试次数 0
retry_if_parsing_fails 如果 JSON 解析失败是否重试 True
throw_error 如果所有重试都失败是否抛出错误 True

处理重试失败

当所有重试都失败时，取决于您的配置

  1. 设置 throw_error=True (默认): 抛出异常
  2. 设置 throw_error=False: 返回最后一次失败的响应，您可以优雅地处理它

有关处理验证失败的更多信息，请参阅回退策略。

错误消息和反馈

Instructor 在重试期间向 LLM 提供详细的错误消息

The following errors occurred during validation:
- price: ensure this value is greater than 0
- name: Product name must be at least 3 characters

Please fix these errors and ensure the response is valid.

此反馈帮助 LLM 准确理解需要修正什么。

重试限制

虽然重试功能强大，但也存在一些限制

  1. 重试预算: 每次重试都会消耗 token 和时间
  2. 持续性错误: 某些错误可能无法由 LLM 修复
  3. 模型限制: 某些模型可能持续难以处理某些验证

对于复杂的验证场景，考虑实现自定义验证器或字段级别验证。

高级重试模式：渐进式验证

对于复杂的 schema，您可以实现渐进式验证模式

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

# Initialize with moderate retries
client = instructor.from_openai(
    OpenAI(),
    max_retries=2
)

# Basic validation first
class BasicProduct(BaseModel):
    name: str
    price: float = Field(..., gt=0)

# Advanced validation second
class DetailedProduct(BasicProduct):
    description: str = Field(..., min_length=10)
    category: str
    in_stock: bool

# Two-step extraction with validation
try:
    # First get basic fields
    basic = client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[
            {"role": "user", "content": "Product: Mini Pen, Price: $2.50"}
        ],
        response_model=BasicProduct
    )

    # Then get full details with context from the first step
    detailed = client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[
            {"role": "user", "content": f"Provide more details about {basic.name} which costs ${basic.price}"}
        ],
        response_model=DetailedProduct
    )
except Exception as e:
    # Handle validation failures
    print(f"Validation failed: {e}")

后续步骤