Skip to content

fewtarius/CachyLLama

BranchesTags
 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

9,665 Commits
.clio
.clio
 
 
.devops
.devops
 
 
.gemini
.gemini
 
 
.github
.github
 
 
.pi/gg
.pi/gg
 
 
app
app
 
 
benches
benches
 
 
ci
ci
 
 
cmake
cmake
 
 
common
common
 
 
conversion
conversion
 
 
docs
docs
 
 
examples
examples
 
 
ggml
ggml
 
 
gguf-py
gguf-py
 
 
grammars
grammars
 
 
include
include
 
 
licenses
licenses
 
 
media
media
 
 
models
models
 
 
pocs
pocs
 
 
requirements
requirements
 
 
scripts
scripts
 
 
src
src
 
 
tests
tests
 
 
tools
tools
 
 
vendor
vendor
 
 
.clang-format
.clang-format
 
 
.clang-tidy
.clang-tidy
 
 
.dockerignore
.dockerignore
 
 
.ecrc
.ecrc
 
 
.editorconfig
.editorconfig
 
 
.flake8
.flake8
 
 
.gitignore
.gitignore
 
 
.gitmodules
.gitmodules
 
 
.pre-commit-config.yaml
.pre-commit-config.yaml
 
 
AGENTS.md
AGENTS.md
 
 
AUTHORS
AUTHORS
 
 
CLAUDE.md
CLAUDE.md
 
 
CMakeLists.txt
CMakeLists.txt
 
 
CMakePresets.json
CMakePresets.json
 
 
CODEOWNERS
CODEOWNERS
 
 
CONTRIBUTING.md
CONTRIBUTING.md
 
 
LICENSE
LICENSE
 
 
Makefile
Makefile
 
 
README.md
README.md
 
 
SECURITY.md
SECURITY.md
 
 
build-xcframework.sh
build-xcframework.sh
 
 
convert_hf_to_gguf.py
convert_hf_to_gguf.py
 
 
convert_hf_to_gguf_update.py
convert_hf_to_gguf_update.py
 
 
convert_llama_ggml_to_gguf.py
convert_llama_ggml_to_gguf.py
 
 
convert_lora_to_gguf.py
convert_lora_to_gguf.py
 
 
flake.nix
flake.nix
 
 
mypy.ini
mypy.ini
 
 
pyproject.toml
pyproject.toml
 
 
pyrightconfig.json
pyrightconfig.json
 
 
requirements.txt
requirements.txt
 
 
test_kv_page_manager.cpp
test_kv_page_manager.cpp
 
 
ty.toml
ty.toml
 
 

Repository files navigation

CachyLLama

A fork of llama.cpp focused on running local LLM inference on lower-spec hardware - AMD APUs, integrated GPUs, handhelds, anything with shared system memory. CachyLLama adds a persistent on-disk KV cache so agentic AI workloads (where every request re-sends thousands of tokens of system prompt and tool definitions) stay usable when the model has to evaluate prompts on hardware that can only generate 5-20 tokens per second.

License: MIT Upstream: ggml-org/llama.cpp Parent project: fewtarius/llama-ai

CachyLLama parent project / CLIO agentic client / Upstream llama.cpp / ggml

What CachyLLama is

CachyLLama is the C++ inference engine in the CachyLLama ecosystem. It tracks upstream llama.cpp master closely and includes everything upstream supports. The CachyLLama additions target one specific use case: agentic AI on AMD APU hardware where prompt evaluation dominates total response time.

If you want the runner scripts, GPU/CPU detection, benchmark harness, and the end-to-end install, use the parent project. If you want just the inference engine with the persistent KV cache and the hybrid-MoE fixes, you're in the right place.

How CachyLLama is different from upstream

We're not faster at inference. We don't support more models. We don't add new quantization types. We do one thing that upstream doesn't: we make the workloads that lower-spec devices can actually run - persistent, multi-turn agentic sessions with 18-30K-token static prefixes - viable by caching aggressively.

Persistent SSD-backed KV cache. Conversation state survives server restarts and power cycles. Hot/warm/cold tiering keeps active conversations in RAM, demotes idle ones to disk, and restores from disk on cold start. Per-conversation ring buffer prevents unbounded disk growth. Kernel readahead (posix_fadvise on Linux, readahead on macOS) overlaps SSD I/O with CPU work. Conversation hash and model compatibility hash prevent mismatched checkpoint restoration. The caché in CachyLLama.

