~/tools / 모델 파일과 채팅 템플릿 / GGUF Metadata Viewer
GGUF Metadata Viewer — GGUF 파일 열기: 양자화, 컨텍스트, 토크나이저, 텐서, KV 캐시
GGUF 모델 파일을 브라우저에서 열어, 모델을 불러오지 않고 내용을 확인합니다. 아키텍처, 양자화, 파라미터 수, 최대 컨텍스트, 레이어와 어텐션 헤드, 토크나이저와 특수 토큰, 채팅 템플릿, 모든 메타데이터 항목과 모든 텐서를 볼 수 있습니다. 컨텍스트 길이별 KV 캐시도 계산하고 llama.cpp와 같은 방식으로 파일을 검사하므로, Ollama로 가져오기 전에 다운로드가 덜 끝난 파일을 알아챌 수 있습니다. 파일의 앞부분만 읽으며, 아무것도 업로드되지 않습니다.
또는 여기에 파일을 끌어다 놓으세요. 파일의 앞부분만 읽으며, 파일은 사용자의 컴퓨터를 벗어나지 않습니다. 우리 테스트에서 Ollama가 models/blobs 폴더에 보관하는 가중치 파일도 GGUF 파일이었습니다.
KV 캐시 = 2 × 레이어 수 × KV 헤드 수 × 헤드 크기 × 2바이트 (f16) × 컨텍스트 길이. qwen2.5:7b는 4096 토큰에서 224 MiB가 되며, 이는 우리 테스트에서 Ollama의 로그에 나온 크기입니다.
가중치는 파일에 저장된 텐서 데이터이며, 헤더와 합쳐 파일이 됩니다. 모델을 실행하려면 KV 캐시와 작업 메모리도 필요하며, 메모리 추정기가 이를 더해 줍니다.
2026-11-08에 GGUF 사양과 llama.cpp의 리더에 대조하고, qwen2.5:7b의 실제 파일로 확인했습니다. 메타데이터와 339개의 텐서는 Ollama 0.40.11이 알려 주는 값과 일치했습니다. GGUF 사양 · Ollama: 모델 가져오기
파일은 브라우저에서 읽으며 업로드되지 않습니다. 파일의 앞부분만 읽습니다.
GGUF는 llama.cpp와 Ollama가 모델에 쓰는 파일 형식입니다. GGUF 파일은 헤더로 시작하며, 헤더에는 형식 버전, 메타데이터 항목 목록(general.architecture, <architecture>.context_length, tokenizer.ggml.tokens, tokenizer.chat_template 등), 텐서의 이름·모양·유형·위치 목록이 들어 있습니다. 가중치는 그 뒤에 이어집니다. 이 도구는 ggml 저장소의 GGUF 사양에 있는 구조에 따라 이 헤더만 읽으므로, 수 GB짜리 파일도 순식간에 열립니다. qwen2.5:7b의 경우 4.36 GiB 파일 중 헤더는 5.7 MiB입니다. 헤더로부터 모델의 이름, 아키텍처, 양자화(general.file_type)를 보여 주고, 텐서의 모양으로 파라미터 수를 세며, llama.cpp의 gguf-py에 있는 블록 크기를 사용해 텐서 유형별 가중치 크기를 합산합니다. 모델의 구조(레이어, 어텐션 헤드, KV 헤드, 헤드 크기, RoPE 설정, 전문가), 문장 시작과 끝 토큰을 포함한 토크나이저, 채팅 템플릿도 보여 줍니다. 레이어, KV 헤드, 헤드 크기로 Ollama의 기본값인 f16의 KV 캐시를 계산합니다. 2 (키와 값) × 레이어 수 × KV 헤드 수 × 헤드 크기 × 2바이트 × 컨텍스트 길이 입니다. 또한 llama.cpp 자체 리더(gguf.cpp)가 검사하는 항목, 즉 형식 버전, 바이트 순서, 중복된 키와 텐서 이름, 정렬, 텐서 유형, 각 텐서의 위치를 검사하고, 헤더가 설명하는 크기를 파일 크기와 비교합니다. 우리는 Ollama 0.40.11이 저장한 qwen2.5:7b의 실제 파일로 도구를 확인했습니다. 메타데이터, 339개의 텐서(이름, 유형, 모양), 파라미터 수는 Ollama의 /api/show가 알려 주는 값과 일치했고, 헤더로 계산한 크기도 파일과 바이트 단위까지 일치했습니다.
이 도구의 핵심 로직은 MIT 라이선스의 오픈 소스로 공개되어 있습니다. github.com/seigo5555/toolkitbox-lib/src/gguf.ts
이럴 때 사용
- Hugging Face에서 받은 GGUF를 Ollama로 가져오기 전에 양자화, 컨텍스트 길이, 채팅 템플릿, 다운로드가 완료되었는지 확인하기
- 모델의 가중치와 KV 캐시에 필요한 메모리를 파일 자체로부터 알아보기
- Ollama가 이미 가지고 있는 모델의 메타데이터와 텐서를, Ollama의 models/blobs 폴더에 있는 파일을 열어 살펴보기
사용법
- .gguf 파일을 선택하거나 상자에 끌어다 놓습니다. Ollama에 있는 모델을 보려면 ollama show --modelfile <model>을 실행하면 FROM 뒤에 파일 경로가 출력됩니다.
- 도구가 파일의 앞부분을 읽고 모델, 모델의 구조, KV 캐시, 유형별 가중치, 토크나이저를 보여 줍니다.
- "모든 메타데이터" 또는 "모든 텐서"를 열면 전체 목록이 나옵니다. 아직 Ollama에 없는 파일에는 가져오기용 Modelfile 줄이 표시됩니다.
FAQ
파일이 업로드되나요?
아니요. 브라우저가 사용자의 컴퓨터에서 파일을 읽고, 도구는 그 앞부분인 메타데이터와 텐서 목록이 있는 헤더만 읽습니다. 가중치는 읽지 않습니다.
파일이 헤더가 말하는 크기보다 작다고 나오는 이유는 무엇인가요?
헤더에는 모든 텐서의 크기와 위치가 적혀 있으므로 파일이 얼마나 커야 하는지 알 수 있습니다. 파일이 그보다 작다면 다운로드나 복사가 중간에 멈추는 등의 이유로 가중치의 일부가 빠진 것입니다. llama.cpp는 이런 파일에 대해 "model is corrupted or incomplete"라고 출력하고 멈춥니다.
general.file_type과 텐서 유형은 무엇이 다른가요?
general.file_type은 파일의 주된 양자화를 나타냅니다(Q4_K_M 등). 파일에는 여러 유형이 섞여 있습니다. qwen2.5:7b Q4_K_M에서는 대부분의 텐서가 Q4_K이고, 일부는 Q6_K, 정규화 가중치 같은 작은 텐서는 F32입니다. 유형별 가중치 표에서 이 구성을 볼 수 있습니다.
Ollama가 이미 내려받은 모델 파일을 열 수 있나요?
예. Ollama는 모델의 가중치를 models/blobs 폴더에 sha256-… 라는 이름의 파일로 보관합니다. 우리 테스트에서 ollama show --modelfile qwen2.5:7b는 FROM 뒤에 그 파일의 경로를 출력했고, 그것은 GGUF 파일이었습니다.
GGUF를 Ollama로 가져오려면 어떻게 하나요?
Ollama의 가져오기 가이드는 FROM /path/to/file.gguf가 들어 있는 Modelfile을 만든 다음 ollama create를 실행합니다. 여러 파일로 나뉜 모델은 원래 파일 이름을 그대로 두고 모든 조각에 맞는 와일드카드를 사용합니다. Ollama는 가져오는 동안 GGUF 모델을 양자화하지 않습니다.
KV 캐시 크기는 얼마나 정확한가요?
우리 테스트에서 이 식은 Ollama의 로그와 일치했습니다(qwen2.5:7b, 4096 토큰에서 224 MiB). Ollama의 기본값인 f16 기준입니다. 슬라이딩 윈도, 공유되거나 압축된 KV 캐시, 순환 레이어가 있는 모델은 사용량이 다릅니다. 메타데이터에서 그것이 드러나면 도구가 알려 줍니다.