senior5207/munche-768-GGUF

Munche-768 GGUF

Baragi-AI/Munche-768 을 llama.cpp 에서 쓸 수 있도록 GGUF 로 변환한 것입니다. 한국어 소설의 문체 유사도를 나타내는 768차원 임베딩 모델입니다.

원본은 google/embeddinggemma-300m 에 대한 LoRA 어댑터이므로, 베이스에 병합한 뒤 변환했습니다. SentenceTransformer 파이프라인의 Dense 프로젝션(768→3072→768)과 mean pooling 도 GGUF 에 포함되어 있어, 별도 후처리 없이 원본과 같은 임베딩이 나옵니다.

파일

파일	크기	최저 코사인 일치도	유사도 최대 오차
munche-768-f32.gguf	1.18 GB	1.000000	0.000054
munche-768-f16.gguf	593 MB	0.999999	0.000121
munche-768-q8_0.gguf	318 MB	0.999437	0.002015
munche-768-q4_k_m.gguf	228 MB	0.990537	0.010029

F16 을 권장합니다. 원본 가중치는 F32 이지만 F16 과의 차이가 측정 노이즈 수준이고, 용량은 절반입니다. F32 는 참조용으로 함께 올려둡니다.

용량이 중요하면 Q8_0 이 무난합니다. Q4_K_M 은 문장 간 유사도가 최대 0.01 까지 흔들리므로, 미세한 문체 차이를 다루는 이 모델의 용도에서는 순위가 뒤집힐 수 있습니다.

측정 방법: 문체가 다른 한국어 문장 5개를 원본 PyTorch 모델과 각 GGUF 로 인코딩해, 같은 문장끼리의 코사인 유사도(최저값)와 문장 간 유사도 행렬의 최대 절대 오차를 비교했습니다.

사용법

llama-server -m munche-768-f16.gguf --embeddings --pooling mean -c 2048 -ub 2048 -b 2048

-ub 와 -b 를 2048 로 지정해야 합니다. 생략하면 llama.cpp 가 배치 크기를 512 로 낮춰서 긴 입력이 잘립니다.

import numpy as np
import requests

texts = [
    "그는 창밖을 오래 바라보았다. 빗소리가 방 안을 가득 채웠다.",
    "야, 그거 진짜야? 말도 안 돼. 나 어제 걔 봤는데 아무 말도 없었거든.",
]

response = requests.post(
    "http://127.0.0.1:8080/v1/embeddings",
    json={"input": texts, "model": "munche-768"},
)
rows = sorted(response.json()["data"], key=lambda r: r["index"])
embeddings = np.array([r["embedding"] for r in rows])

print(embeddings.shape)          # (2, 768)
print(embeddings @ embeddings.T) # 코사인 유사도

--pooling mean 으로 띄우면 llama.cpp 가 L2 정규화까지 마친 벡터를 반환하므로, 코사인 유사도는 내적만으로 계산할 수 있습니다. 다른 pooling 옵션을 쓰거나 값을 직접 다룰 때는 norm 을 확인하세요.

주의사항

프롬프트 프리픽스는 포함되지 않습니다. EmbeddingGemma 계열은 task: search result | query: 같은 프리픽스를 붙여 쓰도록 설계되어 있는데, 이 규칙은 GGUF 에 들어가지 않습니다. 원본 SentenceTransformer 의 encode_query() / encode_document() 와 동일한 결과가 필요하다면 호출하는 쪽에서 프리픽스를 직접 붙여야 합니다. 위 표의 일치도는 양쪽 모두 프리픽스 없이 측정한 값입니다.

최대 입력 길이는 2,048 토큰입니다.

변환 방법

google/embeddinggemma-300m 에 LoRA 어댑터를 병합한 뒤 llama.cpp 로 변환했습니다.

python convert_hf_to_gguf.py munche-768-merged \
    --outfile munche-768-f32.gguf \
    --outtype f32 \
    --sentence-transformers-dense-modules

llama-quantize munche-768-f32.gguf munche-768-q8_0.gguf Q8_0

--sentence-transformers-dense-modules 가 없으면 Dense 레이어가 빠져서, 차원은 768 로 같지만 원본과 다른 임베딩이 나옵니다.

변환 시 알아둘 점이 두 가지 있습니다.

• SentenceTransformer.save() 는 tokenizer.model 을 저장하지 않습니다. 이 파일이 없으면 변환기가 sentencepiece 대신 BPE 경로를 타고, embeddinggemma 의 pre-tokenizer 해시가 등록되어 있지 않아 실패합니다. 베이스 리포에서 함께 복사해야 합니다.
• 원본 어댑터는 텐서 키에 base_model.model. 접두사와 .default 가 빠져 있어, PeftModel.from_pretrained() 로 로드하면 LoRA 가 적용되지 않은 채 경고만 출력됩니다. 키를 교정해 병합했습니다.

라이선스

원본 Munche-768 과 동일하게 Gemma Terms of Use 를 따릅니다. EmbeddingGemma 파생물이므로 사용 전 약관을 확인하시기 바랍니다.

• 원본 모델: Baragi-AI/Munche-768 (Baragi AI)
• 베이스 모델: google/embeddinggemma-300m (Google)

이 리포는 형식 변환만 수행했으며, 모델 가중치와 성능은 원본을 따릅니다. 학습 데이터, 평가 결과, 한계점은 원본 모델 카드를 참고하세요.

인용

@software{munche768,
  title = {Munche-768: Korean Fiction Style Embedding Model},
  author = {Baragi AI},
  year = {2026},
  url = {https://huggingface.co/Baragi-AI/Munche-768}
}