使用基于字符串的初始化的统一提供商接口¶

Instructor 现在提供了一种简化方法，可以使用单个一致的接口初始化任何受支持的 LLM 提供商。这种方法使在不同 LLM 提供商之间切换变得比以往任何时候都更容易，同时保持您所依赖的结构化输出功能。

问题¶

随着 LLM 提供商数量的增加，初始化和使用不同客户端库的复杂性也随之增加。每个提供商都有其自己的初始化模式、API 结构和怪癖。这导致代码在提供商之间不可移植，并且在您想尝试新模型时需要大量的重构。

解决方案：基于字符串的初始化¶

我们引入了一种新的统一接口，允许您使用简单的字符串格式初始化任何受支持的提供商

import instructor
from pydantic import BaseModel

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

# Initialize any provider with a single consistent interface
client = instructor.from_provider("openai/gpt-4")
client = instructor.from_provider("anthropic/claude-3-sonnet")
client = instructor.from_provider("google/gemini-pro")
client = instructor.from_provider("mistral/mistral-large")

from_provider 函数接受 `"provider/model-name"` 格式的字符串，并处理设置具有正确模型的适当客户端的所有细节。这提供了几个主要优势

简化初始化：无需手动创建提供商特定客户端
一致接口：相同的语法适用于所有提供商
减少依赖暴露：您无需在应用程序代码中导入特定的提供商库
轻松实验：通过更改一行代码即可在提供商之间切换

支持的提供商¶

基于字符串的初始化目前支持生态系统中的所有主要提供商

OpenAI: `"openai/gpt-4"`, `"openai/gpt-4o"`, `"openai/gpt-3.5-turbo"`
Anthropic: `"anthropic/claude-3-opus-20240229"`, `"anthropic/claude-3-sonnet-20240229"`, `"anthropic/claude-3-haiku-20240307"`
Google Gemini: `"google/gemini-pro"`, `"google/gemini-pro-vision"`
Mistral: `"mistral/mistral-small-latest"`, `"mistral/mistral-medium-latest"`, `"mistral/mistral-large-latest"`
Cohere: `"cohere/command"`, `"cohere/command-r"`, `"cohere/command-light"`
Perplexity: `"perplexity/sonar-small-online"`, `"perplexity/sonar-medium-online"`
Groq: `"groq/llama2-70b-4096"`, `"groq/mixtral-8x7b-32768"`, `"groq/gemma-7b-it"`
Writer: `"writer/palmyra-instruct"`, `"writer/palmyra-instruct-v2"`
AWS Bedrock: `"bedrock/anthropic.claude-v2"`, `"bedrock/amazon.titan-text-express-v1"`
Cerebras: `"cerebras/cerebras-gpt"`, `"cerebras/cerebras-gpt-2.7b"`
Fireworks: `"fireworks/llama-v2-70b"`, `"fireworks/firellama-13b"`
Vertex AI: `"vertexai/gemini-pro"`, `"vertexai/text-bison"`
Google GenAI: `"genai/gemini-pro"`, `"genai/gemini-pro-vision"`

每个提供商都将使用合理的默认值进行初始化，但您也可以传递额外的关键字参数来自定义配置。有关特定模型的详细信息，请查阅各提供商的文档。

异步支持¶

统一接口完全支持同步和异步客户端

# Synchronous client (default)
client = instructor.from_provider("openai/gpt-4")

# Asynchronous client
async_client = instructor.from_provider("anthropic/claude-3-sonnet", async_client=True)

# Use like any other async client
response = await async_client.chat.completions.create(
    response_model=UserInfo,
    messages=[{"role": "user", "content": "Extract information about John who is 30 years old"}]
)

模式选择¶

您还可以指定与提供商一起使用的结构化输出模式

import instructor
from instructor import Mode

# Override the default mode for a provider
client = instructor.from_provider(
    "anthropic/claude-3-sonnet", 
    mode=Mode.ANTHROPIC_TOOLS
)

# Use JSON mode instead of the default tools mode
client = instructor.from_provider(
    "mistral/mistral-large", 
    mode=Mode.MISTRAL_STRUCTURED_OUTPUTS
)

# Use reasoning tools instead of regular tools for Anthropic
client = instructor.from_provider(
    "anthropic/claude-3-opus", 
    mode=Mode.ANTHROPIC_REASONING_TOOLS
)

如果未指定，每个提供商将使用其推荐的默认模式

OpenAI: Mode.OPENAI_FUNCTIONS
Anthropic: Mode.ANTHROPIC_TOOLS
Google Gemini: Mode.GEMINI_JSON
Mistral: Mode.MISTRAL_TOOLS
Cohere: Mode.COHERE_TOOLS
Perplexity: Mode.JSON
Groq: Mode.GROQ_TOOLS
Writer: Mode.WRITER_JSON
Bedrock: Mode.ANTHROPIC_TOOLS (适用于 Bedrock 上的 Claude)
Vertex AI: Mode.VERTEXAI_TOOLS

您可以始终根据您的具体需求和模型能力进行自定义。

错误处理¶

from_provider 函数包含强大的错误处理机制，可帮助您快速识别和修复问题

# Missing dependency
try:
    client = instructor.from_provider("anthropic/claude-3-sonnet")
except ImportError as e:
    print("Error: Install the anthropic package first")
    # pip install anthropic

# Invalid provider format
try:
    client = instructor.from_provider("invalid-format")
except ValueError as e:
    print(e)  # Model string must be in format "provider/model-name"

# Unsupported provider
try:
    client = instructor.from_provider("unknown/model")
except ValueError as e:
    print(e)  # Unsupported provider: unknown. Supported providers are: ...

该函数验证提供商字符串格式，检查是否支持该提供商，并确保安装了必需的软件包。

环境变量¶

与原生客户端库一样，from_provider 尊重为每个提供商设置的环境变量

# Set environment variables 
import os
os.environ["OPENAI_API_KEY"] = "your-openai-key"
os.environ["ANTHROPIC_API_KEY"] = "your-anthropic-key" 
os.environ["MISTRAL_API_KEY"] = "your-mistral-key"

# No need to pass API keys directly
client = instructor.from_provider("openai/gpt-4")

故障排除¶

以下是使用统一提供商接口时的一些常见问题和解决方案

未找到模型错误¶

如果您收到 404 错误，请检查您使用的模型名称格式是否正确

Error code: 404 - {'type': 'error', 'error': {'type': 'not_found_error', 'message': 'model: claude-3-haiku'}}

对于 Anthropic 模型，始终包含版本日期： - ✅ 正确：anthropic/claude-3-haiku-20240307 - ❌ 不正确：anthropic/claude-3-haiku

提供商特定参数¶

一些提供商需要特定的参数用于 API 调用

# Anthropic requires max_tokens
anthropic_client = instructor.from_provider(
    "anthropic/claude-3-haiku-20240307", 
    max_tokens=400  # Required for Anthropic
)

# Use models with vision capabilities for multimodal content
gemini_client = instructor.from_provider(
    "google/gemini-pro-vision"  # Required for image processing
)

工作示例¶

这是一个完整的示例，演示了使用多个提供商的 automodel 功能

import os
import asyncio
import instructor
from pydantic import BaseModel, Field

class UserInfo(BaseModel):
    """User information extraction model."""
    name: str = Field(description="The user's full name")
    age: int = Field(description="The user's age in years")
    occupation: str = Field(description="The user's job or profession")

async def main():
    # Test OpenAI
    openai_client = instructor.from_provider("openai/gpt-3.5-turbo")
    openai_result = openai_client.chat.completions.create(
        response_model=UserInfo,
        messages=[{"role": "user", "content": "Jane Doe is a 28-year-old data scientist."}]
    )
    print(f"OpenAI result: {openai_result.model_dump()}")

    # Test Anthropic with async client
    if os.environ.get("ANTHROPIC_API_KEY"):
        anthropic_client = instructor.from_provider(
            model="anthropic/claude-3-haiku-20240307",
            async_client=True,
            max_tokens=400  # Required for Anthropic
        )
        anthropic_result = await anthropic_client.chat.completions.create(
            response_model=UserInfo,
            messages=[{"role": "user", "content": "John Smith is a 35-year-old software engineer."}]
        )
        print(f"Anthropic result: {anthropic_result.model_dump()}")

if __name__ == "__main__":
    asyncio.run(main())

结论¶

基于字符串的初始化是使 Instructor 更加用户友好和灵活的重要一步。它降低了使用多个提供商的学习曲线，并使尝试不同模型变得比以往任何时候都更容易。

优点包括： - 使用一致接口简化初始化 - 自动选择适当的默认模式 - 支持同步和异步客户端 - 清晰的错误消息以快速识别问题 - 尊重提供商特定环境变量 - 涵盖整个 LLM 生态系统的全面模型选择

无论您是构建新应用程序还是迁移现有应用程序，统一提供商接口都提供了一种更清晰、更易于维护的方式来处理跨 LLM 生态系统的结构化输出。

立即使用 instructor.from_provider() 尝试，并在我们的仓库中查看完整示例代码！