# buun-llama-cpp ![buunslamma](https://raw.githubusercontent.com/spiritbuun/buun-llama-cpp/HEAD/buunslamma.png) > **This is a highly experimental fork of llama.cpp. Use at your own discretion.** A research and development fork of [llama.cpp](https://github.com/ggml-org/llama.cpp), providing unique KV cache codecs, inference techniques, and bleeding edge features. ## VBR — Variable Bit-Rate KV Cache Why pay 3-bit or 4-bit quality for a context length you only sometimes reach? VBR quantizes the KV cache *dynamically as your session grows* — giving you the highest-quality cache possible at any given depth. It quantizes the cache **layer by layer, using our best KV codecs**, from the least-sensitive layers to the most-sensitive, and only as far down the ladder as your VRAM and context actually require. The cache starts at **FP16** and stays there until there is real budget pressure; then it degrades one (layer, side) tensor at a time — first to an aggregate 15.75 bits/value, then 15.51, and so on down the ladder (`f16 → turbo8 → turbo4 → turbo3_tcq → turbo2_tcq → turbo1_tcq`), following a per-model price order measured on KLD panels. For Qwen35 (16 attention layers) that is **160** distinct steps from FP16 down to turbo1_tcq; for Gemma4-31B (60 layers), **600** — the finest-grained quality control we can give you at every moment of a session. And because VBR always draws from the best codecs on the ladder, **you never have to track KV formats again**: new codecs and research roll straight into VBR, so the default cache will always use the best available ladder. ### Recommended usage On a dedicated GPU, just run: ```sh llama-server -m model.gguf ``` VBR is the default cache, with a **turbo4 quality floor**. It derives a KV VRAM budget from whatever is left after weights and compute, advertises the largest context that fits without going below turbo4 (capped at the model's training length), and degrades tiers on the fly as context fills. The cache is still FP16 until memory pressure actually requires compression. For maximum context, explicitly use `-ct vbr`. That deliberate opt-in opens the complete ladder down to turbo1_tcq unless you also set `--vbr-floor`: ```sh llama-server -m model.gguf -ct vbr ``` Run with `-v` to watch the `VBR degrade #…` steps fire. ### Choose the two things you know VBR balances three quantities: **context length**, **KV VRAM**, and **minimum quality**. Usually specify at most two and let VBR solve the third: | You know | Use | VBR determines | |---|---|---| | How many tokens you need and how much KV VRAM you can spare | `-ct vbr -c N --vbr-vram SIZE` | The highest-quality terminal layer mixture that fits. Explicit `-ct vbr` leaves the full ladder available. | | How many tokens you need and the lowest quality you will accept | `-c N --vbr-floor TIER` | The safe KV VRAM budget available on the machine. | | How much KV VRAM you can spare and the lowest quality you will accept | `--vbr-vram SIZE --vbr-floor TIER` | The largest fillable context. | Setting all three usually just over-constrains the same calculation. Pick the two requirements you actually know; VBR can then optimize the remaining dimension instead of receiving three potentially contradictory answers. ### Settings | flag | meaning | |---|---| | `-ct vbr` (or `-ctk vbr` / `-ctv vbr`) | VBR is already enabled by default. Explicitly selecting it opens the full ladder to t1 when no `--vbr-floor` is supplied. Explicitly pinning a side (`-ctv q8_0`) holds it at fixed bits and never degrades it. Use `-ct f16` or another concrete type to opt out of VBR. | | `-c ` | Cap the context at N tokens; VBR then spends your whole VRAM budget running *that* window at the highest quality it can, instead of advertising the max floor-tier capacity. E.g. `-c 30000` = the best-quality cache that fits a 30k window. | | `--vbr-vram ` | Explicit KV VRAM budget (e.g. `8G`). Default `auto` = whatever VRAM is left after weights and compute. | | `--vbr-floor ` | Literal aggregate bits/value floor for dynamic mode. Implicit VBR defaults to t4 (4.125); explicit `-ct vbr` without this flag uses t1 (1.25). Degrades stop at the last step still ≥ the floor. | | `--vbr-budget ` | Default `dynamic` (runtime controller). A tier (`t8/t4/t3/t2/t1`) or a number instead selects a **fixed** static tier — no runtime degrades. | **Requirements:** a CUDA or ROCm backend (turbo-typed KV needs the TurboQuant interface; layers whose KV lands on the CPU fall back to q8_0). Flash attention is required and force-enabled. Dynamic mode uses unified KV (forced automatically with `-np > 1`). Context-shift / self-extend and slot/session save-restore are disabled in dynamic mode (they would snapshot tier-typed KV that can't restore across a degrade — tier-aware save-restore is planned); context checkpoints stay enabled on hybrid models. Generation stops cleanly when the context fills. Models without a baked price order use a generic cross-model order. ## TCQ (trellis-coded KV cache) Standard KV cache quantization treats each value independently. TCQ constrains the quantization indices to follow a 512-state trellis, giving a much larger effective codebook at the same bit rate (with FWHT rotation and context-adaptive norm scaling on top). At the 3-bit setting, the trellis cuts median KL-divergence by **~40% versus scalar quantization** while using slightly *fewer* bits (3.25 vs 3.50 bpv), and lands perplexity on par with an f16 KV cache. **Paper**: [Closing the Gap: Trellis-Coded Quantization for KV Cache at 2-3 Bits](https://huggingface.co/datasets/spiritbuun/turboquant-tcq-kv-cache) ### Quality (Qwen3.6-27B Q6_K, 16K, RTX 3090) `turbo3` is scalar 3-bit, `turbo3_tcq` the trellis-coded version at fewer bits — the gap is exactly what the trellis buys. `pp` = prefill t/s on a 16K prompt, `tg` = decode t/s at 16K depth. | Codec | bpv | PPL | median KLD | pp (t/s) | tg (t/s) | |-------|-----|-----|------------|----------|----------| | turbo3 (scalar) | 3.5 | 5.730 | 0.00279 | 1015 | 28.1 | | turbo3_tcq | 3.25 | 5.668 | 0.00163 | 818 | 26.6 | The trellis cuts median KLD ~40% (and edges PPL below f16) at fewer bits. Its cost lands in **prefill** — the Viterbi re-encode drops prompt processing to ~818 t/s vs ~1015 for scalar turbo3; decode is barely affected on a dedicated GPU. ### Speed The trellis cost is compute, so it depends on hardware. On dedicated GPUs (e.g. RTX 3090) the fused tensor-core decode path keeps generation at essentially vanilla / f16 speed (the `tg` numbers above). On weaker-compute hardware (e.g. the Strix Halo iGPU) the cost is exposed and the TCQ types can be up to ~40% slower than their scalar counterparts — there, prefer the scalar or higher-bit codecs. ### How it works 1. **FWHT rotation** with random sign flips converts correlated KV vectors into i.i.d. Gaussian entries 2. **Viterbi encoding** on a 512-state (3-bit) or 256-state (2-bit) right-shift trellis finds the globally optimal codeword assignment 3. **O(1) sliding-window decode** -- each value decodes via a bit window lookup, no trellis traversal at inference 4. **Context-adaptive alpha** -- logarithmic norm scaling formula automatically adjusts dequantization scale per context length ### Custom codebooks Trained codebooks are included in `codebooks/`. The defaults are compiled into the CUDA kernels, but you can override them: ```sh TURBO_TCQ_CB=codebooks/3bit/product_aware_iter080.bin \ TURBO_TCQ_CB2=codebooks/2bit/product_aware_iter090.bin \ ./build/bin/llama-server -m model.gguf -ngl 99 -fa \ -ctk turbo3_tcq -ctv turbo3_tcq ``` Codebook training scripts are in `scripts/tcq_train_*.py`. ## Codecs These are the individual KV cache codecs the fork ships. In practice you rarely pick one by hand — **dynamic VBR mixes them per layer automatically and is the recommended default**; the codecs below are mainly for testing and comparison. Measured on Qwen3.6-27B Q6_K at 16K context (18 chunks of the wikitext-2 test set) on an RTX 3090. Median KL-divergence is versus an f16 KV cache (0 = identical logits); `pp` is prefill throughput on a 16K prompt and `tg` is decode throughput at 16K depth. Ordered by KL-divergence (quality) — lower is better. | Codec | bpv | PPL | median KLD | pp (t/s) | tg (t/s) | |-------|-----|-----|------------|----------|----------| | f16 | 16.0 | 5.683 | 0 (ref) | 1104 | 30.7 | | q8_0 | 8.5 | 5.698 | 0.00020 | 1050 | 27.4 | | turbo8 | 8.125 | 5.693 | 0.00020 | 1013 | 28.6 | | turbo4 | 4.125 | 5.723 | 0.00090 | 1017 | 28.4 | | q4_0 | 4.5 | 5.705 | 0.00115 | 1033 | 26.9 | | turbo3_tcq | 3.25 | 5.668 | 0.00163 | 818 | 26.6 | | turbo3 | 3.5 | 5.730 | 0.00279 | 1015 | 28.1 | | turbo2_tcq | 2.25 | 5.711 | 0.00561 | 985 | 28.5 | | turbo2 | 2.5 | 5.964 | 0.01083 | 1013 | 28.2 | | turbo1_tcq | 1.25 | 6.012 | 0.02633 | 991 | 28.5 | ## MTP + Vision (`--mmproj-gpu-swap`) On VRAM-constrained GPUs, MTP speculative decoding and the vision encoder (mmproj) may not fit in VRAM simultaneously. For example, Qwen3.6-27B Q6_K + MTP uses ~22.6 GiB on a 24 GiB RTX 3090, leaving no room for mmproj's ~1.1 GiB GPU footprint. `--mmproj-gpu-swap` solves this by keeping mmproj on CPU at startup, then temporarily swapping MTP out of VRAM when an image arrives, loading mmproj to GPU for fast encoding (~1-2s instead of 30-60s on CPU), and swapping back afterward. MTP has no persistent state, so the swap is lossless. ```sh ./build/bin/llama-server -m Qwen3.6-27B-Q6_K.gguf \ --mmproj mmproj.gguf --spec-type draft-mtp \ --mmproj-gpu-swap -ngl 99 ``` When combined with auto-fit (no `-c` flag), the server automatically sizes context to leave room for the swap. With a single slot, it also auto-enables `--kv-unified` to avoid splitting the KV cache into separate streams, which doubles usable per-slot context. ## Build ### NVIDIA (CUDA) ```sh cmake -B build \ -DGGML_CUDA=ON \ -DGGML_NATIVE=ON \ -DGGML_CUDA_FA=ON \ -DGGML_CUDA_FA_ALL_QUANTS=ON \ -DCMAKE_BUILD_TYPE=Release cmake --build build -j$(nproc) ``` ### AMD (ROCm / HIP) Tested on ROCm 7.2 + RDNA3 (`gfx1100`, RX 7900 XTX). Other RDNA3/RDNA4 targets should work by swapping `AMDGPU_TARGETS`. ```sh cmake -B build \ -DGGML_HIP=ON \ -DAMDGPU_TARGETS=gfx1100 \ -DCMAKE_BUILD_TYPE=Release \ -DLLAMA_BUILD_SERVER=ON \ -DCMAKE_C_COMPILER=/opt/rocm/bin/amdclang \ -DCMAKE_CXX_COMPILER=/opt/rocm/bin/amdclang++ cmake --build build -j$(nproc) ``` #### [For Windows ROCM](https://github.com/lemonade-sdk/llamacpp-rocm/blob/main/docs/manual_instructions.md) Test on ROCm 7.13 + AMD Radeon AI PRO R9700 ## Recommended configurations **For most use, VBR needs no cache flags** — it picks the best codec per layer automatically, spends all your spare VRAM on quality, and keeps a t4 quality floor: ```sh ./build/bin/llama-server -m model.gguf -ngl 99 ``` Use explicit `-ct vbr` to open the complete ladder to t1 for maximum context. The fixed-tier codecs below are for pinning a specific tier — benchmarking, a fixed budget, or a backend without VBR support. ### turbo4 (4.125 bpv) -- low divergence, great compression The safe fixed-tier default. 4-bit KV cache at ~3.8x compression with no speed penalty — higher fidelity (lower KL-divergence from FP16) than the 2–3 bit codecs below. ```sh ./build/bin/llama-server -m model.gguf -ngl 99 -fa \ -ctk turbo4 -ctv turbo4 ``` ### 3-bit TCQ (3.25 bpv) -- best quality at 3-bit The best-quality 3-bit option — about 40% lower KL-divergence than scalar turbo3 at the same tier. ~5x KV cache compression. ```sh ./build/bin/llama-server -m model.gguf -ngl 99 -fa \ -ctk turbo3_tcq -ctv turbo3_tcq ``` ### 2-bit TCQ (2.25 bpv) -- maximum compression ~7x KV cache compression. Best for fitting very long contexts in limited VRAM. ```sh ./build/bin/llama-server -m model.gguf -ngl 99 -fa \ -ctk turbo2_tcq -ctv turbo2_tcq ``` ### Asymmetric 2.75 bpv -- best 2-bit quality 3-bit keys + 2-bit values. 15-17% lower KLD than the reverse, because adaptive alpha already compensates V quantization error. ```sh ./build/bin/llama-server -m model.gguf -ngl 99 -fa \ -ctk turbo3_tcq -ctv turbo2_tcq ``` ### Scalar turbo3 / turbo2 (3.5 / 2.5 bpv) -- no trellis Scalar quantization without TCQ. Faster encode, worse quality than TCQ equivalents. ```sh # 3-bit scalar ./build/bin/llama-server -m model.gguf -ngl 99 -fa \ -ctk turbo3 -ctv turbo3 # 2-bit scalar ./build/bin/llama-server -m model.gguf -ngl 99 -fa \ -ctk turbo2 -ctv turbo2 ``` --- ## Quick start Getting started with llama.cpp is straightforward. Here are several ways to install it on your machine: - Install `llama.cpp` using [brew, nix, winget, or conda-forge](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/docs/install.md) - Run with Docker - see our [Docker documentation](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/docs/docker.md) - Download pre-built binaries from the [releases page](https://github.com/ggml-org/llama.cpp/releases) - Build from source by cloning this repository - check out [our build guide](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/docs/build.md) Once installed, you'll need a model to work with. Head to the [Obtaining and quantizing models](#obtaining-and-quantizing-models) section to learn more. Example command: ```sh # Use a local model file llama-cli -m my_model.gguf # Or download and run a model directly from Hugging Face llama-cli -hf ggml-org/gemma-3-1b-it-GGUF # Launch OpenAI-compatible API server llama-server -hf ggml-org/gemma-3-1b-it-GGUF ``` ## Description The main goal of `llama.cpp` is to enable LLM inference with minimal setup and state-of-the-art performance on a wide range of hardware - locally and in the cloud. - Plain C/C++ implementation without any dependencies - Apple silicon is a first-class citizen - optimized via ARM NEON, Accelerate and Metal frameworks - AVX, AVX2, AVX512 and AMX support for x86 architectures - RVV, ZVFH, ZFH, ZICBOP and ZIHINTPAUSE support for RISC-V architectures - 1.5-bit, 2-bit, 3-bit, 4-bit, 5-bit, 6-bit, and 8-bit integer quantization for faster inference and reduced memory use - Custom CUDA kernels for running LLMs on NVIDIA GPUs (support for AMD GPUs via HIP and Moore Threads GPUs via MUSA) - Vulkan and SYCL backend support - CPU+GPU hybrid inference to partially accelerate models larger than the total VRAM capacity The `llama.cpp` project is the main playground for developing new features for the [ggml](https://github.com/ggml-org/ggml) library.
Models Typically finetunes of the base models below are supported as well. Instructions for adding support for new models: [HOWTO-add-model.md](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/docs/development/HOWTO-add-model.md) #### Text-only - [X] LLaMA 🦙 - [x] LLaMA 2 🦙🦙 - [x] LLaMA 3 🦙🦙🦙 - [X] [Mistral 7B](https://huggingface.co/mistralai/Mistral-7B-v0.1) - [x] [Mixtral MoE](https://huggingface.co/models?search=mistral-ai/Mixtral) - [x] [DBRX](https://huggingface.co/databricks/dbrx-instruct) - [x] [Jamba](https://huggingface.co/ai21labs) - [X] [Falcon](https://huggingface.co/models?search=tiiuae/falcon) - [X] [Chinese LLaMA / Alpaca](https://github.com/ymcui/Chinese-LLaMA-Alpaca) and [Chinese LLaMA-2 / Alpaca-2](https://github.com/ymcui/Chinese-LLaMA-Alpaca-2) - [X] [Vigogne (French)](https://github.com/bofenghuang/vigogne) - [X] [BERT](https://github.com/ggml-org/llama.cpp/pull/5423) - [X] [Koala](https://bair.berkeley.edu/blog/2023/04/03/koala/) - [X] [Baichuan 1 & 2](https://huggingface.co/models?search=baichuan-inc/Baichuan) + [derivations](https://huggingface.co/hiyouga/baichuan-7b-sft) - [X] [Aquila 1 & 2](https://huggingface.co/models?search=BAAI/Aquila) - [X] [Starcoder models](https://github.com/ggml-org/llama.cpp/pull/3187) - [X] [Refact](https://huggingface.co/smallcloudai/Refact-1_6B-fim) - [X] [MPT](https://github.com/ggml-org/llama.cpp/pull/3417) - [X] [Bloom](https://github.com/ggml-org/llama.cpp/pull/3553) - [x] [Yi models](https://huggingface.co/models?search=01-ai/Yi) - [X] [StableLM models](https://huggingface.co/stabilityai) - [x] [Deepseek models](https://huggingface.co/models?search=deepseek-ai/deepseek) - [x] [Qwen models](https://huggingface.co/models?search=Qwen/Qwen) - [x] [PLaMo-13B](https://github.com/ggml-org/llama.cpp/pull/3557) - [x] [Phi models](https://huggingface.co/models?search=microsoft/phi) - [x] [PhiMoE](https://github.com/ggml-org/llama.cpp/pull/11003) - [x] [GPT-2](https://huggingface.co/gpt2) - [x] [Orion 14B](https://github.com/ggml-org/llama.cpp/pull/5118) - [x] [InternLM2](https://huggingface.co/models?search=internlm2) - [x] [CodeShell](https://github.com/WisdomShell/codeshell) - [x] [Gemma](https://ai.google.dev/gemma) - [x] [Mamba](https://github.com/state-spaces/mamba) - [x] [Grok-1](https://huggingface.co/keyfan/grok-1-hf) - [x] [Xverse](https://huggingface.co/models?search=xverse) - [x] [Command-R models](https://huggingface.co/models?search=CohereForAI/c4ai-command-r) - [x] [SEA-LION](https://huggingface.co/models?search=sea-lion) - [x] [GritLM-7B](https://huggingface.co/GritLM/GritLM-7B) + [GritLM-8x7B](https://huggingface.co/GritLM/GritLM-8x7B) - [x] [OLMo](https://allenai.org/olmo) - [x] [OLMo 2](https://allenai.org/olmo) - [x] [OLMoE](https://huggingface.co/allenai/OLMoE-1B-7B-0924) - [x] [Granite models](https://huggingface.co/collections/ibm-granite/granite-code-models-6624c5cec322e4c148c8b330) - [x] [GPT-NeoX](https://github.com/EleutherAI/gpt-neox) + [Pythia](https://github.com/EleutherAI/pythia) - [x] [Snowflake-Arctic MoE](https://huggingface.co/collections/Snowflake/arctic-66290090abe542894a5ac520) - [x] [Smaug](https://huggingface.co/models?search=Smaug) - [x] [Poro 34B](https://huggingface.co/LumiOpen/Poro-34B) - [x] [Bitnet b1.58 models](https://huggingface.co/1bitLLM) - [x] [Flan T5](https://huggingface.co/models?search=flan-t5) - [x] [Open Elm models](https://huggingface.co/collections/apple/openelm-instruct-models-6619ad295d7ae9f868b759ca) - [x] [ChatGLM3-6b](https://huggingface.co/THUDM/chatglm3-6b) + [ChatGLM4-9b](https://huggingface.co/THUDM/glm-4-9b) + [GLMEdge-1.5b](https://huggingface.co/THUDM/glm-edge-1.5b-chat) + [GLMEdge-4b](https://huggingface.co/THUDM/glm-edge-4b-chat) - [x] [GLM-4-0414](https://huggingface.co/collections/THUDM/glm-4-0414-67f3cbcb34dd9d252707cb2e) - [x] [SmolLM](https://huggingface.co/collections/HuggingFaceTB/smollm-6695016cad7167254ce15966) - [x] [EXAONE-3.0-7.8B-Instruct](https://huggingface.co/LGAI-EXAONE/EXAONE-3.0-7.8B-Instruct) - [x] [FalconMamba Models](https://huggingface.co/collections/tiiuae/falconmamba-7b-66b9a580324dd1598b0f6d4a) - [x] [Jais](https://huggingface.co/inceptionai/jais-13b-chat) - [x] [Bielik-11B-v2.3](https://huggingface.co/collections/speakleash/bielik-11b-v23-66ee813238d9b526a072408a) - [x] [RWKV-7](https://huggingface.co/collections/shoumenchougou/rwkv7-gxx-gguf) - [x] [RWKV-6](https://github.com/BlinkDL/RWKV-LM) - [x] [QRWKV-6](https://huggingface.co/recursal/QRWKV6-32B-Instruct-Preview-v0.1) - [x] [GigaChat-20B-A3B](https://huggingface.co/ai-sage/GigaChat-20B-A3B-instruct) - [X] [Trillion-7B-preview](https://huggingface.co/trillionlabs/Trillion-7B-preview) - [x] [Ling models](https://huggingface.co/collections/inclusionAI/ling-67c51c85b34a7ea0aba94c32) - [x] [Liquid LFM2 models](https://huggingface.co/collections/LiquidAI/lfm2) - [x] [Liquid LFM2.5 models](https://huggingface.co/collections/LiquidAI/lfm25) - [x] [Liquid Nanos](https://huggingface.co/collections/LiquidAI/liquid-nanos) - [x] [Hunyuan models](https://huggingface.co/collections/tencent/hunyuan-dense-model-6890632cda26b19119c9c5e7) - [x] [BailingMoeV2 (Ring/Ling 2.0) models](https://huggingface.co/collections/inclusionAI/ling-v2-68bf1dd2fc34c306c1fa6f86) - [x] [Mellum models](https://huggingface.co/JetBrains/models?search=mellum) #### Multimodal - [x] [LLaVA 1.5 models](https://huggingface.co/collections/liuhaotian/llava-15-653aac15d994e992e2677a7e), [LLaVA 1.6 models](https://huggingface.co/collections/liuhaotian/llava-16-65b9e40155f60fd046a5ccf2) - [x] [BakLLaVA](https://huggingface.co/models?search=SkunkworksAI/Bakllava) - [x] [Obsidian](https://huggingface.co/NousResearch/Obsidian-3B-V0.5) - [x] [ShareGPT4V](https://huggingface.co/models?search=Lin-Chen/ShareGPT4V) - [x] [MobileVLM 1.7B/3B models](https://huggingface.co/models?search=mobileVLM) - [x] [Yi-VL](https://huggingface.co/models?search=Yi-VL) - [x] [Mini CPM](https://huggingface.co/models?search=MiniCPM) - [x] [Moondream](https://huggingface.co/vikhyatk/moondream2) - [x] [Bunny](https://github.com/BAAI-DCAI/Bunny) - [x] [GLM-EDGE](https://huggingface.co/models?search=glm-edge) - [x] [Qwen2-VL](https://huggingface.co/collections/Qwen/qwen2-vl-66cee7455501d7126940800d) - [x] [LFM2-VL](https://huggingface.co/collections/LiquidAI/lfm2-vl-68963bbc84a610f7638d5ffa)
Bindings - Python: [ddh0/easy-llama](https://github.com/ddh0/easy-llama) - Python: [abetlen/llama-cpp-python](https://github.com/abetlen/llama-cpp-python) - Go: [go-skynet/go-llama.cpp](https://github.com/go-skynet/go-llama.cpp) - Node.js: [withcatai/node-llama-cpp](https://github.com/withcatai/node-llama-cpp) - JS/TS (llama.cpp server client): [lgrammel/modelfusion](https://modelfusion.dev/integration/model-provider/llamacpp) - JS/TS (Programmable Prompt Engine CLI): [offline-ai/cli](https://github.com/offline-ai/cli) - JavaScript/Wasm (works in browser): [tangledgroup/llama-cpp-wasm](https://github.com/tangledgroup/llama-cpp-wasm) - Typescript/Wasm (nicer API, available on npm): [ngxson/wllama](https://github.com/ngxson/wllama) - Ruby: [yoshoku/llama_cpp.rb](https://github.com/yoshoku/llama_cpp.rb) - Ruby: [docusealco/rllama](https://github.com/docusealco/rllama) - Rust (more features): [edgenai/llama_cpp-rs](https://github.com/edgenai/llama_cpp-rs) - Rust (nicer API): [mdrokz/rust-llama.cpp](https://github.com/mdrokz/rust-llama.cpp) - Rust (more direct bindings): [utilityai/llama-cpp-rs](https://github.com/utilityai/llama-cpp-rs) - Rust (automated build from crates.io): [ShelbyJenkins/llm_client](https://github.com/ShelbyJenkins/llm_client) - C#/.NET: [SciSharp/LLamaSharp](https://github.com/SciSharp/LLamaSharp) - C#/VB.NET (more features - community license): [LM-Kit.NET](https://docs.lm-kit.com/lm-kit-net/index.html) - Scala 3: [donderom/llm4s](https://github.com/donderom/llm4s) - Clojure: [phronmophobic/llama.clj](https://github.com/phronmophobic/llama.clj) - React Native: [mybigday/llama.rn](https://github.com/mybigday/llama.rn) - Java: [kherud/java-llama.cpp](https://github.com/kherud/java-llama.cpp) - Java: [QuasarByte/llama-cpp-jna](https://github.com/QuasarByte/llama-cpp-jna) - Zig: [deins/llama.cpp.zig](https://github.com/Deins/llama.cpp.zig) - Flutter/Dart: [netdur/llama_cpp_dart](https://github.com/netdur/llama_cpp_dart) - Flutter: [xuegao-tzx/Fllama](https://github.com/xuegao-tzx/Fllama) - PHP (API bindings and features built on top of llama.cpp): [distantmagic/resonance](https://github.com/distantmagic/resonance) [(more info)](https://github.com/ggml-org/llama.cpp/pull/6326) - Guile Scheme: [guile_llama_cpp](https://savannah.nongnu.org/projects/guile-llama-cpp) - Swift [srgtuszy/llama-cpp-swift](https://github.com/srgtuszy/llama-cpp-swift) - Swift [ShenghaiWang/SwiftLlama](https://github.com/ShenghaiWang/SwiftLlama) - Delphi [Embarcadero/llama-cpp-delphi](https://github.com/Embarcadero/llama-cpp-delphi) - Go (no CGo needed): [hybridgroup/yzma](https://github.com/hybridgroup/yzma) - Android: [llama.android](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/examples/llama.android)
UIs *(to have a project listed here, it should clearly state that it depends on `llama.cpp`)* - [AI Sublime Text plugin](https://github.com/yaroslavyaroslav/OpenAI-sublime-text) (MIT) - [BonzAI App](https://apps.apple.com/us/app/bonzai-your-local-ai-agent/id6752847988) (proprietary) - [cztomsik/ava](https://github.com/cztomsik/ava) (MIT) - [Dot](https://github.com/alexpinel/Dot) (GPL) - [eva](https://github.com/ylsdamxssjxxdd/eva) (MIT) - [iohub/collama](https://github.com/iohub/coLLaMA) (Apache-2.0) - [janhq/jan](https://github.com/janhq/jan) (AGPL) - [johnbean393/Sidekick](https://github.com/johnbean393/Sidekick) (MIT) - [KanTV](https://github.com/zhouwg/kantv?tab=readme-ov-file) (Apache-2.0) - [KodiBot](https://github.com/firatkiral/kodibot) (GPL) - [llama.vim](https://github.com/ggml-org/llama.vim) (MIT) - [LARS](https://github.com/abgulati/LARS) (AGPL) - [Llama Assistant](https://github.com/vietanhdev/llama-assistant) (GPL) - [LlamaLib](https://github.com/undreamai/LlamaLib) (Apache-2.0) - [LLMFarm](https://github.com/guinmoon/LLMFarm?tab=readme-ov-file) (MIT) - [LLMUnity](https://github.com/undreamai/LLMUnity) (MIT) - [LMStudio](https://lmstudio.ai/) (proprietary) - [LocalAI](https://github.com/mudler/LocalAI) (MIT) - [LostRuins/koboldcpp](https://github.com/LostRuins/koboldcpp) (AGPL) - [MindMac](https://mindmac.app) (proprietary) - [MindWorkAI/AI-Studio](https://github.com/MindWorkAI/AI-Studio) (FSL-1.1-MIT) - [Mobile-Artificial-Intelligence/maid](https://github.com/Mobile-Artificial-Intelligence/maid) (MIT) - [Mozilla-Ocho/llamafile](https://github.com/Mozilla-Ocho/llamafile) (Apache-2.0) - [nat/openplayground](https://github.com/nat/openplayground) (MIT) - [nomic-ai/gpt4all](https://github.com/nomic-ai/gpt4all) (MIT) - [ollama/ollama](https://github.com/ollama/ollama) (MIT) - [oobabooga/text-generation-webui](https://github.com/oobabooga/text-generation-webui) (AGPL) - [PocketPal AI](https://github.com/a-ghorbani/pocketpal-ai) (MIT) - [psugihara/FreeChat](https://github.com/psugihara/FreeChat) (MIT) - [ptsochantaris/emeltal](https://github.com/ptsochantaris/emeltal) (MIT) - [pythops/tenere](https://github.com/pythops/tenere) (AGPL) - [ramalama](https://github.com/containers/ramalama) (MIT) - [semperai/amica](https://github.com/semperai/amica) (MIT) - [withcatai/catai](https://github.com/withcatai/catai) (MIT) - [Autopen](https://github.com/blackhole89/autopen) (GPL)
Tools - [akx/ggify](https://github.com/akx/ggify) – download PyTorch models from Hugging Face Hub and convert them to GGML - [akx/ollama-dl](https://github.com/akx/ollama-dl) – download models from the Ollama library to be used directly with llama.cpp - [crashr/gppm](https://github.com/crashr/gppm) – launch llama.cpp instances utilizing NVIDIA Tesla P40 or P100 GPUs with reduced idle power consumption - [gpustack/gguf-parser](https://github.com/gpustack/gguf-parser-go/tree/main/cmd/gguf-parser) - review/check the GGUF file and estimate the memory usage - [Styled Lines](https://marketplace.unity.com/packages/tools/generative-ai/styled-lines-llama-cpp-model-292902) (proprietary licensed, async wrapper of inference part for game development in Unity3d with pre-built Mobile and Web platform wrappers and a model example) - [unslothai/unsloth](https://github.com/unslothai/unsloth) – 🦥 exports/saves fine-tuned and trained models to GGUF (Apache-2.0)
Infrastructure - [Paddler](https://github.com/intentee/paddler) - Open-source LLMOps platform for hosting and scaling AI in your own infrastructure - [GPUStack](https://github.com/gpustack/gpustack) - Manage GPU clusters for running LLMs - [llama_cpp_canister](https://github.com/onicai/llama_cpp_canister) - llama.cpp as a smart contract on the Internet Computer, using WebAssembly - [llama-swap](https://github.com/mostlygeek/llama-swap) - transparent proxy that adds automatic model switching with llama-server - [Kalavai](https://github.com/kalavai-net/kalavai-client) - Crowdsource end to end LLM deployment at any scale - [llmaz](https://github.com/InftyAI/llmaz) - ☸️ Easy, advanced inference platform for large language models on Kubernetes. - [LLMKube](https://github.com/defilantech/llmkube) - Kubernetes operator for llama.cpp with multi-GPU and Apple Silicon Metal support"
Games - [Lucy's Labyrinth](https://github.com/MorganRO8/Lucys_Labyrinth) - A simple maze game where agents controlled by an AI model will try to trick you.
## Supported backends | Backend | Target devices | | --- | --- | | [Metal](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/docs/build.md#metal-build) | Apple Silicon | | [BLAS](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/docs/build.md#blas-build) | All | | [BLIS](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/docs/backend/BLIS.md) | All | | [SYCL](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/docs/backend/SYCL.md) | Intel GPU | | [OpenVINO [In Progress]](docs/backend/OPENVINO.md) | Intel CPUs, GPUs, and NPUs | | [MUSA](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/docs/build.md#musa) | Moore Threads GPU | | [CUDA](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/docs/build.md#cuda) | Nvidia GPU | | [HIP](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/docs/build.md#hip) | AMD GPU | | [ZenDNN](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/docs/build.md#zendnn) | AMD CPU | | [Vulkan](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/docs/build.md#vulkan) | GPU | | [CANN](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/docs/build.md#cann) | Ascend NPU | | [OpenCL](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/docs/backend/OPENCL.md) | Adreno GPU | | [IBM zDNN](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/docs/backend/zDNN.md) | IBM Z & LinuxONE | | [WebGPU](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/docs/build.md#webgpu) | All | | [RPC](https://github.com/ggml-org/llama.cpp/tree/master/tools/rpc) | All | | [Hexagon [In Progress]](docs/backend/snapdragon/README.md) | Snapdragon | | [VirtGPU](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/docs/backend/VirtGPU.md) | VirtGPU APIR | ## Obtaining and quantizing models The [Hugging Face](https://huggingface.co) platform hosts a [number of LLMs](https://huggingface.co/models?library=gguf&sort=trending) compatible with `llama.cpp`: - [Trending](https://huggingface.co/models?library=gguf&sort=trending) - [LLaMA](https://huggingface.co/models?sort=trending&search=llama+gguf) You can either manually download the GGUF file or directly use any `llama.cpp`-compatible models from [Hugging Face](https://huggingface.co/) or other model hosting sites, by using this CLI argument: `-hf /[:quant]`. For example: ```sh llama-cli -hf ggml-org/gemma-3-1b-it-GGUF ``` By default, the CLI would download from Hugging Face, you can switch to other options with the environment variable `MODEL_ENDPOINT`. The `MODEL_ENDPOINT` must point to a Hugging Face compatible API endpoint. After downloading a model, use the CLI tools to run it locally - see below. `llama.cpp` requires the model to be stored in the [GGUF](https://github.com/ggml-org/ggml/blob/master/docs/gguf.md) file format. Models in other data formats can be converted to GGUF using the `convert_*.py` Python scripts in this repo. The Hugging Face platform provides a variety of online tools for converting, quantizing and hosting models with `llama.cpp`: - Use the [GGUF-my-repo space](https://huggingface.co/spaces/ggml-org/gguf-my-repo) to convert to GGUF format and quantize model weights to smaller sizes - Use the [GGUF-my-LoRA space](https://huggingface.co/spaces/ggml-org/gguf-my-lora) to convert LoRA adapters to GGUF format (more info: https://github.com/ggml-org/llama.cpp/discussions/10123) - Use the [GGUF-editor space](https://huggingface.co/spaces/CISCai/gguf-editor) to edit GGUF meta data in the browser (more info: https://github.com/ggml-org/llama.cpp/discussions/9268) - Use the [Inference Endpoints](https://ui.endpoints.huggingface.co/) to directly host `llama.cpp` in the cloud (more info: https://github.com/ggml-org/llama.cpp/discussions/9669) To learn more about model quantization, [read this documentation](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/tools/quantize/README.md) ## [`llama-cli`](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/tools/cli) #### A CLI tool for accessing and experimenting with most of `llama.cpp`'s functionality. -
Run in conversation mode Models with a built-in chat template will automatically activate conversation mode. If this doesn't occur, you can manually enable it by adding `-cnv` and specifying a suitable chat template with `--chat-template NAME` ```bash llama-cli -m model.gguf # > hi, who are you? # Hi there! I'm your helpful assistant! I'm an AI-powered chatbot designed to assist and provide information to users like you. I'm here to help answer your questions, provide guidance, and offer support on a wide range of topics. I'm a friendly and knowledgeable AI, and I'm always happy to help with anything you need. What's on your mind, and how can I assist you today? # # > what is 1+1? # Easy peasy! The answer to 1+1 is... 2! ```
-
Run in conversation mode with custom chat template ```bash # use the "chatml" template (use -h to see the list of supported templates) llama-cli -m model.gguf -cnv --chat-template chatml # use a custom template llama-cli -m model.gguf -cnv --in-prefix 'User: ' --reverse-prompt 'User:' ```
-
Constrain the output with a custom grammar ```bash llama-cli -m model.gguf -n 256 --grammar-file grammars/json.gbnf -p 'Request: schedule a call at 8pm; Command:' # {"appointmentTime": "8pm", "appointmentDetails": "schedule a a call"} ``` The [grammars/](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/grammars/) folder contains a handful of sample grammars. To write your own, check out the [GBNF Guide](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/grammars/README.md). For authoring more complex JSON grammars, check out https://grammar.intrinsiclabs.ai/
## [`llama-server`](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/tools/server) #### A lightweight, [OpenAI API](https://github.com/openai/openai-openapi) compatible, HTTP server for serving LLMs. -
Start a local HTTP server with default configuration on port 8080 ```bash llama-server -m model.gguf --port 8080 # Basic web UI can be accessed via browser: http://localhost:8080 # Chat completion endpoint: http://localhost:8080/v1/chat/completions ```
-
Support multiple-users and parallel decoding ```bash # up to 4 concurrent requests, each with 4096 max context llama-server -m model.gguf -c 16384 -np 4 ```
-
Enable speculative decoding ```bash # the draft.gguf model should be a small variant of the target model.gguf llama-server -m model.gguf -md draft.gguf ```
-
Serve an embedding model ```bash # use the /embedding endpoint llama-server -m model.gguf --embedding --pooling cls -ub 8192 ```
-
Serve a reranking model ```bash # use the /reranking endpoint llama-server -m model.gguf --reranking ```
-
Constrain all outputs with a grammar ```bash # custom grammar llama-server -m model.gguf --grammar-file grammar.gbnf # JSON llama-server -m model.gguf --grammar-file grammars/json.gbnf ```
## [`llama-perplexity`](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/tools/perplexity) #### A tool for measuring the [perplexity](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/tools/perplexity/README.md) [^1] (and other quality metrics) of a model over a given text. -
Measure the perplexity over a text file ```bash llama-perplexity -m model.gguf -f file.txt # [1]15.2701,[2]5.4007,[3]5.3073,[4]6.2965,[5]5.8940,[6]5.6096,[7]5.7942,[8]4.9297, ... # Final estimate: PPL = 5.4007 +/- 0.67339 ```
-
Measure KL divergence ```bash # TODO ```
[^1]: [https://huggingface.co/docs/transformers/perplexity](https://huggingface.co/docs/transformers/perplexity) ## [`llama-bench`](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/tools/llama-bench) #### Benchmark the performance of the inference for various parameters. -
Run default benchmark ```bash llama-bench -m model.gguf # Output: # | model | size | params | backend | threads | test | t/s | # | ------------------- | ---------: | ---------: | ---------- | ------: | ------------: | -------------------: | # | qwen2 1.5B Q4_0 | 885.97 MiB | 1.54 B | Metal,BLAS | 16 | pp512 | 5765.41 ± 20.55 | # | qwen2 1.5B Q4_0 | 885.97 MiB | 1.54 B | Metal,BLAS | 16 | tg128 | 197.71 ± 0.81 | # # build: 3e0ba0e60 (4229) ```
## [`llama-simple`](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/examples/simple) #### A minimal example for implementing apps with `llama.cpp`. Useful for developers. -
Basic text completion ```bash llama-simple -m model.gguf # Hello my name is Kaitlyn and I am a 16 year old girl. I am a junior in high school and I am currently taking a class called "The Art of ```
## Contributing - Contributors can open PRs - Collaborators will be invited based on contributions - Maintainers can push to branches in the `llama.cpp` repo and merge PRs into the `master` branch - Any help with managing issues, PRs and projects is very appreciated! - See [good first issues](https://github.com/ggml-org/llama.cpp/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) for tasks suitable for first contributions - Read the [CONTRIBUTING.md](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/CONTRIBUTING.md) for more information - Make sure to read this: [Inference at the edge](https://github.com/ggml-org/llama.cpp/discussions/205) - A bit of backstory for those who are interested: [Changelog podcast](https://changelog.com/podcast/532) ## Other documentation - [cli](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/tools/cli/README.md) - [completion](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/tools/completion/README.md) - [server](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/tools/server/README.md) - [GBNF grammars](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/grammars/README.md) #### Development documentation - [How to build](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/docs/build.md) - [Running on Docker](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/docs/docker.md) - [Build on Android](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/docs/android.md) - [Multi-GPU usage](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/docs/multi-gpu.md) - [Performance troubleshooting](https://github.com/spiritbuun/buun-llama-cpp/blob/HEAD/docs/development/token_generation_performance_tips.md) - [GGML tips & tricks](https://github.com/ggml-org/llama.cpp/wiki/GGML-Tips-&-Tricks) #### Seminal papers and background on the models If your issue is with model generation quality, then please at least scan the following links and papers to understand the limitations of LLaMA models. This is especially important when choosing an appropriate model size and appreciating both the significant and subtle differences between LLaMA models and ChatGPT: - LLaMA: - [Introducing LLaMA: A foundational, 65-billion-parameter large language model](https://ai.facebook.com/blog/large-language-model-llama-meta-ai/) - [LLaMA: Open and Efficient Foundation Language Models](https://arxiv.org/abs/2302.13971) - GPT-3 - [Language Models are Few-Shot Learners](https://arxiv.org/abs/2005.14165) - GPT-3.5 / InstructGPT / ChatGPT: - [Aligning language models to follow instructions](https://openai.com/research/instruction-following) - [Training language models to follow instructions with human feedback](https://arxiv.org/abs/2203.02155) ## XCFramework The XCFramework is a precompiled version of the library for iOS, visionOS, tvOS, and macOS. It can be used in Swift projects without the need to compile the library from source. For example: ```swift // swift-tools-version: 5.10 // The swift-tools-version declares the minimum version of Swift required to build this package. import PackageDescription let package = Package( name: "MyLlamaPackage", targets: [ .executableTarget( name: "MyLlamaPackage", dependencies: [ "LlamaFramework" ]), .binaryTarget( name: "LlamaFramework", url: "https://github.com/ggml-org/llama.cpp/releases/download/b5046/llama-b5046-xcframework.zip", checksum: "c19be78b5f00d8d29a25da41042cb7afa094cbf6280a225abe614b03b20029ab" ) ] ) ``` The above example is using an intermediate build `b5046` of the library. This can be modified to use a different version by changing the URL and checksum. ## Completions Command-line completion is available for some environments. #### Bash Completion ```bash $ build/bin/llama-cli --completion-bash > ~/.llama-completion.bash $ source ~/.llama-completion.bash ``` Optionally this can be added to your `.bashrc` or `.bash_profile` to load it automatically. For example: ```console $ echo "source ~/.llama-completion.bash" >> ~/.bashrc ``` ## Dependencies - [yhirose/cpp-httplib](https://github.com/yhirose/cpp-httplib) - Single-header HTTP server, used by `llama-server` - MIT license - [stb-image](https://github.com/nothings/stb) - Single-header image format decoder, used by multimodal subsystem - Public domain - [nlohmann/json](https://github.com/nlohmann/json) - Single-header JSON library, used by various tools/examples - MIT License - [miniaudio.h](https://github.com/mackron/miniaudio) - Single-header audio format decoder, used by multimodal subsystem - Public domain - [subprocess.h](https://github.com/sheredom/subprocess.h) - Single-header process launching solution for C and C++ - Public domain