---
title: "Spring AI OpenAI 스타터 커스텀 base-url 설정 | BroadRouter"
description: "Spring AI의 OpenAI 채팅 스타터를 spring.ai.openai.base-url, BroadNet 모델 ID, max-tokens로 BroadNet Inference에 연결하고 ChatClient로 호출합니다."
url: https://broadrouter.com/ko/guides/spring-ai-openai-base-url/
lang: ko
updated: 2026-11-16
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

이 페이지는 영어 원문을 AI의 도움을 받아 번역했습니다. [영어 원문 읽기](https://broadrouter.com/guides/spring-ai-openai-base-url/) (2026-11-16 업데이트).

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

업데이트 2026-11-16

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의 의존성 관리 문서 참고) 다음을 추가하세요.

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

## 설정

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

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

## 호출과 테스트

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

앱을 시작하세요. 답변이 출력되면 키, 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` |

[모든 모델의 가격](https://broadrouter.com/ko/pricing/)을 확인하세요.

## 문제 해결

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

## 이 가이드의 용어

[종량제(Pay-as-you-go)](https://broadrouter.com/ko/glossary/pay-as-you-go/)

종량제(pay-as-you-go)는 구독이나 최소 약정 없이 토큰, 요청, 오디오 분 같은 단위로 사용량을 측정해 쓴 만큼만 내는 요금 방식입니다. 대부분의 LLM API가 선불 잔액에서 차감하거나 정기 청구서를 발행하는 식으로 이렇게 과금합니다.

[OpenAI 호환 API(OpenAI-compatible API)](https://broadrouter.com/ko/glossary/openai-compatible-api/)

OpenAI 호환 API는 POST /v1/chat/completions처럼 OpenAI API와 같은 요청 및 응답 형식을 받는 HTTP API입니다. 그래서 OpenAI SDK와 도구는 base URL, API 키, 모델 이름만 바꾸면 이 API를 그대로 사용할 수 있습니다.

[구조화된 출력(Structured output)](https://broadrouter.com/ko/glossary/structured-output/)

구조화된 출력(structured output)은 모델의 응답을 개발자가 지정한 형식, 주로 JSON Schema에 맞추도록 제한해 코드가 안정적으로 파싱할 수 있게 하는 LLM API 기능입니다. 유효한 JSON만 보장하고 특정 구조는 보장하지 않는 JSON 모드보다 더 엄격합니다.

[동시 처리(concurrency)](https://broadrouter.com/ko/glossary/concurrency/)

동시 처리(concurrency)는 클라이언트가 같은 시점에 진행 중인 요청 수입니다. LLM API는 분당 요청 수와 별도로 키나 플랜마다 이를 제한하는 경우가 많습니다. 열려 있는 요청은 응답이 끝날 때까지 GPU 용량을 차지하기 때문입니다.

[속도 제한(rate limit)](https://broadrouter.com/ko/glossary/rate-limit/)

속도 제한(rate limit)은 API가 일정 시간 동안 클라이언트가 사용할 수 있는 양에 두는 상한으로, 분당 요청 수나 분당 토큰 수 같은 기준이 있습니다. 한도를 넘은 요청은 사용량이 다시 한도 아래로 내려갈 때까지 거부되며, 보통 HTTP 429 Too Many Requests가 반환됩니다.

[임베딩(embedding)](https://broadrouter.com/ko/glossary/embeddings/)

임베딩은 모델이 텍스트, 이미지 등의 입력을 표현하기 위해 만드는 부동소수점 숫자 목록(벡터)입니다. 의미가 비슷한 입력은 서로 가까운 벡터를 얻으므로, 벡터 사이의 거리로 검색 결과의 순위를 매기거나 문서를 군집화하거나 관련 항목을 찾을 수 있습니다.

[추론 토큰(reasoning tokens)](https://broadrouter.com/ko/glossary/reasoning-tokens/)

추론 토큰(reasoning tokens)은 추론 모델이 눈에 보이는 답변을 쓰기 전에 문제를 풀기 위해 생성하는 토큰입니다. 보통 출력 토큰으로 과금되고, 출력 한도와 컨텍스트 윈도우에 포함되며, API에 따라 숨겨지거나 요약되어 제공됩니다.

[LLM 정액 플랜(Flat-rate LLM plan)](https://broadrouter.com/ko/glossary/flat-rate-llm-plan/)

LLM 정액 플랜은 언어 모델 API를 토큰당 과금하지 않고, 한 달 같은 기간 단위로 고정 요금을 받는 요금제입니다. 이런 플랜은 보통 동시 실행 수, 속도, 모델, 사용 시간대 같은 다른 항목을 제한하므로 가격만큼 제한 조건도 중요합니다.

## 자주 묻는 질문

### 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 레퍼런스에는 임베딩 엔드포인트가 나와 있지 않습니다.

## 관련 가이드

-   [openai-go SDK로 Go에서 BroadNet Inference 호출하기](https://broadrouter.com/ko/guides/openai-go-sdk/)
-   [BroadNet Inference에서 OpenAI Python SDK 사용하기](https://broadrouter.com/ko/guides/openai-python-sdk/)
-   [추론 모델이 빈 답변을 반환하는 이유](https://broadrouter.com/ko/guides/reasoning-tokens-empty-response/)
-   [BroadNet Inference 오류 코드와 재시도해야 하는 경우](https://broadrouter.com/ko/guides/errors-and-retries/)
-   [BroadNet Inference와 함께 쓸 수 있는 모든 도구 (영어)](https://broadrouter.com/integrations/): SDK, 코딩 에이전트, 채팅 UI, 자동화 도구와 각 도구의 정확한 설정

실제 워크로드로 테스트해 보세요. 신규 계정에는 US$5 상당의 초기 크레딧이 제공되며 Gemma 및 음성 전사에 사용할 수 있습니다. DeepSeek, GLM 및 Qwen3.8 모델은 충전이 필요합니다.

[시작하기](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=ko-guides-spring-ai-openai-base-url&utm_content=page-cta) ·

**출처**

-   [Spring AI 레퍼런스, OpenAI Chat(2.0.2)(2026-11-15 확인)](https://docs.spring.io/spring-ai/reference/api/chat/openai-chat.html)
-   [Spring AI 소스 v2.0.2, OpenAiSetup.calculateBaseUrl(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)
-   [BroadNet Inference API 레퍼런스(2026-11-15 확인) (영어)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=ko-guides-spring-ai-openai-base-url&utm_content=sources)
