Manifesto / ggml / ops

LLM inference in C/C++

整合 MTP (Multi-Token Prediction) + TurboQuant，推理速度起飞！提升幅度 2-5 倍。

✅ Vision 多模态已修复：MTP 模式现已完美支持图像输入，多模态 + 推测解码同时启用不再崩溃。

✅ MTP + TurboQuant 完美融合：同时享受 MTP 推测解码的加速和 TurboQuant KV Cache 压缩的显存节省。

⚠️ 模型要求：必须配合内置 MTP 头部的 GGUF 文件使用（如 Qwen3.6-27B-Q4_K_P_mtp.gguf），普通 GGUF 无法启用 MTP。

@echo off
cd /d "源代码目录如 F:\llamacpp_MTP_TurboQuant"

:: ⚡ CUDA 架构号请根据自身显卡修改（例如：75=RTX 2080, 89=RTX 4090, 90=RTX 5090）
cmake -B build ^
  -DGGML_CUDA=ON ^
  -DCMAKE_CUDA_ARCHITECTURES="75" ^
  -DGGML_CUDA_FA_ALL_QUANTS=ON ^
  -DGGML_NATIVE=OFF ^
  -DCMAKE_BUILD_TYPE=Release

cmake --build build --config Release -j --target llama-server llama-cli

（根据你的显卡型号修改 CMAKE_CUDA_ARCHITECTURES） 常见对照：

• 75 — Turing (RTX 20xx, T4)
• 80 — Ampere (RTX 30xx, A100)
• 86 — Ampere (RTX 30xx 消费级)
• 89 — Ada Lovelace (RTX 40xx)
• 120 — Blackwell (RTX 50xx)

@echo off
cd /d "llama-server.exe文件所在目录如 F:\mtp_llamacpp\llama.cpp\build\bin\Release\"

set CUDA_SCALE_LAUNCH_QUEUES=4x

llama-server.exe -m "mtp属性gguf文件路径 如D:\wd3.7\Qwen3.6-27B-Q4_K_P_mtp.gguf" --mmproj "多模态投影文件路径 如D:\wd3.7\mmproj-Qwen3.6-27B.gguf" ^
  --spec-type mtp --spec-draft-n-max 2 ^
  -ctk q8_0 -ctv turbo3 ^
  -c 8000 -b 2048 -ub 512 ^
  --n-gpu-layers 99 ^
  --host 0.0.0.0 --port 8080 ^
  --temp 0.7 --top-k 20 ^
  -np 1 -fa on ^
  -t 7 ^
  --jinja ^
  --chat-template-file "聊天模板文件路径如：F:\llamacpp_MTP_TurboQuant\3.6_chat_template-v10.jinja" ^
  --reasoning auto ^
  --reasoning-format deepseek

pause

参数说明（请根据自身硬件调整）：

• --spec-type mtp — 启用 MTP 投机解码
• --spec-draft-n-max 2 — MTP 每步预测 2 个候选 token
• -ctk q8_0 -ctv turbo3 — KV Cache 非对称压缩（K 用 8-bit 保精度，V 用 TurboQuant 3-bit 省显存），相比全 F16 节省约 76% 显存
• --mmproj — 多模态投影文件，启用视觉识别能力
• -c 8000 — 上下文长度（根据显存调整）
• -t 7 — CPU 线程数（根据你的 CPU 核心数调整）
• --n-gpu-layers 99 — 全量 GPU 卸载
• --jinja + --chat-template-file — 使用增强版 Jinja 模板

该模板专为 llama.cpp 的 minijinja 引擎深度优化，解决了官方模板 9 大缺陷，以下是其在 llama.cpp 环境下的核心优势：

关键参数：搭配 --reasoning auto --reasoning-format deepseek 使用，llama.cpp 可自动解析模板输出的 thinking 块并分离显示，实现类似 DeepSeek 的推理过程可视化。

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

• 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/llama.cpp#9669
• Hugging Face GGUF editor: discussion | tool

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

• Install llama.cpp using brew, nix or winget
• 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

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.

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/llama.cpp#10123)
• Use the GGUF-editor space to edit GGUF meta data in the browser (more info: ggml-org/llama.cpp#9268)
• Use the Inference Endpoints to directly host llama.cpp in the cloud (more info: ggml-org/llama.cpp#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 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/

• 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

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

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

• cli
• completion
• 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 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.

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 it automatically. For example:

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

• 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