Skip to content

Skylark-Software/EagleBranch

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

8,179 Commits
.devops
.devops
 
 
.gemini
.gemini
 
 
.github
.github
 
 
benches
benches
 
 
ci
ci
 
 
cmake
cmake
 
 
common
common
 
 
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
 
 
EAGLE3.md
EAGLE3.md
 
 
LICENSE
LICENSE
 
 
Makefile
Makefile
 
 
README.md
README.md
 
 
SECURITY.md
SECURITY.md
 
 
SETUP.md
SETUP.md
 
 
UPSTREAM_PR_NOTES.md
UPSTREAM_PR_NOTES.md
 
 
USAGE.md
USAGE.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.lock
flake.lock
 
 
flake.nix
flake.nix
 
 
kv-cache-guide.md
kv-cache-guide.md
 
 
mypy.ini
mypy.ini
 
 
poetry.lock
poetry.lock
 
 
pyproject.toml
pyproject.toml
 
 
pyrightconfig.json
pyrightconfig.json
 
 
requirements.txt
requirements.txt
 
 

Repository files navigation

Skylark Software

EagleBranch

A llama.cpp fork by Skylark Software for running large language models on modest and legacy NVIDIA hardware — the GPUs mainline has moved past (Pascal P40/P100/GTX 10xx) and the memory budgets that force hard context-length trade-offs.

License: MIT

Download

📦 Download v1.0 (Linux x86_64 + CUDA, 183 MB)

All releases · v1.0 release notes · Step-by-step setup guide (SETUP.md)

# Quick install — verify, extract, smoke test
curl -LO https://github.com/Skylark-Software/EagleBranch/releases/download/v1.0/skylark-llama-server-v1.0-linux-x86_64-cuda.tar.gz
echo "fd99d81e0d46047c890ea13b188b046b28a2f7411c9a13e41d771321cf14addb  skylark-llama-server-v1.0-linux-x86_64-cuda.tar.gz" | sha256sum -c
tar -xzf skylark-llama-server-v1.0-linux-x86_64-cuda.tar.gz
cd skylark-llama-server-v1.0-linux-x86_64-cuda
./llama-server --version

The prebuilt binary includes TurboQuant; requires the CUDA 12 runtime libraries, not just the driver — see SETUP.md step 1.

What it does

Three things, independently useful:

Pillar What you get Where
TurboQuant KV cache 3-bit/4-bit KV-cache compression (tbq3_1, tbq3_2, tbq4_1): up to 5.12× smaller KV vs f16 at ~2% PPL cost — e.g. 4 × 32K contexts on a single 24 GB P40. Includes the Lane B fused kernel for MLA models. Release binaries only (proprietary)
EAGLE/MTP speculative decoding --eagle3: draft-head speculation for Mistral Large 3, DeepSeek R1/V3/V2 (EAGLE v1/v2, Eagle-3, NextN/MTP) with identical outputs Open source (this branch) + binaries
Legacy hardware enablement Pascal (SM 6.1) fixes and tuning mainline won't take: working MLA path, quantized-KV rules that respect Pascal's flash-attention limits, multi-GPU MoE placement recipes Open source (this branch) + binaries

Fastest start: download the prebuilt skylark-llama-server release (includes TurboQuant) and follow SETUP.md. Building from this source gives you everything except the tbq* cache types.

Documentation

Doc Covers
SETUP.md install, GPU/driver/CUDA requirements, first run
USAGE.md talking to the server (OpenAI-compatible API, streaming)
kv-cache-guide.md the switch reference — every --cache-type-* value, MHA vs MLA rules, measured speed/quality tables
EAGLE3.md speculative decoding: draft heads, flags, honest performance guidance

Licensing, commercial use, source access: info@skylarksoftware.me

EAGLE3-DS architecture — technical notes

The eagle3 branch introduces a new eagle3_ds architecture (EAGLE3-DeepSeekV2) that supports both EAGLE v1/v2 and Eagle-3 style speculative decoding for models using the DeepSeek V2 architecture (MLA attention + MoE), including:

  • Mistral Large 3 (675B) — EAGLE v1/v2 via Mistral Eagle head
  • DeepSeek R1 (671B) — Eagle-3/MTP via DeepSeek-R1-NextN
  • DeepSeek V3 (671B) — Eagle-3/MTP via built-in NextN/MTP module
  • DeepSeek V2 (236B) — any compatible EAGLE draft head

