~/tools / 모델 파일과 채팅 템플릿 / Safetensors Metadata Viewer

Safetensors Metadata Viewer — safetensors 열기: 데이터 유형, 파라미터, 가중치 크기, KV 캐시

Hugging Face 모델의 safetensors 파일을 브라우저에서 열어, 가중치를 불러오지 않고도 안에 무엇이 있는지 확인할 수 있습니다. 모든 텐서의 데이터 유형과 모양, 파라미터 수, 가중치 크기, __metadata__를 볼 수 있습니다. 여러 파일로 나뉜 모델은 model.safetensors.index.json을 추가하면 빠진 파일이나 불완전한 파일을 찾을 수 있고, config.json을 추가하면 아키텍처, 최대 컨텍스트, KV 캐시를 볼 수 있습니다. 이 도구는 공식 safetensors 라이브러리와 같은 방식으로 각 파일을 검사합니다. 각 파일의 앞부분만 읽으며, 아무것도 업로드되지 않습니다.

파일 선택

또는 여기에 파일을 끌어다 놓으세요: .safetensors 파일, model.safetensors.index.json, config.json. 각 .safetensors 파일의 앞부분만 읽으며, 아무것도 사용자의 컴퓨터를 벗어나지 않습니다.

파일의 앞부분만(Range 요청으로 저장한 것)이 경우 도구는 파일 크기를 헤더와 비교하지 않습니다. Hugging Face에 있는 파일의 앞부분을 저장하려면 다음과 같이 하세요(1 MiB면 대부분의 헤더가 들어갑니다):curl -L -r 0-1048575 -o model.safetensors https://huggingface.co/OWNER/REPO/resolve/main/model.safetensors

또는 index.json, config.json 또는 헤더(JSON) 붙여 넣기

파라미터 수는 파일에 있는 모든 텐서의 요소 수(모양의 곱)를 더한 값으로, Hugging Face Hub가 모델에 표시하는 파라미터 수와 같은 방식으로 셉니다. 가중치 크기는 파일이 담고 있는 데이터를 파일의 데이터 유형 그대로 센 것입니다.

KV 캐시 = 2 × 레이어 수 × KV 헤드 수 × 헤드 크기 × 2바이트(f16) × 컨텍스트 길이. 값은 config.json(num_hidden_layers, num_key_value_heads, head_dim 또는 hidden_size ÷ num_attention_heads)에서 가져옵니다. 텍스트 부분이 text_config에 있는 모델은 도구가 그곳에서 읽습니다.

2026-11-09에 다음 자료와 공식 safetensors 0.8.0에 대조해 확인했습니다: safetensors 형식 · Hugging Face: 메타데이터 읽기 · Ollama: 모델 가져오기

모든 작업은 브라우저에서 이루어집니다. 각 .safetensors 파일의 앞부분만 읽으며, 아무것도 어디로도 전송되지 않습니다.

safetensors는 Hugging Face가 모델 가중치에 사용하는 파일 형식입니다. safetensors 파일은 JSON 헤더의 길이를 알려 주는 8바이트로 시작합니다. 헤더에는 모든 텐서의 데이터 유형(dtype), 모양(shape), 위치(data_offsets)가 나열되며, {"format": "pt"} 같은 문자열 맵인 __metadata__를 담을 수도 있습니다. 가중치는 그 뒤에 이어집니다. 이 도구는 safetensors 저장소에 설명된 형식에 따라 이 헤더만 읽으므로, 수 GB 크기의 파일도 순식간에 열립니다. Qwen2.5-7B-Instruct에서는 3.3~3.7 GiB 크기의 파일마다 헤더가 7~11 KiB입니다. 파라미터는 Hugging Face Hub와 같은 방식으로 셉니다(각 텐서 모양의 곱을 데이터 유형별로 더합니다). 가중치 크기를 합산하고, 공식 safetensors 라이브러리가 검사하는 항목도 확인합니다. 헤더 길이, JSON, 데이터 유형, 텐서가 틈이나 겹침 없이 데이터를 채우는지, 각 텐서의 크기가 유형과 모양에 맞는지, 파일이 마지막 텐서 바로 뒤에서 끝나는지입니다. 여러 파일로 나뉜 모델에는 어느 파일에 어떤 텐서가 있는지 알려 주는 model.safetensors.index.json이 함께 있습니다. 파일을 함께 선택하면 빠진 파일, 인덱스가 알려 준 위치에 없는 텐서, 전체 크기가 일치하는지를 나열합니다. config.json을 추가하면 아키텍처, 최대 컨텍스트, 레이어와 어텐션 헤드, Ollama의 기본값인 f16 기준 KV 캐시(2 × 레이어 수 × KV 헤드 수 × 헤드 크기 × 2바이트 × 컨텍스트 길이)를 보여 줍니다. 이 도구는 Hugging Face의 Qwen2.5-7B-Instruct(파일 4개)와 Qwen2.5-0.5B-Instruct의 헤더로 확인했습니다. 파라미터 수는 Hub가 알려 주는 값과 일치했고(7,615,616,512와 494,032,768), 각 헤더로 계산한 크기는 파일과 바이트 단위로 일치했습니다. 또한 올바른 파일과 손상된 파일 52개를 공식 Python 패키지 safetensors 0.8.0으로 열어 보았고, 이 도구는 같은 파일을 받아들이고 같은 파일을 거부합니다.

