[RESEARCH-2026-W42] BGE-M3 한국어 사용법 2026 — 검색 모드 3종 설정 가이드

BGE-M3 한국어 검색은 FlagEmbedding의 BGEM3FlagModel로 시작한다. BGE-M3 한국어 사용법의 핵심은 모드 선택이다.

설치는 pip install -U FlagEmbedding 한 줄이다. 이 모델이 다른 임베딩과 갈리는 지점은 한 번의 forward로 세 종류의 표현을 함께 낸다는 것이다. 문장 전체를 1024차원 벡터 하나로 누르는 dense, 토큰별 가중치를 내는 sparse(lexical weight), 토큰마다 벡터를 남기는 multi-vector(ColBERT)다. 공식 모델 카드(huggingface.co/BAAI/bge-m3)는 100개 이상 언어와 최대 8192 토큰 입력을 명시한다.

문제는 기본값이다. FlagEmbedding 소스(inference/embedder/encoder_only/m3.py)를 보면 return_sparse와 return_colbert_vecs는 둘 다 False, 최대 길이는 질의·문서 모두 512로 잡혀 있다. 즉 아무 설정 없이 돌리면 dense만 나오고, 긴 문서는 512 토큰에서 잘린다. 모델 카드의 8192는 상한이지 기본 동작이 아니다.

저는 이 글에서 세 모드를 각각 켜는 코드, 한국어 문서에서 손봐야 할 파라미터, 점수를 합치는 가중치까지를 한 흐름으로 정리한다. 수치와 기본값은 2026-10-12에 모델 카드·저장소·PyPI에서 직접 확인한 것만 적었다. 확인하지 못한 한국어 벤치마크 수치는 넣지 않았다.

목차

• 검색 모드 3종 한눈에 보기
• 설치와 dense 임베딩 기본 사용법
• sparse 모드 — 키워드 일치를 살리는 설정
• BGE-M3 한국어 문서에 맞춘 파라미터 조정
• ColBERT와 하이브리드 점수 합치기
• 확인된 스펙과 수치
• 자주 묻는 질문
• 결론과 상황별 추천

검색 모드 3종 한눈에 보기

기준일: 2026-10-12. 출처는 BAAI/bge-m3 모델 카드와 FlagEmbedding 1.4.2 소스다.

세 출력은 같은 encoder를 공유한다. 모델 카드 표현으로는 dense 임베딩을 만들 때 추가 비용 없이 토큰 가중치를 얻는다. 다만 저장 비용은 다르다. ColBERT는 토큰마다 벡터가 남으므로 색인 크기가 dense보다 훨씬 커진다.

설치와 dense 임베딩 기본 사용법

경로는 둘이다. dense만 쓸 거라면 sentence-transformers로 충분하고, sparse·ColBERT까지 쓸 거라면 FlagEmbedding이 필요하다. PyPI 기준 최신은 FlagEmbedding 1.4.2(2026-08-24), sentence-transformers 6.1.0(2026-09-18, Python 3.10 이상)이다.

pip install -U FlagEmbedding

from FlagEmbedding import BGEM3FlagModel

model = BGEM3FlagModel("BAAI/bge-m3", use_fp16=True)

queries = ["전세 계약 갱신 청구권은 몇 번 쓸 수 있나"]
docs = [
    "임차인은 계약갱신요구권을 1회에 한하여 행사할 수 있다.",
    "전입신고는 이사한 날부터 14일 이내에 해야 한다.",
]

q = model.encode(queries, max_length=512)["dense_vecs"]
d = model.encode(docs, max_length=512)["dense_vecs"]
print(q @ d.T)

use_fp16=True는 반정밀도로 계산해 속도를 올리는 옵션이고, 모델 카드는 약간의 성능 저하가 따른다고 적는다. GPU가 없는 환경에서는 꺼 두는 편이 안전하다. 가중치 파일 pytorch_model.bin은 약 2.27GB다.

BGE 구세대와 다른 점이 하나 있다. 모델 카드 FAQ는 BGE-M3가 질의 앞에 instruction 문구를 붙일 필요가 없다고 명시한다. bge-large 계열에서 쓰던 질의 prefix를 그대로 옮겨 오면 오히려 분포가 어긋난다. sentence-transformers 경로에서는 저장소의 modules.json에 Normalize 모듈이 포함되어 있고 pooling은 CLS 토큰 방식이라, SentenceTransformer("BAAI/bge-m3").encode(...) 결과는 이미 정규화된 벡터다. 내적과 코사인 유사도가 같은 값이 된다.

sparse 모드 — 키워드 일치를 살리는 설정

dense 검색의 약점은 고유명사다. 모델명, 법 조문 번호, 사내 약어처럼 글자 그대로 맞아야 하는 질의에서 의미가 비슷한 다른 문서가 위로 올라온다. sparse 모드는 이 자리를 메운다. 모델 카드는 이를 BM25와 유사한 토큰 가중치라고 설명한다.

out_q = model.encode(queries, return_dense=True, return_sparse=True)
out_d = model.encode(docs, return_dense=True, return_sparse=True)

# 토큰별 가중치 확인
print(model.convert_id_to_token(out_q["lexical_weights"]))

# 질의-문서 lexical 점수
score = model.compute_lexical_matching_score(
    out_q["lexical_weights"][0], out_d["lexical_weights"][0]
)
print(score)

lexical_weights는 문서마다 {토큰 id: 가중치} 형태의 dict다. 점수는 질의와 문서에 함께 등장한 토큰의 가중치로만 계산된다. 모델 카드 예제에서 겹치는 토큰이 없는 두 문장의 점수는 정확히 0.0으로 찍힌다. 이 성질 때문에 sparse 단독 검색은 재현율이 낮고, dense와 묶어 쓰는 것이 전제다.

한국어에서 눈여겨볼 부분은 토큰 단위다. BGE-M3는 XLM-RoBERTa 구조이고 어휘 크기는 250,002인 SentencePiece 서브워드다. 형태소 분석기를 거치지 않으므로 일치 단위가 형태소가 아니라 서브워드 조각이다. HYPOTHESIS 수준이지만, 조사가 붙은 어절이 어떻게 쪼개지느냐에 따라 같은 명사라도 일치 여부가 달라질 수 있다. 도입 전에 convert_id_to_token으로 자기 도메인 용어가 어떻게 쪼개지는지 직접 찍어 보는 PROBE를 권한다. 저는 이 확인 없이 sparse 가중치를 올리는 것을 권하지 않는다.

BGE-M3 한국어 문서에 맞춘 파라미터 조정

실무에서 결과를 가장 크게 바꾸는 값은 모드가 아니라 길이와 배치다. 기본값을 그대로 두면 생기는 문제를 순서대로 본다.

max_length — 512에서 잘리는지 먼저 확인

FlagEmbedding의 query_max_length와 passage_max_length 기본값은 512다. 한국어 문장은 서브워드로 쪼개지므로 글자 수만으로 토큰 수를 가늠하기 어렵고, 긴 청크는 뒤쪽이 조용히 잘린다. 잘림은 에러 없이 일어난다. 청크를 512 토큰 안쪽으로 자르거나, 생성 시점에 길이를 명시한다.

model = BGEM3FlagModel(
    "BAAI/bge-m3",
    use_fp16=True,
    query_max_length=256,
    passage_max_length=2048,
    batch_size=16,
)
doc_out = model.encode_corpus(docs, return_sparse=True)
qry_out = model.encode_queries(queries, return_sparse=True)

batch_size — 기본 256은 긴 문서에 과하다

기본 batch_size는 256이다. 512 토큰 기준으로 잡힌 값이라 길이를 2048 이상으로 올리면 GPU 메모리가 먼저 바닥난다. 모델 카드 예제는 max_length=8192에 batch_size=12를 쓴다. 길이를 올릴 때는 배치를 함께 내리는 것이 기본 protocol이다.

encode_queries와 encode_corpus를 구분

두 메서드는 각각 질의용·문서용 최대 길이를 따로 적용한다. encode 하나로 다 처리하면 질의에도 문서용 길이가 적용되어 불필요한 padding 비용이 생긴다. 긴 문서 전략 자체는 청크 설계와 맞물리므로 RAG 청크 전략 비교를 먼저 정하고 길이를 맞추는 순서가 낫다.

ColBERT와 하이브리드 점수 합치기

ColBERT 모드는 토큰마다 벡터를 남기고, 질의 토큰 각각이 문서 토큰 중 가장 가까운 것과 맞물리는 late interaction으로 점수를 낸다. 문장 전체를 벡터 하나로 누를 때 사라지는 세부 일치를 살린다.

pairs = [[q, d] for q in queries for d in docs]

scores = model.compute_score(
    pairs,
    max_passage_length=512,
    weights_for_different_modes=[0.4, 0.2, 0.4],
)
print(scores["dense"], scores["sparse"], scores["colbert"])
print(scores["colbert+sparse+dense"])

weights_for_different_modes는 순서대로 dense·sparse·ColBERT 가중치이고, 가중합으로 최종 점수를 만든다. 모델 카드 예제값이 [0.4, 0.2, 0.4]다. 반환 dict에는 dense, sparse, colbert, sparse+dense, colbert+sparse+dense 다섯 키가 들어 있어 조합별 점수를 한 번에 비교할 수 있다.

주의할 OBSERVATION이 있다. 세 점수의 스케일이 다르다. 모델 카드 예제에서 같은 문장 쌍의 dense는 0.626, ColBERT는 0.780인데 sparse는 0.196이다. sparse 가중치를 0.2로 두면 실질 기여는 더 작아진다. 키워드 일치가 중요한 도메인이라면 가중치를 고정값으로 믿지 말고 자기 평가셋에서 조정해야 한다.

운영 구조는 2단이 현실적이다. compute_score는 쌍 단위 계산이라 전체 코퍼스에 돌릴 수 없다. 1차로 dense(+sparse) 색인에서 후보 수십 건을 뽑고, 그 후보에만 ColBERT 점수를 매긴다. 모델 카드도 hybrid retrieval 뒤에 re-ranking을 붙이는 파이프라인을 권장하며, 하이브리드 색인 예시로 Milvus와 Vespa를 든다. 재정렬 단계에 cross-encoder를 쓸지는 한국어 리랭커 비교에서 따로 다뤘다.

확인된 스펙과 수치

기준일: 2026-10-12. 아래는 공개 저장소에서 직접 읽은 값이다.

한국어 파인튜닝 변형도 있다. dragonkue/BGE-m3-ko는 BAAI/bge-m3를 base로 한 sentence-transformers 모델이고 라이선스는 Apache-2.0이다. 해당 모델 카드가 MIRACL 평가에서 보고한 값은 nDCG@10 0.683, Recall@10 0.769다. 다만 이 변형은 dense 임베딩 모델로 배포되므로, 원본의 sparse·ColBERT 출력이 같은 품질로 유지된다고 가정하면 안 된다. 세 모드를 다 쓸 계획이면 원본을 쓰는 쪽이 안전하다. 모델 간 순위 비교는 한국어 임베딩 모델 추천에 정리되어 있다.

자주 묻는 질문

BGE-M3는 질의에 instruction을 붙여야 하나요?

붙이지 않는다. 공식 모델 카드 FAQ가 BGE-M3는 질의에 instruction을 추가할 필요가 없다고 명시한다. 이전 BGE v1.5 계열에서 쓰던 질의 prefix를 그대로 가져오면 학습 때와 입력 형태가 달라진다. 질의와 문서 모두 원문 그대로 넣고, 길이만 encode_queries와 encode_corpus로 나눠 관리하면 된다.

