BroadRouter

Usare Pydantic AI con BroadNet Inference (OpenAICompatibleProvider)

Aggiornato

Installa pydantic-ai-slim[openai], poi crea OpenAIChatModel con un ID di modello BroadNet come broadnet/glm-5.3 e un OpenAICompatibleProvider con base URL https://inference.broadnet.ai/v1 e la tua chiave BroadNet come chiave API. Passa il modello ad Agent. Usa OpenAIChatModel, non il modello Responses, perché BroadNet serve chat completions. Secondo la documentazione di Pydantic AI, OpenAIProvider con base_url è pensato per OpenAI stessa.

Pydantic AI è un framework Python per agenti creato dal team di Pydantic. Per un servizio senza provider integrato, la sua documentazione dice di usare OpenAICompatibleProvider con il base_url del servizio. BroadNet Inference serve chat completions standard su https://inference.broadnet.ai/v1, quindi la strada è questa. BroadRouter è il sito di BroadNet; questa guida segue la documentazione di Pydantic AI alla versione 2.68.

Installazione

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

Connessione

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)

Eseguirlo è già il test: se stampa una risposta, chiave, URL e ID del modello sono corretti.

  • Il primo argomento è l’ID del modello inviato a BroadNet. Usalo esattamente così, con il prefisso broadnet/.
  • Il nome del provider (qui 'broadnet') viene registrato su ogni risposta. La documentazione di Pydantic AI dice di mantenerlo stabile, perché decide quali dati delle risposte precedenti vengono rimandati al servizio.
  • Resta su OpenAIChatModel. La documentazione di Pydantic AI dice di usare OpenAIResponsesModel solo se il servizio implementa la Responses API. BroadNet non la elenca.

Strumenti e output strutturato

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)

Per strumenti e output strutturato usa broadnet/glm-5.3 o broadnet/qwen3.8-27b; la documentazione di BroadNet indica entrambe le funzionalità solo per questi due modelli.

Quando impostare un profilo del modello

Pydantic AI sceglie un profilo di richiesta in base al nome del modello. Se una funzionalità viene ignorata o rifiutata, la sua documentazione dice di passare un tuo OpenAIModelProfile. Per BroadNet conviene conoscere due impostazioni:

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
    ),
)

Passa il limite di output tramite le impostazioni del modello, per esempio agent.run_sync(prompt, model_settings={'max_tokens': 2000}). Su DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B il ragionamento conta in quel limite.

Quale modello scegliere

Agente Modello
Strumenti, output strutturato broadnet/glm-5.3
Immagini o testo arabo, con strumenti broadnet/qwen3.8-27b
Documenti lunghi, piano a prezzo fisso broadnet/deepseek-v4.1-flash
Credito iniziale gratuito broadnet/gemma-4-26b-a4b (contesto da 32.768 token)

Prezzi di tutti i modelli.

Risoluzione dei problemi

  • 401. La chiave è sbagliata, scaduta o ha esaurito la quota.
  • 404 o modello non trovato. base_url deve terminare con /v1. Controlla l’ID del modello. I modelli a pagamento richiedono una ricarica; il credito di $5 copre solo broadnet/gemma-4-26b-a4b e i due modelli Transcribe.
  • Output vuoto o un ciclo di retry di validazione. Il ragionamento ha consumato il budget di output. Alza max_tokens. Perché le risposte arrivano vuote.
  • 400 sulle definizioni degli strumenti. Imposta openai_supports_strict_tool_definition=False nel profilo e usa un modello per cui BroadNet indica gli strumenti.
  • 429 quando esegui agenti in parallelo. Una chiave a consumo consente 30 richieste al minuto e 4 in corso. Vedi errori e nuovi tentativi.

Domande frequenti

Per BroadNet devo usare OpenAIProvider o OpenAICompatibleProvider?

OpenAICompatibleProvider. La documentazione di Pydantic AI dice che anche OpenAIProvider accetta un base_url, ma è pensato per OpenAI stessa o per un proxy trasparente verso OpenAI, e presuppone i modelli e le funzionalità di OpenAI.

Perché usare OpenAIChatModel e non il modello OpenAI predefinito?

Il modello OpenAI predefinito di Pydantic AI usa la Responses API. BroadNet serve chat completions su /v1/chat/completions, ed è quello che chiama OpenAIChatModel.

Strumenti e output strutturato funzionano?

Sì, sui modelli per cui BroadNet indica strumenti e output strutturato: GLM 5.3 e Qwen3.8 27B. La documentazione di BroadNet non indica gli strumenti per DeepSeek V4.1 Flash, quindi prima prova lì gli agenti che usano strumenti.

Come evito che Pydantic AI invii max_completion_tokens?

Passa profile=OpenAIModelProfile(openai_chat_supports_max_completion_tokens=False) a OpenAIChatModel. Pydantic AI invierà allora il vecchio campo max_tokens, quello descritto dal riferimento API di BroadNet.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity