跳到主要内容

Instructor

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

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

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

前置条件​

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

  • 一个受 Instructor 支持的 Python 环境。
  • 一个正在运行且应用可以访问的 AISIX 网关。
  • 一个 AISIX 调用方 API Key。
  • 一个可通过Responses API访问的模型别名。

如果你的组织已经部署 AISIX，请向管理团队获取网关 URL、模型别名和调用方 API Key。否则，请按照开源 AISIX 网关快速上手或 AISIX Cloud 快速上手完成部署，也可以联系 API7申请 Hybrid Cloud 访问权限。

配置 Instructor​

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

pip install instructor openai "pydantic>=2"

设置应用要使用的值：

# 请替换为实际值
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 客户端，再以 Responses 模式传递给 Instructor：

import os

import instructor
from instructor import Mode
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,
  mode=Mode.RESPONSES_TOOLS,
)

ticket = client.responses.create(
  model=os.environ["AISIX_MODEL"],
  response_model=Ticket,
  input="Classify this ticket: production login failures for all users.",
)

print(ticket.model_dump_json(indent=2))

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

Instructor 还通过 client.chat.completions.create(...) 支持 Chat Completions 模式。当工作流需要广泛的兼容 OpenAI 聊天支持时，请使用这些模式。

验证集成​

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

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

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

请在 AISIX 网关日志中验证请求。也可以使用已配置的指标或上游服务提供方日志。

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

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

后续步骤​

  • Responses API：查看面向网关的 Responses 行为。
  • 兼容 OpenAI 的 API：当工作流需要广泛的兼容 OpenAI 支持时使用 Chat Completions。
  • 预算：在 AISIX Cloud 支出控制中考虑校验重试。