Llama.cpp 框架入门与 C/C++ 编码实战

加载 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; 
}

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

三、LLM 模型的量化

量化 (Quantization) 通过使用较低精度的整型格式压缩模型文件大小，例如将参数精度从 FP32 降低到 INT8 或 INT4，减少存储大小和推理内存负载。目的是在适当降低精度后，优化内存占用且不显著影响效果。

1. 量化的分类

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

• Q8 级别量化：8 位量化 (INT8)，保留更多原始精度，文件较大，适合通用场景。
• Q4 级别量化：4 位量化 (INT4)，最节省内存，提高速度和效率，但降低精度，适合专用场景。

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

• 简单量化：统一降低所有参数精度。
• K 均值量化：通过划分聚类方式实现量化。

llama.cpp 支持的常用量化级别：

• Q8_0: 8 位整型量化，文件较大，质量接近 FP16，运行速度较快。
• Q5_K_M, Q5_K_S: 5 位 K 均值量化，平衡文件大小、速度和精度。
• Q4_K_M, Q4_K_S: 4 位 K 均值量化，文件更小，内存更低，Q4_K_M 是许多用户首选。
• Q2_K: 2 位 K 均值量化，文件最小，速度最快，但精度损失较大。

应用举例：

基于 LLaMA-7B 测试，Q4_K_M 相比 FP16，体积减小 63%，推理速度提升 2.5 倍，精度损失仅 0.8%。

含义说明：

• Q: 代表量化。
• #: 表示量化位数。
• K: 表示使用 k 均值聚类。
• M/S/L: 表示量化后的模型大小（中/小/大）。

2. 量化命令实战

使用 quantize 工具进行模型量化：

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

量化过程打印：

四、llama.cpp 命令行

核心命令行工具包括模型推理工具 (main) 和量化工具 (quantize)。main 用于加载 GGUF 模型并执行推理任务。

基本语法：

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

常用命令行参数如下：

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

五、llama.cpp 本地部署实战

Step 1：从 GitHub 仓库下载源码

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

Step 2：编译项目源码

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

Step 3：安装 HuggingFace_Hub Python 环境

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

验证安装：

Step 4：从 HuggingFace Hub 下载大模型

以阿里 Qwen 大模型为例：

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

Step 5：加载 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 服务：

http://127.0.0.1:8080/

也可不生成 Restful 服务，直接用命令行聊天：

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

六、llama.cpp 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();

    int n_parallel = params.n_parallel;
    int n_predict = params.n_predict;

    llama_backend_init();
    llama_numa_init(params.numa);

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

    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, \nn_batch = %u, \nn_parallel = %d, \nn_kv_req = %d\n", 
            __func__, n_predict, n_ctx, ctx_params.n_batch, n_parallel, n_kv_req);

    if (n_kv_req > n_ctx) {
        LOG_ERR("the required KV cache size is not big enough\n");
        return 1;
    }

    LOG("\n");
    for (auto id : tokens_list) {
        LOG("%s", common_token_to_piece(ctx, id).c_str());
    }

    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;
    }

    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);
    }

    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);
    }

    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) {
        common_batch_clear(batch);
        for (int32_t i = 0; i < n_parallel; ++i) {
            if (i_batch[i] < 0) 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 (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/