이 도구의 핵심 로직은 MIT 라이선스의 오픈 소스로 공개되어 있습니다. github.com/seigo5555/toolkitbox-lib/src/safetensors.ts

이럴 때 사용

변환하거나 가져오기 전에 Hugging Face 모델의 safetensors 파일 확인하기: 데이터 유형, 파라미터 수, 모든 파일이 온전한지 여부
여러 파일로 나뉜 모델에서 빠졌거나 중간에 끊긴 파일을 model.safetensors.index.json으로 찾기
각 파일의 앞부분만 저장해, 가중치를 내려받지 않고 Hugging Face에 있는 모델의 내부 살펴보기

사용법

.safetensors 파일(나뉜 모델은 여러 개)을 선택하고, 있다면 model.safetensors.index.json과 config.json도 선택하세요. 상자에 끌어다 놓아도 됩니다.
모델을 내려받지 않고 살펴보려면, 표시되는 curl 명령(Hugging Face 문서에 나온 방법인 Range 요청)으로 각 파일의 앞부분만 저장하고 "파일의 앞부분만"을 선택하세요.
index.json, config.json 또는 헤더(처음 8바이트 뒤의 JSON)를 텍스트 상자에 붙여 넣어 추가할 수도 있습니다.

FAQ

파일이 업로드되나요?

아니요. 브라우저가 사용자의 컴퓨터에 있는 파일을 읽으며, 도구가 읽는 것은 각 .safetensors 파일의 앞부분, 즉 헤더 길이를 알려 주는 8바이트와 헤더뿐입니다. 가중치는 읽지 않습니다.

파라미터 수가 모델 이름과 다른 이유는 무엇인가요?

도구는 Hugging Face Hub와 마찬가지로 파일에 있는 모든 텐서를 셉니다. 7B 같은 이름은 반올림한 값입니다. 또한 일부 모델은 입력과 출력이 하나의 텐서를 공유합니다. Qwen2.5-0.5B-Instruct는 config.json에 tie_word_embeddings가 있고, 파일에는 lm_head.weight가 없습니다.

"file not fully covered"는 무슨 뜻인가요?

공식 safetensors 라이브러리는 파일 크기가 8바이트 + 헤더 + 마지막 텐서의 끝과 정확히 같지 않으면 "incomplete metadata, file not fully covered"라며 거부합니다. 파일이 더 짧다면, 예를 들어 다운로드가 중간에 멈춰서 가중치의 일부가 빠진 것입니다.

문제가 빨간색인 경우와 노란색인 경우는 왜 다른가요?

빨간색 문제는 공식 라이브러리가 거부하는 문제입니다. 노란색 문제는 사양에는 어긋나지만 공식 라이브러리가 파일을 읽을 수 있는 문제입니다. 같은 텐서 이름이 두 번 나오는 경우(라이브러리는 마지막 것을 사용합니다), 또는 헤더가 공백으로 시작하거나 공백 이외의 문자로 채워진 경우입니다.

safetensors를 Ollama로 가져오려면 어떻게 하나요?

Ollama의 가져오기 가이드는 FROM이 safetensors 가중치가 들어 있는 폴더를 가리키게 한 다음 ollama create를 실행하도록 안내합니다. macOS의 Ollama 0.40.11에서 한 우리 테스트에서는 config.json이 없는 폴더는 거부되었고, Qwen2 모델(Qwen2ForCausalLM)도 지원되지 않는 아키텍처로 거부되었습니다. 모델을 가져올 수 없다면 먼저 GGUF로 변환하세요. 예를 들어 llama.cpp의 convert_hf_to_gguf.py를 사용합니다.

KV 캐시 크기는 얼마나 정확한가요?

우리 테스트에서 이 공식은 Ollama의 로그와 일치했고(qwen2.5:7b, 4096 토큰에서 224 MiB), Qwen2.5-7B-Instruct의 config.json으로 계산해도 같은 224 MiB가 나옵니다. Ollama의 기본값인 f16 기준입니다. 슬라이딩 윈도, 압축된 KV(kv_lora_rank), 또는 풀 어텐션이 아닌 레이어가 있는 모델은 필요한 양이 다릅니다. config.json에서 그런 점이 확인되면 도구가 알려 줍니다.