BroadRouter

Usare Spring AI con BroadNet Inference (base-url OpenAI)

Aggiornato

Aggiungi spring-ai-starter-model-openai, poi imposta spring.ai.openai.base-url su https://inference.broadnet.ai/v1, spring.ai.openai.api-key sulla tua chiave BroadNet e spring.ai.openai.chat.model su un ID BroadNet come broadnet/glm-5.3. Imposta spring.ai.openai.chat.max-tokens lasciando spazio al ragionamento. Spring AI 2.x usa l’SDK openai-java, che aggiunge /chat/completions alla base URL.

Spring AI è il framework del progetto Spring per l’AI in Java. Il suo starter chat OpenAI legge una base-url, quindi può chiamare qualsiasi server compatibile con OpenAI. BroadNet Inference serve chat completions standard su https://inference.broadnet.ai/v1. BroadRouter è il sito di BroadNet; questa guida segue il riferimento di Spring AI 2.0.2.

Aggiungere lo starter

Con il BOM di Spring AI già configurato (vedi la documentazione di Spring AI sulla gestione delle dipendenze):

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

Configurazione

application.properties:

spring.ai.openai.base-url=https://inference.broadnet.ai/v1
spring.ai.openai.api-key=${BROADNET_API_KEY}
spring.ai.openai.chat.model=broadnet/glm-5.3
spring.ai.openai.chat.max-tokens=2000
export BROADNET_API_KEY='your-broadnet-key'

Mantieni /v1 nell’URL. In Spring AI 2.x il valore arriva invariato al client openai-java (OpenAiSetup.calculateBaseUrl lo restituisce così com’è), ed è quel client ad aggiungere /chat/completions. Il default che sostituisci è https://api.openai.com/v1.

Chiamarlo e testarlo

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.boot.CommandLineRunner;
import org.springframework.context.annotation.Bean;

@Bean
CommandLineRunner smokeTest(ChatClient.Builder builder) {
    return args -> {
        ChatClient chat = builder.build();
        System.out.println(chat.prompt().user("Say hello in five words.").call().content());
    };
}

Avvia l’app. Se viene stampata una risposta, chiave, URL e ID del modello sono corretti.

Impostazioni che contano per BroadNet

  • max-tokens, non max-completion-tokens. La documentazione di Spring AI dice che si escludono a vicenda e che impostarli entrambi è un errore. Il riferimento API di BroadNet descrive max_tokens. DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B ragionano prima di rispondere, e il ragionamento conta nel limite.
  • Testo del ragionamento. Spring AI può esporre reasoning_content dai server compatibili con OpenAI che lo restituiscono. Il riferimento API di BroadNet riporta il conteggio dei token di ragionamento in usage ma non garantisce il testo del ragionamento, quindi non farci affidamento.
  • Override solo per la chat. spring.ai.openai.chat.base-url e spring.ai.openai.chat.api-key hanno la precedenza sulle proprietà condivise per il modello di chat. Usale se altri modelli OpenAI di Spring AI (come gli embedding) devono restare su OpenAI.
  • Retry. spring.ai.retry.max-attempts vale 10 per default, con backoff esponenziale. Con una chiave a consumo può esaurire il limite al minuto; valuta di abbassarlo.

Quale modello scegliere

Uso spring.ai.openai.chat.model
Tool calling, output strutturato broadnet/glm-5.3
Immagini o testo in arabo broadnet/qwen3.8-27b
Documenti lunghi, piano a prezzo fisso broadnet/deepseek-v4.1-flash
Credito iniziale gratuito broadnet/gemma-4-26b-a4b

Prezzi di tutti i modelli.

Risoluzione dei problemi

  • 401. La chiave è sbagliata, scaduta o ha esaurito la quota, oppure BROADNET_API_KEY non è impostata per la JVM.
  • 404. Alla base URL manca /v1, oppure l’ID del modello è sbagliato. I modelli a pagamento richiedono una ricarica; il credito di $5 copre solo broadnet/gemma-4-26b-a4b e i due modelli Transcribe.
  • content() vuoto. Il ragionamento ha consumato il budget di output. Alza max-tokens. Perché le risposte arrivano vuote.
  • 400 con entrambi i limiti di token impostati. Rimuovi max-completion-tokens.
  • 429. Una chiave a consumo consente 30 richieste al minuto e 4 in corso contemporaneamente. Vedi errori e retry.

Domande frequenti

spring.ai.openai.base-url deve includere /v1?

Sì. In Spring AI 2.x il valore passa invariato al client openai-java, il cui default è https://api.openai.com/v1. Usa https://inference.broadnet.ai/v1.

Con BroadNet devo usare max-tokens o max-completion-tokens?

max-tokens. La documentazione di Spring AI dice che i due si escludono a vicenda. Il riferimento API di BroadNet descrive il campo max_tokens, e il ragionamento conta in quel limite, quindi imposta almeno 1.000 token.

Il tool calling di Spring AI funziona con BroadNet?

Usa GLM 5.3 o Qwen3.8 27B, che BroadNet indica con gli strumenti. La documentazione di BroadNet non indica il tool calling per DeepSeek V4.1 Flash.

Posso tenere OpenAI per gli embedding e usare BroadNet per la chat?

Sì. spring.ai.openai.chat.base-url e spring.ai.openai.chat.api-key sovrascrivono le proprietà condivise solo per il modello di chat. Il riferimento API di BroadNet non elenca un endpoint per gli embedding.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity