BroadRouter

Usar o Spring AI com a BroadNet Inference (base-url da OpenAI)

Atualizado em

Adicione o spring-ai-starter-model-openai e defina spring.ai.openai.base-url como https://inference.broadnet.ai/v1, spring.ai.openai.api-key com a sua chave da BroadNet e spring.ai.openai.chat.model com um ID da BroadNet, por exemplo broadnet/glm-5.3. Defina spring.ai.openai.chat.max-tokens com espaço para o raciocínio. O Spring AI 2.x usa o SDK openai-java, que acrescenta /chat/completions à base URL.

O Spring AI é o framework do projeto Spring para IA em Java. O starter de chat da OpenAI dele lê uma base-url, então pode chamar qualquer servidor compatível com a OpenAI. A BroadNet Inference oferece chat completions padrão em https://inference.broadnet.ai/v1. O BroadRouter é o site da própria BroadNet; este guia segue a referência do Spring AI 2.0.2.

Adicione o starter

Com o BOM do Spring AI já configurado (veja a documentação de gerenciamento de dependências do Spring AI):

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

Configuração

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'

Mantenha o /v1 na URL. No Spring AI 2.x o valor chega sem alteração ao cliente openai-java (OpenAiSetup.calculateBaseUrl devolve o valor como está), e é esse cliente que adiciona /chat/completions. O padrão que você substitui é https://api.openai.com/v1.

Chame e teste

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());
    };
}

Inicie a aplicação. Se uma resposta aparecer impressa, a chave, a URL e o ID do modelo estão certos.

Configurações que importam para a BroadNet

  • max-tokens, não max-completion-tokens. A documentação do Spring AI diz que eles são mutuamente exclusivos e que definir os dois é um erro. A referência da API da BroadNet descreve max_tokens. DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B raciocinam primeiro, e o raciocínio conta no limite.
  • Texto do raciocínio. O Spring AI pode expor reasoning_content de servidores compatíveis com a OpenAI que o devolvem. A referência da API da BroadNet informa a contagem de tokens de raciocínio em usage, mas não garante o texto do raciocínio, então não dependa dele.
  • Override só para o chat. spring.ai.openai.chat.base-url e spring.ai.openai.chat.api-key têm precedência sobre as propriedades compartilhadas para o modelo de chat. Use essas propriedades se outros modelos OpenAI do Spring AI (como embeddings) precisarem continuar na OpenAI.
  • Novas tentativas. spring.ai.retry.max-attempts tem padrão 10, com backoff exponencial. Numa chave de pagamento por uso, isso pode esgotar o limite por minuto; considere reduzir o valor.

Qual modelo escolher

Uso spring.ai.openai.chat.model
Tool calling, saída estruturada broadnet/glm-5.3
Imagens ou texto em árabe 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

Preços de todos os modelos.

Solução de problemas

  • 401. A chave está errada, expirou ou ficou sem cota, ou a BROADNET_API_KEY não está definida para a JVM.
  • 404. Falta /v1 na base URL, ou o ID do modelo está errado. Os modelos pagos exigem uma recarga; o crédito de $5 cobre só broadnet/gemma-4-26b-a4b e os dois modelos Transcribe.
  • content() vazio. O raciocínio consumiu o orçamento de saída. Aumente max-tokens. Por que as respostas vêm vazias.
  • 400 com os dois limites de tokens definidos. Remova max-completion-tokens.
  • 429. Uma chave de pagamento por uso permite 30 requisições por minuto e 4 em andamento. Veja erros e novas tentativas.

Perguntas frequentes

O spring.ai.openai.base-url deve incluir /v1?

Sim. No Spring AI 2.x o valor é repassado sem alteração ao cliente openai-java, cujo padrão é https://api.openai.com/v1. Use https://inference.broadnet.ai/v1.

Uso max-tokens ou max-completion-tokens com a BroadNet?

max-tokens. A documentação do Spring AI diz que os dois são mutuamente exclusivos. A referência da API da BroadNet descreve o campo max_tokens, e o raciocínio conta nele, então reserve 1.000 tokens ou mais.

O tool calling do Spring AI funciona com a BroadNet?

Use GLM 5.3 ou Qwen3.8 27B, que a BroadNet lista com ferramentas. A documentação da BroadNet não lista tool calling para o DeepSeek V4.1 Flash.

Posso manter a OpenAI para embeddings e usar a BroadNet para chat?

Sim. spring.ai.openai.chat.base-url e spring.ai.openai.chat.api-key sobrescrevem as propriedades compartilhadas só para o modelo de chat. A referência da API da BroadNet não lista um endpoint de embeddings.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity