gemma.cpp 完全指南：Google Gemma 系列模型的轻量级 C++ CPU 推理引擎（构建、运行与库集成）

gemma.cpp 完全指南：Google Gemma 系列模型的轻量级 C++ CPU 推理引擎（构建、运行与库集成）

【免费下载链接】gemma.cpplightweight, standalone C++ inference engine for Google's Gemma models.项目地址: https://gitcode.com/GitHub_Trending/ge/gemma.cpp

gemma.cpp 是 Google 官方开源的 Gemma 基础模型（Gemma 2、Gemma 3 与 PaliGemma 2）的轻量级、独立 C++ 推理引擎，以"极简、可直接修改、最小依赖"为设计目标，面向研究与实验场景。本文以 README.md 为主线，结合仓库源码（gemma/gemma_args.h、gemma/configs.cc、gemma/run.cc 等），系统讲解从获取权重、构建、运行到嵌入自有项目的完整实战路径，读完你可以独立在 CPU 上跑通 Gemma 文本模型、RecurrentGemma 与 PaliGemma 视觉语言模型，并掌握全部命令行参数的底层含义。

一、项目定位：gemma.cpp 为谁而写

现代 LLM 推理引擎往往是非常复杂的系统，常常在传统神经网络运行时之外扩展了各种定制能力。这为"高层算法与底层计算的协同设计"带来了研究与创新空间，但也存在一个明显的断层：

• 面向部署的 C++ 推理运行时（例如 ggml、llama.cpp 一类）没有为实验设计，修改成本高；
• 以 Python 为中心的 ML 研究框架通过编译抽象掉了底层计算细节，研究者难以触达底层。

gemma.cpp 正处在这两者之间：它对 Gemma 2、Gemma 3 和 PaliGemma 2 提供了最小化的实现，强调简单直接而非完全通用，这一思路受 ggml、llama.c、llama.rs 等"垂直集成"模型实现的启发。

其目标用户是研究与实验场景：它便于嵌入其他项目（依赖极少），也便于修改——核心实现约 2K 行 C++ 代码，外加约 4K 行支撑工具代码。推理计算借助 Google 的 Highway 库实现可移植 SIMD，同一份代码在运行时自动选择指令集（ISA）。

需要特别说明定位边界：gemma.cpp 并非面向生产的边缘部署方案。README 明确建议生产环境走 JAX、Keras、PyTorch、Transformers 等 Python 框架的标准部署路径。它同时不是一个官方支持的 Google 产品（见 README 末尾 Acknowledgements 部分）。

二、功能全览：仓库里到底有什么

README 的 "What's inside?" 一节把仓库能力分为四块，这里结合源码目录逐一展开：

LLM 推理能力

• 纯 CPU 推理：支持 Gemma 2、Gemma 3、Griffin（SSM，即 RecurrentGemma）与 PaliGemma 2 四类模型；
• 采样策略：TopK + 温度（temperature）采样；
• 研究与训练侧：为 Gemma 提供了反向传播（VJP，vector-Jacobian product）与 Adam 优化器。

优化手段（在 ops/ 与 compression/ 目录）

• 混合精度 GEMM：支持 fp8、bf16、fp32、fp64 位宽的矩阵乘，专门面向 BF16 指令设计，可在不支持时高效模拟；
• 运行时自动调优（autotuning）：对每种矩阵形状自动调整 7 个参数；
• 权重压缩直接集成进 GEMM：自定义 fp8 格式（2~3 位尾数、张量级缩放），也支持 bf16、f32 与非均匀 4-bit（NUQ）格式，且容易扩展新格式。

基础设施

• SIMD：通过 Highway 单一实现，运行时选择 ISA；
• 张量并行：CCX（core complex，共享 L3 缓存的核心簇）感知、多插槽（multi-socket）线程池，见 util/threading.h 中的NestedPools；
• 磁盘 I/O：内存映射（memory map）或并行读取两种方式，默认按启发式自动选择，也允许用户覆盖；
• 自定义权重格式：带前向/后向兼容的元数据序列化（.sbs 文件）；
• 模型转换：提供从 Safetensors 转换的脚本（python/convert_from_safetensors.py）；
• 可移植性：支持 Linux、Windows、macOS，构建系统为 CMake 与 Bazel，可运行于 "Any" CPU。

前端接口

