Repository files navigation

Manifesto /ggml /ops

LLM inference in C/C++

• Changelog forlibllama API
• Changelog forllama-server REST API

• Hot PRs:All |Open
• Multimodal support arrived inllama-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
• Introducing GGUF-my-LoRA#10123
• Hugging Face Inference Endpoints now support GGUF out of the box!#9669
• Hugging Face GGUF editor:discussion |tool

Getting started with llama.cpp is straightforward. Here are several ways to install it on your machine:

• Installllama.cpp usingbrew, nix or winget
• Run with Docker - see ourDocker documentation
• Download pre-built binaries from thereleases page
• Build from source by cloning this repository - check outour build guide

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

Example command:

# Use a local model filellama-cli -m my_model.gguf# Or download and run a model directly from Hugging Facellama-cli -hf ggml-org/gemma-3-1b-it-GGUF# Launch OpenAI-compatible API serverllama-server -hf ggml-org/gemma-3-1b-it-GGUF

The main goal ofllama.cpp is to enable LLM inference with minimal setup and state-of-the-art performance on a widerange 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
• 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

Thellama.cpp project is the main playground for developing new features for theggml library.

TheHugging Face platform hosts anumber of LLMs compatible withllama.cpp:

• Trending
• LLaMA

You can either manually download the GGUF file or directly use anyllama.cpp-compatible models fromHugging Face or other model hosting sites, such asModelScope, 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 variableMODEL_ENDPOINT. For example, you may opt to downloading model checkpoints from ModelScope or other model sharing communities by setting the environment variable, e.g.MODEL_ENDPOINT=https://www.modelscope.cn/.

After downloading a model, use the CLI tools to run it locally - see below.

llama.cpp requires the model to be stored in theGGUF file format. Models in other data formats can be converted to GGUF using theconvert_*.py Python scripts in this repo.

The Hugging Face platform provides a variety of online tools for converting, quantizing and hosting models withllama.cpp:

• Use theGGUF-my-repo space to convert to GGUF format and quantize model weights to smaller sizes
• Use theGGUF-my-LoRA space to convert LoRA adapters to GGUF format (more info:#10123)
• Use theGGUF-editor space to edit GGUF meta data in the browser (more info:#9268)
• Use theInference Endpoints to directly hostllama.cpp in the cloud (more info:#9669)

To learn more about model quantization,read this documentation

• 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 templatellama-cli -m model.gguf -cnv --in-prefix'User:' --reverse-prompt'User:'

• Run simple text completion

  To disable conversation mode explicitly, use-no-cnv

  llama-cli -m model.gguf -p"I believe the meaning of life is" -n 128 -no-cnv# I believe the meaning of life is to find your own truth and to live in accordance with it. For me, this means being true to myself and following my passions, even if they don't align with societal expectations. I think that's what I love about yoga – it's not just a physical practice, but a spiritual one too. It's about connecting with yourself, listening to your inner voice, and honoring your own unique journey.

• 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"}

  Thegrammars/ folder contains a handful of sample grammars. To write your own, check out theGBNF Guide.

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

• 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 contextllama-server -m model.gguf -c 16384 -np 4

• Enable speculative decoding

  # the draft.gguf model should be a small variant of the target model.ggufllama-server -m model.gguf -md draft.gguf

• Serve an embedding model

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

• Serve a reranking model

  # use the /reranking endpointllama-server -m model.gguf --reranking

• Constrain all outputs with a grammar

  # custom grammarllama-server -m model.gguf --grammar-file grammar.gbnf# JSONllama-server -m model.gguf --grammar-file grammars/json.gbnf

• 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

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

• Run a model with a specific prompt (by default it's pulled from Ollama registry)

  llama-run granite-code

• 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

• Contributors can open PRs
• Collaborators can push to branches in thellama.cpp repo and merge PRs into themaster branch
• Collaborators will be invited based on contributions
• Any help with managing issues, PRs and projects is very appreciated!
• Seegood first issues for tasks suitable for first contributions
• Read theCONTRIBUTING.md for more information
• Make sure to read this:Inference at the edge
• A bit of backstory for those who are interested:Changelog podcast

• main (cli)
• server
• GBNF grammars

• How to build
• Running on Docker
• Build on Android
• Performance troubleshooting
• GGML tips & tricks

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

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 thelibrary 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 PackageDescriptionletpackage=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 buildb5046 of the library. This can be modifiedto use a different version by changing the URL and checksum.

Command-line completion is available for some environments.

$ 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 itautomatically. For example:

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

• yhirose/cpp-httplib - Single-header HTTP server, used byllama-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
• minja - Minimal Jinja parser in C++, used by various tools/examples - MIT License
• linenoise.cpp - C++ library that provides readline-like line editing capabilities, used byllama-run - BSD 2-Clause License
• curl - Client-side URL transfer library, used by various tools/examples -CURL License
• miniaudio.h - Single-header audio format decoder, used by multimodal subsystem - Public domain