Instructor 架构¶

本文档解释了 Instructor 的内部工作原理以及它如何与不同的 LLM 提供商集成。

核心组件¶

Instructor 由几个协同工作的关键组件组成

graph TD
    User[User Code] --> PydanticModel[Pydantic Model]
    User --> ClientInit[Initialize Provider Client]
    ClientInit --> PatchedClient[Patched LLM Client]
    PydanticModel --> SchemaConverter[Schema Converter]
    SchemaConverter --> ProviderAdapter[Provider-Specific Adapter]
    PatchedClient --> APIRequest[API Request]
    ProviderAdapter --> APIRequest
    APIRequest --> ResponseParser[Response Parser]
    ResponseParser --> Validator[Pydantic Validator]
    Validator -- Valid --> StructuredOutput[Structured Output]
    Validator -- Invalid --> RetryMechanism[Retry Mechanism]
    RetryMechanism --> APIRequest

组件说明¶

Pydantic 模型: 定义您想要提取的数据结构
Schema 转换器: 将 Pydantic 模型转换为 LLM 理解的 Schema
特定提供商适配器: 为特定的 LLM 提供商格式化请求
修补的 LLM 客户端: 增强提供商客户端的结构化输出能力
响应解析器: 从 LLM 响应中提取结构化数据
验证器: 根据 Pydantic 模型验证响应
重试机制: 验证失败时自动附带反馈进行重试

请求流程¶

以下是典型的 Instructor 请求在系统中流动的过程

sequenceDiagram
    participant User
    participant Instructor
    participant ProviderClient
    participant LLM

    User->>Instructor: create(response_model=Model, messages=[...])
    Instructor->>Instructor: Convert Pydantic model to schema
    Instructor->>Instructor: Format request for provider
    Instructor->>ProviderClient: Forward request with tools/functions
    ProviderClient->>LLM: Make API request
    LLM->>ProviderClient: Return response
    ProviderClient->>Instructor: Return response
    Instructor->>Instructor: Parse structured data
    Instructor->>Instructor: Validate against model

    alt Validation succeeds
        Instructor->>User: Return validated Pydantic object
    else Validation fails
        Instructor->>Instructor: Generate error feedback
        Instructor->>ProviderClient: Retry with feedback
        ProviderClient->>LLM: Make new request
        LLM->>ProviderClient: Return new response
        ProviderClient->>Instructor: Return new response
        Instructor->>Instructor: Parse and validate again
        Instructor->>User: Return validated Pydantic object
    end

这种架构使得 Instructor 能够在不同 LLM 提供商之间提供一致的接口，同时在幕后处理它们特定的实现细节。