~/tools / Tệp mô hình và mẫu chat / Safetensors Metadata Viewer
Safetensors Metadata Viewer — Mở tệp safetensors: kiểu dữ liệu, tham số, kích thước trọng số, KV cache
Mở các tệp safetensors của một mô hình Hugging Face ngay trong trình duyệt và xem bên trong có gì mà không cần tải trọng số: mọi tensor cùng kiểu dữ liệu và hình dạng, số tham số, kích thước trọng số và __metadata__. Với mô hình được chia thành nhiều tệp, hãy thêm model.safetensors.index.json để tìm tệp bị thiếu hoặc không đầy đủ, và thêm config.json để xem kiến trúc, độ dài ngữ cảnh và KV cache. Công cụ kiểm tra từng tệp theo cách của thư viện safetensors chính thức. Chỉ phần đầu của mỗi tệp được đọc và không có gì được tải lên.
Hoặc kéo thả tệp vào đây: các tệp .safetensors, model.safetensors.index.json và config.json. Chỉ phần đầu của mỗi tệp .safetensors được đọc và không có gì rời khỏi máy tính của bạn.
curl -L -r 0-1048575 -o model.safetensors https://huggingface.co/OWNER/REPO/resolve/main/model.safetensorsSố tham số cộng số phần tử của mọi tensor trong các tệp (tích các chiều hình dạng của nó), theo cùng cách Hugging Face Hub đếm số tham số mà nó hiển thị cho một mô hình. Kích thước trọng số là dữ liệu mà các tệp chứa, theo các kiểu dữ liệu của chính các tệp.
KV cache = 2 × số lớp × số KV head × kích thước head × 2 byte (f16) × độ dài ngữ cảnh. Các giá trị lấy từ config.json (num_hidden_layers, num_key_value_heads, head_dim, hoặc hidden_size ÷ num_attention_heads). Với các mô hình có phần văn bản nằm trong text_config, công cụ đọc từ đó.
Đã kiểm tra vào 2026-11-09 theo các nguồn sau và safetensors 0.8.0 chính thức: Định dạng safetensors · Hugging Face: đọc metadata · Ollama: nhập một mô hình
Mọi thứ chạy trong trình duyệt của bạn. Chỉ phần đầu của mỗi tệp .safetensors được đọc và không có gì được gửi đi đâu cả.
safetensors là định dạng tệp mà Hugging Face dùng cho trọng số của mô hình. Một tệp safetensors bắt đầu bằng 8 byte cho biết độ dài của phần đầu (header) JSON. Header liệt kê mọi tensor cùng kiểu dữ liệu (dtype), hình dạng (shape) và vị trí (data_offsets), và có thể chứa một bản đồ chuỗi __metadata__ như {"format": "pt"}. Trọng số nằm ngay sau đó. Công cụ này chỉ đọc header đó, theo định dạng được mô tả trong kho safetensors, nên một tệp vài gigabyte vẫn mở trong chớp mắt: trong Qwen2.5-7B-Instruct, mỗi header dài 7 đến 11 KiB, trong các tệp có dung lượng 3.3 đến 3.7 GiB. Công cụ đếm số tham số theo cách của Hugging Face Hub (tích các chiều hình dạng của mỗi tensor, cộng lại theo từng kiểu dữ liệu), cộng tổng kích thước trọng số, và kiểm tra những gì thư viện safetensors chính thức kiểm tra: độ dài header, JSON, các kiểu dữ liệu, việc các tensor lấp đầy dữ liệu mà không có khoảng trống hay chồng lấn, việc kích thước mỗi tensor khớp với kiểu và hình dạng của nó, và việc tệp kết thúc ngay sau tensor cuối cùng. Một mô hình chia thành nhiều tệp đi kèm model.safetensors.index.json, cho biết tệp nào chứa tensor nào. Hãy chọn các tệp cùng nhau, và công cụ sẽ liệt kê các tệp bị thiếu, các tensor không nằm ở nơi chỉ mục nói, và tổng kích thước có khớp hay không. Thêm config.json, công cụ sẽ hiển thị kiến trúc, độ dài ngữ cảnh, số lớp và attention head, cùng KV cache ở f16, mặc định của Ollama: 2 × số lớp × số KV head × kích thước head × 2 byte × độ dài ngữ cảnh. Chúng tôi đã kiểm tra công cụ với header của Qwen2.5-7B-Instruct (4 tệp) và Qwen2.5-0.5B-Instruct từ Hugging Face: số tham số khớp với con số Hub báo cáo (7,615,616,512 và 494,032,768), và kích thước tính từ mỗi header khớp với tệp đến từng byte. Chúng tôi cũng đã mở 52 tệp hợp lệ và bị hỏng bằng gói Python chính thức safetensors 0.8.0, và công cụ chấp nhận và từ chối đúng những tệp giống như vậy.
Phần xử lý chính của công cụ này là mã nguồn mở theo giấy phép MIT. github.com/seigo5555/toolkitbox-lib/src/safetensors.ts
Trường hợp dùng
- Kiểm tra các tệp safetensors của một mô hình Hugging Face trước khi chuyển đổi hoặc nhập: kiểu dữ liệu, số tham số và liệu mọi tệp có đầy đủ không
- Tìm tệp bị thiếu hoặc bị cắt cụt trong một mô hình chia thành nhiều tệp, bằng model.safetensors.index.json
- Xem bên trong một mô hình trên Hugging Face mà không cần tải trọng số, bằng cách chỉ lưu phần đầu của mỗi tệp
Cách dùng
- Chọn các tệp .safetensors (chọn nhiều tệp cùng lúc với mô hình chia nhỏ) và, nếu có, cả model.safetensors.index.json và config.json. Bạn cũng có thể thả chúng vào khung.
- Để xem một mô hình mà không tải về, hãy chỉ lưu phần đầu của mỗi tệp bằng lệnh curl được hiển thị (một yêu cầu Range, phương pháp trong tài liệu của Hugging Face) và đánh dấu "Chỉ phần đầu của tệp".
- Bạn cũng có thể dán index.json, config.json hoặc một header (JSON sau 8 byte đầu tiên) vào ô văn bản rồi thêm vào.
Hỏi đáp
Tệp có được tải lên không?
Không. Trình duyệt đọc các tệp trên máy tính của bạn, và công cụ chỉ đọc phần đầu của mỗi tệp .safetensors: 8 byte cho biết độ dài header và chính header. Trọng số không được đọc.
Vì sao số tham số khác với tên mô hình?
Công cụ đếm mọi tensor trong các tệp, giống như Hugging Face Hub. Những tên như 7B là số đã làm tròn. Một số mô hình còn dùng chung một tensor cho đầu vào và đầu ra: Qwen2.5-0.5B-Instruct có tie_word_embeddings trong config.json, và tệp của nó không có lm_head.weight.
"file not fully covered" nghĩa là gì?
Thư viện safetensors chính thức từ chối một tệp có kích thước không đúng bằng 8 byte + header + điểm kết thúc của tensor cuối cùng, với thông báo "incomplete metadata, file not fully covered". Nếu tệp ngắn hơn, một phần trọng số bị thiếu, chẳng hạn do quá trình tải về dừng sớm.
Vì sao một số vấn đề màu đỏ còn một số màu vàng?
Vấn đề màu đỏ là những vấn đề thư viện chính thức từ chối. Vấn đề màu vàng vi phạm đặc tả, nhưng thư viện chính thức vẫn đọc được tệp: một tên tensor xuất hiện hai lần (thư viện giữ cái cuối cùng), hoặc một header bắt đầu bằng khoảng trắng hay được đệm bằng ký tự khác ngoài dấu cách.
Làm thế nào để nhập safetensors vào Ollama?
Hướng dẫn nhập của Ollama trỏ FROM tới thư mục chứa trọng số safetensors, rồi chạy ollama create. Trong thử nghiệm của chúng tôi với Ollama 0.40.11 trên macOS, một thư mục không có config.json bị từ chối, và một mô hình Qwen2 (Qwen2ForCausalLM) cũng bị từ chối vì kiến trúc không được hỗ trợ. Nếu mô hình của bạn không nhập được, hãy chuyển nó sang GGUF trước, ví dụ bằng convert_hf_to_gguf.py của llama.cpp.
Kích thước KV cache chính xác đến đâu?
Trong thử nghiệm của chúng tôi, công thức khớp với log của Ollama (224 MiB cho qwen2.5:7b ở 4096 token), và config.json của Qwen2.5-7B-Instruct cho ra đúng 224 MiB đó. Con số này dành cho f16, mặc định của Ollama. Các mô hình có cửa sổ trượt, KV nén (kv_lora_rank) hoặc những lớp không phải full attention dùng lượng khác; công cụ sẽ cho biết điều đó khi config.json cho thấy.