BroadRouter

Usar o Pydantic AI com a BroadNet Inference (OpenAICompatibleProvider)

Atualizado em

Instale pydantic-ai-slim[openai] e crie um OpenAIChatModel com um ID de modelo da BroadNet, como broadnet/glm-5.3, e um OpenAICompatibleProvider com base URL https://inference.broadnet.ai/v1 e a sua chave da BroadNet como chave de API. Passe o modelo para Agent. Use OpenAIChatModel, não o modelo Responses, porque a BroadNet serve chat completions. A documentação do Pydantic AI diz que OpenAIProvider com base_url é para a própria OpenAI.

O Pydantic AI é um framework Python para agentes criado pelo time do Pydantic. Para um serviço sem provider nativo, a documentação dele manda usar OpenAICompatibleProvider com o base_url do serviço. A BroadNet Inference serve chat completions padrão em https://inference.broadnet.ai/v1, então esse é o caminho. O BroadRouter é o site da própria BroadNet; este guia segue a documentação do Pydantic AI na versão 2.68.

Instalação

pip install "pydantic-ai-slim[openai]"
export BROADNET_API_KEY='your-broadnet-key'

Conexão

import os
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai_compatible import OpenAICompatibleProvider

model = OpenAIChatModel(
    'broadnet/glm-5.3',
    provider=OpenAICompatibleProvider(
        'broadnet',
        base_url='https://inference.broadnet.ai/v1',
        api_key=os.environ['BROADNET_API_KEY'],
    ),
)

agent = Agent(model)
result = agent.run_sync('Give me three names for a Go linting tool.')
print(result.output)

Rodar isso já é o teste: se aparecer uma resposta, chave, URL e ID do modelo estão certos.

  • O primeiro argumento é o ID do modelo enviado à BroadNet. Use-o exatamente assim, com o prefixo broadnet/.
  • O nome do provider (aqui, 'broadnet') fica registrado em cada resposta. A documentação do Pydantic AI diz para mantê-lo estável, porque ele decide quais dados de respostas anteriores são enviados de volta ao serviço.
  • Fique no OpenAIChatModel. A documentação do Pydantic AI diz para usar OpenAIResponsesModel só se o serviço implementar a Responses API. A BroadNet não a lista.

Ferramentas e saída estruturada

from pydantic import BaseModel

class City(BaseModel):
    name: str
    country: str

agent = Agent(model, output_type=City)
print(agent.run_sync('Which city hosts the Burj Khalifa?').output)

Use broadnet/glm-5.3 ou broadnet/qwen3.8-27b para ferramentas e saída estruturada; a documentação da BroadNet lista os dois recursos só para esses dois modelos.

Quando definir um perfil de modelo

O Pydantic AI escolhe um perfil de requisição a partir do nome do modelo. Se um recurso for ignorado ou rejeitado, a documentação dele manda passar o seu próprio OpenAIModelProfile. Duas configurações valem a pena conhecer para a BroadNet:

from pydantic_ai.profiles.openai import OpenAIModelProfile

model = OpenAIChatModel(
    'broadnet/glm-5.3',
    provider=OpenAICompatibleProvider('broadnet', base_url='https://inference.broadnet.ai/v1', api_key=os.environ['BROADNET_API_KEY']),
    profile=OpenAIModelProfile(
        openai_chat_supports_max_completion_tokens=False,  # send max_tokens, the field BroadNet documents
        openai_supports_strict_tool_definition=False,      # only if strict tool schemas are rejected
    ),
)

Passe o limite de saída pelas configurações do modelo, por exemplo agent.run_sync(prompt, model_settings={'max_tokens': 2000}). No DeepSeek V4.1 Flash, no GLM 5.3 e no Qwen3.8 27B, o raciocínio conta nesse limite.

Qual modelo escolher

Agente Modelo
Ferramentas, saída estruturada broadnet/glm-5.3
Imagens ou texto em árabe, com ferramentas broadnet/qwen3.8-27b
Documentos longos, plano de preço fixo broadnet/deepseek-v4.1-flash
Crédito inicial gratuito broadnet/gemma-4-26b-a4b (contexto de 32.768 tokens)

Preços de todos os modelos.

Solução de problemas

  • 401. A chave está errada, expirou ou ficou sem cota.
  • 404 ou modelo não encontrado. O base_url precisa terminar em /v1. Confira o ID do modelo. Os modelos pagos exigem uma recarga; o crédito de $5 cobre só broadnet/gemma-4-26b-a4b e os dois modelos Transcribe.
  • Saída vazia ou um loop de retry de validação. O raciocínio gastou o orçamento de saída. Aumente max_tokens. Por que as respostas voltam vazias.
  • 400 nas definições de ferramentas. Defina openai_supports_strict_tool_definition=False no perfil e use um modelo que a BroadNet lista com ferramentas.
  • 429 ao rodar agentes em paralelo. Uma chave de pagamento por uso permite 30 requisições por minuto e 4 em andamento. Veja erros e novas tentativas.

Perguntas frequentes

Para a BroadNet, uso OpenAIProvider ou OpenAICompatibleProvider?

OpenAICompatibleProvider. A documentação do Pydantic AI diz que o OpenAIProvider também aceita um base_url, mas ele é para a própria OpenAI ou para um proxy transparente até ela, e presume os modelos e recursos da OpenAI.

Por que usar OpenAIChatModel e não o modelo OpenAI padrão?

O modelo OpenAI padrão do Pydantic AI usa a Responses API. A BroadNet serve chat completions em /v1/chat/completions, que é o que o OpenAIChatModel chama.

Ferramentas e saída estruturada funcionam?

Sim, nos modelos que a BroadNet lista com ferramentas e saída estruturada: GLM 5.3 e Qwen3.8 27B. A documentação da BroadNet não lista ferramentas para o DeepSeek V4.1 Flash, então teste antes nele os agentes que usam ferramentas.

Como faço o Pydantic AI parar de enviar max_completion_tokens?

Passe profile=OpenAIModelProfile(openai_chat_supports_max_completion_tokens=False) para o OpenAIChatModel. O Pydantic AI passa então a enviar o campo antigo max_tokens, que é o descrito na referência da API da BroadNet.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity