gemma.cpp

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

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

注意：2024-04-04：如果使用 2B 模型，请从 Kaggle 重新下载权重并确保您有最新版本（-mqa 或版本 3）。我们正在更改代码以匹配新的权重。如果您希望使用旧权重，请将 configs.h 中的 ConfigGemma2B 改回 kVocabSize = 256128 和 kKVHeads = 8。

这个项目适合谁？

现代 LLM 推理引擎是复杂的系统，通常具有超越传统神经网络运行时的定制功能。这为通过高级算法和低级计算的协同设计进行研究和创新提供了机会。然而，面向部署的 C++ 推理运行时（不适合实验）和以 Python 为中心的 ML 研究框架（通过编译抽象低级计算）之间存在差距。

gemma.cpp 提供了 Gemma 2B 和 7B 模型的最小化实现，注重简单性和直接性，而非完全通用性。这受到垂直集成模型实现的启发，如 ggml、llama.c 和 llama.rs。

gemma.cpp 针对实验和研究用例。它旨在易于嵌入其他项目，依赖最少，并且易于修改，核心实现约 2K 行代码（以及约 4K 行支持性工具代码）。我们使用 Google Highway 库来利用可移植的 SIMD 进行 CPU 推理。

对于面向生产的边缘部署，我们推荐使用 JAX、Keras、PyTorch 和 Transformers 等 Python 框架的标准部署路径（所有模型变体在此）。

贡献

欢迎大大小小的社区贡献。开发者可参阅 DEVELOPERS.md 获取更多注意事项，并通过此邀请链接加入 Discord。本项目遵循 Google 的开源社区准则。

当前活跃开发在 dev 分支进行。请将拉取请求提交到 dev 分支而非 main 分支，main 分支旨在保持更稳定。

快速开始

系统要求

开始之前，您应该已安装：

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"

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

访问 Kaggle 上的 Gemma 模型页面并选择 Model Variations |> Gemma C++。在此选项卡中，Variation 下拉菜单包含以下选项。注意，bfloat16 权重保真度更高，而 8 位切换浮点权重能实现更快的推理。通常，我们建议从 -sfp 检查点开始。

或者，访问 Hugging Face Hub 上的 gemma.cpp 模型。首先进入所需模型的仓库（参见下面的建议）。然后，点击 Files and versions 选项卡并下载模型和分词器文件。对于程序化下载，如果您已安装 huggingface_hub，也可以通过运行以下命令下载：

huggingface-cli login # 仅首次使用时需要
huggingface-cli download google/gemma-2b-sfp-cpp --local-dir build/

2B 指令微调（it）和预训练（pt）模型：

模型名称	描述
`2b-it`	20 亿参数指令微调模型，bfloat16
`2b-it-sfp`	20 亿参数指令微调模型，8 位切换浮点
`2b-pt`	20 亿参数预训练模型，bfloat16
`2b-pt-sfp`	20 亿参数预训练模型，8 位切换浮点

7B 指令微调（it）和预训练（pt）模型：

模型名称	描述
`7b-it`	70 亿参数指令微调模型，bfloat16
`7b-it-sfp`	70 亿参数指令微调模型，8 位切换浮点
`7b-pt`	70 亿参数预训练模型，bfloat16
`7b-pt-sfp`	70 亿参数预训练模型，8 位切换浮点

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

步骤 2：解压文件

如果您从 Hugging Face 下载了模型，请跳到步骤 3。

填写同意书后，下载应开始获取 tar 归档文件 archive.tar.gz。从 archive.tar.gz 中解压文件（这可能需要几分钟）：

tar -xf archive.tar.gz

这应该会生成一个包含模型权重的文件（如 2b-it-sfp.sbs）和一个分词器文件（tokenizer.spm）。您可能想将这些文件移动到一个方便的目录位置（例如本仓库的 build/ 目录）。

步骤 3：构建

构建系统使用 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 可执行文件。

[!注意] Windows 子系统 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 有以下必需参数：

参数	描述	示例值
`--model`	模型类型。	`2b-it` ... (见下文)
`--weights`	压缩的权重文件。	`2b-it-sfp.sbs`
`--weight_type`	压缩的权重类型。	`sfp`
`--tokenizer`	分词器文件。	`tokenizer.spm`

gemma 的调用方式如下：

./gemma \
--tokenizer [分词器文件] \
--weights [压缩的权重文件] \
--weight_type [f32 或 bf16 或 sfp] \
--model [2b-it 或 2b-pt 或 7b-it 或 7b-pt 或 ...]

以下配置的示例调用：

压缩的权重文件 2b-it-sfp.sbs（2B 指令调优模型，8位开关浮点数）。
分词器文件 tokenizer.spm。

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

RecurrentGemma

这个仓库包含了一个基于 Griffin 的 Gemma 版本（论文，代码）。它的架构包括循环层和局部注意力，因此对于更长的序列更有效，并且比标准 Gemma 的内存占用更小。我们在这里提供了基于该论文的 C++ 实现。

要使用此仓库中包含的 Gemma 循环版本，请按照步骤 3 中所述构建 gemma 二进制文件。从 RecurrentGemma Kaggle 下载压缩的权重和分词器，如步骤 1 所示，然后按如下方式运行二进制文件：

./gemma --tokenizer tokenizer.spm --model gr2b-it --weights 2b-it-sfp.sbs

故障排除和常见问题

运行 ./gemma 失败，提示 "Failed to read cache gating_ein_0 (error 294) ..."

最常见的问题是 --weight_type 参数与模型文件不匹配。重新查看步骤 #3 并检查你下载的权重。

请注意，我们已经将权重类型从编译时决定移到了运行时参数。在接下来的步骤中，我们计划将这些信息嵌入到权重中。

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