System prompt cache. Global, cross-conversation cache keyed on the first N tokens of any prompt. First eval writes the state; subsequent requests skip the entire system prompt re-evaluation. Works for both standard transformer and hybrid (MoE/SSM) models - the per-position recurrent state in the state file means a state saved after the full prompt can be restored with n_past capped to the system prompt boundary. Default: 8 entries per model, 30 days unused before expiry.

Hybrid MoE checkpoint restore (Qwen3.5/3.6, Gemma 4, GLM-4.7). Hybrid architectures combine attention cells with a recurrent state, and the recurrent state covers all positions in the prompt regardless of how the attention cells are split. CachyLLama tracks recurrent state separately from attention cells, uses n_tokens-based matching when searching for checkpoints, and exposes llama_memory_seq_rm_attn_only to clear attention cells without disturbing recurrent state. MLA support for DeepSeek2/DeepSeek3 included.

User isolation. user_id as a first-class request parameter. Routes checkpoints to a u/ namespace on disk. Per-user concurrency cap with HTTP 429 enforcement. Slot affinity (allocation prefers slots already owned by the requesting user for cache locality). OpenAI SDK compatible via extra_body. See docs/development/user-isolation-design.md.

MoE expert activation tracking. HTTP endpoints (/expert-stats, /expert-tracking) plus a C API (llama_expert_tracking_enable, llama_expert_stats_get, llama_model_n_expert, llama_model_n_expert_used) for reading per-layer expert activation counts in real time. Instrumentation only - no compute changes. This is Phase 1 of a planned expert tiering design.

APU/iGPU Vulkan tuning. Automatic nodes_per_submit reduction for RDNA3 iGPUs (the default upstream value is tuned for discrete GPUs and starves the shader engine on shared-memory APUs). Manual override via GGML_VK_NODES_PER_SUBMIT.

CPU ISA auto-detection. The upstream Vulkan build defaults to GGML_NATIVE=OFF and GGML_AVX512=OFF, leaving AVX-512 code paths compiled out on Zen 4 hardware that supports them (5-15% gen speedup on Vulkan, 30-100% on CPU-offloaded layers). CachyLLama's build wrapper reads /proc/cpuinfo and enables the right ISA level for the detected CPU.

Checkpoint matching for cross-conversation safety. When a checkpoint's recurrent state was computed from a different conversation, restoring it produces garbage. CachyLLama's search layer classifies matches as same-conversation (recurrent state is content-accurate, accept any size) or cross-conversation (only restore checkpoints whose n_tokens fits within the common prefix). Overflow handling caps n_past to leave room for new token evaluation instead of resetting.

Why this matters on lower-spec hardware

A 30B MoE model with 3B active parameters fits on an APU with shared memory (6 GB VRAM + 18 GB GTT = 24 GB GPU memory). Generation runs at 5-20 tokens per second on a 780M - acceptable for typing, painful when the model is reading its own tool outputs.

The bottleneck on APUs isn't generation speed. It's prompt evaluation. Every API call in an agentic workflow re-sends 18-30K tokens of system prompt, tool definitions, and prior conversation context. On a 780M iGPU that's 3-5 minutes of pure re-evaluation before the first token appears.

CachyLLama's KV cache collapses that to 1-4 seconds. The static prefix (system prompt, tool definitions) hits at 17,800+ tokens restored from SSD; only the divergent tail needs evaluation.

Benchmarks (Ayaneo Flip KB, 7840U / 780M / 32 GB, Vulkan, Qwen3.6-35B-A3B Q4_K_XL, 128 output tokens):

Prompt size Cold TTFT Warm TTFT Speedup
~1,243 tokens 9.3 s 0.41 s 23.0x
~5,409 tokens 43.3 s 0.57 s 76.2x
~15,700 tokens 143.1 s (2.4 min) 0.99 s 144.5x

Cold prompt eval rate: 109.9-133.4 t/s. Cached: 15,717/15,721 tokens restored from disk (4 tokens evaluated). Full benchmark data in the parent project.

CachyLLama CLI flags

