---
title: "Instructor com base_url compatível com a OpenAI (Pydantic)"
description: "Extraia objetos Pydantic da BroadNet Inference com o Instructor, usando from_openai ou from_provider com um base_url personalizado, e escolha o Mode certo."
url: https://broadrouter.com/pt/guides/instructor-structured-output/
lang: pt-BR
updated: 2026-11-16
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Traduzido do inglês com ajuda de IA. [Leia o original em inglês](https://broadrouter.com/guides/instructor-structured-output/) (atualizado em 2026-11-16).

# Saída estruturada com o Instructor na BroadNet Inference

Atualizado em 2026-11-16

Envolva com instructor.from\_openai um cliente OpenAI com base\_url https://inference.broadnet.ai/v1 e a sua chave da BroadNet, depois chame chat.completions.create com response\_model igual à sua classe Pydantic e model como broadnet/glm-5.3 ou broadnet/qwen3.8-27b. São os dois modelos que a BroadNet lista com ferramentas e saída estruturada. O padrão é Mode.TOOLS; Mode.JSON\_SCHEMA também funciona.

O Instructor é uma biblioteca Python que transforma respostas de LLM em objetos Pydantic validados e pode tentar de novo quando a validação falha. Ele modifica o cliente OpenAI, e a documentação dele cobre servidores compatíveis com a OpenAI por meio de `base_url`. A BroadNet Inference oferece chat completions em `https://inference.broadnet.ai/v1` e lista ferramentas e saída estruturada para GLM 5.3 e Qwen3.8 27B. O BroadRouter é o site da própria BroadNet; este guia segue a documentação do Instructor na versão 1.17.0.

## Instalação

```bash
pip install instructor
export BROADNET_API_KEY='your-broadnet-key'
```

## Extrair um objeto

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

class Invoice(BaseModel):
    vendor: str
    total: float
    currency: str

client = instructor.from_openai(
    OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"]),
    mode=instructor.Mode.TOOLS,
)

invoice = client.chat.completions.create(
    model="broadnet/glm-5.3",
    response_model=Invoice,
    max_tokens=4000,
    messages=[{"role": "user", "content": "Acme Trading invoice, total 1,250.00 SAR"}],
)
print(invoice)
```

O Instructor transforma `Invoice` em um schema de ferramenta, obriga o modelo a chamá-la com `tool_choice` e valida os argumentos. Passe `max_retries` para controlar quantas vezes ele pede de novo, enviando o erro de validação, quando o objeto não valida.

## Ou use from\_provider

```python
pclient = instructor.from_provider(
    "openai/broadnet/glm-5.3",
    base_url="https://inference.broadnet.ai/v1",
    api_key=os.environ["BROADNET_API_KEY"],
)
invoice = pclient.create(response_model=Invoice, max_tokens=4000,
                         messages=[{"role": "user", "content": "Acme Trading, 1,250.00 SAR"}])
```

A parte `openai/` escolhe o cliente. O resto, `broadnet/glm-5.3`, é enviado como ID do modelo.

## Qual mode usar

| Mode | O que envia | Usar com a BroadNet |
| --- | --- | --- |
| `Mode.TOOLS` (padrão) | Uma chamada de ferramenta forçada com o seu schema | Sim, no GLM 5.3 ou no Qwen3.8 27B |
| `Mode.JSON_SCHEMA` | `response_format` do tipo `json_schema` | Sim, no GLM 5.3 ou no Qwen3.8 27B |
| `Mode.MD_JSON` | Uma requisição simples; JSON extraído do texto | Alternativa para outros modelos; teste antes |
| `Mode.RESPONSES_TOOLS` | A Responses API | Não: a BroadNet oferece chat completions |

## Imagens

O Qwen3.8 27B aceita imagens além de ferramentas, então consegue ler uma foto ou um documento digitalizado direto para o seu modelo:

```python
import base64
img = base64.b64encode(open("invoice.jpg", "rb").read()).decode()
invoice = client.chat.completions.create(
    model="broadnet/qwen3.8-27b",
    response_model=Invoice,
    max_tokens=4000,
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "Extract the invoice fields."},
        {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64," + img}},
    ]}],
)
```

Em uma chave de pagamento por uso, a imagem conta como tokens de entrada. Veja [leitura de notas fiscais em árabe com visão](https://broadrouter.com/pt/guides/read-arabic-invoices-with-vision/).

## Como testamos

Em 2026-11-15 instalamos o instructor 1.17.0 com o openai 3.3.0 em um ambiente virtual limpo e rodamos os exemplos acima contra um servidor mock local que imita o formato de chat completions da BroadNet. Lemos as requisições registradas. `Mode.TOOLS` enviou o schema como ferramenta com um `tool_choice` forçado, `Mode.JSON_SCHEMA` enviou um response format `json_schema`, e os dois retornaram um `Invoice` válido. O `from_provider` enviou o ID do modelo sem alteração. O nosso mock não escreve JSON em texto livre, então não testamos `Mode.MD_JSON`, e não enviamos o exemplo com imagem. Não tínhamos uma chave da BroadNet, então não testamos a saída real dos modelos.

## Solução de problemas

-   **Novas tentativas de validação que nunca dão certo.** No GLM 5.3 e no Qwen3.8 27B, o raciocínio conta para `max_tokens`. Um limite baixo pode cortar os argumentos da ferramenta. Aumente o valor. [Por que as respostas vêm vazias](https://broadrouter.com/pt/guides/reasoning-tokens-empty-response/).
-   **400 na requisição.** Confira se você está usando GLM 5.3 ou Qwen3.8 27B. Se um `tool_choice` forçado for recusado, tente `Mode.JSON_SCHEMA`.
-   **401.** A chave está errada, expirou ou ficou sem cota.
-   **404.** `base_url` precisa terminar em `/v1`. GLM 5.3 e Qwen3.8 27B exigem uma recarga; o crédito de $5 não cobre esses modelos.
-   **429 em extração em lote.** Uma chave de pagamento por uso permite 30 requisições por minuto e 4 em andamento. Cada nova tentativa de validação é mais uma requisição. Veja [erros e novas tentativas](https://broadrouter.com/pt/guides/errors-and-retries/).

## Termos neste guia

[Pagamento por uso (pay-as-you-go)](https://broadrouter.com/pt/glossary/pay-as-you-go/)

Pagamento por uso é um modelo de preço em que você paga só pelo que usa, medido por unidade, como tokens, requisições ou minutos de áudio, sem assinatura nem compromisso mínimo. A maioria das APIs de LLM cobra assim, a partir de um saldo pré-pago ou de uma fatura periódica.

[Chat Completions API](https://broadrouter.com/pt/glossary/chat-completions-api/)

A Chat Completions API é o endpoint HTTP da OpenAI, POST /v1/chat/completions, que recebe o nome de um modelo e uma lista de mensagens marcadas com papéis e devolve a próxima mensagem do modelo. O formato da requisição e da resposta virou o padrão comum que provedores e SDKs compatíveis com a OpenAI reutilizam.

[Token](https://broadrouter.com/pt/glossary/token/)

Um token é a unidade de texto que um modelo de linguagem lê e escreve: uma palavra, parte de uma palavra, um sinal de pontuação ou uma sequência de bytes gerada pelo tokenizador do modelo. As APIs de LLM contam, limitam e normalmente cobram o uso em tokens.

[Concorrência (concurrency)](https://broadrouter.com/pt/glossary/concurrency/)

Concorrência é o número de requisições que um cliente tem em andamento ao mesmo tempo. APIs de LLM muitas vezes a limitam por chave ou por plano, separadamente das requisições por minuto, porque cada requisição aberta ocupa capacidade de GPU até a resposta terminar.

[Rate limit (limite de taxa)](https://broadrouter.com/pt/glossary/rate-limit/)

Um rate limit é um teto que uma API impõe a quanto um cliente pode usá-la em um intervalo de tempo, como requisições por minuto ou tokens por minuto. As requisições acima do limite são recusadas, normalmente com HTTP 429 Too Many Requests, até que o uso volte a ficar abaixo dele.

[Tool calling (chamada de ferramentas)](https://broadrouter.com/pt/glossary/tool-calling/)

Tool calling, também chamado de function calling ou chamada de ferramentas, é um recurso de APIs de LLM em que o modelo devolve um pedido estruturado para executar uma função definida pelo desenvolvedor, com argumentos JSON. A aplicação executa a função e devolve o resultado; o modelo nunca executa código sozinho.

[Crédito pré-pago (prepaid credit)](https://broadrouter.com/pt/glossary/prepaid-credit/)

Crédito pré-pago é dinheiro adicionado a uma conta de API antes do uso. Cada requisição desconta o próprio custo do saldo e, quando o saldo acaba, as requisições cobradas por uso param até você fazer uma recarga. Ele limita o gasto ao que você já pagou.

[Saída estruturada (structured output)](https://broadrouter.com/pt/glossary/structured-output/)

Saída estruturada é um recurso de APIs de LLM que restringe a resposta de um modelo a um formato definido pelo desenvolvedor, normalmente um JSON Schema, para que o código consiga interpretá-la de forma confiável. É mais rigorosa que o JSON mode, que garante um JSON válido, mas não uma estrutura específica.

## Perguntas frequentes

### Qual mode do Instructor devo usar com a BroadNet?

Mode.TOOLS, o padrão, no GLM 5.3 ou no Qwen3.8 27B, que a BroadNet lista com ferramentas e saída estruturada. Mode.JSON\_SCHEMA envia um response\_format json\_schema. Os dois geraram objetos válidos no nosso teste com servidor mock.

### Posso usar Mode.RESPONSES\_TOOLS?

Não. A documentação do Instructor diz para não escolhê-lo a menos que o servidor implemente a Responses API. A BroadNet oferece só chat completions.

### O Instructor funciona com DeepSeek V4.1 Flash ou Gemma na BroadNet?

A BroadNet não lista ferramentas nem saída estruturada para esses modelos. Mode.MD\_JSON pede JSON em texto simples e faz o parse, o que pode funcionar, mas teste com os seus próprios dados antes de depender disso.

### Como escrevo a string do modelo no from\_provider?

Use openai/broadnet/glm-5.3. O Instructor separa o primeiro segmento como provedor e, no nosso teste, enviou broadnet/glm-5.3 ao servidor sem alteração.

## Guias relacionados

-   [Como usar o SDK Python da OpenAI com a BroadNet Inference](https://broadrouter.com/pt/guides/openai-python-sdk/)
-   [Usar o Pydantic AI com a BroadNet Inference (OpenAICompatibleProvider)](https://broadrouter.com/pt/guides/pydantic-ai-openai-compatible/)
-   [Ler notas fiscais e recibos em árabe com um modelo de visão](https://broadrouter.com/pt/guides/read-arabic-invoices-with-vision/)
-   [Por que um modelo de raciocínio devolve uma resposta vazia](https://broadrouter.com/pt/guides/reasoning-tokens-empty-response/)
-   [Todas as ferramentas que funcionam com a BroadNet Inference (em inglês)](https://broadrouter.com/integrations/): SDKs, agentes de programação, interfaces de chat e ferramentas de automação, com as configurações exatas de cada uma

Teste com a sua carga de trabalho real. Contas novas começam com US$ 5 de crédito para Gemma e transcrição. DeepSeek, GLM e Qwen3.8 exigem uma recarga.

[Começar](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-guides-instructor-structured-output&utm_content=page-cta) ·

**Fontes**

-   [Documentação do Instructor, OpenAI e servidores compatíveis com a OpenAI (conferido em 2026-11-15)](https://python.useinstructor.com/integrations/openai/)
-   [PyPI, instructor 1.17.0 (conferido em 2026-11-15)](https://pypi.org/project/instructor/)
-   [Referência da API da BroadNet Inference (conferido em 2026-11-15) (em inglês)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-guides-instructor-structured-output&utm_content=sources)
