ghcr.io/ggml-org/llama.cpp:server

llama.cpp

C/C++ 实现的 LLM 推理

近期 API 变更

• https://github.com/ggml-org/llama.cpp/issues/9289
• https://github.com/ggml-org/llama.cpp/issues/9291

热门话题

• Hugging Face 缓存迁移：使用 -hf 下载的模型现在存储在标准 Hugging Face 缓存目录中，可与其他 HF 工具共享。
• https://github.com/ggml-org/llama.cpp/discussions/***
• https://github.com/ggml-org/llama.cpp/discussions/***
• https://github.com/ggml-org/llama.cpp/discussions/***
• llama-server 现已支持多模态：https://github.com/ggml-org/llama.cpp/pull/*** | 文档
• 用于 FIM 补全的 VS Code 扩展：https://github.com/ggml-org/llama.vscode
• 用于 FIM 补全的 Vim/Neovim 插件：https://github.com/ggml-org/llama.vim
• Hugging Face GGUF 编辑器：https://github.com/ggml-org/llama.cpp/discussions/9268 | 工具
• 浏览器中现已支持 WebGPU，查看介绍它的博客/演示 https://reeselevine.github.io/llamas-on-the-web/%E3%80%82

---

快速开始

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

• 使用 brew、nix 或 winget 安装 llama.cpp
• 使用 Docker 运行 - 参见我们的 Docker 文档
• 从 https://github.com/ggml-org/llama.cpp/releases 下载预构建二进制文件
• 通过克隆此仓库从源代码构建 - 查看 我们的构建指南

安装完成后，您需要一个模型来使用。前往 获取和量化模型 部分了解更多信息。

示例命令：

# 使用本地模型文件
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++ 实现，无任何依赖
• Apple 芯片是一等公民 - 通过 ARM NEON、Accelerate 和 Metal 框架进行优化
• 对 x86 架构的 AVX、AVX2、AVX512 和 AMX 支持
• 对 RISC-V 架构的 RVV、ZVFH、ZFH、ZICBOP 和 ZIHINTPAUSE 支持
• 1.5 位、2 位、3 位、4 位、5 位、6 位和 8 位整数量化，以实现更快的推理和减少内存使用
• 用于在 NVIDIA GPU 上运行 LLM 的自定义 CUDA 内核（通过 HIP 支持 AMD GPU，通过 MUSA 支持摩尔线程 GPU）
• Vulkan 和 SYCL 后端支持
• CPU+GPU 混合推理，可部分加速大于总 VRAM 容量的模型

llama.cpp 项目是 https://github.com/ggml-org/ggml 库新功能开发的主要试验场。

模型

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

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

纯文本

• LLaMA 🦙
• LLaMA 2 🦙🦙
• LLaMA 3 🦙🦙🦙
• Mistral 7B
• Mixtral MoE
• DBRX
• Jamba
• Falcon
• https://github.com/ymcui/Chinese-LLaMA-Alpaca 和 https://github.com/ymcui/Chinese-LLaMA-Alpaca-2
• https://github.com/bofenghuang/vigogne
• https://github.com/ggml-org/llama.cpp/pull/5423
• Koala
• Baichuan 1 & 2 + derivations
• Aquila 1 & 2
• https://github.com/ggml-org/llama.cpp/pull/3187
• Refact
• https://github.com/ggml-org/llama.cpp/pull/3417
• https://github.com/ggml-org/llama.cpp/pull/3553
• Yi models
• StableLM models
• Deepseek models
• Qwen models
• https://github.com/ggml-org/llama.cpp/pull/3557
• Phi models
• https://github.com/ggml-org/llama.cpp/pull/***
• GPT-2
• https://github.com/ggml-org/llama.cpp/pull/5118
• InternLM2
• https://github.com/WisdomShell/codeshell
• Gemma
• https://github.com/state-spaces/mamba
• Grok-1
• Xverse
• Command-R models
• SEA-LION
• GritLM-7B + GritLM-8x7B
• OLMo
• OLMo 2
• OLMoE
• Granite models
• https://github.com/EleutherAI/gpt-neox + https://github.com/EleutherAI/pythia
• ***-Arctic MoE
• Smaug
• Poro 34B
• Bitnet b1.58 models
• Flan T5
• Open Elm models
• GLM-4-0414
• SmolLM
• EXAONE-3.0-7.8B-Instruct
• FalconMamba Models
• Jais
• Bielik-11B-v2.3
• RWKV-7
• https://github.com/BlinkDL/RWKV-LM
• QRWKV-6
• GigaChat-20B-A3B
• Trillion-7B-preview
• Ling models
• LFM2 models
• Hunyuan models
• BailingMoeV2 (Ring/Ling 2.0) models
• Mellum models