• C++ API：支持流式输出，覆盖单查询（single query）与批处理（batched inference）两种模式，见 gemma/gemma.h 中的Generate/GenerateBatch接口；
• 交互式命令行应用：gemma/run.cc；
• Python 绑定（基于 pybind11）：python/。

三、快速上手：从零运行第一个 Gemma 模型

3.1 系统要求

开始前需要安装：

• CMake；
• Clang C++ 编译器，至少支持 C++17（gemma/run.cc 第 41~43 行会在编译期检查：HWY_CXX_LANG < 201703L时直接报错）；
• tar，用于解压从 Kaggle 下载的归档文件。

在 Windows 上原生构建，需要 Visual Studio 2022 Build Tools 及其可选的 Clang/LLVM C++ 前端（clang-cl）。README 给出了一行winget安装命令（winget install --id Microsoft.VisualStudio.2022.BuildTools --force --override ...添加 VCTools 工作负载与 Clang 组件，另安装 Kitware.CMake）。不过 README 的排障章节也明确建议：Windows 用户优先在 WSL（Windows Subsystem for Linux）中构建。

3.2 第一步：从 Kaggle 获取模型权重与分词器

访问 Kaggle 上 Gemma 的模型页面，进入Gemma C++变体（Model Variations |> Gemma C++），其下拉框包含多个Variation选项。README 强调两点：

1. bfloat16 权重保真度更高，8-bit 切换浮点（-sfp）权重推理更快；
2. 强烈建议从gemma2-2b-it-sfp模型开始（Gemma 2 的 2B 指令微调 + sfp 量化版本）。

Gemma 2 模型命名规则为：2B 对应gemma2-2b-it，其余为9b-it、27b-it。模型前缀（ModelPrefix）的完整映射定义在 gemma/configs.cc 的ModelPrefix()函数（第 540~575 行），例如gemma2-2b、9b、27b、gr2b、gemma3-4b、paligemma2-3b-224等。

3.3 第二步：解压文件

填写同意书后，下载会得到一个archive.tar.gz。解压（可能需要几分钟）：

tar -xf archive.tar.gz

解压后应得到模型权重文件（如2b-it-sfp.sbs）和分词器文件（tokenizer.spm）。建议把这两个文件移动到方便的位置，例如本仓库的build/目录。

3.4 第三步：构建

