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 건까지 허용합니다. 오류와 재시도를 참고하세요.
