# GGUF

Hugging Face Hub tüm dosya biçimlerini destekler ancak modellerin hızlı yüklenmesi ve kaydedilmesi için optimize edilmiş bir ikili biçim olan [GGUF formatı](https://github.com/ggerganov/ggml/blob/master/docs/gguf.md) için yerleşik özelliklere sahiptir; bu da onu çıkarım (inference) amaçları için son derece verimli kılar. GGUF, GGML ve diğer yürütücülerle (executors) kullanılmak üzere tasarlanmıştır. GGUF, popüler C/C++ LLM çıkarım çerçevesi olan [llama.cpp](https://github.com/ggerganov/llama.cpp)'nin de geliştiricisi olan [@ggerganov](https://huggingface.co/ggerganov) tarafından geliştirilmiştir. PyTorch gibi çerçevelerde başlangıçta geliştirilen modeller, bu motorlarla kullanılmak üzere GGUF formatına dönüştürülebilir.

Bu grafikte görebileceğimiz üzere, [safetensors](https://huggingface.co/docs/safetensors) gibi yalnızca tensör içeren dosya biçimlerinin aksine – ki Hub için önerilen model biçimlerinden biridir – GGUF, hem tensörleri hem de standartlaştırılmış bir metadata setini kodlar.

## GGUF dosyalarını bulma

GGUF etiketiyle filtreleyerek GGUF dosyalarına sahip tüm modellere göz atabilirsiniz: [hf.co/models?library=gguf](https://huggingface.co/models?library=gguf). Ayrıca, model ağırlıklarınızı GGUF ağırlıklarına dönüştürmek/kuantize etmek için [ggml-org/gguf-my-repo](https://huggingface.co/spaces/ggml-org/gguf-my-repo) aracını kullanabilirsiniz.

Örneğin, GGUF dosyalarının nasıl çalıştığını görmek için [TheBloke/Mixtral-8x7B-Instruct-v0.1-GGUF](https://huggingface.co/TheBloke/Mixtral-8x7B-Instruct-v0.1-GGUF) deposuna göz atabilirsiniz.

## Üstveri ve tensör bilgisi görüntüleyicisi

Hub, GGUF dosyaları için bir görüntüleyiciye sahiptir; bu görüntüleyici kullanıcıların meta verileri ve tensör bilgilerini (ad, şekil, hassasiyet) incelemesini sağlar. Görüntüleyici, model sayfasında ([örnek](https://huggingface.co/TheBloke/Mixtral-8x7B-Instruct-v0.1-GGUF?show_tensors=mixtral-8x7b-instruct-v0.1.Q4_0.gguf)) ve dosyalar sayfasında ([örnek](https://huggingface.co/TheBloke/Mixtral-8x7B-Instruct-v0.1-GGUF/tree/main?show_tensors=mixtral-8x7b-instruct-v0.1.Q5_K_M.gguf)) kullanılabilir.

## Açık kaynak araçlarla kullanım

* [llama.cpp](./gguf-llamacpp)
* [LM Studio](./lmstudio)
* [GPT4All](./gguf-gpt4all)
* [Ollama](./ollama)

## @huggingface/gguf ile meta verileri ayrıştırma

Uzak konaklamalı dosyalarla (ör. Hugging Face Hub) çalışan bir javascript GGUF ayrıştırıcısı da oluşturduk.

```bash
npm install @huggingface/gguf
```

```ts
import { gguf } from "@huggingface/gguf";
// remote GGUF file from https://huggingface.co/TheBloke/Llama-2-7B-Chat-GGUF
const URL_LLAMA = "https://huggingface.co/TheBloke/Llama-2-7B-Chat-GGUF/resolve/191239b/llama-2-7b-chat.Q2_K.gguf";
const { metadata, tensorInfos } = await gguf(URL_LLAMA);
```

Daha fazla bilgi için [buraya](https://github.com/huggingface/huggingface.js/tree/main/packages/gguf) bakın.

## Kantizasyon Türleri

| tür         | kaynak | açıklama |
|---------------------------|--------|-------------|
| F64 | [Wikipedia](https://en.wikipedia.org/wiki/Double-precision_floating-point_format) | 64-bit standart IEEE 754 çift hassasiyetli kayan noktalı sayı. |
| I64 | [GH](https://github.com/ggerganov/llama.cpp/pull/6062) | 64-bit sabit genişlikli tamsayı. |
| F32  | [Wikipedia](https://en.wikipedia.org/wiki/Single-precision_floating-point_format) | 32-bit standart IEEE 754 tek hassasiyetli kayan noktalı sayı. |
| I32 | [GH](https://github.com/ggerganov/llama.cpp/pull/6045) | 32-bit sabit genişlikli tamsayı. |
| F16  | [Wikipedia](https://en.wikipedia.org/wiki/Half-precision_floating-point_format) | 16-bit standart IEEE 754 yarı hassasiyetli kayan noktalı sayı. |
| BF16 | [Wikipedia](https://en.wikipedia.org/wiki/Bfloat16_floating-point_format) | 32-bit IEEE 754 tek hassasiyetli kayan noktalı sayının 16-bit kısaltılmış versiyonu. |
| I16 | [GH](https://github.com/ggerganov/llama.cpp/pull/6045) | 16-bit sabit genişlikli tamsayı. |
| Q8_K | [GH](https://github.com/ggerganov/llama.cpp/pull/1684#issue-1739619305) | 8-bit kuantizasyon (`q`). Her blok 256 ağırlık içerir. Yalnızca ara sonuçların kuantize edilmesi için kullanılır. Bu kuantizasyon tipi için tüm 2-6 bit nokta çarpımları uygulanmıştır. Ağırlık formülü: `w = q * block_scale`. |
| I8 | [GH](https://github.com/ggerganov/llama.cpp/pull/6045) | 8-bit sabit genişlikli tamsayı. |
| Q6_K | [GH](https://github.com/ggerganov/llama.cpp/pull/1684#issue-1739619305) | 6-bit kuantizasyon (`q`). 16 bloktan oluşan süper bloklar, her blok 16 ağırlık içerir. Ağırlık formülü: `w = q * block_scale(8-bit)`, bu da ağırlık başına 6.5625 bit sonucunu verir. |
| Q5_K | [GH](https://github.com/ggerganov/llama.cpp/pull/1684#issue-1739619305) | 5-bit kuantizasyon (`q`). 8 bloktan oluşan süper bloklar, her blok 32 ağırlık içerir. Ağırlık formülü: `w = q * block_scale(6-bit) + block_min(6-bit)`, bu da ağırlık başına 5,5 bit sonucunu verir. |
| Q4_K | [GH](https://github.com/ggerganov/llama.cpp/pull/1684#issue-1739619305) | 4-bit kuantizasyon (`q`). 8 bloktan oluşan süper bloklar, her blok 32 ağırlık içerir. Ağırlık formülü: `w = q * block_scale(6-bit) + block_min(6-bit)`, bu da ağırlık başına 4,5 bit sonucunu verir. |
| Q3_K | [GH](https://github.com/ggerganov/llama.cpp/pull/1684#issue-1739619305) | 3-bit kuantizasyon (`q`). 16 bloktan oluşan süper bloklar, her blok 16 ağırlık içerir. Ağırlık formülü: `w = q * block_scale(6-bit)`, bu da ağırlık başına 3.4375 bit sonucunu verir. |
| Q2_K | [GH](https://github.com/ggerganov/llama.cpp/pull/1684#issue-1739619305) | 2-bit kuantizasyon (`q`). 16 bloktan oluşan süper bloklar, her blok 16 ağırlık içerir. Ağırlık formülü: `w = q * block_scale(4-bit) + block_min(4-bit)`, bu da ağırlık başına 2.625 bit sonucunu verir. |
| IQ4_NL | [GH](https://github.com/ggerganov/llama.cpp/pull/5590) | 4-bit kuantizasyon (`q`). 256 ağırlıklı süper bloklar. `w` ağırlığı, `super_block_scale` & `importance matrix` kullanılarak elde edilir. |
| IQ4_XS | [HF](https://huggingface.co/CISCai/OpenCodeInterpreter-DS-6.7B-SOTA-GGUF/blob/main/README.md?code=true#L59-L70) | 4-bit kuantizasyon (`q`). 256 ağırlıklı süper bloklar. `w` ağırlığı, `super_block_scale` & `importance matrix` kullanılarak elde edilir ve bu, ağırlık başına 4,25 bit sonucunu verir. |
| IQ3_S | [HF](https://huggingface.co/CISCai/OpenCodeInterpreter-DS-6.7B-SOTA-GGUF/blob/main/README.md?code=true#L59-L70) | 3-bit kuantizasyon (`q`). 256 ağırlıklı süper bloklar. `w` ağırlığı, `super_block_scale` & `importance matrix` kullanılarak elde edilir ve bu, ağırlık başına 3,44 bit sonucunu verir. |
| IQ3_XXS | [HF](https://huggingface.co/CISCai/OpenCodeInterpreter-DS-6.7B-SOTA-GGUF/blob/main/README.md?code=true#L59-L70) | 3-bit kuantizasyon (`q`). 256 ağırlıklı süper bloklar. `w` ağırlığı, `super_block_scale` & `importance matrix` kullanılarak elde edilir ve bu, ağırlık başına 3,06 bit sonucunu verir. |
| IQ2_XXS | [HF](https://huggingface.co/CISCai/OpenCodeInterpreter-DS-6.7B-SOTA-GGUF/blob/main/README.md?code=true#L59-L70) | 2-bit kuantizasyon (`q`). 256 ağırlıklı süper bloklar. `w` ağırlığı, `super_block_scale` & `importance matrix` kullanılarak elde edilir ve bu, ağırlık başına 2,06 bit sonucunu verir. |
| IQ2_S | [HF](https://huggingface.co/CISCai/OpenCodeInterpreter-DS-6.7B-SOTA-GGUF/blob/main/README.md?code=true#L59-L70) | 2-bit kuantizasyon (`q`). 256 ağırlıklı süper bloklar. `w` ağırlığı, `super_block_scale` & `importance matrix` kullanılarak elde edilir ve bu, ağırlık başına 2,5 bit sonucunu verir. |
| IQ2_XS | [HF](https://huggingface.co/CISCai/OpenCodeInterpreter-DS-6.7B-SOTA-GGUF/blob/main/README.md?code=true#L59-L70) | 2-bit kuantizasyon (`q`). 256 ağırlıklı süper bloklar. `w` ağırlığı, `super_block_scale` & `importance matrix` kullanılarak elde edilir ve bu, ağırlık başına 2,31 bit sonucunu verir. |
| IQ1_S | [HF](https://huggingface.co/CISCai/OpenCodeInterpreter-DS-6.7B-SOTA-GGUF/blob/main/README.md?code=true#L59-L70) | 1-bit kuantizasyon (`q`). 256 ağırlıklı süper bloklar. `w` ağırlığı, `super_block_scale` & `importance matrix` kullanılarak elde edilir ve bu, ağırlık başına 1,56 bit sonucunu verir. |
| IQ1_M | [GH](https://github.com/ggerganov/llama.cpp/pull/6302) | 1-bit kuantizasyon (`q`). 256 ağırlıklı süper bloklar. `w` ağırlığı, `super_block_scale` & `importance matrix` kullanılarak elde edilir ve bu, ağırlık başına 1,75 bit sonucunu verir. |
| TQ1_0 | [GH](https://github.com/ggml-org/llama.cpp/pull/8151) | Üçlü kuantizasyon. |
| TQ2_0 | [GH](https://github.com/ggml-org/llama.cpp/pull/8151) | Üçlü kuantizasyon. |
| MXFP4 | [GH](https://github.com/ggml-org/llama.cpp/pull/15091) | 4-bit Microscaling Blok Kayan Nokta. |
| **Eski türler** | | |
| Q8_0 | [GH](https://github.com/huggingface/huggingface.js/pull/615#discussion_r1557654249) | 8-bit en yakın yuvarlama kuantizasyonu (`q`). Her blok 32 ağırlık içerir. Ağırlık formülü: `w = q * block_scale`. Eski kuantizleme yöntemi (bugüne kadar yaygın olarak kullanılmamıştır). |
| Q8_1 | [GH](https://github.com/huggingface/huggingface.js/pull/615#discussion_r1557682290) | 8-bit en yakın yuvarlama kuantizasyonu (`q`). Her blok 32 ağırlık içerir. Ağırlık formülü: `w = q * block_scale + block_minimum`. Eski kuantizleme yöntemi (bugüne kadar yaygın olarak kullanılmamıştır). |
| Q5_0 | [GH](https://github.com/huggingface/huggingface.js/pull/615#discussion_r1557654249) | 5-bit en yakın yuvarlama kuantizasyonu (`q`). Her blok 32 ağırlık içerir. Ağırlık formülü: `w = q * block_scale`. Eski kuantizleme yöntemi (bugüne kadar yaygın olarak kullanılmamıştır). |
| Q5_1 | [GH](https://github.com/huggingface/huggingface.js/pull/615#discussion_r1557682290) | 5-bit en yakın yuvarlama kuantizasyonu (`q`). Her blok 32 ağırlık içerir. Ağırlık formülü: `w = q * block_scale + block_minimum`. Eski kuantizleme yöntemi (bugüne kadar yaygın olarak kullanılmamıştır). |
| Q4_0 | [GH](https://github.com/huggingface/huggingface.js/pull/615#discussion_r1557654249) | 4-bit en yakın yuvarlama kuantizasyonu (`q`). Her blok 32 ağırlık içerir. Ağırlık formülü: `w = q * block_scale`. Eski kuantizleme yöntemi (bugüne kadar yaygın olarak kullanılmamıştır). |
| Q4_1 | [GH](https://github.com/huggingface/huggingface.js/pull/615#discussion_r1557682290) | 4-bit en yakın yuvarlama kuantizasyonu (`q`). Her blok 32 ağırlık içerir. Ağırlık formülü: `w = q * block_scale + block_minimum`. Eski kuantizasyon yöntemi (bugüne kadar yaygın olarak kullanılmamıştır). |

*yukarıdaki tabloda herhangi bir hata varsa, lütfen [bu dosya](https://github.com/huggingface/huggingface.js/blob/main/packages/gguf/src/quant-descriptions.ts) için bir PR açın.*