Integração de saída estruturada com o Instructor

AI Gateway

Roteie suas chamadas de LLM pelo AI Gateway alterando apenas a base URL. Sem dependência de fornecedor: use sempre o melhor modelo pelo menor custo para o seu caso de uso.

Observabilidade

Instrumente seu código com OpenTelemetry para capturar traces, logs e métricas de cada chamada de LLM, etapa de agente e uso de ferramenta.

AI Gateway

Visão geral

O Instructor é uma biblioteca para extrair saídas estruturadas de LLMs usando modelos Pydantic. Ao conectar o Instructor ao AI Gateway do Toqan Router, você obtém extração estruturada com tipagem segura e acesso a mais de 500 modelos com uma única alteração de configuração.

Principais benefícios

O AI Gateway do Toqan Router aprimora suas aplicações Instructor com:

Observabilidade completa

Acompanhe cada extração, validação e nova tentativa com traces detalhados

Confiabilidade integrada

Fallbacks automáticos, novas tentativas e balanceamento de carga para resiliência em produção

Otimização de custos

Acompanhamento de custos em tempo real e gestão de gastos em todas as suas operações de IA

Acesso a múltiplos provedores

Acesse mais de 500 LLMs e mais de 30 provedores por meio de uma integração única e unificada

Pré-requisitos

Antes de integrar o Instructor ao Toqan Router, certifique-se de ter:

Uma conta no Toqan Router e uma chave de API
Python 3.8 ou superior

Para configurar sua chave de API, consulte Chaves de API e endpoints.

Instalação

pip install instructor openai

Configuração

Configure o Instructor para usar o AI Gateway do Toqan Router aplicando um patch em um cliente OpenAI com uma base_url personalizada:

Python

import instructor
from openai import OpenAI
import os

client = instructor.from_openai(OpenAI(
    base_url="https://router.toqan.ai/eu/v3/router",
    api_key=os.getenv("TOQAN_API_KEY"),
))

base_url: https://router.toqan.ai/eu/v3/router

Extração básica

Python

import instructor
from pydantic import BaseModel
from openai import OpenAI
import os

client = instructor.from_openai(OpenAI(
    base_url="https://router.toqan.ai/eu/v3/router",
    api_key=os.getenv("TOQAN_API_KEY"),
))

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

user_info = client.chat.completions.create(
    model="openai/gpt-5.6-sol",
    response_model=UserInfo,
    messages=[{"role": "user", "content": "John Doe is 30 years old."}],
)

print(user_info.name)   # John Doe
print(user_info.age)    # 30

Classificação

Use o Instructor com tipos Literal para classificação:

Python

import instructor
from pydantic import BaseModel, Field
from openai import OpenAI
from typing import Literal
import os

client = instructor.from_openai(OpenAI(
    base_url="https://router.toqan.ai/eu/v3/router",
    api_key=os.getenv("TOQAN_API_KEY"),
))

class Sentiment(BaseModel):
    label: Literal["positive", "negative", "neutral"]
    confidence: float = Field(ge=0.0, le=1.0)

result = client.chat.completions.create(
    model="openai/gpt-5.6-sol",
    response_model=Sentiment,
    messages=[{"role": "user", "content": "Classify: 'This product is absolutely amazing!'"}],
)
print(f"Sentiment: {result.label}, Confidence: {result.confidence:.2f}")

Seleção de modelo

Com o Toqan Router, você pode usar qualquer modelo compatível de mais de 30 provedores:

Python

import instructor
from pydantic import BaseModel
from openai import OpenAI
import os

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

# Use Claude
claude_client = instructor.from_openai(OpenAI(
    base_url="https://router.toqan.ai/eu/v3/router",
    api_key=os.getenv("TOQAN_API_KEY"),
))

result = claude_client.chat.completions.create(
    model="anthropic/claude-sonnet-5",
    response_model=UserInfo,
    messages=[{"role": "user", "content": "Jane Smith is 25 years old."}],
)
print(f"{result.name}, {result.age}")

# Use Gemini
gemini_client = instructor.from_openai(OpenAI(
    base_url="https://router.toqan.ai/eu/v3/router",
    api_key=os.getenv("TOQAN_API_KEY"),
))

result = gemini_client.chat.completions.create(
    model="google-ai/gemini-2.5-flash",
    response_model=UserInfo,
    messages=[{"role": "user", "content": "Bob Johnson is 40 years old."}],
)
print(f"{result.name}, {result.age}")

Observabilidade

Primeiros passos

O Instructor permite obter saídas estruturadas de modelos de linguagem usando schemas Pydantic. Rastrear o Instructor com o Toqan Router oferece insights abrangentes sobre padrões de extração de dados, taxas de sucesso de validação, mecanismos de nova tentativa e desempenho das saídas estruturadas, para que você otimize seus pipelines de processamento de dados com LLMs.

Pré-requisitos

Antes de começar, certifique-se de ter:

