DeepSeek总结的llama.cpp使用说明

l1t2026-02-21 18:09

llama.cpp

原文地址：https://github.com/ggml-org/llama.cpp

llama

许可证： MIT 协议 | 发布服务器

核心： Manifesto / ggml / ops

功能： 用 C/C++ 实现 LLM 推理

📋 近期更新

API 变更日志

  • libllama API 变更日志
  • llama-server REST API 变更日志

🔥 热门话题

  • 指南：使用 llama.cpp 的新 WebUI
  • 指南：使用 llama.cpp 运行 GPT-OSS 模型
  • [反馈] 为 llama.cpp 提供更好的打包方案，以支持下游消费者 🤗
  • 新增对 GPT-OSS 模型的原生 MXFP4 格式支持 | [PR] | [与 NVIDIA 合作] | [评论]
  • 多模态支持现已登陆 llama-server：[#12898] | [文档]
  • VS Code 扩展（用于 FIM 补全）：https://github.com/ggml-org/llama.vscode
  • Vim/Neovim 插件（用于 FIM 补全）：https://github.com/ggml-org/llama.vim
  • Hugging Face 推理端点现已原生支持 GGUF！ [#9669]
  • Hugging Face GGUF 编辑器：[讨论] | [工具]

🚀 快速开始

使用 llama.cpp 入门非常简单。以下是几种在你的机器上安装它的方法：

  • 使用 brew、nix 或 winget 安装 llama.cpp
  • 使用 Docker 运行------查看我们的 [Docker 文档]
  • 从[发布页面]下载预构建的二进制文件
  • 通过克隆此仓库从源代码构建------查看我们的[构建指南]

安装完成后，你需要一个模型才能开始工作。请前往[获取和量化模型]部分了解更多信息。

示例命令

bash 复制代码 
# 使用本地模型文件
llama-cli -m my_model.gguf

# 或者直接从 Hugging Face 下载并运行模型
llama-cli -hf ggml-org/gemma-3-1b-it-GGUF

# 启动兼容 OpenAI API 的服务器
llama-server -hf ggml-org/gemma-3-1b-it-GGUF

📖 项目描述

llama.cpp 的主要目标是实现 LLM 推理，在各类硬件上（本地和云端）实现最少的设置步骤 和最先进的性能。

✨ 核心特性

  • 纯 C/C++ 实现，无任何依赖
  • 苹果芯片是一等公民------通过 ARM NEON、Accelerate 和 Metal 框架优化
  • 支持 x86 架构的 AVX、AVX2、AVX512 和 AMX 指令集
  • 支持 RISC-V 架构的 RVV、ZVFH、ZFH、ZICBOP 和 ZIHINTPAUSE 指令集
  • 1.5-bit、2-bit、3-bit、4-bit、5-bit、6-bit 和 8-bit 整数量化，实现更快的推理和更少的内存使用
  • 用于在 NVIDIA GPU 上运行 LLM 的自定义 CUDA 内核（通过 HIP 支持 AMD GPU，通过 MUSA 支持摩尔线程 GPU）
  • 支持 Vulkan 和 SYCL 后端
  • CPU+GPU 混合推理，可部分加速大于总 VRAM 容量的模型

llama.cpp 项目是开发 ggml 库新功能的主要试验场。

🧩 生态系统

分类 资源
模型 支持的模型列表
绑定 各种编程语言的绑定
界面 图形用户界面
工具 辅助工具
基础设施 部署和运维
游戏 基于 llama.cpp 的游戏

⚙️ 支持的后端

后端 目标设备
Metal 苹果芯片
BLAS 所有
BLIS 所有
SYCL 英特尔和英伟达 GPU
MUSA 摩尔线程 GPU
CUDA 英伟达 GPU
HIP AMD GPU
ZenDNN AMD CPU
Vulkan GPU
CANN 昇腾 NPU
OpenCL Adreno GPU
IBM zDNN IBM Z 和 LinuxONE
WebGPU [进行中] 所有
RPC 所有
Hexagon [进行中] 骁龙
VirtGPU VirtGPU API

📥 获取和量化模型

Hugging Face 平台托管了许多与 llama.cpp 兼容的 LLM：

  • 趋势模型

  • LLaMA 模型

你可以手动下载 GGUF 文件，也可以使用 CLI 参数 -hf <user>/<model>[:quant] 直接使用 Hugging Face 或其他模型托管站点（如 ModelScope）上与 llama.cpp 兼容的模型。例如：

bash 复制代码 
llama-cli -hf ggml-org/gemma-3-1b-it-GGUF

默认情况下，CLI 会从 Hugging Face 下载。你可以通过设置环境变量 MODEL_ENDPOINT 切换到其他选项。例如，你可以通过设置环境变量来选择从 ModelScope 或其他模型共享社区下载模型检查点，如 MODEL_ENDPOINT=https://www.modelscope.cn/。

下载模型后，使用 CLI 工具在本地运行------见下文。

llama.cpp 要求模型以 GGUF 文件格式 存储。其他数据格式的模型可以使用此仓库中的 convert_*.py Python 脚本转换为 GGUF 格式。

Hugging Face 平台提供了一系列在线工具，用于使用 llama.cpp 转换、量化和托管模型：

  • 使用 [GGUF-my-repo] 空间转换为 GGUF 格式并将模型权重量化为更小的尺寸
  • 使用 [GGUF-my-LoRA] 空间将 LoRA 适配器转换为 GGUF 格式（更多信息：[#10123]）
  • 使用 [GGUF-editor] 空间在浏览器中编辑 GGUF 元数据（更多信息：[#9268]）
  • 使用 [推理端点] 直接在云端托管 llama.cpp（更多信息：[#9669]）

要了解有关模型量化的更多信息，请阅读[此文档]。

🛠️ 工具详解

llama-cli

一个 CLI 工具，用于访问和试验 llama.cpp 的大部分功能。

运行对话模式

带有内置聊天模板的模型会自动激活对话模式。如果未激活，你可以通过添加 -cnv 并使用 --chat-template NAME 指定合适的聊天模板来手动启用它。

bash 复制代码 
llama-cli -m model.gguf

# > 嗨，你是谁？
# 你好！我是你的得力助手！我是一个基于人工智能的聊天机器人，旨在帮助像你这样的用户并提供信息。我在这里帮助你解答问题、提供指导，并在广泛的主题上提供支持。我是一个友好且知识渊博的人工智能，随时乐意帮助你解决任何需求。你有什么想法，我今天能如何帮助你？
#
# > 1+1 等于几？
# 小菜一碟！1+1 的答案是... 2！
其他功能
  • 使用自定义聊天模板运行对话模式
  • 使用自定义语法约束输出

llama-server

一个轻量级的、兼容 OpenAI API 的 HTTP 服务器，用于提供 LLM 服务。

启动服务器

使用默认配置在端口 8080 上启动本地 HTTP 服务器

bash 复制代码 
llama-server -m model.gguf --port 8080

# 基本的 Web UI 可通过浏览器访问：http://localhost:8080
# 聊天补全端点：http://localhost:8080/v1/chat/completions
高级功能
  • 支持多用户和并行解码
  • 启用推测解码
  • 提供嵌入模型服务
  • 提供重排序模型服务
  • 使用语法约束所有输出

llama-perplexity

一个用于测量模型在给定文本上的困惑度[1](#1)（和其他质量指标）的工具。

测量困惑度
bash 复制代码 
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
其他功能
  • 测量 KL 散度

llama-bench

基准测试工具，用于衡量各种参数下的推理性能。

运行默认基准测试
bash 复制代码 
llama-bench -m model.gguf

# 输出：
# | 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

一个用于使用 llama.cpp 实现应用程序的最小示例。对开发者很有用。

基础功能
  • 基本文本补全

🤝 贡献指南

  • 贡献者：可以开启 PR
  • 合作者：将根据贡献邀请加入
  • 维护者 ：可以向 llama.cpp 仓库的分支推送代码，并将 PR 合并到 master 分支

非常感激任何帮助管理 issues、PR 和项目的贡献！

  • 查看 [good first issues] 了解适合初次贡献的任务
  • 阅读 [CONTRIBUTING.md] 获取更多信息
  • 请务必阅读此文：[边缘计算推理]

对那些感兴趣的人来说，这里有一段背景故事：[Changelog 播客]

📚 其他文档

  • 命令行界面 (CLI)
  • 补全功能
  • 服务器
  • GBNF 语法
  • 开发文档
  • 如何构建
  • 在 Docker 上运行
  • 在 Android 上构建
  • 性能故障排除
  • GGML 技巧与窍门
  • 开创性论文和模型背景

如果你的问题涉及模型生成质量，那么请至少阅读以下链接和论文，以了解 LLaMA 模型的局限性。这在选择合适的模型大小以及理解 LLaMA 模型与 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

📱 XCFramework

XCFramework 是库的预编译版本，适用于 iOS、visionOS、tvOS 和 macOS。可以在 Swift 项目中使用，而无需从源代码编译库。例如：

swift 复制代码 
// swift-tools-version: 5.10
// swift-tools-version 声明构建此包所需的最低 Swift 版本。

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"
        )
    ]
)

以上示例使用的是库的中间版本 b5046。可以通过更改 URL 和校验和来使用不同版本。

🔧 命令行补全

某些环境支持命令行补全。

Bash 补全

bash 复制代码 
$ build/bin/llama-cli --completion-bash > ~/.llama-completion.bash
$ source ~/.llama-completion.bash

可以选择将其添加到你的 .bashrc 或 .bash_profile 中以自动加载。例如：

bash 复制代码 
$ echo "source ~/.llama-completion.bash" >> ~/.bashrc

📦 依赖项

库 用途 许可证
[yhirose/cpp-httplib] 单头文件 HTTP 服务器，用于 llama-server MIT
[stb-image] 单头文件图像格式解码器，用于多模态子系统 公共领域
[nlohmann/json] 单头文件 JSON 库，用于各种工具/示例 MIT
[miniaudio.h] 单头文件音频格式解码器，用于多模态子系统 公共领域
[subprocess.h] 用于 C 和 C++ 的单头文件进程启动解决方案 公共领域
  1. https://huggingface.co/docs/transformers/perplexity ↩︎
相关推荐
爱跑步的程序员~3 天前
SpringBoot集成SpringAI与Ollama本地大模型
java·后端·spring·ai·llama·springai
向量引擎小橙5 天前
视觉艺术的“奇点”：深度拆解 Gemini-3-Pro-Image-Preview 绘画模型，看这只“香蕉”如何重塑 AI 创作逻辑！
人工智能·python·gpt·深度学习·llama
正宗咸豆花5 天前
开源大模型涨价策略分析：Llama 3.5 与 GLM-5 的商业化博弈
开源·llama
qq_214803295 天前
使用 LLaMA-Factory 微调 Qwen2.5 模型，并转换为 GGUF 格式部署
llama
yyoc978 天前
Mac基于LLaMA Factory微调模型导入Ollama踩坑记录
大模型·微调·llama·ollama
zhangfeng11339 天前
大语言模型调试框架 Hugging Face vs LLaMA-Factory详细对比
人工智能·语言模型·llama
zhangfeng11339 天前
大语言模型 llama-factory 通常不推荐只用 LoRA 做新词库预热 embedding
深度学习·语言模型·llama
木卫二号Coding10 天前
第八十篇-E5-2680V4+V100-32G+llama-cpp运行+Qwen3-Next-80B-UD-Q2_K_XL.GGUF
llama
小明_GLC10 天前
大模型微调 PEFT vs LLaMA-Factory
人工智能·llama·peft·大模型微调·方法对比
热门推荐
01GitHub 镜像站点02Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services03AI Agent 平台横评：ZeroClaw vs OpenClaw vs Nanobot04全面体验 Grok API 中转站（2025 · Grok 4 系列最新版）05MIUI显示/隐藏5G开关的方法，信号弱时开启手机Wifi通话方法06如何解决 OpenClaw “Pairing required” 报错：两种官方解决方案详解07配置 OpenClaw 使用 Ollama 本地模型08从零搭建一个 PHP 登录注册系统（含完整源码）09openClaw安装飞书插件｜核心踩坑：spawn EINVAL 错误终极解决指南10使用 1panel面板 部署 php网站