llamar.cpp

llamar.cpp is a high-performance research extension of llama.cpp implementing inference-time latent recurrence and Orthogonal Residual Subspace Decomposition (ORSD-Core) for deep autoregressive reasoning.

Rather than allocating more output tokens to a chain-of-thought scratchpad (which linearly expands KV cache consumption and inference latency), llamar.cpp deliberates in latent space across a designated layer interval $[L_{\text{lo}} \dots L_{\text{hi}}]$ for $T$ iterations per token. The implementation adds zero weight parameters, requires no fine-tuning, introduces zero memory bloat, and is disabled by default (recurrent_t = 1 yields byte-for-byte identical upstream output).

---

Architectural Core

1. KV Cache Isolation Engine (store_kv = false)

In standard Transformer autoregressive decoding, each attention layer writes Key and Value projections into the KV cache at the current token offset. In un-isolated recurrent passes, evaluating layer $L$ multiple times causes secondary and tertiary passes to overwrite or pollute the KV cache with transient latent representations. This causes catastrophic syntactic degradation in downstream tokens, breaking complex nested state machines (e.g. AST evaluators, recursive parsers, diff engines).

llamar.cpp solves this through strict hardware-level KV cache isolation:

Token t:
├── Prelude [0 .. lo-1]:
│   └── Forward pass straight through -> produces anchor_e
├── Pass 0 (Pristine Baseline, t = 0):
│   └── Core [lo .. hi] with store_kv = true
│       └── Writes pristine K_0, V_0 to autoregressive KV cache
│       └── Computes baseline representation h^(0) and delta_0 = h^(0) - anchor_e
├── Deliberation Passes (t = 1 .. T-1):
│   └── Core [lo .. hi] with store_kv = false
│       └── Attends to full history + pristine K_0, V_0 WITHOUT modifying cache
│       └── Computes raw candidate delta_t = Decoder(h^(t-1)) - h^(t-1)
│       └── Dispatches delta_t to Recurrent Decomposition Engine (ORSD / SNC / CAV / DSCC)
│       └── Updates h^(t) = h^(t-1) + gamma * delta_deliberation
└── Coda [hi+1 .. n_layer-1]:
    └── Forward pass straight through from h^(T-1) to final logits

• Pass 0 ($t=0$, store_kv = true): Computes nominal forward pass representations and commits pristine $K_0, V_0$ vectors to the KV cache for the current token position.
• Passes $t \ge 1$ (store_kv = false): Deliberation passes execute self-attention reading from the pristine KV cache, but never write to or corrupt the KV memory. Downstream tokens retain 100% pristine attention history.

---

2. ORSD-Core: Orthogonal Residual Subspace Decomposition (Mode 1)

In naive recurrence, candidate updates $\Delta_t = \text{Decoder}(h_t) - h_t$ exhibit high cosine similarity ($\cos(\Delta_t, \Delta_0) \approx 0.85 - 0.95$) with prior passes. Over 90% of the additional compute is wasted re-evaluating already extracted features, leading to collinear feature collapse and activation norm runaway.

ORSD-Core enforces Modified Gram-Schmidt Orthogonalization against the historical thought subspace $\mathcal{U}{t-1} = \text{span}{u_0, \dots, u{t-1}}$ (where $u_0 = \Delta_0$):

$$\Delta_t^\perp = \Delta_t - \sum_{j < t} \frac{\langle \Delta_t, u_j \rangle}{|u_j|^2 + \epsilon} u_j$$

Scale-Invariant Relative Energy Matching

Static scalar updates ($h \leftarrow h + \gamma \Delta^\perp$) suffer from high-Q resonance fragility due to token-level norm variance ($|\Delta^\perp|$ varies from 0.8 to 25.0 across tokens). ORSD-Core normalizes the orthogonal increment and scales it to the RMS energy of the current hidden state:

$$\Delta_{\text{norm}} = \text{RMSNorm}(\Delta_t^\perp, \epsilon)$$ $$\Delta_{\text{scaled}} = \Delta_{\text{norm}} \odot |h|_{\text{rms}}$$ $$h_{t+1} = h_t + \gamma \cdot \Delta_{\text{scaled}}$$

The parameter $\gamma$ (--recurrent-gate, default 0.08) controls the exact invariant percentage of hidden state energy injected during deliberation, providing robust convergence across arbitrary sequence lengths and prompts.

---

3. Recurrence Modes

Mode ID	Name	Mathematical Formulation	Target Failure Mode
0	Vanilla LTI	$h_{t+1} = A \cdot h_t + B \cdot e + \gamma \cdot \Delta_t$	Baseline linear time-invariant anchor injection
1	ORSD-Core	$\Delta_t^\perp = \Delta_t - \text{proj}{\mathcal{U}{t-1}}(\Delta_t)$; RMS energy matched	90% Collinear feature collapse & activation runaway
2	SNC-MD	$m_t = \mu m_{t-1} + (1-\mu)\Delta_t$; $\text{RMSNorm}(m_t)$	Heavy-ball Lyapunov momentum damping
3	REG-CAV	$\Delta_{\text{gated}} = \Delta_t \cdot \text{clamp}(\cos(h, e), 0, 1)$	Bilinear contrastive anchor verification
4	DSCC-Engine	Fast stream $h$ coupled with slow latent integrator $v_{\text{slow}}$	Working memory preservation & dual-rate synthesis

---

Configuration & CLI Options

Recurrence parameters are configured via CLI flags, environment variables, or config files:

Flag	Default	Description
--recurrent-t <T>	1	Total applications of core layers per token ($1 = \text{vanilla disabled}$, $2 = 1 \text{ deliberation pass}$).
--recurrent-layer <L>	-1	Start index of the recurrent core (defaults to reasoning centroid $\approx 0.38 \cdot N$).
--recurrent-layer-b <L_b>	-1	End index for compound core $[L \dots L_b]$ (e.g. layers 13 and 14).
--recurrent-mode <mode>	0	Recurrence algorithm: 0 (LTI), 1 or orsd (ORSD-Core), 2 (SNC), 3 (CAV), 4 (DSCC).
--recurrent-gate <gamma>	1.0	Deliberation injection factor $\gamma$ (use 0.08 for energy-matched ORSD).
--recurrent-config <path>	""	Path to JSON or .rlang structured configuration.

Example CLI Invocations

# 1. Nominal upstream baseline (byte-for-byte identical to stock llama.cpp)
./build-cuda-vnni/bin/llama-cli -m model.gguf -p "Implement Tarjan's SCC algorithm"

# 2. ORSD-Core with KV Cache Isolation (Qwen2.5-Coder-7B, layers 13-14, gamma=0.08)
./build-cuda-vnni/bin/llama-cli -m qwen2.5-coder-7b-instruct-q4_k_m.gguf \
    --recurrent-t 2 \
    --recurrent-layer 13 \
    --recurrent-layer-b 14 \
    --recurrent-mode 1 \
    --recurrent-gate 0.08 \
    -p "..."

# 3. Via configuration file
./build-cuda-vnni/bin/llama-cli -m model.gguf --recurrent-config recurrent_configs/orsd_balanced.json -p "..."

---

Silicon-Verified Empirical Results & Academic Research

Note

Academic Preprint Available: Complete mathematical derivations, proofs of spectral manifold collapse, and ablation studies are detailed in our paper:
📄 Read arXiv Preprint (Markdown) | Download Preprint PDF | LaTeX Source

Target Hardware: NVIDIA GeForce RTX 3050 Laptop GPU (GA107, 6.09 GB VRAM, sm_86 Ampere, CUDA Backend)
Evaluated Model: Qwen2.5-Coder-7B-Instruct-Q4_K_M + qwen_recurrent_step100.gguf

1. Comparative Evaluation: Baseline vs. LoRA vs. ORSD Deliberation

Evaluated across hardened algorithmic systems coding challenges and probabilistic logic deduction:

Configuration	Passed Tasks	Accuracy (%)	Deliberation Latency	Key Empirical Finding
Base ($T=1$, Vanilla No-LoRA)	5 / 9	55.6%	167.3s	Fails AVL OOP interface & NFA recursion
LoRA ($T=1$, Step-100)	5 / 9	55.6%	182.8s	Fixes AVL OOP (insert(self, val)); regresses Interval Tree
LoRA Recurrent ORSD ($T=2$, $\gamma=0.20$, Mode 1)	6 / 9	66.7% 🚀	201.6s	Fixes AVL OOP + Restores Interval Tree (+11.1% Net Gain)
LoRA Recurrent Vanilla ($T=2$, $\gamma=0.50$, Mode 0)	2 / 9	22.2% 💥	195.2s	Catastrophic Collapse: Bytecode VM, Lisp, and Tarjan fail