构建系统基于 CMake。构建预设定义在 CMakePresets.json 中，包含make（Unix Makefiles）、windows（Visual Studio 2022 + ClangCL）和windows-dll（DLL 共享库构建）三组 preset。注意：如果之前运行过cmake，换配置重跑前务必清空build/目录（README 原话为rm -rf build/*）。

Unix-like 平台

cmake -B build

或使用预设（CMakePresets.json 中makepreset 默认把二进制目录设为${sourceDir}/build）：

# 配置 build 目录 cmake --preset make # 使用 make 构建 cmake --build --preset make -j [并行线程数]

并行线程数可参考 CPU 核心数，例如make -j4 gemma表示用 4 线程构建；如果系统有nproc命令，可写成make -j$(nproc) gemma。不确定时直接make gemma也能构建出./gemma可执行文件。

[!NOTE] 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/目录。

此外，README 还提及社区维护的 Makefile 方案（作者 @jart），适合偏好 Makefiles 的读者。

3.5 第四步：运行

在build/目录内运行gemma，它有两个必填参数：

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

例如（Gemma2 2B 指令微调 + 8-bit 切换浮点）：

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

[!NOTE] 对于2025-05-06 之后创建的单文件格式权重（或由migrate_weights工具输出的文件），--tokenizer参数可以省略——单文件格式已内嵌分词器与模型类型信息。这一点对应仓库中的新权重格式（见 io/migrate_weights.cc 与 README "Migrating to single-file format" 一节）。

四、支持的模型家族：源码级模型配置一览

README 提到"见ModelPrefix函数在configs.cc"，而gemma/configs.cc 实际上为每类模型定义了完整的ModelConfig与LayerConfig（模型维度、层数、注意力头数、KV 头数、注意力窗口、EOS id、词表大小、最大序列长度等）。下表汇总了当前仓库支持的全部模型及其关键配置：

模型（Model枚举）	显示名	model_dim	层数	词表大小	max_seq_len
GEMMA2_2B	Gemma2_2B	2304	26	256000	8192
GEMMA2_9B	Gemma2_9B	3584	42	256000	8192
GEMMA2_27B	Gemma2_27B	4608	46	256000	8192
GRIFFIN_2B	Griffin2B	2560	26	256000	2048（局部注意力窗口）
PALIGEMMA2_3B_224/448	PaliGemma2_3B_*	2304	26（+27 层 ViT）	257152	8192
PALIGEMMA2_10B_224/448	PaliGemma2_10B_*	3584	42（+27 层 ViT）	257152	8192
GEMMA3_270M	Gemma3_270M	640	18	262144	32K
GEMMA3_1B	Gemma3_1B	1152	26	262144	32K
GEMMA3_4B	Gemma3_4B	2560	34	262144	32K
GEMMA3_12B	Gemma3_12B	3840	48	262144	32K
GEMMA3_27B	Gemma3_27B	5376	62	262144	32K

（数据取自 gemma/configs.cc 中ConfigGemma2_2B至ConfigGemma3_27B等配置函数；Gemma 2 与 Gemma 3 词表大小分别由kVocabSize = 256000与kGemmaV3VocabSize = 262144常量定义。）

几个值得注意的实现细节：

• Gemma 2 使用交替的局部/全局注意力窗口（如 2B 模型为{4096, max_seq_len}循环 26 层），Gemma 3 为每 6 层插入一个全局层（如{512, 512, 512, 512, 512, max_seq_len}）；
• Griffin 2B 的max_seq_len实际是局部注意力窗口（2048），且每 3 层把 1 层替换为标准 Gemma 注意力层（gemma/configs.cc 第 197~200 行）；
• PaliGemma 的 ViT（SigLIP SoViT，27 层，patch 14×14，patch 数量由 image_size 决定）在AddVitConfig()中配置，448 分辨率变体通过--image_size 448传入；
• 加载单文件权重时，仓库可通过层数与层类型自动推导模型类型（DeduceModel()，gemma/configs.cc 第 749 行起）。

五、RecurrentGemma：基于 Griffin 的循环版本

仓库包含一个基于Griffin架构的 Gemma 变体（对应 RecurrentGemma 论文与开源代码）。其架构同时包含循环层（recurrent layers）与局部注意力（local attention），因此相比标准 Gemma，对长序列更高效、内存占用更小。仓库提供了基于论文的 C++ 实现（见 gemma/griffin.cc 与 gemma/griffin.h）。

使用方式：按第 3 步构建gemma二进制，从 Kaggle 的 RecurrentGemma GemmaCpp 页面下载压缩权重与分词器，然后运行：

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

注意这里出现了--model参数，取值为模型前缀（如gr2b-it），用于在多模型权重的旧格式下指定具体模型；这也是ModelPrefix()返回值被解析使用的场景之一。

六、PaliGemma 2：视觉语言模型

仓库包含 PaliGemma 2 VLM（Vision-Language Model，视觉语言模型）的 C++ 实现，结构上为SigLIP 视觉编码器（ViT） + Gemma 2 语言模型，视觉编码器实现在 gemma/vit.cc、图像读写在 paligemma/image.cc。

运行方式：构建gemma二进制后，从 Kaggle 的 PaliGemma 2 GemmaCpp 页面下载权重与分词器（README 示例为paligemma2-3b-mix-224），再执行：

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

图像输入格式：为保证最小依赖，图像读取代码非常简单，目前只支持二进制 PPM（P6 格式）。可用convert等工具先把图片转为 PPM，并且可以提前缩放到 224×224（推理时反正会重新缩放，提前缩放可加快加载）：

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

仓库自带一张测试图片 paligemma/testdata/image.ppm 可用于验证。PaliGemma 使用 prefix-LM 式注意力：在 gemma/run.cc 第 201~209 行，图片 token 与提示词作为前缀一次性处理，并因此把prefill_tbatch_size提升为整个 prompt 长度（源码注释说明在线 softmax 尚在路线图中，在此之前需一次性看到全部前缀 token）。

README 给出了 mix-224 检查点的真实交互示例（大意）：

> Describe the image briefly A large building with two towers in the middle of a city. > What type of building is it? church > What color is the church? gray > caption image A large building with two towers stands tall on the water's edge. ...

七、迁移到单文件权重格式

仓库引入了一种新的单文件权重格式：权重文件可以直接内嵌分词器与模型类型信息。迁移工具是migrate_weights（对应源码 io/migrate_weights.cc，该文件实现很简洁：解析--output_weights参数，加载权重后调用Gemma::Save()写出单文件）：

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

迁移完成后即可省略 tokenizer 参数：

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

该工具也由 CMakeLists.txt 的migrate_weights目标构建。

八、命令行参数全解：从源码看每个参数的作用

README 只详细列出了--weights与--tokenizer两个必填参数，但完整的参数体系定义在 gemma/gemma_args.h（LoaderArgs、InferenceArgs）与 util/threading_context.h（ThreadingArgs）中，参数解析框架在 util/args.h（ArgsBase，扫描--name形式参数）。下面分类汇总。

加载参数（LoaderArgs，gemma/gemma_args.h 第 39~67 行）

参数	默认值	说明
--tokenizer	空	分词器路径；仅旧格式（2025 年之前）权重需要
--weights	空（必填）	模型权重（.sbs）文件路径
--map	-1（自动）	启用内存映射？-1 = 自动，0 = 否，1 = 是
--to_bf16	-1（自动）	把权重转换为 bf16？-1 = 自动，0 = 否，1 = 是
--wrapping	-1（自动）	启用 prompt 包装（chat template）？旧格式 PT 模型建议设为 0

--wrapping的语义在 gemma/configs.cc 的ChooseWrapping()（第 577~593 行）中有详细实现：默认按指令微调（IT）格式包装，--wrapping=0时使用预训练（PT）格式；PaliGemma 与 Gemma 3 VLM 模型的包装方式固定，传入该参数会被忽略并给出警告。

推理参数（InferenceArgs，gemma/gemma_args.h 第 166~259 行）

参数	默认值	说明
--verbosity	1	0 = 只打印生成输出；1 = 标准用户终端 UI；2 = 显示开发者/调试信息
--seq_len	8192	序列长度，受ModelConfig.max_seq_len上限约束
--max_generated_tokens	4096	最多生成的 token 数
--prefill_tbatch	256	预填充阶段每个 batch 的最大 token 数
--decode_qbatch	16	解码阶段每个 batch 的最大查询数
--temperature	1.0	Top-K 采样的温度
--top_k	1	采样时从 top-K 个 token 中选取（1 = 贪心）
--deterministic	false	使 top-k 采样确定性化
--multiturn	0	多轮模式：0 = 每轮清空 KV cache，1 = 跨轮保留
--image_file	空	要加载的图片文件（PaliGemma）
--prompt	空	非交互模式的初始 prompt，指定后生成并退出
--prompt_file	空	包含 prompt 的文件路径（用于超过终端 4K 编辑缓冲的长 prompt）
--eot_line	空	结束回合标记行：输入中出现单独一行为该字符串时结束本轮

注意prefill_tbatch与decode_qbatch都有上限检查（MMStorage::kMaxM，gemma/gemma_args.h 第 243~254 行），超出会直接 abort 并提示减小或调整常量。

线程参数（ThreadingArgs，util/threading_context.h 第 56~86 行）

参数	默认值	说明
--num_threads	0（不限）	最大线程数，在检测到的集群间分配
--pin	-1（自动）	线程绑定到核心？-1 = 自动，0 = 否，1 = 是
--spin	-1（自动）	使用自旋等待（减少 barrier 同步延迟）？-1 = 自动，0 = 否，1 = 是
--skip_packages/--max_packages	0 / 1	跳过的/最大使用的 CPU 插槽（socket）数，用于多实例分区
--skip_clusters/--max_clusters	0 / 0（不限）	跳过的/最大使用的 CCX（共享 L3 的核簇）数
--skip_lps/--max_lps	0 / 0（不限）	拓扑未知时使用的逻辑处理器范围
--bind	-1（自动）	内存绑定到插槽（NUMA）？-1 = 自动，0 = 否，1 = 是

线程池实现（util/threading.h 的NestedPools）按"包 → 集群（CCX）→ 核"建立三级池层级：每个包一个AllPackages池、每个集群一个Cluster池，注释中的示例说明其目的在于让共享缓存/NUMA 节点的任务在更低延迟的 barrier 下并行。自旋等待默认只在线程成功绑定核心时才开启（MaybeStartSpinning，util/threading.h 第 86~102 行），因为自旋独占核心时如果绑定失败反而会增加尾部延迟。

九、三种使用模式：verbosity 与交互式 REPL

gemma有不同使用模式，由 verbosity 标志控制。所有模式目前都是交互式的：按下换行（回车）即触发文本生成。

Verbosity	使用模式	说明
--verbosity 0	Minimal	只打印生成输出，适合作为 CLI 工具使用
--verbosity 1	默认	标准用户终端 UI
--verbosity 2	Detailed	显示额外的开发者与调试信息

交互式终端应用

默认 verbosity=1，调用gemma时会进入终端交互界面，显示 ASCII 艺术横幅（该横幅源码就在 gemma/run.cc 第 49~56 行）与用法说明：

$ ./gemma [...] __ _ ___ _ __ ___ _ __ ___ __ _ ___ _ __ _ __ / _` |/ _ \ '_ ` _ \| '_ ` _ \ / _` | / __| '_ \| '_ \ | (_| | __/ | | | | | | | | | | (_| || (__| |_) | |_) | \__, |\___|_| |_| |_|_| |_| |_|\__,_(_)___| .__/| .__/ __/ | | | | | |___/ |_| |_| *Usage* Enter an instruction and press enter (%C reset conversation, %Q quits). *Examples* - Write an email to grandma thanking her for the cookies. - What are some historical attractions to visit around Massachusetts? - Compute the nth fibonacci number in javascript. - Write a standup comedy bit about WebGPU programming. > What are some outdoorsy places to visit around Boston?

两个特殊命令在 gemma/run.cc 第 172~178 行实现：输入以%开头时，%q/%Q退出，%c/%C重置对话（abs_pos归零）。

交互循环ReplGemma()的核心流程是：读取 prompt → 对 prompt 做 chat 模板包装与分词（WrapAndTokenize）→ 调用gemma.Generate()→ 流式打印每个 token，prompt_size之前的 token 显示为进度点号，遇到 EOS 后结束本轮。多轮模式下按--multiturn决定是否保留 KV cache（gemma/run.cc 第 234~248 行）。

作为命令行工具使用

把gemma当作 CLI 工具时，建议为完整参数创建 shell alias：

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

（把路径替换为你下载的模型与分词器路径。）然后用管道喂入 prompt 文本：

cat configs.h | tail -n 35 | tr '\n' ' ' | xargs -0 echo "What does this C++ code do: " | gemma2b

[!NOTE] CLI 管道用法是实验性的，需要注意上下文长度限制。

计时信息

当verbosity >= 1时，推理结束后会输出计时统计（实现见 gemma/gemma.h 的TimingInfo，第 169~226 行），包括：预填充耗时与预填充 token/秒、首 token 延迟（TTFT）、以及总生成耗时与平均生成速度（token/秒）。verbosity >= 2时每生成 128 个 token 还会打印一次中间速度。

十、把 gemma.cpp 作为库嵌入你的项目

gemma.cpp 可以方便地作为库被其他项目使用。最简单的方式是用 CMake 的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 92d327e841d78e11ae888757a3e16d291951cf64) FetchContent_MakeAvailable(highway)

其中 gemma.cpp 的GIT_TAG默认origin/main，可替换为具体 commit hash 以固定版本（本仓库 CMakeLists.txt 中 pinned 的 highway 与 sentencepiece 版本标签可作参考，注意该文件使用的是较新版本号）。定义你自己的可执行目标后（把[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})

单独构建 libgemma 库

gemma.cpp 也可以作为库依赖单独构建：把 make 调用的目标从gemma改为libgemma即可。

[!NOTE] 如果你通过上一节的FetchContent方式使用，库会由cmake自动构建，本节可跳过。

cmake -B build cd build make -j [并行线程数] libgemma

成功后build/目录下出现库文件，Unix 平台文件名为libgemma.a（CMakeLists.txt 第 132~141 行，链接hwy hwy_contrib sentencepiece-static）。

C API 与跨语言集成

对于需要跨语言调用的场景，仓库还提供 C 风格 API（gemma/bindings/c_api.h），包括GemmaCreate、GemmaGenerate、GemmaGenerateMultimodal（多模态，接收图片数据）、GemmaCountTokens，以及运行时配置函数（GemmaSetTemperature、GemmaSetTopK、GemmaSetMultiturn、GemmaSetDeterministic）与多会话管理函数（创建/切换/删除会话、保存会话）。该 C API 由BUILD_GEMMA_DLL构建选项控制（生成gemma_shared共享库），Windows 下配合GemmaInterop.cs（gemma/bindings/GemmaInterop.cs）可实现 C# 互操作。Python 绑定位于 python/（pybind11 实现）。

十一、常见问题与排障（FAQ）

README 的 Troubleshooting 章节总结了若干高频问题，这里结合源码补充细节：

在 Windows / Visual Studio 构建遇到问题？当前建议在 WSL 中构建。其他构建配置的探索正在 issue 中讨论。

模型不响应指令、输出奇怪？常见原因是误用了预训练（pre-trained）模型——它没有经过指令微调，自然不响应指令。请使用指令微调模型（gemma2-2b-it-sfp），不要使用带-pt后缀的模型。从实现看，--wrapping默认按 IT 模板包装 prompt（gemma/configs.cc 的ChooseWrapping），PT 模型需要--wrapping=0以避免错误包装。

支持多长的序列？见 gemma/configs.cc 中各模型的max_seq_len与InferenceArgs.seq_len（默认 8192，受模型上限约束）。Gemma 3 大于 1B 的模型通常为 32K；RAM 充足时 128K 也可行。注意长序列因注意力二次方复杂度会很慢。

如何把微调模型转成.sbs压缩格式？PaliGemma 2 检查点可用 python/convert_from_safetensors.py 从 safetensors 格式转换（README 注明该脚本经 bazel 构建验证）。对于 adapter 模型，转换前通常需要调用merge_and_unload()先合并为单文件。README 给出的 bazel 构建流程示例：

bazel build //compression/python:compression BAZEL_OUTPUT_DIR="${PWD}/bazel-bin/compression" python3 -c "import site; print(site.getsitepackages())" # 使用你自己的 site-packages 路径： ln -s $BAZEL_OUTPUT_DIR [...]/site-packages/compression python3 python/convert_from_safetensors.py --load_path [...].safetensors.index.json

（要求本地安装 torch、numpy、safetensors、absl-py 等。）

有哪些简单方法让模型跑得更快？

1. 使用 8-bit 切换浮点（-sfp）模型——体积只有 bf16 的一半，占用更少内存带宽与缓存；
2. 由于自动调优（autotuning），第二次、尤其是第三次查询会更快；
3. 笔记本用户确保电源模式为"最佳性能"，关闭省电模式（多数笔记本在未插电时会自动启用省电）；
4. 关闭其他占用 CPU 的应用；
5. Mac 上经验性地观察到速度"热身"爬升——性能核逐渐被调动起来。

此外，README 提到正在研究算法与优化手段以进一步提升推理速度。

十二、独立项目与生态

README 列举了一些基于 gemma.cpp 的独立项目，包括 gemma-cpp-python（Python 绑定）、lua-cgemma（Lua 绑定）以及一个 Godot 引擎 demo 项目。如果你的项目也基于 gemma.cpp，可以通过 PR 修改 README 将其加入列表。仓库自身的示例还包括 examples/hello_world（最小运行示例）与 examples/simplified_gemma（简化版 Gemma 教学实现）。

十三、开发与贡献指南

社区贡献（不论大小）均受欢迎。开发相关的补充说明见 DEVELOPERS.md，本项目遵循 Google 开源社区准则。重要开发约定：当前活跃开发在dev分支上进行，请把 PR 指向dev分支而非main（main旨在保持更稳定）。测试代码分布在 gemma/configs_test.cc、ops/ops_test.cc、paligemma/paligemma_test.cc 等文件，可通过 CMakeLists.txt 的GEMMA_ENABLE_TESTS选项（默认 OFF）启用；goldens 目录（goldens/）存放了模型输出的 golden 参考文本。

最后，README 的致谢部分说明：gemma.cpp 于 2023 年秋由 Austin Huang 与 Jan Wassenberg 启动，2024 年 2 月发布，Griffin 支持于 2024 年 4 月加入，Gemma-2 支持于 2024 年 6/7 月加入，PaliGemma 支持于 2024 年 9 月加入。再次强调：本项目不是官方支持的 Google 产品，定位是面向实验与研究的轻量级推理引擎。

【免费下载链接】gemma.cpplightweight, standalone C++ inference engine for Google's Gemma models.项目地址: https://gitcode.com/GitHub_Trending/ge/gemma.cpp