多模态

• LLaVA 1.5 models, LLaVA 1.6 models
• BakLLaVA
• Obsidian
• ShareGPT4V
• MobileVLM 1.7B/3B models
• Yi-VL
• Mini CPM
• Moondream
• https://github.com/BAAI-DCAI/Bunny
• GLM-EDGE
• Qwen2-VL
• LFM2-VL

绑定

• Python: https://github.com/ddh0/easy-llama
• Python: https://github.com/abetlen/llama-cpp-python
• Go: https://github.com/go-skynet/go-llama.cpp
• Node.js: https://github.com/withcatai/node-llama-cpp
• JS/TS (llama.cpp 服务器客户端): lgrammel/modelfusion
• JS/TS (可编程提示引擎 CLI): https://github.com/offline-ai/cli
• JavaScript/Wasm (可在浏览器中运行): https://github.com/tangledgroup/llama-cpp-wasm
• TypeScript/Wasm (更友好的 API，可在 npm 上获取): https://github.com/ngxson/wllama
• Ruby: https://github.com/yoshoku/llama_cpp.rb
• Ruby: https://github.com/docusealco/rllama
• Rust (功能更丰富): https://github.com/edgenai/llama_cpp-rs
• Rust (更友好的 API): https://github.com/mdrokz/rust-llama.cpp
• Rust (更直接的绑定): https://github.com/utilityai/llama-cpp-rs
• Rust (从 crates.io 自动构建): https://github.com/ShelbyJenkins/llm_client
• C#/.NET: https://github.com/SciSharp/LLamaSharp
• C#/VB.NET (功能更丰富 - 社区许可证): LM-Kit.NET
• Scala 3: https://github.com/donderom/llm4s
• Clojure: https://github.com/phronmophobic/llama.clj
• React Native: https://github.com/mybigday/llama.rn
• Java: https://github.com/kherud/java-llama.cpp
• Java: https://github.com/QuasarByte/llama-cpp-jna
• Zig: https://github.com/Deins/llama.cpp.zig
• Flutter/Dart: https://github.com/netdur/llama_cpp_dart
• Flutter: https://github.com/xuegao-tzx/Fllama
• PHP (基于 llama.cpp 构建的 API 绑定和功能): https://github.com/distantmagic/resonance https://github.com/ggml-org/llama.cpp/pull/6326
• Guile Scheme: guile_llama_cpp
• Swift: https://github.com/srgtuszy/llama-cpp-swift
• Swift: https://github.com/ShenghaiWang/SwiftLlama
• Delphi: https://github.com/Embarcadero/llama-cpp-delphi
• Go (无需 CGo): https://github.com/hybridgroup/yzma
• Android: llama.android

UIs

(若要在此列出项目，该项目应明确声明依赖于 llama.cpp)

• https://github.com/yaroslavyaroslav/OpenAI-sublime-text (MIT)
• BonzAI App (专有)
• https://github.com/cztomsik/ava (MIT)
• https://github.com/alexpinel/Dot (GPL)
• https://github.com/ylsdamxssjxxdd/eva (MIT)
• https://github.com/iohub/coLLaMA (Apache-2.0)
• https://github.com/janhq/jan (AGPL)
• https://github.com/johnbean393/Sidekick (MIT)
• https://github.com/zhouwg/kantv?tab=readme-ov-file (Apache-2.0)
• https://github.com/firatkiral/kodibot (GPL)
• https://github.com/ggml-org/llama.vim (MIT)
• https://github.com/abgulati/LARS (AGPL)
• https://github.com/vietanhdev/llama-assistant (GPL)
• https://github.com/undreamai/LlamaLib (Apache-2.0)
• https://github.com/guinmoon/LLMFarm?tab=readme-ov-file (MIT)
• https://github.com/undreamai/LLMUnity (MIT)
• LMStudio (专有)
• https://github.com/mudler/LocalAI (MIT)
• https://github.com/LostRuins/koboldcpp (AGPL)
• MindMac (专有)
• https://github.com/MindWorkAI/AI-Studio (FSL-1.1-MIT)
• https://github.com/Mobile-Artificial-Intelligence/maid (MIT)
• https://github.com/Mozilla-Ocho/llamafile (Apache-2.0)
• https://github.com/nat/openplayground (MIT)
• https://github.com/nomic-ai/gpt4all (MIT)
• https://github.com/ollama/ollama (MIT)
• https://github.com/oobabooga/text-generation-webui (AGPL)
• https://github.com/a-ghorbani/pocketpal-ai (MIT)
• https://github.com/psugihara/FreeChat (MIT)
• https://github.com/ptsochantaris/emeltal (MIT)
• https://github.com/pythops/tenere (AGPL)
• https://github.com/containers/ramalama (MIT)
• https://github.com/semperai/amica (MIT)
• https://github.com/withcatai/catai (MIT)
• https://github.com/***89/autopen (GPL)

