wehub/ggml-org--llama.cpp
1
0
Fork 0
Code Issues Pull Requests Actions 12 Deployments Models Agent Notes Packages Projects Releases Wiki Activity
Files
main
ggml-org--llama.cpp/README.md
T
wehub-resource-sync 69235fc2ec docs: make Chinese README the default
2026-07-13 08:34:04 +00:00

30 KiB
Raw Permalink Blame History

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

llama.cpp

llama

License: MIT Release Server Docker Winget

Manifesto / ggml / ops

C/C++ 实现的 LLM 推理

近期 API 变更

热门话题

快速开始

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

安装完成后，你还需要一个模型才能开始使用。请前往获取模型与量化章节了解更多。

示例命令：

# 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

描述

llama.cpp 的主要目标是在本地和云端的各种硬件上，以最少的配置实现 LLM 推理，并提供业界领先的性能。

  • 纯 C/C++ 实现，无任何依赖
  • Apple silicon 为第一等公民——通过 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 整数量化，实现更快的推理和更少的内存使用
  • 自定义 CUDA 内核，用于在 NVIDIA GPU 上运行 LLM（通过 HIP 支持 AMD GPU，通过 MUSA 支持 Moore Threads GPU）
  • Vulkan 和 SYCL 后端支持
  • CPU+GPU 混合推理，可部分加速超过总显存容量的大模型

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

模型

以下基础模型的微调版本通常也同样支持。

添加新模型支持的说明：HOWTO-add-model.md

纯文本

多模态

绑定
用户界面

（要让项目列在此处，应明确声明其依赖 llama.cpp）

工具
  • akx/ggify —— 从 Hugging Face Hub 下载 PyTorch 模型并转换为 GGML 格式
  • akx/ollama-dl —— 从 Ollama 库下载模型，以便直接与 llama.cpp 配合使用
  • crashr/gppm —— 利用 NVIDIA Tesla P40 或 P100 GPU 启动 llama.cpp 实例，降低空闲功耗
  • gpustack/gguf-parser —— 审查/检查 GGUF 文件并估算内存用量
  • Styled Lines（专有许可，推理部分的异步封装，用于 Unity3d 游戏开发，附带预构建的移动端和 Web 平台封装器及示例模型）
  • unslothai/unsloth —— 🦥 导出/保存微调及训练完成的模型为 GGUF 格式（Apache-2.0）
基础设施
  • Paddler —— 开源 LLMOps 平台，用于在你自己的基础设施中托管和扩展 AI
  • GPUStack —— 管理用于运行 LLM 的 GPU 集群
  • llama_cpp_canister —— 将 llama.cpp 作为互联网计算机上的智能合约运行（基于 WebAssembly）
  • llama-swap —— 透明代理，配合 llama-server 实现自动模型切换
  • Kalavai —— 众包端到端 LLM 部署，支持任意规模
  • llmaz —— ☸️ 在 Kubernetes 上运行大语言模型的简便、高级推理平台
  • LLMKube —— 用于 llama.cpp 的 Kubernetes 算子，支持多 GPU 和 Apple Silicon Metal 加速 USD 预算：$0/$3；剩余 $3；本次会话 USD 支出：$0
游戏
  • 露西的迷宫) —— 一个由 AI 模型控制的智能体试图迷惑你的简单迷宫游戏。

支持的后端

后端 目标设备
Metal Apple Silicon
BLAS 全部
BLIS 全部
SYCL Intel GPU
OpenVINO [进行中] Intel CPU、GPU 和 NPU
MUSA 摩尔线程 GPU
CUDA Nvidia GPU
HIP AMD GPU
ZenDNN AMD CPU
Vulkan GPU
CANN Ascend NPU
OpenCL Adreno GPU
IBM zDNN IBM Z 及 LinuxONE
WebGPU 全部
RPC) 全部
Hexagon [进行中] Snapdragon
VirtGPU VirtGPU APIR

获取与量化模型

