정정지용
기술스택 목록
백엔드

Hibernate Vector

프로젝트 1개에서 사용했습니다. 각 프로젝트에서 어떤 역할로 썼는지 아래에 정리했습니다.

이 기술은 무엇인가요?

Hibernate ORM에서 벡터 임베딩을 JPA 엔티티로 매핑할 수 있게 하는 확장 라이브러리

Hibernate Vector는 PostgreSQL의 pgvector 같은 데이터베이스 벡터 타입을 JPA 엔티티 필드로 다룰 수 있게 해주는 Hibernate 확장입니다. AI/ML 모델이 생성한 임베딩 벡터를 관계형 데이터베이스에 저장하고 유사도 검색을 수행해야 할 때, ORM 레이어에서 타입 안전하게 벡터 데이터를 매핑하고 쿼리할 수 있도록 지원합니다.

이럴 때 사용합니다

  • 얼굴 인식, 이미지 유사도 검색 등 임베딩 벡터를 RDB에 저장하고 JPA로 관리할 때
  • pgvector 같은 벡터 확장을 쓰면서도 기존 JPA 엔티티 구조를 유지하고 싶을 때
  • 벡터 유사도 검색을 JPQL/HQL 쿼리로 작성해 타입 안전성을 확보하고 싶을 때

핵심 개념

Vector Embedding
텍스트, 이미지 등을 고정된 차원의 실수 배열로 표현한 것. 의미적 유사도를 수치 거리로 계산할 수 있어 검색·추천·분류에 활용됩니다.
@JdbcTypeCode
Hibernate에서 필드의 JDBC 타입을 명시적으로 지정하는 어노테이션. Hibernate Vector는 이를 통해 벡터 타입을 매핑합니다.
Vector Type
PostgreSQL pgvector 등 데이터베이스가 제공하는 네이티브 벡터 자료형. 유사도 검색을 위한 인덱스와 거리 함수를 지원합니다.
Cosine Distance
두 벡터 간 각도 기반 거리 측정 방식. 벡터의 방향 유사도를 계산하며, Hibernate Vector는 이를 JPQL/HQL 함수로 제공합니다.

JPA 엔티티에서 벡터 필드 매핑

float 배열 필드에 @JdbcTypeCode로 벡터 타입을 지정하면, Hibernate가 데이터베이스 벡터 컬럼과 자동 매핑하고 HQL에서 거리 함수를 쓸 수 있습니다.

Java
@Entity
public class FaceEmbedding {
    @Id
    @GeneratedValue
    private Long id;

    // float 배열을 PostgreSQL vector 타입으로 매핑
    @JdbcTypeCode(SqlTypes.VECTOR)
    private float[] embedding;

    // HQL에서 벡터 거리 함수 사용
    // SELECT f FROM FaceEmbedding f
    // ORDER BY cosine_distance(f.embedding, :queryVector)
}

처음 쓸 때 흔한 함정

  • 데이터베이스에 pgvector 등 벡터 확장이 먼저 설치되어 있어야 동작합니다
  • 벡터 차원 수가 맞지 않으면 런타임 오류가 발생하므로 엔티티 필드와 DB 스키마 일치 필요
  • 대량 벡터 검색 시 인덱스(IVFFlat, HNSW 등) 없이는 성능이 크게 떨어질 수 있습니다

위 개요는 기술 학습을 돕기 위해 자동 생성된 일반 설명입니다. 정확한 사양과 최신 정보는 공식 문서를 확인하세요.

프로젝트별 활용 방식

위 개념이 실제 프로젝트에서 어떻게 쓰였는지 보여줍니다.

함께 사용한 기술

위 프로젝트들에서 같이 쓰인 다른 기술입니다.

DockerFlywayGradleJavaJJWTPostgreSQLSpring BootSpring Data JPASpring SecuritySwaggerWebFlux