目前如果你使用 Windows，我们建议在 WSL（Windows 子系统 for Linux）中构建。我们正在探索启用其他构建配置的选项，请查看 issues 以了解正在进行的讨论。

模型不响应指令并产生奇怪的输出

一个常见的问题是你使用了预训练模型，它没有经过指令调优，因此不会响应指令。确保你使用的是经过指令调优的模型（2b-it-sfp、2b-it、7b-it-sfp、7b-it），而不是预训练模型（任何带有 -pt 后缀的模型）。

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

我们正在开发一个 Python 脚本来将标准模型格式转换为 .sbs，希望在接下来的一两周内提供。关注这个 issue以获取更新。

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

确保你使用的是 8 位开关浮点数 -sfp 模型。
如果你使用笔记本电脑，确保电源模式设置为最大化性能，并且节能模式已关闭。对于大多数笔记本电脑，如果未插电，节能模式会自动激活。
关闭其他未使用的 CPU 密集型应用程序。
在 Mac 上，根据经验，我们观察到随着性能核心的参与，速度会出现"预热"上升。
尝试调整 --num_threads 参数值。根据设备情况，更大的数值并不总是意味着更好的性能。

我们也在研究算法和优化方法以实现更快的推理，敬请期待。

使用方法

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

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

详细程度	使用模式	详情
`--verbosity 0`	最小化	仅打印生成输出。适合作为 CLI 工具。
`--verbosity 1`	默认	标准的面向用户的终端 UI。
`--verbosity 2`	详细	显示额外的开发者和调试信息。

交互式终端应用

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

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

tokenizer                     : tokenizer.spm
compressed_weights            : 2b-it-sfp.sbs
model                         : 2b-it
weights                       : [未指定路径]
max_tokens                    : 3072
max_generated_tokens          : 2048

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

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

> 波士顿周边有哪些户外景点可以参观？

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


**波士顿港和岛屿：**

* **波士顿港岛国家和州立公园：** 探索原始海滩、野生动物和海洋历史。
* **查尔斯河滨河公园：** 欣赏港口和城市天际线的美景。
* **波士顿港游船公司：** 乘坐轻松的港口游船，从不同角度欣赏城市。
* **海港村：** 参观迷人的滨水区，有商店、餐厅和海港博物馆。

**森林和自然：**

* **森林公园：** 徒步穿越风景优美的森林，观赏多样的野生动物。
* **夸宾水库：** 在风景优美的环境中享受划船、钓鱼和徒步。
* **森林山：** 探索一座山，欣赏城市和周围景观的令人惊叹的景色。

...

作为命令行工具使用

要将 gemma 可执行文件用作命令行工具，创建一个带有完整指定参数的 gemma.cpp 别名可能很有用：

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

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

以下是用截断的输入文件提示 gemma 的示例（使用如上定义的 gemma2b 别名）：

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

[!注意] gemma.cpp 的 CLI 使用是实验性的，应考虑上下文长度限制。

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

$ cat configs.h | tail -35 | tr '\n' ' ' | xargs -0 echo "这段C++代码的作用是什么：" | gemma2b
[ 正在读取提示 ] ......................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
该代码定义了两个C++结构体，`ConfigGemma7B`和`ConfigGemma2B`，用于配置深度学习模型。

**ConfigGemma7B**：

* `kSeqLen`：存储要处理的序列长度。设置为7168。
* `kVocabSize`：存储词汇表大小，为256128。
* `kLayers`：深度学习模型的层数。设置为28。
* `kModelDim`：模型内部表示的维度。设置为3072。
* `kFFHiddenDim`：前馈和循环层隐藏表示的维度。设置为16 * 3072 / 2。

**ConfigGemma2B**：

* `kSeqLen`：存储要处理的序列长度。也设置为7168。
* `kVocabSize`：词汇表大小，为256128。
* `kLayers`：深度学习模型的层数。设置为18。
* `kModelDim`：模型内部表示的维度。设置为2048。
* `kFFHiddenDim`：前馈和循环层隐藏表示的维度。设置为16 * 2048 / 2。

这些结构体用于为Gemma7B或Gemma2B架构配置具有特定参数的深度学习模型。

将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 da250571a45826b21eebbddc1e50d0c1137dee5f)
FetchContent_MakeAvailable(highway)

注意，对于gemma.cpp的GIT_TAG，如果您想固定库版本，可以将origin/main替换为特定的提交哈希。

定义可执行文件后（将下面的[可执行文件名称]替换为您的可执行文件名称）：

target_link_libraries([可执行文件名称] libgemma hwy hwy_contrib sentencepiece)
FetchContent_GetProperties(gemma)
FetchContent_GetProperties(sentencepiece)
target_include_directories([可执行文件名称] PRIVATE ${gemma_SOURCE_DIR})
target_include_directories([可执行文件名称] PRIVATE ${sentencepiece_SOURCE_DIR})

将gemma.cpp构建为库

gemma.cpp也可以作为库依赖项用于您自己的项目。可以通过修改make调用，将目标从gemma改为libgemma来构建共享库制品。

[!注意] 如果您在自己的项目中使用gemma.cpp，并按照上一节中的FetchContent步骤操作，cmake会自动构建库，可以跳过本节。

首先，运行cmake：

cmake -B build

然后，使用libgemma目标运行make：

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

如果成功，您现在应该在build/目录中看到一个libgemma库文件。在Unix平台上，文件名为libgemma.a。

使用gemma.cpp的独立项目

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

如果您希望将您的项目包含在内，请随时联系我们或提交一个包含README.md编辑的PR。

致谢和联系方式

gemma.cpp由Austin Huang和Jan Wassenberg于2023年秋季启动，随后在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的贡献。

这不是Google官方支持的产品。