gemma.cpp

gemma.cpp 是一个轻量级的、独立的 C++ 推理引擎，用于运行来自 Google 的 Gemma 基础模型。

有关 Gemma 的更多信息，请参阅 ai.google.dev/gemma。模型权重，包括 gemma.cpp 特有的文件，可在 kaggle 上获取。

本项目适合哪些人群？

现代大型语言模型（LLM）推理引擎是高度复杂的系统，通常具备超越传统神经网络运行时的定制化功能。这为通过高层算法与底层计算的协同设计进行研究和创新提供了机会。然而，面向部署的 C++ 推理运行时并不适合实验性开发；而以 Python 为中心的机器学习研究框架则通过编译抽象了底层计算细节，两者之间存在一定的差距。

gemma.cpp 提供了 Gemma-2、Gemma-3 和 PaliGemma-2 模型的极简实现，专注于简洁性和直接性，而非全面通用性。这一设计灵感来源于垂直整合的模型实现，例如 ggml、llama.c 和 llama.rs 等项目。

gemma.cpp 主要面向实验和研究场景。它易于嵌入到其他项目中，依赖性极低，并且核心实现代码量较小（约 2K 行），加上约 4K 行的支持工具代码，便于修改和扩展。我们使用 Google Highway 库来利用可移植的 SIMD 指令进行 CPU 推理。

对于生产环境下的边缘部署，我们建议采用标准的 Python 框架（如 JAX、Keras、PyTorch 和 Transformers）来进行部署，这些框架支持所有版本的 Gemma 模型（详见 kaggle）。

贡献说明

欢迎社区成员以各种方式参与贡献。更多关于开发者贡献的信息，请参阅 DEVELOPERS.md，并可通过此邀请链接加入我们的 Discord 社区：[discord.gg/H5jCBAWxAe]。本项目遵循 Google 开源社区行为准则。

[!注意] 目前的活跃开发工作在 dev 分支上进行。请将拉取请求提交至 dev 分支，而不是 main 分支，后者旨在保持更高的稳定性。

项目内容概览

• LLM

  • 仅限 CPU 的推理：Gemma 2-3、PaliGemma 2。
  • 使用 TopK 和温度采样。
  • 支持反向传播（VJP）和 Adam 优化器，适用于 Gemma 的研究用途。

• 优化技术

  • 混合精度（fp8、bf16、fp32、fp64）矩阵乘法：
    • 针对 BF16 指令设计，能够高效模拟其行为。
    • 自动运行时调优，每种矩阵形状有 7 个参数可供调整。
  • 权重压缩直接集成到 GEMM 中：
    • 自定义 fp8 格式，具有 2–3 位尾数；张量缩放。
    • 同时支持 bf16、f32 和非均匀 4 位量化（NUQ）；易于添加新格式。

• 基础设施

  • SIMD：通过 Highway 实现单一接口，在运行时选择合适的指令集。
  • 张量并行：支持 CCX 感知和多插槽线程池。
  • 磁盘 I/O：支持内存映射或并行读取，并提供用户可覆盖的启发式策略。
  • 自定义格式，支持正向和反向兼容的元数据序列化。
  • 模型转换功能基于 Safetensors，但尚未开源。
  • 跨平台支持：Linux、Windows 和 OS X 均可运行。使用 CMake 或 Bazel 构建，兼容任意 CPU。

• 前端接口

  • C++ API，支持单次查询和批量推理的流式处理。
  • 基本的交互式命令行应用。
  • 基本的 Python 绑定（使用 pybind11）。

快速入门

系统要求

在开始之前，您需要安装以下工具：

• CMake
• Clang C++ 编译器，至少支持 C++17。
• tar 工具，用于解压 Kaggle 下载的归档文件。

在 Windows 上原生构建需要 Visual Studio 2012 Build Tools，并安装可选的 Clang/LLVM C++ 前端 (clang-cl)。可以通过命令行使用 winget 安装：