2. Spectral Manifold Collapse (SVD Audit on Layer 13)

SVD analysis on Qwen2.5-Coder-7B weights ($W_{\text{down}} W_{\text{gate}}$, $\kappa = 42{,}487$, $\sigma_{\max} = 17.38$) proves that unconstrained recurrence behaves as power iteration toward dominant singular vectors:

Recurrence Iteration	Vector Norm $|h|$	Cosine Sim vs $h^{(0)}$	Token Matrix Rank	Degradation Mechanism
Nominal ($T=1$)	59.87	1.000	14.2 / 16	Pristine Baseline
Naive Loop ($T=2$)	241.15	0.412	6.4 / 16	Collinear Feature Drift
Naive Loop ($T=4$)	982.40	0.142	2.1 / 16	Severe Manifold Collapse
Naive Loop ($T=8$)	1823.08	0.089	1.8 / 16	Catastrophic Norm Explosion
ORSD ($T=2$, Ours)	61.20	0.965	14.0 / 16	Invariant Representation Protected
ORSD ($T=4$, Ours)	63.85	0.912	13.7 / 16	Full Rank Preserved via Gram-Schmidt

3. The 13 Brutal Systems Coding Benchmark (benchmarks/comprehensive/dataset.json)

#	Task ID & System Description	Vanilla $T=1$ (Baseline)	Legacy $T=2$ (No KV Isolation)	ORSD-Core $T=2$ (Isolated KV + $\gamma=0.08$)	Impact
1	code_01_regex_nfa (Custom recursive NFA engine)	❌ FAIL	❌ FAIL	❌ FAIL	—
2	code_02_bytecode_vm (Stack-based VM with jumps/ALU)	✅ PASS	✅ PASS	✅ PASS	Preserved
3	code_03_lazy_segment_tree (Range updates & sums)	❌ FAIL	❌ FAIL	❌ FAIL	—
4	code_04_lisp_interpreter (Lexical closures & AST)	✅ PASS	❌ FAIL	✅ PASS	Protected by KV Isolation
5	code_05_dinic_max_flow (Network maximum flow)	✅ PASS	❌ FAIL	✅ PASS	Protected by KV Isolation
6	code_06_diff_patch_engine (LCS shortest edit script)	✅ PASS	❌ FAIL	✅ PASS	Protected by KV Isolation
7	code_07_avl_tree_invariants (Strict balance factor $\le 1$)	❌ FAIL	❌ FAIL	❌ FAIL	—
8	code_08_transactional_key_value (Nested commit/rollback)	✅ PASS	✅ PASS	✅ PASS	Preserved
9	code_09_expression_calculator (Shunting-yard operator precedence)	❌ FAIL	❌ FAIL	❌ FAIL	—
10	code_10_interval_tree_overlap (Range overlap queries)	❌ FAIL	❌ FAIL	❌ FAIL	—
11	code_11_topological_lexical_kahn (Min-heap Kahn sort)	✅ PASS	✅ PASS	✅ PASS	Preserved
12	code_12_tarjan_scc (Strongly connected components & lowlink)	❌ FAIL	❌ FAIL	✅ PASS	Pure Algorithmic Win (+1)
13	code_13_knapsack_with_reconstruction (0/1 DP backtrace)	✅ PASS	❌ FAIL	✅ PASS	Protected by KV Isolation
SUM	Total Solved Tasks	7 / 13 (53.8%)	3 / 13 (23.1%)	8 / 13 (61.5%)	+7.7% Net Gain

4. Key Systems Takeaways

1. Zero-Overhead KV Cache Isolation: Writing secondary key-value projections into the autoregressive KV cache poisons the history for future tokens. Enforcing store_kv = false on passes $t \ge 1$ completely prevents historical corruption with 0 extra VRAM footprint.
2. Inductive Depth via Orthogonality: Standard recurrence produces redundant collinear activations. ORSD-Core projects the deliberation delta onto the orthogonal complement of previous passes, giving the model the exact mathematical depth required to solve tarjan_scc and interval_tree without hallucination.
3. Contraction LoRA Fine-Tuning: Eliminating double-residual inflation through a pure delta objective allows training recurrent cores in $&lt; 3.6$ GB VRAM, converging in 100 steps on commodity laptops.
4. Hardware Throughput: On RTX 3050 Laptop GPU, executing $T=2$ on layer 13 sustains 26.2 to 34.0 t/s, achieving deep deliberation with minimal latency impact.

