BroadRouter

BroadNet Inference에서 Spring AI 사용하기(OpenAI base-url)

업데이트

spring-ai-starter-model-openai를 추가한 뒤 spring.ai.openai.base-url을 https://inference.broadnet.ai/v1로, spring.ai.openai.api-key를 BroadNet 키로, spring.ai.openai.chat.model을 broadnet/glm-5.3 같은 BroadNet ID로 설정하세요. spring.ai.openai.chat.max-tokens는 추론할 여유를 두어 설정합니다. Spring AI 2.x는 openai-java SDK를 쓰며, 이 SDK가 base URL 뒤에 /chat/completions를 붙입니다.

Spring AI는 Java에서 AI를 쓰기 위한 Spring 프로젝트의 프레임워크입니다. OpenAI 채팅 스타터는 base-url을 읽으므로 OpenAI 호환 서버라면 어디든 호출할 수 있습니다. BroadNet Inference는 https://inference.broadnet.ai/v1 주소에서 표준 chat completions를 제공합니다. BroadRouter는 BroadNet이 운영하는 사이트이며, 이 글은 Spring AI 2.0.2 레퍼런스를 따릅니다.

스타터 추가

Spring AI BOM을 설정한 상태에서(Spring AI의 의존성 관리 문서 참고) 다음을 추가하세요.

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

설정

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'

URL에 /v1을 남겨 두세요. Spring AI 2.x에서는 이 값이 그대로 openai-java 클라이언트에 전달되고(OpenAiSetup.calculateBaseUrl이 값을 변경 없이 반환), 그 클라이언트가 /chat/completions를 붙입니다. 이 설정이 대체하는 기본값은 https://api.openai.com/v1입니다.

호출과 테스트

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

앱을 시작하세요. 답변이 출력되면 키, URL, 모델 ID가 올바른 것입니다.

BroadNet에서 중요한 설정

  • max-completion-tokens가 아니라 max-tokens. Spring AI 문서에 따르면 두 설정은 함께 쓸 수 없으며, 둘 다 설정하면 오류가 납니다. BroadNet API 레퍼런스가 설명하는 필드는 max_tokens입니다. DeepSeek V4.1 Flash, GLM 5.3, Qwen3.8 27B는 먼저 추론하며, 그 추론도 한도에 포함됩니다.
  • 추론 텍스트. Spring AI는 OpenAI 호환 서버가 reasoning_content를 반환하면 이를 노출할 수 있습니다. BroadNet API 레퍼런스는 추론 토큰 수를 usage에 보고하지만 추론 텍스트 자체는 보장하지 않으므로, 이에 의존하지 마세요.
  • 채팅 전용 재정의. spring.ai.openai.chat.base-url과 spring.ai.openai.chat.api-key는 채팅 모델에 한해 공통 속성보다 우선합니다. 임베딩 같은 다른 Spring AI OpenAI 모델은 OpenAI에 그대로 두어야 한다면 이 속성을 쓰세요.
  • 재시도. spring.ai.retry.max-attempts의 기본값은 10이며 지수 백오프를 씁니다. 종량제 키에서는 이 때문에 분당 한도가 금방 소진될 수 있으니 값을 낮추는 것을 고려하세요.

어떤 모델을 고를까

용도 spring.ai.openai.chat.model
도구 호출, 구조화된 출력 broadnet/glm-5.3
이미지나 아랍어 텍스트 broadnet/qwen3.8-27b
긴 문서, 정액 플랜 broadnet/deepseek-v4.1-flash
무료 초기 크레딧 broadnet/gemma-4-26b-a4b

모든 모델의 가격을 확인하세요.

문제 해결

  • 401. 키가 잘못되었거나 만료되었거나 사용 가능 금액이 소진된 경우, 또는 JVM에 BROADNET_API_KEY가 설정되지 않은 경우입니다.
  • 404. base URL에 /v1이 빠졌거나 모델 ID가 잘못된 경우입니다. 유료 모델은 충전이 필요하며, 초기 크레딧($5 상당)은 broadnet/gemma-4-26b-a4b 모델과 Transcribe 모델 두 개에만 쓸 수 있습니다.
  • content()가 비어 있음. 추론이 출력 예산을 다 썼습니다. max-tokens를 늘리세요. 답변이 비어서 오는 이유를 참고하세요.
  • 두 토큰 한도를 모두 설정해 400 발생. max-completion-tokens를 제거하세요.
  • 429. 종량제 키는 분당 30 요청, 동시 처리 4 건까지 허용합니다. 오류와 재시도를 참고하세요.

자주 묻는 질문

spring.ai.openai.base-url에 /v1을 포함해야 하나요?

네. Spring AI 2.x에서는 이 값이 그대로 openai-java 클라이언트에 전달되며, 이 클라이언트의 기본값은 https://api.openai.com/v1입니다. https://inference.broadnet.ai/v1을 쓰세요.

BroadNet에는 max-tokens와 max-completion-tokens 중 무엇을 써야 하나요?

max-tokens를 쓰세요. Spring AI 문서에 따르면 두 설정은 함께 쓸 수 없습니다. BroadNet API 레퍼런스는 max_tokens 필드를 설명하며, 추론도 여기에 포함되므로 1,000토큰 이상을 허용하세요.

Spring AI 도구 호출이 BroadNet에서 작동하나요?

BroadNet이 도구를 표기한 GLM 5.3이나 Qwen3.8 27B를 쓰세요. BroadNet 문서는 DeepSeek V4.1 Flash에 도구 호출을 표기하지 않습니다.

임베딩은 OpenAI에 두고 채팅만 BroadNet으로 쓸 수 있나요?

네. spring.ai.openai.chat.base-url과 spring.ai.openai.chat.api-key는 채팅 모델에 한해 공통 속성보다 우선합니다. BroadNet API 레퍼런스에는 임베딩 엔드포인트가 나와 있지 않습니다.

Markdown으로 읽기ChatGPT에 질문하기Claude에 질문하기Perplexity에 질문하기