修补¶

讲师通过三个新的关键字增强了客户端功能，以实现向后兼容性。这使得可以像往常一样使用增强的客户端，同时享受结构化输出的好处。

response_model：定义chat.completions.create的响应类型。
max_retries: 决定失败的 chat.completions.create 验证的重试次数。
validation_context: 提供额外的上下文信息给验证过程。

默认模式是instructor.Mode.TOOLS，这是OpenAI客户端的推荐模式。此模式最为稳定，强烈推荐给OpenAI客户端使用。其他模式适用于其他客户端，不建议OpenAI客户端使用。

工具调用¶

这是推荐给OpenAI客户端的方法。由于函数即将被弃用，这是最稳定的方法。

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字段，根据提供的模式生成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,
)