C/C++版LLM推理框架Llama.cpp——入门与编码实战

一、Llama.cpp框架简介

llama.cpp是由Georgi Gerganov创建的轻量级推理引擎，它是基于C/C++语言编码实现的LLM框架，支持大模型的训练和推理，专注于在本地硬件环境(比如个人电脑、树莓派等)上高效运行LLM模型。

llama.cpp框架目前支持的大模型有LLaMA系列、Qwen系列、Gemma系列、LLaVA系列等。

llama.cpp框架支持运行在CPU、GPU、 嵌入式等设备上，对消费级硬件和资源受限的边缘计算设备支持较好。

由于llama.cpp的实现代码以C/C++为主，因此它也具备跨平台兼容性(支持Windows、Linux、macOS等平台)，并支持Python编码调用，比如llama-cpp-python第三方库。

Georgi Gerganov本人是AI开源社区知名的开发者，专注于高性能机器学习框架的C/C++编程实现，在Georgi Gerganov创建llama.cpp项目之前，此前已经开发出了以极简主义和高性能而闻名的whisper.cpp框架和专为机器学习优化的张量计算库ggml。

2023年初，Meta公司发布了LLaMA模型，但原版LLaMA模型的推理运行需要消耗大量计算资源，且依赖Pytorch和GPU算力，此时Georgi Gerganov开始意识到他可以将LLaMA模型移植到基于C语言开发的ggml张量库中，并实现基于CPU处理器本地运行大模型的推理和训练过程，由此导致业界闻名的llama.cpp框架的诞生。

llama.cpp的应用场景：

边缘人工智能：在计算能力有限的设备(例如智能手机、物联网设备)上部署 LLaMA 或类似 GPT 的模型。

模型研究：研究人员可以快速迭代量化模型，而无需担心资源密集型硬件设置。

离线推理：将人工智能服务部署在本地离线环境，不与云服务器交互，用来确保数据隐私和商业机密。

二、关于GGUF模型文件

llama.cpp框架不能直接使用PyTorch或TensorFlow生成的原始模型文件，它主要使用的文件格式是GGUF(GGML Unified Format)，用于存储LLM大模型的权重和配置。

llama.cpp早期采用的是GGML文件格式， 后来改为使用GGUF文件格式。

在GGML/GGUF出现之前，最早期的机器学习模型文件格式主要侧重于存储未量化的模型，并确保不同的AI框架和硬件平台之间的兼容性。

最早期的机器学习模型文件格式有".pb"文件格式(应用于TensorFlow框架)，".pt"或".pth"文件格式(应用于PyTorch框架)，虽然这些格式适用于较小的AI模型，但它们有很大的局限性，比如:

1.不支持量化，这些模型存储了全精度(32位浮点)权重，导致模型文件过大。

2.内存使用率高，由于模型未压缩，它们需要大量内存来存储和推理，在消费级硬件上部署时占用了过高的内存。

引入GGML文件格式(通用GPT模型语言)是为了满足LLaMA等大型LLM模型的量化和压缩需求。GGML允许以较低精度的格式存储模型权重，例如8位整型(INT8)或4位整型(INT4)，从而大大减少了模型的大小和内存占用。

GGUF是在GGML格式的基础上做的优化，GGUF包含了更多的元数据，并且设计上更易于扩展和使用，GGUF格式将权重、分词器和元数据等集成到一个高效的二进制文件中，该二进制文件加载速度快，可跨平台工作。

GGUF格式的核心特性：

硬件兼容性强：支持在消费级硬件(例如CPU)上运行LLM模型，无需昂贵的GPU配置。

内存占用低：通过量化显著减少内存占用，使大模型更易于部署。

支持自定义量化：通过选择量化级别来微调模型的性能和精度之间的平衡。

模型可扩展性强：GGUF能够存储和运行巨大规模的LLM模型(例如LLaMA 2)，而不会遇到GGML格式下的可扩展性问题。

易于部署：GGUF可以部署在云服务器、边缘设备和移动端设备上，即使在算力较低的硬件设备上也能高效完成推理过程。

丰富的元数据信息：GGUF能够存储LLM模型的更广泛的元数据信息，这些元数据包括模型的层级结构、配置参数和量化级别等。

GGUF模型文件的获取和转换

开发者可以使用llama.cpp提供的convert.py脚本，将原始的PyTorch模型转换为GGUF格式，命令示例：

python convert.py path/to/model --outtype gguf --outfile model.gguf

llama.cpp中加载GGUF文件的代码实现： 

struct gguf_context * gguf_init_from_file(const char * fname, struct gguf_init_params params) { FILE * file = ggml_fopen(fname, "rb"); if (!file) { GGML_LOG_ERROR("%s: failed to open GGUF file '%s'\n", __func__, fname); return nullptr; } struct gguf_context * result = gguf_init_from_file_impl(file, params); fclose(file); return result; }

struct gguf_context { uint32_t version = GGUF_VERSION; std::vector<struct gguf_kv> kv; std::vector<struct gguf_tensor_info> info; size_t alignment = GGUF_DEFAULT_ALIGNMENT; // offset of `data` from beginning of file size_t offset = 0; // size of `data` in bytes size_t size = 0; void * data = nullptr; };

用户可以从Hugging Face Hub下载预转换的GGUF模型：

三、LLM模型的量化

量化(Quantization)就是通过使用较低精度的整型格式来压缩LLM模型文件的大小，比如将LLM模型参数(比如权重、偏差等)的精度从32位浮点型(FP32)等较高精度格式降低到8位整型(INT8)或4位整型(INT4)等较低精度的过程，这大大减少了模型的存储大小和推理计算时的内存负载。

量化技术的目的就是在适当降低模型的精度后，达到既没有显著降低模型的效果，又能大幅度优化模型的内存占用。

量化技术对于在内存资源有限的边缘硬件设备上部署LLM模型至关重要。

1.量化的分类

(1).按量化等级分类：

Q8级别量化：

8位量化 (INT8)，保留了LLM模型更多的原始精度，但模型文件较大，且内存占用仍然很高，适合应用在对话生成等通用场景。

Q4级别量化：

4位量化 (INT4)，最节省内存的量化方案，可显著提高内存和推理速度，但会降低模型的精度，适合应用在关键字提取、语义搜索等专用场景。

(2).按量化方法分类： 

简单量化：

简单量化统一降低所有参数的精度。

K均值量化：

K均值量化是通过划分聚类的方式来实现量化。

llama.cpp支持多种量化级别，常用的级别如下：

Q8_0: 8位整型量化，文件较大，质量接近FP16，但运行速度较快。

Q5_K_M, Q5_K_S: 5位K均值量化，平衡了模型文件大小、运行速度和精度，折衷方案。

Q4_K_M, Q4_K_S: 5位K均值量化，模型文件更小，内存占用更低，但精度有所下降，Q4_K_M是许多用户首选的入门级别，因为它能在消费级硬件上较好地运行。

Q2_K: 2位K均值量化，文件最小，运行速度最快，但精度损失较大。

量化的应用举例：

基于LLaMA-7B模型测试发现，Q4_K_M级别相比FP16级别，模型体积减小了63%，推理速度提升了2.5倍，但LLaMA-7B模型的精度损失仅0.8%。

llama.cpp量化级别中的"Q#_K_M"的含义：

*Q：代表量化。

*#：表示量化过程中使用的位数。

*K：表示在量化中使用 k 均值聚类。

*M：表示量化后的模型大小。S=小，M=中，L=大。

2.量化命令实战

用户可以通过llama.cpp的quantize工具进行模型的量化。

参考示例：llama.cpp/tools/quantize

./llama-quantize ./models/ggml-vocab-deepseek-llm.gguf Q4_K_M

量化过程打印： 

四、llama.cpp命令行

llama.cpp的核心命令行工具包括模型推理工具(main) 和量化工具(quantize)，main是llama.cpp的核心命令行工具，用于加载GGUF模型并执行推理任务。基本语法为：

./main [选项] -m <模型路径>

常用命令行参数如下：

全量的命令行参数参考官方文档： https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md

五、llama.cpp本地部署实战

step.01：从github仓库下载llama.cpp项目源码

git clone https://github.com/ggml-org/llama.cpp

step.02：编译llama.cpp项目源码

cmake -B build cmake --build build --config Release

step.03：安装HuggingFace_Hub Python环境，推荐使用env虚拟环境安装。

python3 -m venv .env source .env/bin/activate pip install huggingface_hub

安装完成以后可以使用"hf"命令进行验证：

step.04：从HuggingFace_Hub下载大模型到本地，以阿里的Qwen大模型为例。

https://huggingface.co/Qwen/Qwen3-0.6B-GGUF/

step.05：使用llama.cpp加载Qwen3大模型，并生成Restful服务。

./llama-server -m /home/dev/LLM/llama.cpp/models/Qwen3-0.6B-Q8_0.gguf --host 0.0.0.0 --port 8080

Restful服务的后台日志打印：

访问LLM对应的Restful服务：

http://127.0.0.1:8080/

也可以不生成Restful服务，直接用llama.cpp命令行与模型进行聊天： 

./llama-cli -m /home/dev/LLM/llama.cpp/models/Qwen3-0.6B-Q8_0.gguf

六、llama.cpp Python编码实战

Python编码之前，需要先安装依赖库"llama-cpp-python"：

pip install llama-cpp-python

Demo1：

from llama_cpp import Llama # Load the model llm = Llama( model_path="/home/dev/LLM/llama.cpp/models/Qwen3-0.6B-Q8_0.gguf", n_ctx=512, n_threads=4 ) # Provide a prompt prompt = "What is LLM?" # Generate the response output = llm(prompt, max_tokens=250) # Print the response print(output["choices"][0]["text"].strip())

运行结果： 

七、llama.cpp C++编码实战

Demo2：

#include "arg.h" #include "common.h" #include "log.h" #include "llama.h" #include <algorithm> #include <cstdio> #include <string> #include <vector> int main(int argc, char ** argv) { common_params params; params.model.path = "/home/dev/LLM/llama.cpp/models/Qwen3-0.6B-Q8_0.gguf"; params.prompt = "What is LLM?"; params.n_predict = 128; common_init(); // number of parallel batches int n_parallel = params.n_parallel; // total length of the sequences including the prompt int n_predict = params.n_predict; // init LLM llama_backend_init(); llama_numa_init(params.numa); // initialize the model llama_model_params model_params = common_model_params_to_llama(params); llama_model *model = llama_model_load_from_file(params.model.path.c_str(), model_params); if (model == NULL) { LOG_ERR("%s: error: unable to load model\n" , __func__); return 1; } const llama_vocab * vocab = llama_model_get_vocab(model); // tokenize the prompt std::vector<llama_token> tokens_list; tokens_list = common_tokenize(vocab, params.prompt, true); const int n_kv_req = tokens_list.size() + (n_predict - tokens_list.size())*n_parallel; // initialize the context llama_context_params ctx_params = common_context_params_to_llama(params); ctx_params.n_ctx = n_kv_req; ctx_params.n_batch = std::max(n_predict, n_parallel); llama_context * ctx = llama_init_from_model(model, ctx_params); auto sparams = llama_sampler_chain_default_params(); sparams.no_perf = false; llama_sampler * smpl = llama_sampler_chain_init(sparams); llama_sampler_chain_add(smpl, llama_sampler_init_top_k(params.sampling.top_k)); llama_sampler_chain_add(smpl, llama_sampler_init_top_p(params.sampling.top_p, params.sampling.min_keep)); llama_sampler_chain_add(smpl, llama_sampler_init_temp (params.sampling.temp)); llama_sampler_chain_add(smpl, llama_sampler_init_dist (params.sampling.seed)); if (ctx == NULL) { LOG_ERR("%s: error: failed to create the llama_context\n" , __func__); return 1; } const int n_ctx = llama_n_ctx(ctx); LOG_INF("\n%s: n_predict = %d, \ n_ctx = %d, \ n_batch = %u, \ n_parallel = %d, \ n_kv_req = %d\n", __func__, n_predict, n_ctx, ctx_params.n_batch, n_parallel, n_kv_req); // make sure the KV cache is big enough to hold all the prompt and generated tokens if (n_kv_req > n_ctx) { LOG_ERR("the required KV cache size is not big enough\n"); return 1; } // print the prompt token-by-token LOG("\n"); for (auto id : tokens_list) { LOG("%s", common_token_to_piece(ctx, id).c_str()); } // create a llama_batch // we use this object to submit token data for decoding llama_batch batch = llama_batch_init(std::max(tokens_list.size(), (size_t) n_parallel), 0, n_parallel); std::vector<llama_seq_id> seq_ids(n_parallel, 0); for (int32_t i = 0; i < n_parallel; ++i) { seq_ids[i] = i; } // evaluate the initial prompt for (size_t i = 0; i < tokens_list.size(); ++i) { common_batch_add(batch, tokens_list[i], i, seq_ids, false); } GGML_ASSERT(batch.n_tokens == (int) tokens_list.size()); if (llama_model_has_encoder(model)) { if (llama_encode(ctx, batch)) { LOG_ERR("%s : failed to eval\n", __func__); return 1; } llama_token decoder_start_token_id = llama_model_decoder_start_token(model); if (decoder_start_token_id == LLAMA_TOKEN_NULL) { decoder_start_token_id = llama_vocab_bos(vocab); } common_batch_clear(batch); common_batch_add(batch, decoder_start_token_id, 0, seq_ids, false); } // llama_decode will output logits only for the last token of the prompt batch.logits[batch.n_tokens - 1] = true; if (llama_decode(ctx, batch) != 0) { LOG_ERR("%s: llama_decode() failed\n", __func__); return 1; } if (n_parallel > 1) { LOG("\n\n%s: generating %d sequences ...\n", __func__, n_parallel); } // main loop // we will store the parallel decoded sequences in this vector std::vector<std::string> streams(n_parallel); std::vector<int32_t> i_batch(n_parallel, batch.n_tokens - 1); int n_cur = batch.n_tokens; int n_decode = 0; const auto t_main_start = ggml_time_us(); while (n_cur <= n_predict) { // prepare the next batch common_batch_clear(batch); // sample the next token for each parallel sequence / stream for (int32_t i = 0; i < n_parallel; ++i) { if (i_batch[i] < 0) { // the stream has already finished continue; } const llama_token new_token_id = llama_sampler_sample(smpl, ctx, i_batch[i]); if (llama_vocab_is_eog(vocab, new_token_id) || n_cur == n_predict) { i_batch[i] = -1; LOG("\n"); if (n_parallel > 1) { LOG_INF("%s: stream %d finished at n_cur = %d", __func__, i, n_cur); } continue; } // if there is only one stream, we print immediately to stdout if (n_parallel == 1) { LOG("%s", common_token_to_piece(ctx, new_token_id).c_str()); } streams[i] += common_token_to_piece(ctx, new_token_id); i_batch[i] = batch.n_tokens; common_batch_add(batch, new_token_id, n_cur, { i }, true); n_decode += 1; } if (batch.n_tokens == 0) { break; } n_cur += 1; if (llama_decode(ctx, batch)) { LOG_ERR("%s : failed to eval, return code %d\n", __func__, 1); return 1; } } if (n_parallel > 1) { LOG("\n"); for (int32_t i = 0; i < n_parallel; ++i) { LOG("sequence %d:\n\n%s%s\n\n", i, params.prompt.c_str(), streams[i].c_str()); } } const auto t_main_end = ggml_time_us(); LOG_INF("%s: decoded %d tokens in %.2f s, speed: %.2f t/s\n", __func__, n_decode, (t_main_end - t_main_start) / 1000000.0f, n_decode / ((t_main_end - t_main_start) / 1000000.0f)); LOG("\n"); llama_perf_sampler_print(smpl); llama_perf_context_print(ctx); fprintf(stderr, "\n"); llama_batch_free(batch); llama_sampler_free(smpl); llama_free(ctx); llama_model_free(model); llama_backend_free(); return 0; }

运行结果：

参考阅读：

https://medium.com/@vimalkansal/understanding-the-gguf-format-a-comprehensive-guide-67de48848256

https://qwen.readthedocs.io/zh-cn/latest/run_locally/llama.cpp.html

https://learn.arm.com/learning-paths/servers-and-cloud-computing/llama_cpp_streamline/2_llama.cpp_intro/

https://newsletter.maartengrootendorst.com/p/a-visual-guide-to-quantization

http://www.bimant.com/blog/llama-cpp-quantization-manual/