SSD cache

Flag Default Description
--cache-ssd PATH (off) Enable SSD-backed KV cache
--cache-ssd-checkpoints N 64 Max checkpoints per slot
--cache-ssd-hot-window N 16384 Always-keep window in tokens
--cache-ssd-warm-window N 32768 Keep-in-RAM window in tokens
--cache-ssd-max-cold N 0 Max cold tier checkpoints (0 = unlimited)
--cache-ssd-page-size N 1024 Tokens per page (512 / 1024 / 2048)
--cache-ssd-max-conversations N 16 Max conversation directories
--cache-ssd-hot-ram N auto Hot tier RAM budget in MiB (0 = auto)
--cache-ssd-warm-ram N auto Warm tier RAM budget in MiB (0 = auto)

System prompt cache

Flag Default Description
--cache-ssd-system-prompts N 8 Max global system prompt entries cached for reuse across conversations
--cache-ssd-system-max-days N 30 Expire system prompt entries unused for N days

User isolation

Flag Default Description
--max-concurrent-per-user N 0 Per-user slot cap (0 = unlimited)

When the cap is hit, the server returns HTTP 429:

{
  "error": {
    "code": 429,
    "message": "User 'tenant-42-user-7' has reached the concurrent request limit (2)",
    "type": "rate_limit_error"
  }
}

To identify a request, pass llama_user_id in the request body. OpenAI SDK callers use extra_body={"llama_user_id": "..."}. Validated to ^[a-zA-Z0-9\-_]+$ with a 512-char ceiling.

Vulkan APU/iGPU tuning

Flag Default Description
GGML_VK_NODES_PER_SUBMIT auto Override automatic nodes_per_submit (lower values feed RDNA3 iGPUs more frequently)

MoE expert tracking API

GET /expert-stats

Per-layer expert activation counts, frequencies, and token counts:

{
  "n_expert": 256,
  "n_expert_used": 8,
  "total_tokens": 1500,
  "tracking_enabled": true,
  "layers": [
    {
      "layer": 0,
      "activations": [
        {"expert": 42, "count": 150, "frequency": 0.0125},
        {"expert": 7,  "count": 148, "frequency": 0.0123}
      ]
    }
  ]
}

POST /expert-tracking

Enable/disable tracking and optionally reset counters:

{"enabled": true, "reset": true}

C API

llama_expert_tracking_enable(ctx, true);

// Per-layer stats (returns 0 on success, -1 if tracking disabled)
struct llama_expert_stats stats;
llama_expert_stats_get(ctx, /*layer=*/0, &stats);

// Reset all counters
llama_expert_stats_reset(ctx);

// Model-level constants
int32_t n_expert      = llama_model_n_expert(model);
int32_t n_expert_used = llama_model_n_expert_used(model);

The llama_expert_stats struct exposes activations[] (per-expert count and frequency) and token_count for the layer.

Building CachyLLama

For end-to-end install (runner scripts, GPU detection, benchmark harness, GTT configuration), use the parent project:

git clone --recurse-submodules https://github.com/fewtarius/llama-ai.git
cd llama-ai
./scripts/rebuild.sh

To build just the inference engine from this repo:

cmake -B build
cmake --build build --config Release -j$(nproc)

All standard llama.cpp build options are supported. CachyLLama adds no new build flags - everything is runtime config via the CLI flags above.

Documentation

License

Source code: MIT-licensed (upstream llama.cpp base, see LICENSE, Copyright (c) 2023-2026 The ggml authors). The CachyLLama additions are released under the same terms unless otherwise noted; see the CachyLLama parent project for the full project license.

The upstream llama.cpp README

Everything below this point is the unmodified upstream llama.cpp README. CachyLLama is a fork of llama.cpp; the rest of the file documents the base project, its supported models, and its build options. The CachyLLama additions are described in the sections above.

Recent API changes

Hot topics

Quick start

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

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

Multimodal

Bindings
UIs

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

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:

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:

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

Development documentation

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:

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 ↩

About

LLM inference in C/C++

Resources

Readme

License

MIT license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages

  • C++ 57.2%
  • C 13.9%
  • Python 7.5%
  • Cuda 5.5%
  • TypeScript 3.4%
  • HTML 2.6%
  • Other 9.9%