Key changes (13 files, 3 commits)

  1. EAGLE3_DS architecture — Full decoder implementation with MLA (Multi-head Latent Attention) and MoE (Mixture of Experts) support, matching the target model's DeepSeek V2 architecture
  2. EAGLE v1/v2 mode — The Mistral Eagle head uses EAGLE v1 (FC(concat(embedding, final_hidden_state))), not Eagle-3 multi-layer feature extraction. The fork auto-detects the method from GGUF metadata (eagle_method = "eagle")
  3. result_norm extraction — Captures post-norm final hidden states from the target model for EAGLE v1 autoregressive drafting
  4. GGUF conversion — convert_hf_to_gguf.py handles Mistral Eagle → eagle3_ds conversion with automatic method detection

Files modified

File Description
src/models/eagle3_ds.cpp EAGLE3-DS decoder graph (MLA + MoE + EAGLE v1/v3 dual mode)
common/speculative.cpp EAGLE v1 draft loop, skip encoder for v1, g_embeddings wiring
src/llama-context.cpp result_norm capture, extraction, output_all for v1
src/llama-model.cpp GGUF loading, eagle_is_v1 flag, FC tensor sizing
convert_hf_to_gguf.py Mistral Eagle conversion with method detection
src/llama-arch.{h,cpp} LLM_KV_EAGLE3_METHOD key
src/llama-hparams.h eagle_is_v1 flag
src/llama-graph.h result_norm fields in eagle3 state
src/llama-context.h API declarations
include/llama.h C API for result_norm access
gguf-py/gguf/constants.py EAGLE3_METHOD constant
common/arg.cpp --no-warmup for speculative example

Results

Mistral Large 3 675B (EAGLE v1)

Tested with Q4_K_M (383 GB) on 4x Tesla P40 + 503 GB RAM:

Metric Value
Acceptance rate 64.5% (71/110 drafted tokens)
Generation speed 2.86 tok/s (with speculation)
Baseline (no speculation) 4.72 tok/s
Draft decoder speed 141 tok/s on GPU

The 64.5% acceptance rate confirms the EAGLE v1 implementation is correct. However, speculative decoding does not provide a net throughput improvement for this hardware configuration — the target model's verification cost (1085 graph splits across 4 GPUs + CPU for the massive MoE architecture) dominates, negating the ~2.3x tokens-per-step gain. Speculation would benefit from faster target model inference (more GPU offload or a smaller target model).

Usage

# Convert Mistral Eagle head to GGUF
python convert_hf_to_gguf.py /path/to/Mistral-Large-3-675B-Instruct-2512-Eagle \
  --outtype q8_0 --outfile mistral-eagle-v1-q8_0.gguf

# Run speculative decoding
./build/bin/llama-speculative-simple \
  -m /path/to/Mistral-Large-3-Q4_K_M.gguf \
  -md /path/to/mistral-eagle-v1-q8_0.gguf \
  --eagle3 --no-mmap -devd CUDA3 -ngld 99 \
  -ngl 4 -c 2048 --draft 8 -n 128 \
  -p "Write a short essay about the future of artificial intelligence."

Upstream

This fork is based on llama.cpp build 8150 (ggml-org/llama.cpp), incorporating PR #18039 (Eagle-3 support). All upstream code is licensed under the MIT License.

For the full llama.cpp documentation, see the upstream repository. Release Server

Manifesto / ggml / ops

LLM inference in C/C++

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 HuggingFace 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.
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 and Nvidia GPU
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 [In Progress] 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, such as ModelScope, 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. 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 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

EagleBranch is a llama.cpp fork with TurboQuant 3-bit KV cache compression and speculative decoding (EAGLE v1/v2/v3, NextN/MTP) for current, legacy, and CPU inference. Includes multiple bug fixes that enable legacy NVIDIA hardware and a fused rotated-domain matvec kernel ("Lane B") that closes most of the throughput gap to IQ4_NL on MLA models.

skylarksoftware.me

Resources

Readme

License

MIT license

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

8 tags

Packages

 
 
 

Contributors

Languages