Spring AI 시리즈 4화 – Hugging Face 연동: Inference API 실습

B컷개발자 2025. 6. 2. 10:06

728x90

Spring AI를 활용해 Hugging Face Inference API와 연동하는 방법을 설명합니다. 모델 선택, 설정 파일 구성, 텍스트 생성 실습까지 Java 기반에서 손쉽게 구현할 수 있는 방법을 소개합니다.

Spring AI는 OpenAI뿐만 아니라 Hugging Face Hub의 모델들도 손쉽게 연동할 수 있도록 설계되어 있습니다.
이번 글에서는 Spring AI를 통해 Hugging Face Inference API를 연동하고,
BLOOM 또는 Falcon 등 텍스트 생성 모델을 활용하는 방법을 실습 중심으로 소개합니다.

1. Hugging Face Inference API란?

Hugging Face Inference API는 Hugging Face에 업로드된 사전 학습 모델을 REST API로 호출할 수 있는 서비스입니다.
사용자는 직접 모델을 호스팅하지 않고도 텍스트 생성, 번역, 요약 등의 기능을 사용할 수 있습니다.

Spring AI는 이 API를 내부적으로 래핑하여, 동일한 방식으로 OpenAI나 Hugging Face를 호출할 수 있도록 지원합니다.

2. 의존성 추가

Hugging Face 연동을 위해 아래 의존성을 추가합니다.

Maven

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-huggingface-spring-boot-starter</artifactId>
  <version>0.8.0</version>
</dependency>

Gradle

implementation 'org.springframework.ai:spring-ai-huggingface-spring-boot-starter:0.8.0'

OpenAI Starter와 충돌하지 않으므로, 동시에 두 API를 사용할 수도 있습니다.

3. application.yml 설정

Hugging Face의 Inference API를 사용하려면 다음과 같은 설정이 필요합니다.
기본 모델은 텍스트 생성용으로 많이 사용되는 google/flan-t5-large 또는 tiiuae/falcon-7b-instruct 등을 선택할 수 있습니다.

spring:
  ai:
    huggingface:
      api-key: ${HUGGINGFACE_API_KEY}
      text:
        options:
          model: google/flan-t5-large
          temperature: 0.5
          max-tokens: 200

Hugging Face API 키는 https://huggingface.co/settings/tokens에서 발급받을 수 있습니다.

4. 텍스트 생성 API 호출

OpenAI 연동과 마찬가지로 ChatClient를 그대로 사용할 수 있습니다.
Spring AI는 동일한 추상화를 통해 다양한 LLM을 교체 가능하게 구성되어 있습니다.

@RestController
@RequestMapping("/huggingface")
public class HuggingFaceController {

    private final ChatClient chatClient;

    public HuggingFaceController(ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    @GetMapping("/generate")
    public String generate(@RequestParam String prompt) {
        return chatClient.call(prompt).getResult().getOutput().getContent();
    }
}

위 컨트롤러는 /huggingface/generate?prompt=물리학이란 무엇인가요와 같은 요청에 대해 Hugging Face 모델이 생성한 텍스트를 반환합니다.

5. PromptTemplate을 활용한 템플릿 구성

PromptTemplate은 OpenAI뿐 아니라 Hugging Face 연동 시에도 동일하게 사용할 수 있습니다.

@GetMapping("/template")
public String templatePrompt(@RequestParam String topic) {
    PromptTemplate template = new PromptTemplate("다음 주제에 대해 설명해줘: {topic}");
    template.add("topic", topic);
    return chatClient.call(template.create()).getResult().getOutput().getContent();
}

6. 모델 선택 시 유의사항

Hugging Face에서는 수천 개의 모델을 제공하지만,
Spring AI에서 Inference API를 사용할 경우 다음 사항을 고려해야 합니다.

항목 설명

모델 크기	flan-t5-small, flan-t5-large, bloomz, falcon 등
사용 가능성	일부 모델은 유료 계정에서만 사용 가능
텍스트 길이	max-tokens 제한이 작거나 응답이 느린 모델 존재
지연 시간	OpenAI에 비해 상대적으로 느릴 수 있음

권장 모델 예시

tiiuae/falcon-7b-instruct
google/flan-t5-large
bigscience/bloomz-560m

7. OpenAI와 비교

항목 Hugging Face OpenAI

호스팅 방식	공개 모델 API 호출	OpenAI 서버 API 호출
커스터마이징	자유롭게 모델 선택	제한된 모델 (GPT 시리즈)
응답 속도	다소 느림	비교적 빠름
사용 비용	무료 모델 다수	GPT-4 등 유료 플랜 필요
API 호출 방식	유사	동일한 ChatClient 사용 가능

실습 정리

Hugging Face는 OpenAI와 동일한 방식으로 연동되며, 설정만 다릅니다.
ChatClient, PromptTemplate 사용 방식은 그대로 유지됩니다.
다양한 공개 모델을 실험할 수 있는 유연성이 장점입니다.
다만 응답 속도와 모델 품질은 모델마다 차이가 있습니다.

728x90