FastEmbed - 경량 로컬 임베딩 치트시트

FastEmbed - 경량 로컬 임베딩 치트시트

FastEmbed (Qdrant)는 텍스트 임베딩을 로컬에서 생성하기 위한 빠르고 경량인 라이브러리입니다. ONNX 런타임을 통해 모델을 실행합니다 (무거운 PyTorch 의존성 없음). 이는 작고 빠르게 설치되며 CPU에서 효율적입니다. 밀집 임베딩 외에도 희소 (BM25, SPLADE), 늦은 상호작용 (ColBERT), 재순위 지정 모델을 지원합니다 — RAG를 위한 하이브리드 밀집+희소 검색을 구축하는 데 필요한 모든 것입니다. Qdrant 벡터 데이터베이스와 긴밀하게 통합됩니다.

설치

방법	명령어
pip	pip install fastembed
GPU (CUDA)	pip install fastembed-gpu
확인	python -c "from fastembed import TextEmbedding; print('ok')"

밀집 임베딩

from fastembed import TextEmbedding

model = TextEmbedding("BAAI/bge-small-en-v1.5")   # 한 번 다운로드
docs = ["FastEmbed runs on ONNX.", "It is CPU-friendly."]
vectors = list(model.embed(docs))   # numpy 배열의 생성기
print(len(vectors), vectors[0].shape)

호출	설명
TextEmbedding(model_name)	밀집 임베딩 모델 로드
.embed(list)	문서 임베드 (배치, 지연)
.query_embed(str)	쿼리 임베드 (일부 모델은 q/d 다름)
.passage_embed(list)	패시지 임베드
TextEmbedding.list_supported_models()	사용 가능한 모델 보기

모델 타입

타입	클래스	사용
밀집	TextEmbedding	의미론적 유사성
희소 (BM25/SPLADE)	SparseTextEmbedding	키워드/정확 항 매칭
늦은 상호작용 (ColBERT)	LateInteractionTextEmbedding	높은 정밀도 재순위 검색
재순위 지정	TextCrossEncoder	후보 재순서
이미지	ImageEmbedding	다중 모드 임베딩

희소 임베딩 (하이브리드 검색용)

from fastembed import SparseTextEmbedding

sparse = SparseTextEmbedding("Qdrant/bm25")
sv = list(sparse.embed(["exact term ABC-123 matters"]))
print(sv[0].indices, sv[0].values)   # 희소: 토큰 인덱스 + 가중치

희소 벡터는 정밀한 임베딩이 평활화하는 정확한 항 (식별자, 숫자)을 캡처합니다 — 강력한 하이브리드 검색의 핵심입니다.

재순위 지정

from fastembed.rerank.cross_encoder import TextCrossEncoder

reranker = TextCrossEncoder("Xenova/ms-marco-MiniLM-L-6-v2")
scores = reranker.rerank("what is fastembed?",
                         ["FastEmbed is an embedding lib.", "Unrelated text."])

Qdrant를 사용한 하이브리드 검색

from fastembed import TextEmbedding, SparseTextEmbedding
# 각 청크에 대해 밀집과 희소 벡터를 계산하고, Qdrant에 업셀트하고,
# 둘 다로 쿼리한 후 Qdrant가 결과를 퓨즈 (RRF) 하도록 합니다.
dense = TextEmbedding("BAAI/bge-small-en-v1.5")
sparse = SparseTextEmbedding("Qdrant/bm25")

단계	도구
밀집 벡터	TextEmbedding
희소 벡터	SparseTextEmbedding (BM25)
저장 + 퓨즈	Qdrant 네이티브 하이브리드 쿼리
선택적 재순위 지정	TextCrossEncoder

FastEmbed가 있는 이유 (설계)

속성	이점
ONNX 런타임	PyTorch 없음; 작은 설치, CPU에서 빠름
양자화된 모델	낮은 메모리/지연
지연 생성기	임베딩 스트림, 낮은 메모리
로컬	API 호출 없음; 데이터는 비공개 유지

일반적인 워크플로우

# 벡터 DB를 위한 말뭉치를 배치로 임베드 (CPU 친화적)
from fastembed import TextEmbedding
model = TextEmbedding("BAAI/bge-base-en-v1.5")
embeddings = list(model.embed(corpus, batch_size=64))

# 하이브리드 검색 구축: 밀집 + BM25 희소, Qdrant에서 퓨즈

FastEmbed vs 대체

측면	FastEmbed	sentence-transformers	OpenAI embeddings API
런타임	ONNX (torch 없음)	PyTorch	호스팅 API
희소/ColBERT	빌트인	추가 라이브러리	없음
로컬/비공개	예	예	아니요
최적 용도	경량 로컬 + 하이브리드	전체 torch 생태계	관리형 단순성

자료

• GitHub 저장소
• 문서
• Qdrant (하이브리드 검색)