---
title: "Spring AI: starter da OpenAI com base-url personalizada"
description: "Aponte o starter de chat da OpenAI do Spring AI para a BroadNet Inference com spring.ai.openai.base-url, um ID da BroadNet e max-tokens, e chame pelo ChatClient."
url: https://broadrouter.com/pt/guides/spring-ai-openai-base-url/
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/spring-ai-openai-base-url/) (atualizado em 2026-11-16).

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

Atualizado em 2026-11-16

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

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

## Configuração

`application.properties`:

```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
```

```bash
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

```java
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](https://broadrouter.com/pt/pricing/).

## 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](https://broadrouter.com/pt/guides/reasoning-tokens-empty-response/).
-   **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](https://broadrouter.com/pt/guides/errors-and-retries/).

## Termos neste guia

[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.

[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.

[Base URL (URL base)](https://broadrouter.com/pt/glossary/base-url/)

A base URL é o endereço raiz fixo de uma API, como https://api.example.com/v1, que um cliente coloca antes de cada caminho de endpoint, como /chat/completions. Nos SDKs compatíveis com a OpenAI, trocar a base URL, junto com a chave de API e o ID do modelo, aponta o mesmo código para outro provedor.

[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.

[Embeddings](https://broadrouter.com/pt/glossary/embeddings/)

Embeddings são listas de números de ponto flutuante (vetores) que um modelo produz para representar um texto, uma imagem ou outra entrada. Entradas com significado parecido recebem vetores próximos, então a distância entre vetores serve para ordenar resultados de busca, agrupar documentos ou encontrar itens relacionados.

[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.

[Backoff exponencial (exponential backoff)](https://broadrouter.com/pt/glossary/exponential-backoff/)

Backoff exponencial é uma estratégia de retry em que o cliente espera mais tempo depois de cada tentativa que falha, normalmente dobrando o atraso até um teto, antes de tentar de novo. Adicionar um jitter aleatório a cada espera espalha os retries de muitos clientes, para que não atinjam o servidor no mesmo instante.

## 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.

## Guias relacionados

-   [Chamar a BroadNet Inference em Go com o SDK openai-go](https://broadrouter.com/pt/guides/openai-go-sdk/)
-   [Como usar o SDK Python da OpenAI com a BroadNet Inference](https://broadrouter.com/pt/guides/openai-python-sdk/)
-   [Por que um modelo de raciocínio devolve uma resposta vazia](https://broadrouter.com/pt/guides/reasoning-tokens-empty-response/)
-   [Códigos de erro da BroadNet Inference e quando tentar de novo](https://broadrouter.com/pt/guides/errors-and-retries/)
-   [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-spring-ai-openai-base-url&utm_content=page-cta) ·

**Fontes**

-   [Referência do Spring AI, OpenAI Chat (2.0.2) (conferido em 2026-11-15)](https://docs.spring.io/spring-ai/reference/api/chat/openai-chat.html)
-   [Código-fonte do Spring AI na v2.0.2, OpenAiSetup.calculateBaseUrl (conferido em 2026-11-16)](https://github.com/spring-projects/spring-ai/blob/v2.0.2/models/spring-ai-openai/src/main/java/org/springframework/ai/openai/setup/OpenAiSetup.java)
-   [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-spring-ai-openai-base-url&utm_content=sources)