Uma conta no Toqan Router e uma chave de API
Python 3.8+
A biblioteca Instructor instalada no seu projeto
Chave de API da OpenAI (ou credenciais de outro provedor de LLM compatível)

Instalar dependências

# Core Instructor and OpenTelemetry packages
pip install instructor openai opentelemetry-sdk opentelemetry-exporter-otlp

# OpenInference instrumentation for Instructor
pip install openinference-instrumentation-instructor

Configurar o Toqan Router

Configure suas variáveis de ambiente para se conectar ao coletor OpenTelemetry do Toqan Router: Unix/Linux/macOS:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://router.toqan.ai/eu/v2/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <TOQAN_API_KEY>"
export OTEL_RESOURCE_ATTRIBUTES="service.name=instructor-app,service.version=1.0.0"
export OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"

Windows (PowerShell):

$env:OTEL_EXPORTER_OTLP_ENDPOINT = "https://router.toqan.ai/eu/v2/otel"
$env:OTEL_EXPORTER_OTLP_HEADERS = "Authorization=Bearer <TOQAN_API_KEY>"
$env:OTEL_RESOURCE_ATTRIBUTES = "service.name=instructor-app,service.version=1.0.0"
$env:OPENAI_API_KEY = "<YOUR_OPENAI_API_KEY>"

Usando um arquivo .env:

OTEL_EXPORTER_OTLP_ENDPOINT=https://router.toqan.ai/eu/v2/otel
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <TOQAN_API_KEY>
OTEL_RESOURCE_ATTRIBUTES=service.name=instructor-app,service.version=1.0.0
OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>

Integração

O Instructor usa a instrumentação OpenInference para tracing automático com OpenTelemetry.

Configure a instrumentação na sua aplicação:

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
import os

# Configure tracer provider
tracer_provider = TracerProvider(
    resource=Resource({"service.name": "instructor-app"})
)

# Set up OTLP exporter
otlp_exporter = OTLPSpanExporter(
    endpoint=f"{os.getenv('OTEL_EXPORTER_OTLP_ENDPOINT')}/v1/traces",
    headers={"Authorization": os.getenv('OTEL_EXPORTER_OTLP_HEADERS').split('=', 1)[1]}
)

tracer_provider.add_span_processor(BatchSpanProcessor(otlp_exporter))

# Instrument Instructor
from openinference.instrumentation.instructor import InstructorInstrumentor

InstructorInstrumentor().instrument(tracer_provider=tracer_provider)

Use o Instructor com tracing automático:

import instructor
from pydantic import BaseModel
from openai import OpenAI
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
import os

# Configure OpenTelemetry
tracer_provider = TracerProvider(
    resource=Resource({"service.name": "instructor-app"})
)

otlp_exporter = OTLPSpanExporter(
    endpoint=f"{os.getenv('OTEL_EXPORTER_OTLP_ENDPOINT')}/v1/traces",
    headers={"Authorization": os.getenv('OTEL_EXPORTER_OTLP_HEADERS').split('=', 1)[1]}
)

tracer_provider.add_span_processor(BatchSpanProcessor(otlp_exporter))

# Instrument Instructor
from openinference.instrumentation.instructor import InstructorInstrumentor

InstructorInstrumentor().instrument(tracer_provider=tracer_provider)

# Define response schema
class UserInfo(BaseModel):
    name: str
    age: int
    occupation: str

# Create Instructor client
client = instructor.from_openai(OpenAI(
    base_url="https://router.toqan.ai/eu/v3/router",
    api_key=os.getenv("TOQAN_API_KEY"),
))

# Extract structured data (automatically traced)
user_info = client.chat.completions.create(
    model="openai/gpt-5.6-sol",
    response_model=UserInfo,
    messages=[{
        "role": "user",
        "content": "John Smith is a 32-year-old software engineer."
    }]
)

print(f"Extracted: {user_info.name}, {user_info.age}, {user_info.occupation}")

Todas as extrações de saída estruturada do Instructor serão instrumentadas automaticamente e exportadas para o Toqan Router pelo exporter OTLP. Para mais detalhes, consulte Traces.

Exemplos avançados

Schemas aninhados complexos

import instructor
from pydantic import BaseModel, Field
from openai import OpenAI
from typing import List
import os

# Setup done as shown in Integration section above

class Address(BaseModel):
    street: str
    city: str
    country: str
    postal_code: str

class OrderItem(BaseModel):
    product_name: str
    quantity: int
    price: float

class Invoice(BaseModel):
    invoice_number: str = Field(description="Unique invoice identifier")
    customer_name: str
    billing_address: Address
    items: List[OrderItem]
    subtotal: float
    tax: float
    total: float

client = instructor.from_openai(OpenAI(
    base_url="https://router.toqan.ai/eu/v3/router",
    api_key=os.getenv("TOQAN_API_KEY"),
))