winget install --id Kitware.CMake
winget install --id Microsoft.VisualStudio.2022.BuildTools --force --override "--passive --wait --add Microsoft.VisualStudio.Workload.VCTools;installRecommended --add Microsoft.VisualStudio.Component.VC.Llvm.Clang --add Microsoft.VisualStudio.Component.VC.Llvm.ClangToolset"

第一步：从 Kaggle 或 Hugging Face Hub 获取模型权重和分词器

访问 Gemma-2 的 Kaggle 页面，选择“Model Variations”中的“Gemma C++”。

在该选项卡中，“Variation”下拉菜单包含以下选项。请注意，bfloat16 权重具有更高的保真度，而 8 位浮点权重则能加速推理。总体而言，我们建议从 -sfp 检查点开始。

[!注意] 重要提示：强烈建议从 gemma2-2b-it-sfp 模型开始，以便快速上手。

Gemma 2 模型的命名规则为 gemma2-2b-it 对应 2B 参数量，9b-it 或 27b-it 则分别对应 9B 和 27B 参数量。具体命名规则请参考 configs.cc 文件中的 ModelPrefix 函数。

第二步：解压文件

填写同意书后，下载将生成一个名为 archive.tar.gz 的归档文件。使用以下命令解压该文件（可能需要几分钟）：

tar -xf archive.tar.gz

解压后会得到包含模型权重的文件，例如 2b-it-sfp.sbs，以及分词器文件 (tokenizer.spm)。您可以将这些文件移动到方便的位置，例如本项目的 build/ 目录。

第三步：构建

构建系统使用 CMake。要构建 gemma 推理运行时，首先创建一个构建目录，并从项目根目录运行 cmake 生成构建文件。请注意，如果您之前已经运行过 cmake 并希望使用不同的配置重新构建，请务必先删除 build/ 目录下的所有文件，命令如下：