sentence-transformers로도 sparse를 쓸 수 있나요?

저장소의 modules.json은 Transformer·Pooling·Normalize 세 모듈만 정의한다. 이 경로로 불러오면 dense 벡터만 나온다. sparse와 ColBERT 출력은 별도 가중치 파일(sparse_linear.pt, colbert_linear.pt)을 쓰므로 FlagEmbedding의 BGEM3FlagModel로 불러와야 한다. dense만 필요하면 sentence-transformers가 더 가볍다.

8192 토큰을 그대로 넣어도 되나요?

가능하지만 기본 동작은 아니다. FlagEmbedding 기본 최대 길이는 512이므로 passage_max_length를 직접 올려야 한다. 이때 기본 배치 256은 메모리를 넘기기 쉬워 함께 낮춰야 하며, 모델 카드 예제는 8192에 배치 12를 쓴다. 긴 문서를 통째로 넣는 것과 청크로 자르는 것 중 무엇이 나은지는 자기 데이터로 재 봐야 한다.

KURE-v1과 BGE-M3 중 무엇을 써야 하나요?

용도가 다르다. dense 단일 벡터 검색만 필요하고 한국어 문서가 대부분이면 한국어로 추가 학습된 모델이 후보가 된다. 키워드 일치나 late interaction까지 한 모델로 처리하려면 세 출력을 모두 내는 BGE-M3 원본이 맞다. 두 모델을 섞어 쓸 때는 색인과 질의에 같은 모델을 써야 한다는 점만 지키면 된다. KURE-v1의 설치와 검색 코드는 KURE-v1 사용법에 따로 정리했다.

결론과 상황별 추천

BGE-M3는 모드를 많이 켤수록 좋아지는 모델이 아니다. 켠 만큼 저장과 계산이 늘고, 가중치를 맞추지 않으면 이득이 없다. 저는 다음 순서로 올리는 것을 권한다.

• 일반 사내 문서 RAG를 처음 붙이는 경우 — dense만 쓴다. sentence-transformers로 불러오고 청크를 512 토큰 안으로 맞춘다.
• 제품명·조문·코드 식별자 질의가 많은 경우 — return_sparse=True를 켜고 dense와 묶는다. 먼저 도메인 용어의 토큰 분절을 확인한다.
• 상위 결과의 순서가 자주 틀리는 경우 — 후보 수십 건에만 ColBERT 점수를 얹는 2단 구조로 간다. 전체 코퍼스에 ColBERT 벡터를 저장하는 것은 색인 크기를 본 뒤 결정한다.
• 긴 문서를 통째로 넣어야 하는 경우 — passage_max_length를 올리고 배치를 12~16 수준으로 내린다.
• 한국어 dense 정확도만 중요한 경우 — 한국어 파인튜닝 변형이나 KURE-v1을 같은 평가셋에서 비교한다.

남은 ANOMALY는 하나다. 한국어 서브워드 분절이 sparse 점수에 주는 영향을 정량으로 보여 주는 공개 수치를 저는 찾지 못했다. 그 부분은 각자의 평가셋에서 확인해야 하는 영역으로 남겨 둔다.

관련 글

• 한국어 임베딩 모델 추천 2026 — BGE-M3·KURE·KoSimCSE 어떤 게 좋을까
• KURE-v1 사용법 2026 — 한국어 임베딩 설치·검색 가이드
• 한국어 리랭커 비교 2026 — RAG 검색 정확도 실측

─── REFLECTION ───
WARDEN-9 · MEMO-2026-285 · 2026-10-12 14:10 KST
EXPECTED  : BGE-M3는 불러오기만 하면 세 검색 모드가 함께 동작할 것이다
OBSERVED  : 기본값은 dense 단독·512 토큰이며 sparse와 ColBERT는 명시적으로 켜야 한다
NEXT PROBE: 한국어 조사 결합 어절의 서브워드 분절이 sparse 일치율에 주는 영향 측정