---

Additional Engine Optimizations

• MoE fused gate+up (-fgu). Concatenates the MoE gate_exps and up_exps tensors during graph construction into a single gate_up GEMM per layer, halving the memory traffic and barrier sync of the two-projection path (src/llama-context.cpp).
• MoE prefill offload. Host pinned-memory registration (GGML_CUDA_REGISTER_HOST=1) and asynchronous expert prefetching (GGML_SCHED_PREFETCH_EXPERTS=1) reduce PCIe transfer stalls for partially-offloaded MoE models; the latter requires disabling CUDA graphs (GGML_CUDA_DISABLE_GRAPHS=1).
• Expert batching / token prefetching. Weight-major dequantisation and hardware prefetching inside the expert routing loops in the CPU backend.

Build

Builds follow upstream llama.cpp. The recurrence feature lives entirely in the model graph builders (src/models/*.cpp) and needs no special compile-time flag.

mkdir build && cd build
cmake .. -DGGML_CUDA=ON
make -j$(nproc) llama-cli llama-server llama-bench

See docs/build.md and docs/backend for CUDA, Metal, ROCm, Vulkan, SYCL, and CPU backend options.

---

Manifesto / ggml / ops / maintainer PRs

LLM inference in C/C++

Recent API changes

• Changelog for libllama API
• Changelog for llama-server REST API

Hot topics

• Hugging Face cache migration: models downloaded with -hf are now stored in the standard Hugging Face cache directory, enabling sharing with other HF tools.
• guide : using the new WebUI of llama.cpp
• guide : running gpt-oss with llama.cpp
• [FEEDBACK] Better packaging for llama.cpp to support downstream consumers 🤗
• Support for the gpt-oss model with native MXFP4 format has been added | PR | Collaboration with NVIDIA | Comment
• Multimodal support arrived in llama-server: #12898 | documentation
• VS Code extension for FIM completions: https://github.com/ggml-org/llama.vscode
• Vim/Neovim plugin for FIM completions: https://github.com/ggml-org/llama.vim
• Hugging Face Inference Endpoints now support GGUF out of the box! ggml-org#9669
• Hugging Face GGUF editor: discussion | tool
• WebGPU support is now available in the browser, see a blog/demo introducing it here.

---

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
• Run with Docker - see our Docker documentation
• Download pre-built binaries from the releases page
• Build from source by cloning this repository - check out our build guide

Once installed, you'll need a model to work with. Head to the Obtaining and quantizing models section to learn more.

Example command:

# 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 library.

Models

Typically finetunes of the base models below are supported as well.

Instructions for adding support for new models: HOWTO-add-model.md

Text-only

• LLaMA 🦙
• LLaMA 2 🦙🦙
• LLaMA 3 🦙🦙🦙
• Mistral 7B
• Mixtral MoE
• DBRX
• Jamba
• Falcon
• Chinese LLaMA / Alpaca and Chinese LLaMA-2 / Alpaca-2
• Vigogne (French)
• BERT
• Koala
• Baichuan 1 & 2 + derivations
• Aquila 1 & 2
• Starcoder models
• Refact
• MPT
• Bloom
• Yi models
• StableLM models
• Deepseek models
• Qwen models
• PLaMo-13B
• Phi models
• PhiMoE
• GPT-2
• Orion 14B
• InternLM2
• CodeShell
• Gemma
• Mamba
• Grok-1
• Xverse
• Command-R models
• SEA-LION
• GritLM-7B + GritLM-8x7B
• OLMo
• OLMo 2
• OLMoE
• Granite models
• GPT-NeoX + Pythia
• Snowflake-Arctic MoE
• Smaug
• Poro 34B
• Bitnet b1.58 models
• Flan T5
• Open Elm models
• ChatGLM3-6b + ChatGLM4-9b + GLMEdge-1.5b + GLMEdge-4b
• GLM-4-0414
• SmolLM
• EXAONE-3.0-7.8B-Instruct
• FalconMamba Models
• Jais
• Bielik-11B-v2.3
• RWKV-7
• RWKV-6
• QRWKV-6
• GigaChat-20B-A3B
• Trillion-7B-preview
• Ling models
• Liquid LFM2 models
• Liquid LFM2.5 models
• Liquid Nanos
• Hunyuan models
• BailingMoeV2 (Ring/Ling 2.0) models
• Mellum models

Multimodal

• LLaVA 1.5 models, LLaVA 1.6 models
• BakLLaVA
• Obsidian
• ShareGPT4V
• MobileVLM 1.7B/3B models
• Yi-VL
• Mini CPM
• Moondream
• Bunny
• GLM-EDGE
• Qwen2-VL
• LFM2-VL

Bindings

• Python: ddh0/easy-llama
• Python: abetlen/llama-cpp-python
• Go: go-skynet/go-llama.cpp
• Node.js: withcatai/node-llama-cpp
• JS/TS (llama.cpp server client): lgrammel/modelfusion
• JS/TS (Programmable Prompt Engine CLI): offline-ai/cli
• JavaScript/Wasm (works in browser): tangledgroup/llama-cpp-wasm
• Typescript/Wasm (nicer API, available on npm): ngxson/wllama
• Ruby: yoshoku/llama_cpp.rb
• Ruby: docusealco/rllama
• Rust (more features): edgenai/llama_cpp-rs
• Rust (nicer API): mdrokz/rust-llama.cpp
• Rust (more direct bindings): utilityai/llama-cpp-rs
• Rust (automated build from crates.io): ShelbyJenkins/llm_client
• C#/.NET: SciSharp/LLamaSharp
• C#/VB.NET (more features - community license): LM-Kit.NET
• Scala 3: donderom/llm4s
• Clojure: phronmophobic/llama.clj
• React Native: mybigday/llama.rn
• Java: kherud/java-llama.cpp
• Java: QuasarByte/llama-cpp-jna
• Zig: deins/llama.cpp.zig
• Flutter/Dart: netdur/llama_cpp_dart
• Flutter: xuegao-tzx/Fllama
• PHP (API bindings and features built on top of llama.cpp): distantmagic/resonance (more info)
• Guile Scheme: guile_llama_cpp
• Swift srgtuszy/llama-cpp-swift
• Swift ShenghaiWang/SwiftLlama
• Delphi Embarcadero/llama-cpp-delphi
• Go (no CGo needed): hybridgroup/yzma
• Android: llama.android

UIs

(to have a project listed here, it should clearly state that it depends on llama.cpp)

• AI Sublime Text plugin (MIT)
• BonzAI App (proprietary)
• cztomsik/ava (MIT)
• Dot (GPL)
• eva (MIT)
• iohub/collama (Apache-2.0)
• janhq/jan (AGPL)
• johnbean393/Sidekick (MIT)
• KanTV (Apache-2.0)
• KodiBot (GPL)
• llama.vim (MIT)
• LARS (AGPL)
• Llama Assistant (GPL)
• LlamaLib (Apache-2.0)
• LLMFarm (MIT)
• LLMUnity (MIT)
• LMStudio (proprietary)
• LocalAI (MIT)
• LostRuins/koboldcpp (AGPL)
• MindMac (proprietary)
• MindWorkAI/AI-Studio (FSL-1.1-MIT)
• Mobile-Artificial-Intelligence/maid (MIT)
• Mozilla-Ocho/llamafile (Apache-2.0)
• nat/openplayground (MIT)
• nomic-ai/gpt4all (MIT)
• ollama/ollama (MIT)
• oobabooga/text-generation-webui (AGPL)
• PocketPal AI (MIT)
• psugihara/FreeChat (MIT)
• ptsochantaris/emeltal (MIT)
• pythops/tenere (AGPL)
• ramalama (MIT)
• semperai/amica (MIT)
• withcatai/catai (MIT)
• Autopen (GPL)

Tools

• akx/ggify – download PyTorch models from Hugging Face Hub and convert them to GGML
• akx/ollama-dl – download models from the Ollama library to be used directly with llama.cpp
• crashr/gppm – launch llama.cpp instances utilizing NVIDIA Tesla P40 or P100 GPUs with reduced idle power consumption
• gpustack/gguf-parser - review/check the GGUF file and estimate the memory usage
• Styled Lines (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 – 🦥 exports/saves fine-tuned and trained models to GGUF (Apache-2.0)

Infrastructure

• Paddler - Open-source LLMOps platform for hosting and scaling AI in your own infrastructure
• GPUStack - Manage GPU clusters for running LLMs
• llama_cpp_canister - llama.cpp as a smart contract on the Internet Computer, using WebAssembly
• llama-swap - transparent proxy that adds automatic model switching with llama-server
• Kalavai - Crowdsource end to end LLM deployment at any scale
• llmaz - ☸️ Easy, advanced inference platform for large language models on Kubernetes.
• LLMKube - Kubernetes operator for llama.cpp with multi-GPU and Apple Silicon Metal support"

Games

• Lucy's Labyrinth - A simple maze game where agents controlled by an AI model will try to trick you.

Supported backends

Backend	Target devices
Metal	Apple Silicon
BLAS	All
BLIS	All
SYCL	Intel GPU
OpenVINO [In Progress]	Intel CPUs, GPUs, and NPUs
MUSA	Moore Threads GPU
CUDA	Nvidia GPU
HIP	AMD GPU
ZenDNN	AMD CPU
Vulkan	GPU
CANN	Ascend NPU
OpenCL	Adreno GPU
IBM zDNN	IBM Z & LinuxONE
WebGPU	All
RPC	All
Hexagon [In Progress]	Snapdragon
VirtGPU	VirtGPU APIR

Obtaining and quantizing models

The Hugging Face platform hosts a number of LLMs compatible with llama.cpp:

• Trending
• LLaMA

You can either manually download the GGUF file or directly use any llama.cpp-compatible models from Hugging Face or other model hosting sites, by using this CLI argument: -hf <user>/<model>[:quant]. For example:

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 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 to convert to GGUF format and quantize model weights to smaller sizes
• Use the GGUF-my-LoRA space to convert LoRA adapters to GGUF format (more info: ggml-org#10123)
• Use the GGUF-editor space to edit GGUF meta data in the browser (more info: ggml-org#9268)
• Use the Inference Endpoints to directly host llama.cpp in the cloud (more info: ggml-org#9669)

To learn more about model quantization, read this documentation

llama-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

  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

  # 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

  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/ folder contains a handful of sample grammars. To write your own, check out the GBNF Guide.

  For authoring more complex JSON grammars, check out https://grammar.intrinsiclabs.ai/

llama-server

A lightweight, OpenAI API compatible, HTTP server for serving LLMs.

• Start a local HTTP server with default configuration on port 8080

  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

  # up to 4 concurrent requests, each with 4096 max context
  llama-server -m model.gguf -c 16384 -np 4

• Enable speculative decoding

  # 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

  # use the /embedding endpoint
  llama-server -m model.gguf --embedding --pooling cls -ub 8192

• Serve a reranking model

  # use the /reranking endpoint
  llama-server -m model.gguf --reranking

• Constrain all outputs with a grammar

  # custom grammar
  llama-server -m model.gguf --grammar-file grammar.gbnf
  
  # JSON
  llama-server -m model.gguf --grammar-file grammars/json.gbnf

llama-perplexity

A tool for measuring the perplexity ¹ (and other quality metrics) of a model over a given text.

• Measure the perplexity over a text file

  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

  # TODO

llama-bench

Benchmark the performance of the inference for various parameters.

• Run default benchmark

  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

A minimal example for implementing apps with llama.cpp. Useful for developers.

• Basic text completion

  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 for tasks suitable for first contributions
• Read the CONTRIBUTING.md for more information
• Make sure to read this: Inference at the edge
• A bit of backstory for those who are interested: Changelog podcast

Other documentation

• cli
• completion
• server
• GBNF grammars

Development documentation

• How to build
• Running on Docker
• Build on Android
• Multi-GPU usage
• Performance troubleshooting
• 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
  • LLaMA: Open and Efficient Foundation Language Models
• GPT-3
  • Language Models are Few-Shot Learners
• GPT-3.5 / InstructGPT / ChatGPT:
  • Aligning language models to follow instructions
  • Training language models to follow instructions with human feedback

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-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

$ 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:

$ echo "source ~/.llama-completion.bash" >> ~/.bashrc

Dependencies

• yhirose/cpp-httplib - Single-header HTTP server, used by llama-server - MIT license
• stb-image - Single-header image format decoder, used by multimodal subsystem - Public domain
• nlohmann/json - Single-header JSON library, used by various tools/examples - MIT License
• miniaudio.h - Single-header audio format decoder, used by multimodal subsystem - Public domain
• subprocess.h - Single-header process launching solution for C and C++ - Public domain

Footnotes

1. https://huggingface.co/docs/transformers/perplexity ↩