huggingface/sentence-transformers

Sentence-Transformers란 무엇인가요?

Sentence-Transformers는 Hugging Face Transformers를 기반으로 구축된 텍스트 임베딩 (text embedding) 모델을 쉽게 다룰 수 있게 해주는 Python 라이브러리입니다. 다음과 같은 기능을 위한 가볍고 사용자 친화적인 API를 제공합니다:

밀집 또는 희소 문장 임베딩 계산 (각 문장을 저장, 비교 또는 인덱싱할 수 있는 고정 크기 벡터로 변환).
Cross-Encoder를 사용한 리랭킹 – 쿼리-문서 쌍을 직접 점수화하는 모델로, 검색 및 리랭킹 파이프라인의 두 번째 단계에 유용합니다.
후기 상호작용 / 다중 벡터 인코더 (ColBERT 스타일) – 더 정확한 유사도를 위해 토큰 수준의 벡터를 유지합니다.
학습 / 미세 조정 – 위 모델 유형 중 무엇이든 자신의 데이터로 학습하거나 미세 조정할 수 있습니다.

이 모든 기능이 단일 패키지에 포함되어 있으며, Hugging Face Hub에 호스팅된 15,000개 이상의 사전 학습된 모델을 통해 다양한 언어와 작업을 지원합니다.

빠른 시작 (복사하여 붙여넣을 수 있는 코드)

# 라이브러리 설치 (Python 3.10+, PyTorch 2.2+, transformers 5.0+ 권장)
# pip install -U sentence-transformers

# 1️⃣ 기성 밀집 임베딩 모델 로드
from sentence_transformers import SentenceTransformer
model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")

sentences = [
    "The weather is lovely today.",
    "It's so sunny outside!",
    "He drove to the stadium."
]
emb = model.encode(sentences)          # 형태 → (3, 384)
print(emb.shape)

# 2️⃣ 쌍별 유사도 계산 (코사인 유사도와 유사한 점수)
print(model.similarity(emb, emb))

리랭킹 예시 (Cross-Encoder):

from sentence_transformers import CrossEncoder
ranker = CrossEncoder("cross-encoder/ms-marco-MiniLM-L6-v2")
query = "How many people live in Berlin?"
passages = [
    "Berlin had a population of 3,520,031 registered inhabitants…",
    "Berlin has a yearly total of about 135 million day visitors…",
    "In 2013 around 600,000 Berliners were registered in sport clubs."
]
# 각 (쿼리, 구절) 쌍 점수화
scores = ranker.predict([(query, p) for p in passages])
print(scores)
# 또는 라이브러리가 직접 랭킹을 수행하도록 설정
print(ranker.rank(query, passages, return_documents=True))

희소 임베딩 예시:

from sentence_transformers import SparseEncoder
sparse = SparseEncoder("naver/splade-cocondenser-ensembledistil")
emb = sparse.encode(["The weather is lovely today."])
print(emb.shape)          # 예: (1, 30522) – 어휘 토큰당 1차원
print(SparseEncoder.sparsity(emb))

후기 상호작용 (다중 벡터) 예시:

from sentence_transformers import MultiVectorEncoder
mv = MultiVectorEncoder("lightonai/GTE-ModernColBERT-v1")
q_emb = mv.encode_query(["What is the capital of France?"])
 d_emb = mv.encode_document(["Paris is the capital of France.", "Berlin is the capital of Germany."])
print(mv.similarity(q_emb, d_emb))

언제 사용하나요?

시나리오	권장 모델 유형	Sentence-Transformers를 사용하는 이유
의미론적 검색 / 검색	밀집 또는 희소 인코더	한 줄의 `model.encode` → FAISS, Annoy 등으로 인덱싱 가능한 벡터
상위 k개 결과 리랭킹	Cross-Encoder (리랭커)	쿼리-문서 쌍을 직접 점수화하여 더 높은 정밀도 제공
하이브리드 검색 (밀집 + 희소)	밀집 인코더와 희소 인코더 결합	어휘 일치와 의미론적 유사도를 동시에 활용
다국어 유사도	다국어 Sentence-BERT 모델	100개 이상의 언어에서 즉시 사용 가능
RAM이 제한된 대규모 말뭉치	희소 또는 Matryoshka 임베딩	희소 벡터는 매우 작으며, Matryoshka는 즉석에서 잘라낼 수 있음
사용자 정의 데이터셋 미세 조정	4가지 모델 제품군 중 하나	20개 이상의 손실 함수와 학습 유틸리티 제공

내부 작동 원리

기본 Transformer – 🤗 Transformers의 BERT/RoBERTa 등 모델.
풀링 레이어 (Pooling layer) – 밀집 모델의 경우 토큰 임베딩을 단일 문장 벡터로 압축 (평균, CLS, 최대 풀링 등).
Cross-Encoder 헤드 – 연결된 쌍 [CLS] query [SEP] passage를 입력받아 관련성 점수를 출력하는 분류 헤드.
희소 헤드 – 어휘 분포를 예측하여 고차원 희소 벡터(SPLADE 등) 생성.
다중 벡터 헤드 – 토큰 수준의 임베딩을 유지하여 단일 벡터로 압축하지 않고 후기 상호작용 점수화 가능.

이 모든 구성 요소가 `sentence_transformers` 패키지에 통합되어 있어 직접 보일러플레이트 코드를 작성할 필요가 없습니다.

라이브러리 설치

# 권장 Python 버전
pip install -U sentence-transformers

선택적 추가 기능(pip install "sentence-transformers[train]" 등으로 설치)은 다음을 지원합니다:

이미지 / 오디오 / 비디오 인코더 ([image], [audio], [video])
ONNX / OpenVINO 내보내기를 통한 빠른 추론 ([onnx], [openvino])
학습 유틸리티 ([train])
개발 도구 ([dev])

문서 및 커뮤니티

전체 문서: www.sbert.net – 설치 가이드, API 참조, 튜토리얼 및 모델 Zoo 포함.
모델 허브: 🤗 Hub – library=sentence-transformers – 15,000개 이상의 사전 학습된 모델 탐색.
블로그 게시물: 학습 가이드, 멀티모달 확장, 효율성 팁 (Matryoshka, 정적 임베딩, 양자화).
문제 및 기여: CONTRIBUTING.md 참조; 메인테이너는 Tom Aarsen (🤗 Hugging Face)입니다.

연구 인용

연구에서 이 라이브러리를 사용하는 경우, 원본 Sentence-BERT 논문 (Reimers & Gurevych 2019)과 다국어 모델의 경우 2020년 증류 논문을 인용해 주십시오. 서지 정보는 README에 제공되어 있습니다.