Hugging Face) 平台托管了一批与 llama.cpp 兼容的 LLM)：

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

llama-cli -hf ggml-org/gemma-3-1b-it-GGUF

默认情况下，CLI 会从 Hugging Face 下载；你可以通过环境变量 MODEL_ENDPOINT 切换到其他选项。MODEL_ENDPOINT 必须指向与 Hugging Face 兼容的 API 端点。

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

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

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

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

llama-cli

用于访问和实验 llama.cpp 大部分功能的 CLI 工具。

  • 以对话模式运行

    带有内置对话模板的模型会自动激活对话模式。如果未自动激活，可以通过添加 -cnv 并使用 --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!
  • 使用自定义对话模板以对话模式运行 
    # 使用 "chatml" 模板（使用 -h 查看支持的模板列表）
llama-cli -m model.gguf -cnv --chat-template chatml

# 使用自定义模板
llama-cli -m model.gguf -cnv --in-prefix 'User: ' --reverse-prompt 'User:'
  • 使用自定义语法约束输出 
    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"}

    grammars/ 文件夹包含若干示例语法文件。如需编写自己的语法，请查阅 GBNF 指南。

    如需编写更复杂的 JSON 语法，请参阅 https://grammar.intrinsiclabs.ai/

llama-server

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

  • 在端口 8080 上以默认配置启动本地 HTTP 服务器 
    llama-server -m model.gguf --port 8080

# 基本 Web UI 可通过浏览器访问：http://localhost:8080
# 聊天补全端点：http://localhost:8080/v1/chat/completions
  • 支持多用户和并行解码 
    # 最多 4 个并发请求，每个最大上下文为 4096
llama-server -m model.gguf -c 16384 -np 4
  • 启用推测解码 
    # draft.gguf 模型应为目标 model.gguf 的小型变体
llama-server -m model.gguf -md draft.gguf
  • 托管嵌入模型 
    # 使用 /embedding 端点
llama-server -m model.gguf --embedding --pooling cls -ub 8192
  • 托管重排序模型 
    # 使用 /reranking 端点
llama-server -m model.gguf --reranking
  • 使用语法约束所有输出 
    # 自定义语法
llama-server -m model.gguf --grammar-file grammar.gbnf

# JSON
llama-server -m model.gguf --grammar-file grammars/json.gbnf

llama-perplexity

用于衡量模型在给定文本上的困惑度1 （及其他质量指标）的工具。

  • 衡量文本文件的困惑度 
    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 散度 
    # TODO

llama-bench

基准测试推理在不同参数下的性能。

  • 运行默认基准测试 
    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 实现应用的最小示例，对开发者非常有用。

  • 基础文本补全 
    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

贡献指南

  • 贡献者可以提交 PR
  • 根据贡献情况邀请协作者
  • 维护者可以向 llama.cpp 仓库推送分支并将 PR 合入 master 分支
  • 欢迎任何帮助管理 Issue、PR 和项目的工作！
  • 参见 good first issues 寻找适合初次贡献的任务
  • 阅读 CONTRIBUTING.md 获取更多信息
  • 请务必阅读：Inference at the edge
  • 感兴趣的读者可了解一点背景故事：Changelog podcast

其他文档

开发文档

重要论文及模型背景

如果你的问题是关于模型生成质量的，请至少阅读以下链接和论文，了解 LLaMA 模型的局限性。这对于选择合适的模型大小以及理解 LLaMA 模型与 ChatGPT 之间显著和微妙的差异尤为重要：

XCFramework

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

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

以上示例使用了该库的中间构建版本 b5046。可通过修改 URL 和校验和来使用不同版本。

命令补全

部分环境支持命令行补全。

Bash 补全

$ build/bin/llama-cli --completion-bash > ~/.llama-completion.bash
$ source ~/.llama-completion.bash

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

$ 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++ 的单头文件进程启动解决方案 — 公有领域
Reference in New Issue View Git Blame Copy Permalink