解析instructor包实现LLM输出结构化的底层原理及调试方法

两段代码的运行机制 #

Instructor的核心作用是封装OpenAI客户端，自动将Pydantic模型转换为LLM可理解的提示规则，并把LLM返回的JSON结果解析为Pydantic实例，让结构化输出的实现更简洁。

第一段代码的运行流程 #

1. 定义User类继承自BaseModel，声明name（字符串类型）和age（整数类型）两个字段，这就是我们期望的结构化输出格式。
2. 通过instructor.from_openai(OpenAI())创建增强版OpenAI客户端，该客户端被注入了处理结构化输出的逻辑。
3. 调用chat.completions.create时指定response_model=User：
   • Instructor自动生成包含User模型字段类型、约束的提示文本，追加到请求的messages中。
   • 客户端将完整请求发送给GPT-4-turbo模型。
   • LLM根据提示生成符合User结构的JSON响应。
   • Instructor自动把JSON解析为User类实例，因此可以直接通过user.name、user.age访问对应字段值。

第二段代码的差异与运行逻辑 #

第二段代码和第一段核心逻辑完全一致，唯一区别是给UserInfo模型添加了文档字符串：

• Instructor会将该文档字符串加入生成的提示中，向LLM说明模型的用途和结构（比如示例中的文档描述内容）。
• 由于当前任务简单，文档字符串未改变最终输出结果，但在复杂场景下，文档字符串能帮助LLM更准确理解输出要求，生成更符合预期的结构化数据。

如何查看发送至API的实际提示词 #

有两种简单方法可以查看Instructor生成并发送给OpenAI API的完整提示：

方法1：启用Instructor的Debug模式 #

创建客户端时添加debug=True参数，调用create方法时会直接打印出生成的提示和完整请求内容：

import instructor
from openai import OpenAI
from pydantic import BaseModel

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

# 启用debug模式
client = instructor.from_openai(OpenAI(), debug=True)

user = client.chat.completions.create(
    model="gpt-4-turbo",
    response_model=User,
    messages=[{"role": "user", "content": "John Doe is 30 years old."}]
)

运行后控制台会输出包含完整提示的请求细节，其中就有Instructor自动生成的结构化要求文本。

方法2：开启OpenAI客户端日志 #

通过Python的logging模块开启DEBUG级别日志，会打印出OpenAI客户端发送的所有请求内容，包括messages中的完整提示：

import logging
import instructor
from openai import OpenAI
from pydantic import BaseModel

# 配置日志级别
logging.basicConfig(level=logging.DEBUG)

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

client = instructor.from_openai(OpenAI())

user = client.chat.completions.create(
    model="gpt-4-turbo",
    response_model=User,
    messages=[{"role": "user", "content": "John Doe is 30 years old."}]
)

日志中会包含request.body字段，里面的messages数组就是实际发送给API的内容。

内容的提问来源于stack exchange，提问作者Mischa