Moves the jupyter notebooks from main repo (#390)

This moves the jupyter notebooks from the main repo to demos. It follows the trend where the main tracks master while demo tracks releases or nightly snapshots.
deepjavalibrary · Nov 22, 2023 · 2ae32a7 · 2ae32a7
1 parent 0adb891
commit 2ae32a7
Show file tree

Hide file tree

Showing 25 changed files with 5,528 additions and 1 deletion.
diff --git a/aws/sagemaker/notebook/README.md b/aws/sagemaker/notebook/README.md
@@ -18,7 +18,7 @@ Wait for approximately 20 second and refresh the JupyterLab. You will see the Ja
 
 Now, you can try with different Notebooks provided by DJL:
 
-- [DJL Jupyter Notebooks](https://github.com/deepjavalibrary/djl/tree/master/jupyter)
+- [DJL Jupyter Notebooks](http://docs.djl.ai/docs/demos/jupyter/index.html)
 - [Dive into Deep Learning (DJL edition)](https://github.com/deepjavalibrary/d2l-java)
 
 ## Setup Scala

diff --git a/jupyter/BERTQA.ipynb b/jupyter/BERTQA.ipynb
@@ -0,0 +1,214 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# DJL BERT Inference Demo\n",
+    "\n",
+    "## Introduction\n",
+    "\n",
+    "In this tutorial, you walk through running inference using DJL on a [BERT](https://towardsdatascience.com/bert-explained-state-of-the-art-language-model-for-nlp-f8b21a9b6270) QA model trained with MXNet and PyTorch. \n",
+    "You can provide a question and a paragraph containing the answer to the model. The model is then able to find the best answer from the answer paragraph.\n",
+    "\n",
+    "Example:\n",
+    "```text\n",
+    "Q: When did BBC Japan start broadcasting?\n",
+    "```\n",
+    "\n",
+    "Answer paragraph:\n",
+    "```text\n",
+    "BBC Japan was a general entertainment channel, which operated between December 2004 and April 2006.\n",
+    "It ceased operations after its Japanese distributor folded.\n",
+    "```\n",
+    "And it picked the right answer:\n",
+    "```text\n",
+    "A: December 2004\n",
+    "```\n",
+    "\n",
+    "One of the most powerful features of DJL is that it's engine agnostic. Because of this, you can run different backend engines seamlessly. We showcase BERT QA first with an MXNet pre-trained model, then with a PyTorch model."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Preparation\n",
+    "\n",
+    "This tutorial requires the installation of Java Kernel. To install the Java Kernel, see the [README](http://docs.djl.ai/docs/demos/jupyter/index.html)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "// %mavenRepo snapshots https://oss.sonatype.org/content/repositories/snapshots/\n",
+    "\n",
+    "%maven ai.djl:api:0.24.0\n",
+    "%maven ai.djl.mxnet:mxnet-engine:0.24.0\n",
+    "%maven ai.djl.mxnet:mxnet-model-zoo:0.24.0\n",
+    "%maven ai.djl.pytorch:pytorch-engine:0.24.0\n",
+    "%maven ai.djl.pytorch:pytorch-model-zoo:0.24.0\n",
+    "%maven org.slf4j:slf4j-simple:1.7.32"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Import java packages by running the following:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import ai.djl.*;\n",
+    "import ai.djl.engine.*;\n",
+    "import ai.djl.modality.nlp.qa.*;\n",
+    "import ai.djl.repository.zoo.*;\n",
+    "import ai.djl.training.util.*;\n",
+    "import ai.djl.inference.*;\n",
+    "import ai.djl.repository.zoo.*;"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now that all of the prerequisites are complete, start writing code to run inference with this example.\n",
+    "\n",
+    "\n",
+    "## Load the model and input\n",
+    "\n",
+    "**First, load the input**"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "var question = \"When did BBC Japan start broadcasting?\";\n",
+    "var resourceDocument = \"BBC Japan was a general entertainment Channel.\\n\" +\n",
+    "    \"Which operated between December 2004 and April 2006.\\n\" +\n",
+    "    \"It ceased operations after its Japanese distributor folded.\";\n",
+    "\n",
+    "QAInput input = new QAInput(question, resourceDocument);"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Then load the model and vocabulary. Create a variable `model` by using the `ModelZoo` as shown in the following code."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "Criteria<QAInput, String> criteria = Criteria.builder()\n",
+    "    .optApplication(Application.NLP.QUESTION_ANSWER)\n",
+    "    .setTypes(QAInput.class, String.class)\n",
+    "    .optEngine(\"MXNet\") // For DJL to use MXNet engine\n",
+    "    .optProgress(new ProgressBar()).build();\n",
+    "ZooModel<QAInput, String> model = criteria.loadModel();"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Run inference\n",
+    "Once the model is loaded, you can call `Predictor` and run inference as follows"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "Predictor<QAInput, String> predictor = model.newPredictor();\n",
+    "String answer = predictor.predict(input);\n",
+    "answer"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Running inference on DJL is that easy. Now, let's try the PyTorch engine by specifying PyTorch engine in Criteria.optEngine(\"PyTorch\"). Let's rerun the inference code."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "var question = \"When did BBC Japan start broadcasting?\";\n",
+    "var resourceDocument = \"BBC Japan was a general entertainment Channel.\\n\" +\n",
+    "    \"Which operated between December 2004 and April 2006.\\n\" +\n",
+    "    \"It ceased operations after its Japanese distributor folded.\";\n",
+    "\n",
+    "QAInput input = new QAInput(question, resourceDocument);\n",
+    "\n",
+    "Criteria<QAInput, String> criteria = Criteria.builder()\n",
+    "    .optApplication(Application.NLP.QUESTION_ANSWER)\n",
+    "    .setTypes(QAInput.class, String.class)\n",
+    "    .optFilter(\"modelType\", \"distilbert\")\n",
+    "    .optEngine(\"PyTorch\") // Use PyTorch engine\n",
+    "    .optProgress(new ProgressBar()).build();\n",
+    "ZooModel<QAInput, String> model = criteria.loadModel();\n",
+    "Predictor<QAInput, String> predictor = model.newPredictor();\n",
+    "String answer = predictor.predict(input);\n",
+    "answer"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Summary\n",
+    "Suprisingly, there are no differences between the PyTorch code snippet and MXNet code snippet. \n",
+    "This is power of DJL. We define a unified API where you can switch to different backend engines on the fly.\n",
+    "Next chapter: Inference with your own BERT: [MXNet](mxnet/load_your_own_mxnet_bert.ipynb) [PyTorch](pytorch/load_your_own_pytorch_bert.ipynb)."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Java",
+   "language": "java",
+   "name": "java"
+  },
+  "language_info": {
+   "codemirror_mode": "java",
+   "file_extension": ".jshell",
+   "mimetype": "text/x-java-source",
+   "name": "Java",
+   "pygments_lexer": "java",
+   "version": "14.0.2+12"
+  },
+  "pycharm": {
+   "stem_cell": {
+    "cell_type": "raw",
+    "metadata": {
+     "collapsed": false
+    },
+    "source": []
+   }
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/jupyter/Dockerfile b/jupyter/Dockerfile
@@ -0,0 +1,24 @@
+FROM ubuntu:18.04
+
+RUN apt-get update || true
+RUN apt-get install -y openjdk-11-jdk-headless
+RUN apt-get install -y python3-pip git
+RUN pip3 install jupyter
+RUN apt-get update \
+    && DEBIAN_FRONTEND=noninteractive apt-get install -y locales \
+    && sed -i -e 's/# en_US.UTF-8 UTF-8/en_US.UTF-8 UTF-8/' /etc/locale.gen \
+    && dpkg-reconfigure --frontend=noninteractive locales \
+    && update-locale LANG=en_US.UTF-8
+RUN apt-get install -y curl
+
+RUN git clone https://github.com/frankfliu/IJava.git
+RUN cd IJava/ && ./gradlew installKernel && cd .. && rm -rf IJava/
+RUN rm -rf ~/.gradle
+
+WORKDIR /home/jupyter
+
+ENV LANG en_US.UTF-8
+ENV LC_ALL en_US.UTF-8
+
+EXPOSE 8888
+ENTRYPOINT ["jupyter", "notebook", "--ip=0.0.0.0", "--no-browser", "--allow-root", "--NotebookApp.token=''",  "--NotebookApp.password=''"]
diff --git a/jupyter/README.md b/jupyter/README.md
@@ -0,0 +1,83 @@
+# DJL - Jupyter notebooks
+
+## Overview
+
+This folder contains tutorials that illustrate how to accomplish basic AI tasks with Deep Java Library (DJL).
+
+## [Beginner Tutorial](tutorial/README.md)
+
+## More Tutorial Notebooks
+
+- [Run object detection with model zoo](object_detection_with_model_zoo.ipynb)
+- [Load pre-trained PyTorch model](load_pytorch_model.ipynb)
+- [Load pre-trained Apache MXNet model](load_mxnet_model.ipynb)
+- [Transfer learning example](transfer_learning_on_cifar10.ipynb)
+- [Question answering example](BERTQA.ipynb)
+
+You can run our notebook online: [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/deepjavalibrary/djl/master?filepath=jupyter)
+
+## Setup
+
+### JDK 11 (not jre)
+
+JDK 11 (or above are required) to run the examples provided in this folder.
+
+to confirm the java path is configured properly:
+
+```bash
+java --list-modules | grep "jdk.jshell"
+
+> [email protected]
+```
+
+### Install jupyter notebook on python3
+
+```bash
+pip3 install jupyter
+```
+
+### Install IJava kernel for jupyter
+
+```bash
+git clone https://github.com/frankfliu/IJava.git
+cd IJava/
+./gradlew installKernel
+```
+
+## Start jupyter notebook
+
+```bash
+jupyter notebook
+```
+
+## Docker setup
+
+You may want to use docker for simple installation or you are using Windows.
+
+### Run docker image
+
+```sh
+cd jupyter
+docker run -itd -p 127.0.0.1:8888:8888 -v $PWD:/home/jupyter deepjavalibrary/jupyter
+```
+
+You can open the `http://localhost:8888` to see the hosted instance on docker.
+
+### Build docker image by yourself
+
+You can read [Dockerfile](https://docs.djl.ai/docs/demos/jupyter/Dockerfile) for detail. To build docker image:
+
+```sh
+cd jupyter
+docker build -t deepjavalibrary/jupyter .
+```
+
+### Run docker compose
+
+```sh
+cd jupyter
+docker-compose build
+docker-compose up -d
+```
+
+You can open the `http://localhost:8888` to see the hosted instance on docker compose.
diff --git a/jupyter/docker-compose.yml b/jupyter/docker-compose.yml
@@ -0,0 +1,12 @@
+version: "2.4"
+services:
+    deepjavalibrary_container:
+        build:
+            context: .
+            dockerfile: Dockerfile
+        ports:
+            - 8888:8888
+        volumes:
+            - ./:/home/jupyter
+        restart: always
+