Tools

• https://github.com/akx/ggify – 从 Hugging Face Hub 下载 PyTorch 模型并将其转换为 GGML
• https://github.com/akx/ollama-dl – 从 Ollama 库下载模型以直接用于 llama.cpp
• https://github.com/crashr/gppm – 启动利用 NVIDIA Tesla P40 或 P100 GPU 的 llama.cpp 实例，降低空闲功耗
• https://github.com/gpustack/gguf-parser-go/tree/main/cmd/gguf-parser - 查看/检查 GGUF 文件并估算内存使用情况
• Styled Lines（专有许可，Unity3d 游戏开发推理部分的异步包装器，带有预构建的移动和 Web 平台包装器以及模型示例）
• https://github.com/unslothai/unsloth – 🦥 将微调及训练后的模型导出/保存为 GGUF（Apache-2.0）

Infrastructure

• https://github.com/intentee/paddler - 用于在自有基础设施中托管和扩展 AI 的开源 LLMOps 平台
• https://github.com/gpustack/gpustack - 管理用于运行 LLM 的 GPU 集群
• https://github.com/onicai/llama_cpp_canister - 在 Internet Computer 上作为智能合约的 llama.cpp，使用 WebAssembly
• https://github.com/mostlygeek/llama-swap - 透明代理，通过 llama-server 添加自动模型切换功能
• https://github.com/kalavai-net/kalavai-client - 众包端到端 LLM 部署，支持任意规模
• https://github.com/InftyAI/llmaz - ☸️ 基于 Kubernetes 的简单、高级大型语言模型推理平台。
• https://github.com/defilantech/llmkube - 用于 llama.cpp 的 Kubernetes 算子，支持多 GPU 和 Apple Silicon Metal

游戏

llama-server

一个轻量级、与 https://github.com/openai/openai-openapi 兼容的 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

输出：

| 模型 | 大小 | 参数 | 后端 | 线程数 | 测试 | tokens/秒 |

| ------------------- | ---------: | ---------: | ---------- | ------: | ------------: | -------------------: |

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

构建版本：3e0ba0e60 (4229)

## [`llama-simple`](examples/simple)

#### 使用`llama.cpp`实现应用的最小示例。对开发人员很有用。

-
基本文本补全
```bash
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分支
• 任何有关问题、PR和项目管理的帮助都非常感谢！
• 适合首次贡献的任务请参见https://github.com/ggml-org/llama.cpp/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
• 更多信息请阅读CONTRIBUTING.md
• 请务必阅读：https://github.com/ggml-org/llama.cpp/discussions/205
• 对感兴趣的人提供一些背景故事：Changelog播客

其他文档

• 命令行界面
• 补全功能
• 服务器
• GBNF语法

开发文档

• 构建方法
• 在Docker上运行
• 在Android上构建
• 多GPU使用
• 性能故障排除
• https://github.com/ggml-org/llama.cpp/wiki/GGML-Tips-&-Tricks

模型的开创性论文和背景

如果您遇到的问题与模型生成质量有关，请至少浏览以下链接和论文，以了解LLaMA模型的局限性。在选择合适的模型大小以及理解LLaMA模型与ChatGPT之间的显著和细微差异时，这一点尤为重要：

• LLaMA：
• LLaMA简介：一个拥有650亿参数的基础大型语言模型
• LLaMA：开放高效的基础语言模型
• GPT-3
• 语言模型是少样本学习者
• GPT-3.5 / InstructGPT / ChatGPT：
• 使语言模型遵循指令
• 通过人类反馈训练语言模型遵循指令

XCFramework

XCFramework是适用于iOS、visionOS、tvOS和macOS的库预编译版本。它可用于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补全

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

也可以选择将其添加到您的.bashrc或.bash_profile中，以实现自动加载。例如：

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

依赖项

• https://github.com/yhirose/cpp-httplib - 单头文件HTTP服务器，供llama-server使用 - MIT许可证
• https://github.com/nothings/stb - 单头文件图像格式解码器，供多模态子系统使用 - 公共领域
• https://github.com/nlohmann/json - 单头文件JSON库，供各种工具/示例使用 - MIT许可证
• https://github.com/mackron/miniaudio - 单头文件音频格式解码器，供多模态子系统使用 - 公共领域
• https://github.com/sheredom/subprocess.h - 用于C和C++的单头文件进程启动解决方案 - 公共领域