Groq Chat
Groq Chat
Groq는 초저지연 추론으로 유명한 AI 하드웨어·클라우드 제공자예요. Spring AI는 OpenAI 호환 클라이언트를 재사용해 Groq API에 연결해요. 다만 Groq API는 OpenAI API와 완전히 호환되지는 않으니 호환성 제약을 꼭 확인해야 해요. 또한 현재 Groq는 멀티모달 메시지를 지원하지 않아요.
출처: 공식문서
사전 준비
- API 키 생성: 여기에서 API 키를 만들어요. Spring AI 프로젝트는
spring.ai.openai.api-key라는 구성 속성을 정의하는데, groq.com에서 얻은API Key값을 이 속성에 설정하면 돼요. - Groq URL 설정:
spring.ai.openai.base-url속성을https://api.groq.com/openai/v1로 설정해야 해요. - Groq 모델 선택:
spring.ai.openai.chat.model=<모델명>속성으로 Groq 모델 중 하나를 선택해요.
application.properties 파일에 다음과 같이 설정할 수 있어요.
spring.ai.openai.api-key=<your-groq-api-key> spring.ai.openai.base-url=https://api.groq.com/openai/v1 spring.ai.openai.chat.model=llama3-70b-8192
API 키 같은 민감 정보를 다룰 때 보안을 강화하려면 Spring Expression Language(SpEL)로 사용자 정의 환경 변수를 참조할 수 있어요.
# In application.yml spring: ai: openai: api-key: ${GROQ_API_KEY} base-url: ${GROQ_BASE_URL} chat: model: ${GROQ_MODEL}
# In your environment or .env file export GROQ_API_KEY=<your-groq-api-key> export GROQ_BASE_URL=https://api.groq.com/openai/v1 export GROQ_MODEL=llama3-70b-8192
애플리케이션 코드에서 프로그래밍 방식으로도 설정할 수 있어요.
// Retrieve configuration from secure sources or environment variables String apiKey = System.getenv("GROQ_API_KEY"); String baseUrl = System.getenv("GROQ_BASE_URL"); String model = System.getenv("GROQ_MODEL");
저장소와 BOM 추가
Spring AI 아티팩트는 Maven Central과 Spring Snapshot 저장소에 게시돼요. Artifact Repositories 섹션을 참고해 빌드 시스템에 저장소를 추가해요. 의존성 관리를 돕기 위해 Spring AI는 버전 일관성을 보장하는 BOM을 제공해요. Dependency Management 섹션을 참고해 추가해요.
자동 설정 (Auto-configuration)
Spring AI의 자동 설정과 스타터 모듈의 아티팩트 이름이 크게 바뀌었어요. 자세한 내용은 업그레이드 노트를 확인해주세요.
Spring AI는 OpenAI 채팅 클라이언트를 위한 Spring Boot 자동 설정을 제공해요. Maven pom.xml이나 Gradle build.gradle에 다음 의존성을 추가하면 돼요.
- Maven
- Gradle
<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-model-openai</artifactId> </dependency>
dependencies { implementation 'org.springframework.ai:spring-ai-starter-model-openai' }
채팅 속성 (Chat Properties)
재시도 속성
| 속성 | 설명 | 기본값 |
|---|---|---|
| spring.ai.retry.max-attempts | 최대 재시도 횟수 | 10 |
| spring.ai.retry.backoff.initial-interval | 지수 백오프 정책의 초기 대기 시간 | 2 sec. |
| spring.ai.retry.backoff.multiplier | 백오프 간격 배수 | 5 |
| spring.ai.retry.backoff.max-interval | 최대 백오프 지속 시간 | 3 min. |
| spring.ai.retry.on-client-errors | false면 NonTransientAiException을 던지고 4xx 클라이언트 오류에 재시도하지 않음 |
false |
| spring.ai.retry.exclude-on-http-codes | 재시도를 트리거하지 않아야 하는 HTTP 상태 코드 목록 | empty |
| spring.ai.retry.on-http-codes | 재시도를 트리거해야 하는 HTTP 상태 코드 목록 | empty |
연결 속성
| 속성 | 설명 | 기본값 |
|---|---|---|
| spring.ai.openai.base-url | 연결할 URL. 반드시 https://api.groq.com/openai/v1로 설정해야 함 |
- |
| spring.ai.openai.api-key | Groq API 키 | - |
구성 속성
채팅 자동 설정의 활성·비활성은 프리픽스 spring.ai.model.chat로 관리해요. 활성화하려면 spring.ai.model.chat=openai(기본값), 비활성화하려면 spring.ai.model.chat=none을 쓰면 돼요.
| 속성 | 설명 | 기본값 |
|---|---|---|
| spring.ai.openai.chat.enabled (제거됨, 더는 유효하지 않음) | OpenAI 채팅 모델 활성화 | true |
| spring.ai.openai.chat | OpenAI 채팅 모델 활성화 | openai |
| spring.ai.openai.chat.base-url | chat 전용 url을 제공하기 위한 spring.ai.openai.base-url의 선택적 재정의. 반드시 https://api.groq.com/openai/v1로 설정해야 함 |
- |
| spring.ai.openai.chat.api-key | chat 전용 api-key를 제공하기 위한 선택적 재정의 | - |
| spring.ai.openai.chat.model | 사용 가능한 모델 이름은 llama3-8b-8192, llama3-70b-8192, mixtral-8x7b-32768, gemma2-9b-it |
- |
| spring.ai.openai.chat.temperature | 생성 완료의 창의성을 제어하는 샘플링 온도. 높을수록 무작위, 낮을수록 집중적이고 결정적. 같은 요청에서 temperature와 top_p를 함께 수정하는 건 권장하지 않음 | 0.8 |
| spring.ai.openai.chat.frequency-penalty | -2.0 ~ 2.0 사이 숫자. 양수는 지금까지의 텍스트에서 이미 존재하는 빈도를 기반으로 새 토큰을 페널티해 같은 라인을 그대로 반복할 가능성을 줄임 | 0.0f |
| spring.ai.openai.chat.max-tokens | 채팅 완료에서 생성할 최대 토큰 수 | - |
| spring.ai.openai.chat.n | 각 입력 메시지에 대해 생성할 채팅 완료 선택지 수. 모든 선택지의 생성 토큰 수 기준으로 과금됨. 비용 최소화를 위해 1 유지 권장 | 1 |
| spring.ai.openai.chat.presence-penalty | -2.0 ~ 2.0 사이 숫자. 양수는 새 토큰이 지금까지의 텍스트에 나타나는지 여부를 기준으로 페널티해 새 주제에 대해 말할 가능성을 높임 | - |
| spring.ai.openai.chat.response-format | 모델이 출력해야 하는 형식을 지정하는 객체. { "type": "json_object" }로 설정하면 JSON 모드가 켜져 모델이 생성하는 메시지가 유효한 JSON임을 보장 |
- |
| spring.ai.openai.chat.seed | Beta 기능. 지정하면 시스템이 결정적으로 샘플링하도록 최선을 다해 동일한 seed와 파라미터로 반복 요청 시 동일한 결과를 반환 | - |
| spring.ai.openai.chat.stop | API가 추가 토큰 생성을 중지할 최대 4개 시퀀스 | - |
| spring.ai.openai.chat.top-p | nucleus sampling이라 불리는 temperature 대안. 0.1은 상위 10% 확률 질량만 구성하는 토큰만 고려 | - |
| spring.ai.openai.chat.tools | 모델이 호출할 수 있는 도구 목록. 현재 함수만 도구로 지원 | - |
| spring.ai.openai.chat.tool-choice | 모델이 호출하는 함수(있는 경우)를 제어. none은 함수 호출 없이 메시지 생성. auto는 메시지 생성과 함수 호출 사이 선택. 특정 함수를 지정하면 그 함수를 강제 호출. 함수 없으면 none이 기본, 있으면 auto가 기본 | - |
| spring.ai.openai.chat.user | 최종 사용자를 나타내는 고유 식별자. OpenAI가 남용을 모니터링·탐지하는 데 도움 | - |
| spring.ai.openai.chat.stream-usage | (스트리밍 전용) 전체 요청의 토큰 사용 통계가 담긴 추가 청크를 포함하도록 설정. 이 청크의 choices 필드는 빈 배열이고 다른 모든 청크에도 usage 필드가 포함되지만 null 값 |
false |
| spring.ai.openai.chat.tool-callbacks | ChatModel에 등록할 Tool 콜백 | - |
spring.ai.openai.chat 프리픽스가 붙은 모든 속성은 Prompt 호출에 요청별 runtime 옵션을 추가해 런타임에 덮어쓸 수 있어요.
런타임 옵션
OpenAiChatOptions.java는 사용할 모델, temperature, frequency penalty 같은 모델 구성을 제공해요.
시작 시 기본 옵션은 OpenAiChatModel(api, options) 생성자나 spring.ai.openai.chat.* 속성으로 구성해요. 런타임에는 Prompt 호출에 요청별 옵션을 추가해 기본값을 덮어쓸 수 있어요. 특정 요청의 기본 모델과 temperature를 덮어쓰는 예시예요.
ChatResponse response = chatModel.call( new Prompt( "Generate the names of 5 famous pirates.", OpenAiChatOptions.builder() .model("mixtral-8x7b-32768") .temperature(0.4) .build() ));
함수 호출 (Function Calling)
Groq API 엔드포인트는 Tool/Function을 지원하는 모델을 선택할 때 tool/function calling을 지원해요.
ChatModel에 사용자 정의 Java 함수를 등록하고, 제공된 Groq 모델이 등록된 함수 중 하나 이상을 호출하는 인자를 담은 JSON 객체를 출력하도록 지능적으로 선택하게 할 수 있어요. LLM 기능을 외부 도구·API와 연결하는 강력한 기법이에요.
도구 예시
Spring AI에서 Groq 도구 호출을 사용하는 간단한 예시를 볼게요.
public class WeatherService implements Function<WeatherService.Request, WeatherService.Response> { public record Request(String location, String unit) {} public record Response(double temp, String unit) {} @Override public Response apply(Request request) { double temperature = request.location().contains("Amsterdam") ? 20 : 25; return new Response(temperature, request.unit); } }
ToolCallback weatherCallback = FunctionToolCallback.builder("getCurrentWeather", new WeatherService()) .description("Get the weather in location") .inputType(WeatherService.Request.class) .build(); var response = chatClient.prompt() .user("What is the weather in Amsterdam and Paris?") .tools(weatherCallback) .call() .content();
이 예시에서 모델은 날씨 정보가 필요할 때 WeatherService를 자동으로 호출하고, 그 서비스가 실시간 날씨 데이터를 가져올 수 있어요. 예상 응답은 "The weather in Amsterdam is currently 20 degrees Celsius, and the weather in Paris is currently 25 degrees Celsius." 형태예요.
현재 Groq API는 미디어 콘텐츠를 지원하지 않아요.
샘플 컨트롤러
start.spring.io에서 새 Spring Boot 프로젝트를 만들고 spring-ai-starter-model-openai를 pom(또는 gradle) 의존성에 추가해요.
src/main/resources 아래에 application.properties 파일을 추가해 OpenAI 채팅 모델을 활성화·구성해요.
spring.ai.openai.api-key=<GROQ_API_KEY> spring.ai.openai.base-url=https://api.groq.com/openai/v1 spring.ai.openai.chat.model=llama3-70b-8192 spring.ai.openai.chat.temperature=0.7
api-key를 Groq 또는 OpenAI 자격 증명으로 바꿔주세요.
이렇게 하면 클래스에 주입할 수 있는 OpenAiChatModel 구현이 만들어져요. 텍스트 생성을 위한 간단한 @Controller 클래스 예시를 볼게요.
@RestController public class ChatController { private final OpenAiChatModel chatModel; @Autowired public ChatController(OpenAiChatModel chatModel) { this.chatModel = chatModel; } @GetMapping("/ai/generate") public Map generate(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) { return Map.of("generation", this.chatModel.call(message)); } @GetMapping("/ai/generateStream") public Flux<ChatResponse> generateStream(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) { Prompt prompt = new Prompt(new UserMessage(message)); return this.chatModel.stream(prompt); } }
수동 설정
Maven pom.xml에 spring-ai-openai 의존성을 추가해요.
<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-openai</artifactId> </dependency>
또는 Gradle build.gradle 파일에 추가해요.
dependencies { implementation 'org.springframework.ai:spring-ai-openai' }
다음으로 OpenAiChatModel을 만들어 텍스트 생성에 사용해요.
var chatModel = OpenAiChatModel.builder() .options(OpenAiChatOptions.builder() .baseUrl("https://api.groq.com/openai/v1") .apiKey(System.getenv("GROQ_API_KEY")) .model("llama3-70b-8192") .temperature(0.4) .maxTokens(200) .build()) .build(); ChatResponse response = this.chatModel.call( new Prompt("Generate the names of 5 famous pirates.")); // Or with streaming responses Flux<ChatResponse> response = this.chatModel.stream( new Prompt("Generate the names of 5 famous pirates."));
OpenAiChatOptions는 채팅 요청의 구성 정보를 제공하고, OpenAiChatOptions.Builder는 플루언트 옵션 빌더예요.