修补¶

Instructor 通过修补 LLM 客户端，为其增强了结构化输出功能。这使得您可以像往常一样使用增强后的客户端，同时获得结构化输出的好处。

核心修补功能¶

Instructor 为客户端的 chat.completions.create 方法添加了三个关键参数

response_model：定义预期的响应类型（Pydantic 模型或简单类型）
max_retries：控制验证失败时应尝试的最大重试次数
validation_context：为验证钩子提供额外的上下文

修补模式¶

默认模式是 instructor.Mode.TOOLS，这是推荐用于 OpenAI 客户端的模式。不同的提供商根据其能力支持不同的模式。

工具调用¶

这是 OpenAI 客户端的推荐方法。它是最稳定的，因为函数调用（functions）即将被弃用。

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI(), mode=instructor.Mode.TOOLS)

Gemini 工具调用¶

Gemini 支持工具调用用于结构化数据提取。Gemini 工具调用需要安装 jsonref。

限制

Gemini 工具调用存在一些已知限制

- `strict` Pydantic validation can fail for integer/float and enum validations
- Gemini tool calling is incompatible with Pydantic schema customizations such as examples due to API limitations and may result in errors
- Gemini can sometimes call the wrong function name, resulting in malformed or invalid json
- Gemini tool calling could fail with enum and literal field types
- Gemini tool calling doesn't preserve the order of the fields in the response. Don't rely on the order of the fields in the response.

import instructor
import google.generativeai as genai

client = instructor.from_gemini(
    genai.GenerativeModel(), mode=instructor.Mode.GEMINI_TOOLS
)

Gemini Vertex AI 工具调用¶

此方法允许我们通过使用 Vertex AI SDK 的工具调用从 Gemini 获取结构化输出。

注意： Gemini 工具调用处于预览阶段，存在一些限制，您可以在Vertex AI 示例笔记本中了解更多信息。

import instructor
from vertexai.generative_models import GenerativeModel  # type: ignore
import vertexai

vertexai.init(project="vertexai-generative-models")


client = instructor.from_vertexai(
    client=GenerativeModel("gemini-1.5-pro-preview-0409"),
    mode=instructor.Mode.VERTEXAI_TOOLS,
)

并行工具调用¶

并行工具调用也是一种选择，但您必须将 response_model 设置为 Iterable[Union[...]] 类型，因为我们期望得到一个结果数组。请参阅并行工具调用以获取更多信息。

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI(), mode=instructor.Mode.PARALLEL_TOOLS)

函数调用¶

请注意，对于 OpenAI，函数调用即将被弃用，转而使用 TOOL 模式。但对于其他客户端仍将支持。

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI(), mode=instructor.Mode.TOOLS)

JSON 模式¶

JSON 模式通过在 chat.completions.create 方法中设置 response_format={"type": "json_object"} 来使用 OpenAI 的 JSON 格式作为响应。

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI(), mode=instructor.Mode.JSON)

JSON 模式也需要用于通过 OpenAI SDK 使用 Gemini 模型。

pip install google-auth

import google.auth
import google.auth.transport.requests
import instructor
from openai import OpenAI

creds, project = google.auth.default()
auth_req = google.auth.transport.requests.Request()
creds.refresh(auth_req)

# Pass the Vertex endpoint and authentication to the OpenAI SDK
PROJECT = 'PROJECT_ID'
LOCATION = 'LOCATION'

base_url = f'https://{LOCATION}-aiplatform.googleapis.com/v1beta1/projects/{PROJECT}/locations/{LOCATION}/endpoints/openapi'
client = instructor.from_openai(
    OpenAI(base_url=base_url, api_key=creds.token), mode=instructor.Mode.JSON
)

Gemini JSON 模式¶

此模式使用 Gemini 的响应 mimetype 字段，根据提供的 schema 生成 JSON 格式的响应。

import instructor
import google.generativeai as genai

client = instructor.from_gemini(
    genai.GenerativeModel(), mode=instructor.Mode.GEMINI_JSON
)

Markdown JSON 模式¶

这只是简单地要求以 JSON 格式返回响应，但不推荐使用此模式，将来可能不再支持。保留此模式仅用于支持视觉模型和由 Databricks 提供的模型，并且无法为您提供 instructor 的全部好处。

实验性

不推荐使用此模式，将来可能不再支持。保留此模式仅用于支持视觉模型和由 Databricks 提供的模型。

通用语法

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI(), mode=instructor.Mode.MD_JSON)

Databricks 语法

import instructor
import os
from openai import OpenAI

DATABRICKS_TOKEN = os.environ.get("DATABRICKS_TOKEN", "")
DATABRICKS_HOST = os.environ.get("DATABRICKS_HOST", "")

# Assuming Databricks environment variables are set
client = instructor.from_openai(
    OpenAI(
        api_key=DATABRICKS_TOKEN,
        base_url=f"{DATABRICKS_HOST}/serving-endpoints",
    ),
    mode=instructor.Mode.MD_JSON,
)