Hugging Face Chat

Hugging Face의 Text Generation Inference(TGI)는 대규모 언어 모델(LLM)을 클라우드에서 서빙하기 위한 전용 배포 솔루션이에요. TGI로 모델을 배포하면 API로 접근할 수 있게 되고, Spring AI는 이렇게 배포된 Inference Endpoint에 연결해 채팅 모델로 사용해요.

출처: 공식문서

Text Generation Inference는 모델이 아키텍처 특화 최적화와 호환되어야 해요. 많은 인기 LLM이 지원되지만, Hugging Face Hub의 모든 모델이 TGI로 배포될 수 있는 건 아니에요. 다른 유형의 모델을 배포해야 한다면 표준 Hugging Face Inference Endpoints를 고려하세요. 지원 모델과 아키텍처의 전체·최신 목록은 Text Generation Inference 지원 모델 문서를 참고해요.

사전 준비

Hugging Face에 Inference Endpoint를 만들고 엔드포인트에 접근하기 위한 API 토큰을 생성해야 해요. 자세한 내용은 여기에서 확인할 수 있어요.

Spring AI 프로젝트는 spring.ai.huggingface.chat.api-key라는 구성 속성을 정의하는데, Hugging Face에서 얻은 API 토큰 값을 이 속성에 설정하면 돼요. 또한 spring.ai.huggingface.chat.url이라는 구성 속성이 있는데, Hugging Face에서 모델을 프로비저닝할 때 얻은 inference endpoint URL을 설정해요. 이건 Inference Endpoint의 UI 여기에서 찾을 수 있어요.

환경 변수를 export 하는 것도 이 속성들을 설정하는 한 방법이에요.

export SPRING_AI_HUGGINGFACE_CHAT_API_KEY=<INSERT KEY HERE>
export SPRING_AI_HUGGINGFACE_CHAT_URL=<INSERT INFERENCE ENDPOINT URL HERE>

저장소와 BOM 추가

Spring AI 아티팩트는 Maven Central과 Spring Snapshot 저장소에 게시돼요. Repositories 섹션을 참고해 빌드 시스템에 추가해요. 의존성 관리를 돕기 위해 Spring AI는 프로젝트 전체에 일관된 버전을 보장하는 BOM(일자재 명세서)을 제공해요. Dependency Management 섹션을 참고해 Spring AI BOM을 빌드 시스템에 추가해요.

자동 설정 (Auto-configuration)

Spring AI는 Hugging Face 채팅 클라이언트를 위한 Spring Boot 자동 설정을 제공해요. Maven pom.xml에 다음 의존성을 추가하면 활성화돼요.

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

또는 Gradle build.gradle 빌드 파일에 추가해요.

dependencies {
    implementation 'org.springframework.ai:spring-ai-huggingface-spring-boot-starter'
}

Dependency Management 섹션을 참고해 Spring AI BOM을 빌드 파일에 추가하세요.

채팅 속성 (Chat Properties)

spring.ai.huggingface 프리픽스는 Hugging Face의 채팅 모델 구현을 구성하는 속성 프리픽스예요.

| 속성 | 설명 | 기본값 | | spring.ai.huggingface.chat.api-key | Inference Endpoint 인증용 API 키 | - | | spring.ai.huggingface.chat.url | 연결할 Inference Endpoint URL | - | | spring.ai.huggingface.chat.enabled | Hugging Face 채팅 모델 활성화 | true |

샘플 컨트롤러 (자동 설정)

start.spring.io에서 새 Spring Boot 프로젝트를 만들고 spring-ai-huggingface-spring-boot-starter를 pom(또는 gradle) 의존성에 추가해요.

src/main/resources 아래에 application.properties 파일을 추가해 Hugging Face 채팅 모델을 활성화·구성해요.

spring.ai.huggingface.chat.api-key=YOUR_API_KEY
spring.ai.huggingface.chat.url=YOUR_INFERENCE_ENDPOINT_URL

api-key와 url을 여러분의 Hugging Face 값으로 바꿔주세요.

이렇게 하면 클래스에 주입할 수 있는 HuggingfaceChatModel 구현이 만들어져요. 텍스트 생성을 위해 채팅 모델을 사용하는 간단한 @Controller 클래스 예시를 볼게요.

@RestController
public class ChatController {

    private final HuggingfaceChatModel chatModel;

    @Autowired
    public ChatController(HuggingfaceChatModel 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));
    }
}

수동 설정

HuggingfaceChatModel은 ChatModel 인터페이스를 구현하고, Hugging Face inference endpoints에 연결하기 위해 [low-level-api]를 사용해요.

Maven pom.xml에 spring-ai-huggingface 의존성을 추가해요.

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-huggingface</artifactId>
</dependency>

또는 Gradle build.gradle 빌드 파일에 추가해요.

dependencies {
    implementation 'org.springframework.ai:spring-ai-huggingface'
}

Dependency Management 섹션을 참고해 Spring AI BOM을 빌드 파일에 추가하세요.

다음으로 HuggingfaceChatModel을 만들어 텍스트 생성에 사용해요.

HuggingfaceChatModel chatModel = new HuggingfaceChatModel(apiKey, url);

ChatResponse response = this.chatModel.call(
    new Prompt("Generate the names of 5 famous pirates."));

System.out.println(response.getGeneration().getResult().getOutput().getContent());

Hugging Face Chat