循环Gemma

RecurrentGemma 是由 Google DeepMind 推出的一系列开放权重语言模型，基于新颖的 Griffin 架构。该架构通过用局部注意力与线性递归的混合机制替代全局注意力，实现了在生成长序列时的快速推理。

本仓库包含模型的实现以及采样和微调的示例。我们建议大多数用户采用高度优化的 Flax 实现。同时，我们也提供了未优化的 PyTorch 实现作为参考。

了解更多关于 RecurrentGemma 的信息

• RecurrentGemma 技术报告 提供了关于 RecurrentGemma 训练和评估的具体细节。
• Griffin 论文 描述了其底层模型架构。

快速入门

安装

使用 Poetry

RecurrentGemma 使用 Poetry 进行依赖管理。

要为整个项目安装依赖：

• 克隆代码库。
• 运行 poetry install -E full 创建包含所有依赖的虚拟环境。
• 运行 poetry shell 激活创建的虚拟环境。

如果只需要安装部分依赖，请使用以下针对不同库的命令。

使用 pip

如果您希望使用 pip 而不是 Poetry，则需要创建一个虚拟环境（运行 python -m venv recurrentgemma-demo 并激活 . recurrentgemma-demo/bin/activate），然后：

• 克隆代码库。
• 运行 pip install .[full]。

安装特定于库的包

JAX

仅安装 JAX 路径所需的依赖： poetry install -E jax 或 (pip install .[jax])。

PyTorch

仅安装 PyTorch 路径所需的依赖： poetry install -E torch（或 pip install .[torch]）。

测试

要安装运行单元测试所需的依赖： poetry install -E test（或 pip install .[test]）。

下载模型

模型检查点可通过 Kaggle 获取，地址为：http://kaggle.com/models/google/recurrentgemma。选择 Flax 或 PyTorch 版本，点击 ⤓ 按钮下载模型压缩包，然后将其解压到本地目录。

无论哪种情况，压缩包中都包含模型权重和分词器。

运行单元测试

要运行测试，请从源码根目录安装可选的 [test] 依赖（例如使用 pip install .[test]），然后执行：

pytest .

示例

要运行示例采样脚本，需传入权重目录和分词器的路径：

python examples/sampling_jax.py \
  --path_checkpoint=/path/to/archive/contents/2b/ \
  --path_tokenizer=/path/to/archive/contents/tokenizer.model

Colab 笔记本教程

• colabs/sampling_tutorial_jax.ipynb 包含一个使用 JAX 进行采样的 Colab 笔记本。
• colabs/sampling_tutorial_pytorch.ipynb 包含一个使用 PyTorch 进行采样的 Colab 笔记本。
• colabs/fine_tuning_tutorial_jax.ipynb 包含一个使用 JAX 对 RecurrentGemma 进行微调的基础教程，例如用于英法翻译任务。

要运行这些笔记本，您需要拥有 Kaggle 账户，并首先阅读并接受 RecurrentGemma 页面上的 Gemma 许可条款。之后即可运行笔记本，它们会自动从那里下载权重和分词器。

目前不同笔记本支持的硬件如下：

硬件	T4	P100	V100	A100	TPUv2	TPUv3+
Jax 中采样	✅	✅	✅	✅	✅	✅
PyTorch 中采样	✅	✅	✅	✅	✅	✅
Jax 中微调	✅	✅	✅	✅	❌	✅

系统要求

RecurrentGemma 代码可以在 CPU、GPU 或 TPU 上运行。代码已针对使用 Flax 实现的 TPU 进行优化，其中包含一个低级 Pallas 内核，用于在循环层中执行线性扫描。

贡献

我们欢迎 bug 报告和问题反馈。有关 PR 的详细信息，请参阅 CONTRIBUTING.md。

许可证

版权所有 2024 DeepMind Technologies Limited

本代码根据 Apache License, Version 2.0（“许可证”）授权；除非符合许可证规定，否则不得使用此文件。您可以在 http://www.apache.org/licenses/LICENSE-2.0 获取许可证副本。

