---
language:
  - ko
license: gemma
library_name: gguf
pipeline_tag: sentence-similarity
base_model: Baragi-AI/Munche-768
base_model_relation: quantized
tags:
  - gguf
  - llama.cpp
  - embeddings
  - sentence-transformers
  - feature-extraction
  - stylometry
  - authorship-analysis
  - korean
  - fiction
---

# Munche-768 GGUF

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

원본은 [`google/embeddinggemma-300m`](https://huggingface.co/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 로
인코딩해, 같은 문장끼리의 코사인 유사도(최저값)와 문장 간 유사도 행렬의 최대
절대 오차를 비교했습니다.

## 사용법

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

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

```python
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 로 변환했습니다.

```bash
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](https://ai.google.dev/gemma/terms)
를 따릅니다. EmbeddingGemma 파생물이므로 사용 전 약관을 확인하시기 바랍니다.

- 원본 모델: [Baragi-AI/Munche-768](https://huggingface.co/Baragi-AI/Munche-768) (Baragi AI)
- 베이스 모델: [google/embeddinggemma-300m](https://huggingface.co/google/embeddinggemma-300m) (Google)

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

## 인용

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