客户端设置¶

设置正确的客户端是使用 Instructor 与各种 LLM 提供商的第一步。本指南介绍了如何为不同的提供商配置客户端并解释了可用的各种模式。

OpenAI¶

最常见的配置是使用 OpenAI

import instructor
from openai import OpenAI

# Default mode (TOOLS)
client = instructor.from_openai(OpenAI())

# With JSON mode
client = instructor.from_openai(
    OpenAI(),
    mode=instructor.Mode.JSON  # Use JSON mode instead
)

Anthropic (Claude)¶

对于 Anthropic 的 Claude 模型

import instructor
from anthropic import Anthropic

# Default mode (ANTHROPIC_TOOLS)
client = instructor.from_anthropic(Anthropic())

# With JSON mode
client = instructor.from_anthropic(
    Anthropic(),
    mode=instructor.Mode.JSON
)

Google Gemini¶

对于 Google 的 Gemini 模型

import instructor
import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")
model = genai.GenerativeModel("gemini-1.5-flash")

client = instructor.from_gemini(
    model,
    mode=instructor.Mode.GEMINI_TOOLS  # or GEMINI_JSON
)

Cohere¶

对于 Cohere 的模型

import instructor
import cohere

cohere_client = cohere.Client("YOUR_API_KEY")
client = instructor.from_cohere(cohere_client)

Mistral¶

对于 Mistral AI 的模型

import instructor
from mistralai.client import MistralClient

mistral_client = MistralClient(api_key="YOUR_API_KEY")
client = instructor.from_mistral(mistral_client)

理解模式¶

Instructor 支持用于结构化提取的不同模式

from instructor import Mode

Mode.TOOLS         # OpenAI function calling format (default for OpenAI)
Mode.JSON          # Plain JSON generation
Mode.MD_JSON       # Markdown JSON (used by some providers)
Mode.ANTHROPIC_TOOLS # Claude tools mode (default for Anthropic)
Mode.GEMINI_TOOLS  # Gemini tools format
Mode.GEMINI_JSON   # Gemini JSON format

何时使用每种模式¶

TOOLS/FUNCTION_CALL：OpenAI 的默认模式。使用函数调用来获取可靠的结构化输出。
JSON：适用于大多数提供商。模型直接生成 JSON。
MD_JSON：适用于能很好地处理 Markdown 格式 JSON 的模型。
ANTHROPIC_TOOLS：Anthropic 的默认模式。使用 Claude 的工具 API。
GEMINI_TOOLS/GEMINI_JSON：适用于 Google 的 Gemini 模型。

选择最适合你所选提供商和模型的模式。

异步客户端¶

对于异步操作，请使用客户端的异步版本。

import asyncio
import instructor
from openai import AsyncOpenAI
from pydantic import BaseModel

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

async def extract_user():
    async_client = instructor.from_openai(AsyncOpenAI())
    return await async_client.chat.completions.create(
        model="gpt-3.5-turbo",
        response_model=User,
        messages=[
            {"role": "user", "content": "John is 30 years old."}
        ]
    )

user = asyncio.run(extract_user())

类似的 async 模式也适用于 Anthropic 和 Mistral 等其他提供商。

高级 OpenAI 配置¶

你可以向 OpenAI 客户端传递额外的参数。

import instructor
from openai import OpenAI

client = instructor.from_openai(
    OpenAI(),
    mode=instructor.Mode.TOOLS,
    max_retries=2,  # Number of retries for validation failures
)

# With API key explicitly defined
client = instructor.from_openai(
    OpenAI(api_key="your-api-key"),
    mode=instructor.Mode.JSON
)

# With organization ID
client = instructor.from_openai(
    OpenAI(
        api_key="your-api-key",
        organization="org-..."
    )
)

通过 OpenAI 兼容接口与其他提供商一起使用¶

许多提供商提供 OpenAI 兼容的 API。

import instructor
from openai import OpenAI

# Example for Azure OpenAI
azure_client = instructor.from_openai(
    OpenAI(
        api_key="your-azure-api-key",
        base_url="https://your-resource-name.openai.azure.com/openai/deployments/your-deployment-name"
    )
)

# Example for Groq
groq_client = instructor.from_openai(
    OpenAI(
        api_key="your-groq-api-key",
        base_url="https://api.groq.com/openai/v1"
    )
)

下一步¶

设置好客户端后，你可以

创建简单对象提取
使用列表和嵌套结构
向你的模型添加验证
处理可选字段

以下章节将通过越来越复杂的示例引导你了解这些模式。