除非适用法律另有规定或双方另有约定，否则根据本许可证分发的软件以“现状”提供，不附带任何明示或暗示的保证或条件。具体的权利和限制请参阅许可证文本。

免责声明

本项目并非 Google 官方产品。

RecurrentGemma 快速上手指南

RecurrentGemma 是 Google DeepMind 推出的一系列开源语言模型，基于创新的 Griffin 架构。该架构通过混合局部注意力机制和线性递归，替代了全局注意力机制，从而在生成长序列时实现更快的推理速度。本指南将帮助您快速在中国开发环境中部署并使用该模型。

1. 环境准备

系统要求

• 硬件：支持 CPU、GPU (NVIDIA T4/P100/V100/A100) 或 TPU (v2/v3+)。
  • 推荐：使用 TPU 配合 Flax/JAX 实现以获得最佳性能（包含优化的 Pallas 内核）。
  • 参考：提供未优化的 PyTorch 实现供参考。
• 操作系统：Linux 或 macOS (Windows 需通过 WSL2 运行)。
• Python 版本：建议 Python 3.9+。

前置依赖

• 包管理工具：推荐使用 Poetry 进行依赖管理，也可使用 pip。
• Kaggle 账号：下载模型权重和分词器需要 Kaggle 账号，并需先同意 RecurrentGemma 许可条款。

注意：目前官方暂未提供中国镜像源。国内用户若遇到 pip 或 poetry 下载依赖缓慢，可临时配置国内镜像（如清华源、阿里源）加速 Python 包安装，但模型权重仍需从 Kaggle 下载。

2. 安装步骤

您可以选择使用 Poetry（推荐）或 pip 进行安装。

方式一：使用 Poetry (推荐)

1. 克隆代码库

   git clone https://github.com/google-deepmind/recurrentgemma.git
   cd recurrentgemma
   

2. 安装依赖

   • 完整安装（包含所有依赖）：

     poetry install -E full
     poetry shell
     

   • 仅安装 JAX/Flax 路径（高性能推荐）：

     poetry install -E jax
     poetry shell
     

   • 仅安装 PyTorch 路径（参考用）：

     poetry install -E torch
     poetry shell
     

方式二：使用 pip

1. 克隆代码库并创建虚拟环境

   git clone https://github.com/google-deepmind/recurrentgemma.git
   cd recurrentgemma
   python -m venv recurrentgemma-demo
   source recurrentgemma-demo/bin/activate  # Windows 用户请使用: recurrentgemma-demo\Scripts\activate
   

2. 安装依赖

   • 完整安装：

     pip install .[full]
     

   • 仅安装 JAX 路径：

     pip install .[jax]
     

   • 仅安装 PyTorch 路径：

     pip install .[torch]
     

3. 基本使用

第一步：下载模型

1. 访问 Kaggle RecurrentGemma 页面。
2. 登录账号并接受许可协议。
3. 选择 Flax 或 PyTorch 版本的模型变体。
4. 点击 ⤓ 按钮下载模型归档文件。
5. 将文件解压到本地目录（例如 /path/to/archive/contents/）。
   • 注：归档文件中已包含模型权重 (2b/ 等文件夹) 和分词器 (tokenizer.model)。

第二步：运行采样示例 (Sampling)

以下命令演示如何使用 JAX 后端进行文本生成采样。请根据您的实际路径替换参数。

python examples/sampling_jax.py \
  --path_checkpoint=/path/to/archive/contents/2b/ \
  --path_tokenizer=/path/to/archive/contents/tokenizer.model

• --path_checkpoint: 指向解压后的模型权重目录（如 2b, 7b 等）。
• --path_tokenizer: 指向 tokenizer.model 文件的路径。

进阶：使用 Colab 教程

如果您希望直接在云端运行示例或进行微调，可以使用官方提供的 Colab Notebook（需绑定 Kaggle 账号自动下载权重）：

• JAX 采样教程: colabs/sampling_tutorial_jax.ipynb
• PyTorch 采样教程: colabs/sampling_tutorial_pytorch.ipynb
• JAX 微调教程 (如英法翻译任务): colabs/fine_tuning_tutorial_jax.ipynb