rm -rf build/*

类 Unix 平台

cmake -B build

运行 cmake 后，进入 build/ 目录并执行 make，即可编译出 ./gemma 可执行文件：

# 配置 build 目录
cmake --preset make

# 使用 make 构建项目
cmake --build --preset make -j [要使用的并行线程数]

将 [要使用的并行线程数] 替换为一个数字——系统可用的核心数是一个合理的参考值。例如，make -j4 gemma 将使用 4 个线程进行构建。如果 nproc 命令可用，可以使用 make -j$(nproc) gemma 作为线程数的合理默认值。

如果你不确定 -j 标志的合适值，也可以直接运行 make gemma，它仍然会构建出 ./gemma 可执行文件。

[!NOTE] 在 Windows Subsystem for Linux (WSL) 上的用户应将并行线程数设置为 1。使用更大的线程数可能会导致错误。

如果构建成功，你现在应该在 build/ 目录下有一个 gemma 可执行文件。

Windows

# 配置 `build` 目录
cmake --preset windows

# 使用 Visual Studio Build Tools 构建项目
cmake --build --preset windows -j [要使用的并行线程数]

如果构建成功，你现在应该在 build/ 目录下有一个 gemma.exe 可执行文件。

Bazel

bazel build -c opt --cxxopt=-std=c++20 :gemma

如果构建成功，你现在应该在 bazel-bin/ 目录下有一个 gemma 可执行文件。

Make

如果你更喜欢 Makefile，@jart 在这里提供了一个：

https://github.com/jart/gemma3/blob/main/Makefile

第 4 步：运行

现在你可以从 build/ 目录内运行 gemma。

gemma 有以下必需参数：

参数	描述	示例值
--weights	压缩的权重文件。	2b-it-sfp.sbs
--tokenizer	分词器文件。	tokenizer.spm

以下配置的示例调用：

• 权重文件 gemma2-2b-it-sfp.sbs（Gemma2 2B 指令微调模型，8 位切换浮点）。
• 分词器文件 tokenizer.spm（对于 2025 年 5 月 6 日之后创建的单格式权重文件，或由 migrate_weights.cc 输出的文件，可以省略）。

./gemma \
--tokenizer tokenizer.spm --weights gemma2-2b-it-sfp.sbs

PaliGemma 视觉语言模型

本仓库包含 PaliGemma 2 VLM 的版本（论文）。我们在此提供了 PaliGemma 2 模型的 C++ 实现。

要使用本仓库中包含的 PaliGemma 版本，请按照上述第 3 步构建 gemma 二进制文件。从 Kaggle 下载压缩的权重和分词器：

Kaggle

然后按如下方式运行二进制文件：

./gemma \
--tokenizer paligemma_tokenizer.model \
--weights paligemma2-3b-mix-224-sfp.sbs \
--image_file paligemma/testdata/image.ppm

请注意，图像读取代码非常简单，暂时避免依赖图像处理库。目前我们仅支持读取二进制 PPM（P6）格式。因此，可以使用 convert 等工具先将图像转换为该格式，例如：

convert image.jpeg -resize 224x224^ image.ppm

（由于图像最终仍会被调整大小以供处理，因此在此阶段提前调整大小可以略微加快加载速度。）

与图像交互（使用 mix-224 检查点）可能看起来像这样：

> 简要描述一下这张图片
城市中央有一座带有两座塔的大楼。
> 这是什么类型的建筑？
教堂
> 教堂是什么颜色的？
灰色
> 图片说明
一座带有两座塔的大楼矗立在水边。大楼有一个棕色的屋顶和一侧的窗户。大楼前面有一棵树，顶部飘扬着一面旗帜。水面平静而湛蓝，映照着天空。一座桥横跨水面，一艘红白相间的船停在水面上。大楼侧面有一扇窗，顶部插着一面旗子。大楼前方有一棵高大的树，从水面上可以看到大楼的一侧窗户。水面呈绿色，天空是蓝色的。

迁移到单文件格式

现在有一种新的权重文件格式，即单文件格式，可以直接包含分词器（以及模型类型）。有一个工具可用于将多文件格式迁移到单文件格式。

io/migrate_weights \
  --tokenizer .../tokenizer.spm --weights .../gemma2-2b-it-sfp.sbs \
  --output_weights .../gemma2-2b-it-sfp-single.sbs

迁移完成后，你可以省略分词器参数，如下所示：

./gemma --weights .../gemma2-2b-it-sfp-single.sbs

故障排除与常见问题解答

在 Windows / Visual Studio 中构建时出现问题

目前，如果你使用的是 Windows，我们建议在 WSL（Windows Subsystem for Linux）中进行构建。我们正在探索其他构建配置的可能性，相关讨论请参见 issues。

模型对指令无反应并产生奇怪的输出

常见问题之一是你使用的是预训练模型，而不是经过指令微调的模型，因此无法响应指令。请确保你使用的是指令微调模型（gemma2-2b-it-sfp），而不是预训练模型（任何带有 -pt 后缀的模型）。

支持哪些序列长度？

请查看 configs.cc 和 InferenceArgs.seq_len 中的 max_seq_len。对于大于 1B 的 Gemma 3 模型，通常为 32K，但如果内存充足，128K 也可以工作。请注意，长序列由于注意力机制的二次复杂度，处理速度会较慢。

如何将我的微调模型转换为 .sbs 压缩模型文件？

对于 PaliGemma 2 检查点，你可以使用 python/convert_from_safetensors.py 从 safetensors 格式转换（已通过 bazel 构建测试）。对于适配器模型，你可能需要调用 merge_and_unload() 将适配器模型转换为单文件格式，然后再进行转换。

以下是使用本地安装了 (venv) torch、numpy、safetensors、absl-py 等库的情况下，通过 bazel 构建压缩库来使用的方法：

bazel build //compression/python:compression
BAZEL_OUTPUT_DIR="${PWD}/bazel-bin/compression"
python3 -c "import site; print(site.getsitepackages())"

# 在此处使用你的 sites-packages 文件：
ln -s $BAZEL_OUTPUT_DIR [...]/site-packages/compression
python3 python/convert_from_safetensors.py --load_path [...].safetensors.index.json

有哪些简单的方法可以让模型运行得更快呢？

1. 确保你使用的是 8 位切换浮点 -sfp 模型。 这些模型的大小是 bf16 的一半，因此占用更少的内存带宽和缓存空间。
2. 由于自动调优机制，第二次及尤其是第三次查询会更快。
3. 如果你在笔记本电脑上运行，请确保电源模式设置为最大化性能， 并且节能模式已关闭。大多数笔记本电脑在未插电时会自动启用节能模式。
4. 关闭其他未使用的、占用大量 CPU 资源的应用程序。
5. 根据经验，在 Mac 上，我们观察到随着性能核心被激活，速度会有一个“预热”提升的过程。

我们也在研究算法和优化方法以提高推理速度，敬请期待。

使用方法

gemma 有不同的使用模式，由详细程度标志控制。

目前所有使用模式都是交互式的，会在用户输入换行符后触发文本生成。

详细程度	使用模式	说明
--verbosity 0	极简模式	只打印生成的文本内容。适合作为命令行工具。
--verbosity 1	默认模式	标准的面向用户的终端界面。
--verbosity 2	详细模式	显示额外的开发者和调试信息。

交互式终端应用

默认情况下，详细程度设置为 1，调用 gemma 时会启动基于终端的交互界面：

$ ./gemma [...]
  __ _  ___ _ __ ___  _ __ ___   __ _   ___ _ __  _ __
 / _` |/ _ \ '_ ` _ \| '_ ` _ \ / _` | / __| '_ \| '_ \
| (_| |  __/ | | | | | | | | | | (_| || (__| |_) | |_) |
 \__, |\___|_| |_| |_|_| |_| |_|\__,_(_)___| .__/| .__/
  __/ |                                    | |   | |
 |___/                                     |_|   |_|

...

*使用说明*
  输入指令并按回车键（%C 重置对话，%Q 退出）。

*示例*
  - 给奶奶写封邮件，感谢她送来的饼干。
  - 马萨诸塞州周边有哪些值得参观的历史景点？
  - 用 JavaScript 计算第 n 个斐波那契数。
  - 写一段关于 WebGPU 编程的单口喜剧段子。

> 波士顿周边有哪些适合户外活动的地方？

[ 正在读取提示 ] .....................


**波士顿港与群岛：**

* **波士顿港国家与州立公园：** 探索原始海滩、野生动物和航海历史。
* **查尔斯河滨步道：** 欣赏港口和城市天际线的迷人景色。
* **波士顿港游轮公司：** 乘坐轻松的港口游轮，从不同角度欣赏城市风光。
* **海港村：** 参观一个迷人的海滨区域，那里有商店、餐厅和海港博物馆。

**森林与自然：**

* **森林公园：** 徒步穿越风景优美的森林，观赏多样化的野生动物。
* **夸宾水库：** 在风景如画的环境中划船、钓鱼和徒步旅行。
* **森林山：** 探索一座可以俯瞰城市及周边景观的山峰。

...

作为命令行工具使用

如果想将 gemma 可执行文件用作命令行工具，可以为 gemma.cpp 创建一个带有完整参数的别名：

alias gemma2b="~/gemma.cpp/build/gemma -- --tokenizer ~/gemma.cpp/build/tokenizer.spm --weights ~/gemma.cpp/build/gemma2-2b-it-sfp.sbs --verbosity 0"

请将上述路径替换为你自己下载的模型和分词器路径。

以下是一个使用 gemma2b 别名（如上定义）来调用 gemma 并传入截断输入文件的示例：

cat configs.h | tail -n 35 | tr '\n' ' ' | xargs -0 echo "这段 C++ 代码的作用是什么：" | gemma2b

[!注意] gemma.cpp 的命令行使用仍处于实验阶段，需考虑上下文长度的限制。

上述命令的输出应如下所示：

[ 正在读取提示 ] [...]
这段 C++ 代码片段定义了一组用于大型语言模型（LLM）实现的**常量**，很可能与**注意力机制**相关。

让我们逐行解析这段代码：
[...]

将 gemma.cpp 作为库集成到你的项目中

将 gemma.cpp 集成到你自己的项目中最简单的方式是使用 FetchContent 引入 gemma.cpp 及其依赖项。你可以在 CMakeLists.txt 中添加以下内容：

include(FetchContent)

FetchContent_Declare(sentencepiece GIT_REPOSITORY https://github.com/google/sentencepiece GIT_TAG 53de76561cfc149d3c01037f0595669ad32a5e7c)
FetchContent_MakeAvailable(sentencepiece)

FetchContent_Declare(gemma GIT_REPOSITORY https://github.com/google/gemma.cpp GIT_TAG origin/main)
FetchContent_MakeAvailable(gemma)

FetchContent_Declare(highway GIT_REPOSITORY https://github.com/google/highway.git GIT_TAG 2a16a50ff61071bb25ddef0ce35d92b0e2b9c579)
FetchContent_MakeAvailable(highway)

请注意，对于 gemma.cpp 的 GIT_TAG，你可以将其替换为特定的提交哈希值，以便固定库的版本。

在定义好你的可执行文件后（将 [Executable Name] 替换为你自己的可执行文件名称）：

target_link_libraries([Executable Name] libgemma hwy hwy_contrib sentencepiece)
FetchContent_GetProperties(gemma)
FetchContent_GetProperties(sentencepiece)
target_include_directories([Executable Name] PRIVATE ${gemma_SOURCE_DIR})
target_include_directories([Executable Name] PRIVATE ${sentencepiece_SOURCE_DIR})

将 gemma.cpp 构建为库

gemma.cpp 也可以作为库依赖项用于你自己的项目。只需修改构建命令，将目标改为 libgemma 而不是 gemma 即可构建共享库文件。

[!注意] 如果你已经在前一节中通过 FetchContent 步骤将 gemma.cpp 集成到你的项目中，那么库的构建会由 cmake 自动完成，本节可以跳过。

首先运行 cmake：

cmake -B build

然后使用 libgemma 目标运行 make：

cd build
make -j [要使用的并行线程数] libgemma

如果成功，你应该会在 build/ 目录下得到一个 libgemma 库文件。在 Unix 系统上，文件名为 libgemma.a。

使用 gemma.cpp 的独立项目

一些使用 gemma.cpp 的独立项目：

• gemma-cpp-python - Python 绑定
• lua-cgemma - Lua 绑定
• Godot 引擎演示项目

如果你希望你的项目也被收录，请随时联系我们或提交包含 README.md 修改的 PR。

致谢与联系方式

gemma.cpp 项目于 2023 年秋季由 Austin Huang 和 Jan Wassenberg 启动，并在 Phil Culliton、Paul Chang 和 Dan Zheng 等人的贡献下，于 2024 年 2 月正式发布。

Griffin 支持于 2024 年 4 月实现，这得益于 Andrey Mikhaylov、Eugene Kliuchnikov、Jan Wassenberg、Jyrki Alakuijala、Lode Vandevenne、Luca Versari、Martin Bruse、Phil Culliton、Sami Boukortt、Thomas Fischbacher 和 Zoltan Szabadka 等人的贡献。该支持已于 2025 年 9 月移除。

Gemma-2 支持于 2024 年 6 月至 7 月期间，在多位人士的帮助下得以实现。

PaliGemma 支持则于 2024 年 9 月实现，Daniel Keysers 为此做出了重要贡献。

自首次发布以来，Jan Wassenberg 持续贡献了多项改进，其中包括显著提升效率。

本项目并非 Google 官方支持的产品。

gemma.cpp 快速上手指南

gemma.cpp 是 Google Gemma 基础模型的轻量级独立 C++ 推理引擎，专为实验和研究场景设计。它支持 Gemma-2、Gemma-3 和 PaliGemma-2 模型，具有依赖少、代码简洁、易于嵌入等特点。

环境准备

在开始之前，请确保您的系统已安装以下依赖：

• CMake: 构建系统工具。
• C++ 编译器: 推荐使用 Clang，需支持至少 C++17 标准。
• tar: 用于解压从 Kaggle 下载的模型归档文件。

Windows 用户特别说明

若在 Windows 原生环境构建，需要安装 Visual Studio 2022 Build Tools 并包含 Clang/LLVM C++ 前端 (clang-cl)。可通过 winget 快速安装：

winget install --id Kitware.CMake
winget install --id Microsoft.VisualStudio.2022.BuildTools --force --override "--passive --wait --add Microsoft.VisualStudio.Workload.VCTools;installRecommended --add Microsoft.VisualStudio.Component.VC.Llvm.Clang --add Microsoft.VisualStudio.Component.VC.Llvm.ClangToolset"

建议：Windows 用户推荐使用 WSL (Windows Subsystem for Linux) 进行构建，以获得更稳定的体验。

安装步骤

第一步：获取模型权重和分词器

访问 Kaggle Gemma-2 页面 或 Hugging Face Hub。

1. 选择 Model Variations > Gemma C++。
2. 在 Variation 下拉菜单中选择模型版本。
   • 推荐新手：选择 gemma2-2b-it-sfp（8-bit switched floating point），推理速度更快且易于上手。
   • 注意：带 -it 后缀的是指令微调模型，带 -pt 的是预训练模型（不支持指令交互）。
3. 同意协议后下载 archive.tar.gz 文件。

第二步：解压文件

在下载目录执行以下命令解压（可能需要几分钟）：

tar -xf archive.tar.gz

解压后将得到权重文件（如 2b-it-sfp.sbs）和分词器文件（tokenizer.spm）。建议将它们移动到项目构建目录或方便访问的位置。

第三步：编译项目

在项目根目录下创建构建目录并生成构建文件。

Linux / macOS (Unix-like)

# 配置构建目录
cmake -B build

# 进入构建目录并编译
cd build
cmake --preset make
# 使用多核编译，将 <线程数> 替换为 CPU 核心数（如 4, 8），或直接运行 make gemma
cmake --build --preset make -j <线程数>

WSL 用户注意：如果在 WSL 中遇到错误，请尝试将线程数设置为 1 (-j 1)。

Windows (Visual Studio)

# 配置构建目录
cmake --preset windows

# 使用 Visual Studio Build Tools 编译
cmake --build --preset windows -j <线程数>

Bazel (可选)

bazel build -c opt --cxxopt=-std=c++20 :gemma

编译成功后，您将在 build/ (CMake) 或 bazel-bin/ (Bazel) 目录下找到 gemma (或 gemma.exe) 可执行文件。

基本使用

进入包含可执行文件的目录，即可运行推理。

运行文本模型

您需要指定权重文件和分词器文件。以下以 Gemma-2 2B 指令模型为例：

./gemma \
--tokenizer tokenizer.spm \
--weights gemma2-2b-it-sfp.sbs

运行后进入交互式命令行，您可以直接输入提示词与模型对话。

提示：如果您使用了迁移后的单文件格式（包含分词器），可以省略 --tokenizer 参数： ./gemma --weights gemma2-2b-it-sfp-single.sbs

运行 PaliGemma 视觉语言模型

gemma.cpp 也支持 PaliGemma-2 模型。首先从 Kaggle 下载对应的权重和分词器，并将图片转换为二进制 PPM 格式（P6）。

1. 转换图片格式 (需安装 ImageMagick):

   convert image.jpeg -resize 224x224^ image.ppm
   

2. 运行推理:

   ./gemma \
   --tokenizer paligemma_tokenizer.model \
   --weights paligemma2-3b-mix-224-sfp.sbs \
   --image_file paligemma/testdata/image.ppm
   

随后即可针对图片内容进行提问（例如："Describe the image briefly"）。