跳到主要内容

Instructor

Instructor 是一个 Python 库，可使用 Pydantic 模型从 LLM 响应中提取结构化数据。它在服务提供方客户端之上提供响应模型校验与重试能力。

Instructor 可以包装已指向 AISIX 的兼容 OpenAI 客户端。当应用需要保留 Instructor 的响应模型工作流，同时通过网关路由模型流量时，请使用此配置。

本指南将 Instructor 与 OpenAI Python 客户端结合使用。你将使用 AISIX 代理 URL、调用方 API Key 和模型别名配置该客户端，再将其交给 Instructor。

前置条件​

开始前，请准备以下内容：

  • 一个受 Instructor 支持的 Python 环境。
  • 一个代理监听器可用的运行中 AISIX 网关。
  • 一个 AISIX 调用方 API Key。
  • 一个可通过兼容 OpenAI 的 API访问的模型别名。

配置 Instructor​

如果应用尚未包含相应 Python 包，请先安装：

pip install instructor openai "pydantic>=2"

设置应用要使用的值：

# Replace with your values
export AISIX_BASE_URL="http://127.0.0.1:3000/v1"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="gpt-4o-prod"

创建指向 AISIX 的 OpenAI 客户端，再传递给 Instructor：

import os

import instructor
from openai import OpenAI
from pydantic import BaseModel


class Ticket(BaseModel):
  category: str
  priority: str


openai_client = OpenAI(
  base_url=os.environ["AISIX_BASE_URL"],
  api_key=os.environ["AISIX_API_KEY"],
)

client = instructor.from_openai(openai_client)

ticket = client.chat.completions.create(
  model=os.environ["AISIX_MODEL"],
  response_model=Ticket,
  messages=[
    {
      "role": "user",
      "content": "Classify this ticket: production login failures for all users.",
    }
  ],
)

print(ticket.model_dump_json(indent=2))

模型值应填写 AISIX 模型别名，而不是上游服务提供方模型 ID。AISIX 负责模型请求路径：验证调用方 API Key、解析别名、应用策略、记录遥测数据，并将请求分发到别名背后的服务提供方。Instructor 仍负责 Schema 校验和重试。

验证路由​

在已设置 AISIX 环境变量的 Shell 中运行脚本。

请求成功后，请确认以下结果：

  • 脚本输出通过校验的 Pydantic 对象。
  • AISIX 为所选模型别名记录一条或多条成功的 POST /v1/chat/completions 请求。

如果使用 AISIX Cloud 或私有化部署的托管控制面，请在托管网关日志中验证请求。对于自托管网关，请使用已配置的日志、指标或上游服务提供方日志。

处理兼容性问题​

如果请求失败，请先确认调用方 API Key 可以访问所选模型别名，且 OpenAI 客户端使用 AISIX 的 base_url。

当校验失败时，Instructor 可能重试请求。配置预算、限流和用量审查时应考虑这些重试。如果持续重试，请检查上游模型是否能满足 Schema，以及所选 Instructor 模式是否受 AISIX 路由支持。

后续步骤​