[nnx] add gemma notebook

docs_nnx/conf.py

@@ -148,6 +148,7 @@
   'transfer_learning.ipynb',  # <-- transformers requires flax<=0.7.0
   'flax/nnx',  # exclude nnx
   'guides/demo.ipynb',  # TODO(cgarciae): broken, remove or update
+  'guides/gemma.ipynb',
 ]
 # raise exceptions on execution so CI can catch errors
 nb_execution_allow_errors = False

docs_nnx/guides/gemma.ipynb

@@ -0,0 +1,292 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Copyright 2024 The Flax Authors.\n",
+    "\n",
+    "Licensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with the License. You may obtain a copy of the License at\n",
+    "\n",
+    "http://www.apache.org/licenses/LICENSE-2.0\n",
+    "\n",
+    "Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n",
+    "\n",
+    "---"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Getting Started with Gemma Sampling using NNX: A Step-by-Step Guide\n",
+    "\n",
+    "You will find in this colab a detailed tutorial explaining how to use NNX to load a Gemma checkpoint and sample from it."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Installation"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "! pip install --no-deps -U flax\n",
+    "! pip install jaxtyping kagglehub penzai"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Downloading the checkpoint\n",
+    "\n",
+    "\"To use Gemma's checkpoints, you'll need a Kaggle account and API key. Here's how to get them:\n",
+    "\n",
+    "1. Visit https://www.kaggle.com/ and create an account.\n",
+    "2. Go to your account settings, then the 'API' section.\n",
+    "3. Click 'Create new token' to download your key.\n",
+    "\n",
+    "Then run the cell below."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [
+    {
+     "ename": "ModuleNotFoundError",
+     "evalue": "No module named 'kagglehub'",
+     "output_type": "error",
+     "traceback": [
+      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
+      "\u001b[0;31mModuleNotFoundError\u001b[0m                       Traceback (most recent call last)",
+      "Cell \u001b[0;32mIn[1], line 1\u001b[0m\n\u001b[0;32m----> 1\u001b[0m \u001b[38;5;28;01mimport\u001b[39;00m \u001b[38;5;21;01mkagglehub\u001b[39;00m\n\u001b[1;32m      2\u001b[0m kagglehub\u001b[38;5;241m.\u001b[39mlogin()\n",
+      "\u001b[0;31mModuleNotFoundError\u001b[0m: No module named 'kagglehub'"
+     ]
+    }
+   ],
+   "source": [
+    "import kagglehub\n",
+    "kagglehub.login()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If everything went well, you should see:\n",
+    "```\n",
+    "Kaggle credentials set.\n",
+    "Kaggle credentials successfully validated.\n",
+    "```\n",
+    "\n",
+    "Now select and download the checkpoint you want to try. Note that you will need an A100 runtime for the 7b models."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "VARIANT = '2b-it' # @param ['2b', '2b-it', '7b', '7b-it'] {type:\"string\"}\n",
+    "weights_dir = kagglehub.model_download(f'google/gemma/Flax/{VARIANT}')\n",
+    "ckpt_path = f'{weights_dir}/{VARIANT}'\n",
+    "vocab_path = f'{weights_dir}/tokenizer.model'"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Python imports"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from flax import nnx\n",
+    "import sentencepiece as spm"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Flax examples are not exposed as packages so you need to use the workaround in the next cells to import from NNX's Gemma example."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "! git clone https://github.com/google/flax.git flax_examples"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import sys\n",
+    "\n",
+    "sys.path.append(\"./flax_examples/flax/nnx/examples/gemma\")\n",
+    "import params as params_lib\n",
+    "import sampler as sampler_lib\n",
+    "import transformer as transformer_lib\n",
+    "sys.path.pop();"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Start Generating with Your Model\n",
+    "\n",
+    "Load and prepare your LLM's checkpoint for use with Flax."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "cellView": "form"
+   },
+   "outputs": [],
+   "source": [
+    "# Load parameters\n",
+    "params = params_lib.load_and_format_params(ckpt_path)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Load your tokenizer, which we'll construct using the [SentencePiece](https://github.com/google/sentencepiece) library."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "cellView": "form"
+   },
+   "outputs": [],
+   "source": [
+    "vocab = spm.SentencePieceProcessor()\n",
+    "vocab.Load(vocab_path)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Use the `transformer_lib.TransformerConfig.from_params` function to automatically load the correct configuration from a checkpoint. Note that the vocabulary size is smaller than the number of input embeddings due to unused tokens in this release."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "transformer = transformer_lib.Transformer.from_params(params)\n",
+    "nnx.display(transformer)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Finally, build a sampler on top of your model and your tokenizer."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "cellView": "form"
+   },
+   "outputs": [],
+   "source": [
+    "# Create a sampler with the right param shapes.\n",
+    "sampler = sampler_lib.Sampler(\n",
+    "    transformer=transformer,\n",
+    "    vocab=vocab,\n",
+    "    params=params['transformer'],\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You're ready to start sampling ! This sampler uses just-in-time compilation, so changing the input shape triggers recompilation, which can slow things down. For the fastest and most efficient results, keep your batch size consistent."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "cellView": "form"
+   },
+   "outputs": [],
+   "source": [
+    "input_batch = [\n",
+    "    \"\\n# Python program for implementation of Bubble Sort\\n\\ndef bubbleSort(arr):\",\n",
+    "    \"What are the planets of the solar system?\",\n",
+    "  ]\n",
+    "\n",
+    "out_data = sampler(\n",
+    "    input_strings=input_batch,\n",
+    "    total_generation_steps=300,  # number of steps performed when generating\n",
+    "  )\n",
+    "\n",
+    "for input_string, out_string in zip(input_batch, out_data.text):\n",
+    "  print(f\"Prompt:\\n{input_string}\\nOutput:\\n{out_string}\")\n",
+    "  print()\n",
+    "  print(10*'#')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You should get an implementation of bubble sort and a description of the solar system."
+   ]
+  }
+ ],
+ "metadata": {
+  "jupytext": {
+   "formats": "ipynb,md:myst"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.13"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}