# Extract complex nested data (automatically traced)
invoice_text = """
Invoice #INV-2024-001
Customer: Acme Corporation
Address: 123 Main St, New York, NY, USA, 10001

Items:
- Premium Widget x5 @ $50.00
- Standard Gadget x10 @ $25.00

Subtotal: $500.00
Tax: $40.00
Total: $540.00
"""

invoice = client.chat.completions.create(
    model="openai/gpt-5.6-sol",
    response_model=Invoice,
    messages=[{"role": "user", "content": f"Extract invoice data: {invoice_text}"}]
)

print(f"Invoice {invoice.invoice_number} for {invoice.customer_name}")
print(f"Total: ${invoice.total}")

Processamento em lote com validação

import instructor
from pydantic import BaseModel, Field, field_validator
from openai import OpenAI
from typing import List
import os

class ProductReview(BaseModel):
    reviewer_name: str
    rating: int = Field(ge=1, le=5, description="Rating from 1-5 stars")
    sentiment: str = Field(description="positive, negative, or neutral")
    key_points: List[str]

    @field_validator('sentiment')
    @classmethod
    def validate_sentiment(cls, v):
        if v.lower() not in ['positive', 'negative', 'neutral']:
            raise ValueError('Invalid sentiment')
        return v.lower()

client = instructor.from_openai(OpenAI(
    base_url="https://router.toqan.ai/eu/v3/router",
    api_key=os.getenv("TOQAN_API_KEY"),
))

reviews_text = [
    "Amazing product! Best purchase ever. 5 stars from John.",
    "Terrible quality. Broke after one day. Very disappointed. - Sarah",
    "It's okay, nothing special but works as expected. 3 stars - Mike"
]

extracted_reviews = []

# Process batch with validation (automatically traced)
for review in reviews_text:
    try:
        result = client.chat.completions.create(
            model="openai/gpt-5.6-sol",
            response_model=ProductReview,
            messages=[{"role": "user", "content": f"Extract review data: {review}"}]
        )
        extracted_reviews.append(result)
    except Exception as e:
        print(f"Failed to process review: {e}")

print(f"Successfully processed {len(extracted_reviews)} reviews")

Nova tentativa com lógica personalizada

import instructor
from pydantic import BaseModel, Field, field_validator
from openai import OpenAI
from datetime import datetime
import os

class EventInfo(BaseModel):
    title: str = Field(min_length=5, max_length=100)
    date: str = Field(description="Date in YYYY-MM-DD format")
    time: str = Field(description="Time in HH:MM format")
    attendees: int = Field(ge=1, le=10000)

    @field_validator('date')
    @classmethod
    def validate_date(cls, v):
        try:
            datetime.strptime(v, '%Y-%m-%d')
            return v
        except ValueError:
            raise ValueError('Date must be in YYYY-MM-DD format')

client = instructor.from_openai(OpenAI(
    base_url="https://router.toqan.ai/eu/v3/router",
    api_key=os.getenv("TOQAN_API_KEY"),
))

event_description = """
AI in Healthcare Summit 2024
Date: April 15, 2024
Time: 9:00 AM
Expected Attendees: 500
"""

# Extract with automatic retries on validation errors (automatically traced)
event = client.chat.completions.create(
    model="openai/gpt-5.6-sol",
    response_model=EventInfo,
    messages=[{"role": "user", "content": f"Extract event info: {event_description}"}],
    max_retries=3
)

print(f"Event: {event.title} on {event.date} at {event.time}")

O Instructor também é compatível com nosso AI Gateway. Para saber mais, consulte Instructor.

Visão geral

Instrumente seu app

Explorar

Monitorar

Exportar

Revisar

Privacidade e segurança de dados

Integrações com frameworks

Integração de saída estruturada com o Instructor

AI Gateway

Observabilidade

AI Gateway

Visão geral

Principais benefícios

Observabilidade completa

Confiabilidade integrada

Otimização de custos

Acesso a múltiplos provedores

Pré-requisitos

Instalação

Configuração

Extração básica

Classificação

Seleção de modelo

Observabilidade

Primeiros passos

Pré-requisitos

Instalar dependências

Configurar o Toqan Router

Integração

Exemplos avançados

AI Gateway

Observabilidade

​AI Gateway

​Visão geral

​Principais benefícios

Observabilidade completa

Confiabilidade integrada

Otimização de custos

Acesso a múltiplos provedores

​Pré-requisitos

​Instalação

​Configuração

​Extração básica

​Classificação

​Seleção de modelo

​Observabilidade

​Primeiros passos

​Pré-requisitos

​Instalar dependências

​Configurar o Toqan Router

​Integração

​Exemplos avançados

AI Gateway

Visão geral

Principais benefícios

Pré-requisitos

Instalação

Configuração

Extração básica

Classificação

Seleção de modelo

Observabilidade

Primeiros passos

Pré-requisitos

Instalar dependências

Configurar o Toqan Router

Integração

Exemplos avançados