Jupyter Notebook入门指南

作者：京东科技隐私计算产品部 孙晓军

1. Jupyter Notebook介绍

图1 Jupter项目整体架构

[​​https://docs.jupyter.org/en/latest/projects/architecture/content-architecture.html​​]

Jupyter Notebook是一套基于web的交互式开发环境。用户可以在线开发和分享包含代码和输出的交互式文档，支持实时代码，数学方程，可视化和 markdown等。用途包括：数据清理和转换，数值模拟，统计建模，机器学习等等。

Jupyter Notebook内部通过内核维护状态并运行代码片段，浏览器显示代码片段和其执行的结果。Jupyter Notebook提供了一个用户交互式的开发环境，用户可以通过执行一部分代码片段，并观察执行结果。这种交互式设计，使得Jupyter Notebook非常适合数据科学和机器学习的开发工作。

注意本文的代码和脚本，均基于Jupyter Notebook v6.5.2稳定版本。

2. Jupyter的工作方式

图2 Jupter Notebook工作方式

[​​https://docs.jupyter.org/en/latest/projects/architecture/content-architecture.html​​]

Jupyter的主要工作单元是Jupyter Server和Kernel。其中Jupyter Server用来提供基于Web的界面和API服务，Kernel用来执行代码片段。浏览器通过Http和Websockets的方式和Jupyter Server进行交互，Jupyter Server和kernel之间，通过ZeroMQ进行数据通信。

Jupyter Server采用经典的MVC模式，使用了tornado作为web服务器，用来提供地址映射和控制器逻辑，使用jinja2来提供模板视图功能。

Jupyter Notebook（v6.5.2）项目的主要模块结构如下：

3. 安装Jupyter Notebook

前置条件

Python和pip

不同的Jupyter Notebook对Python有不同的版本要求。我们安装的最新的稳定版本v6.5.2的Jupyter Notebook，要求Python的最低版本为3.6。注意这个Python的版本，不同于内核的Python版本。对于Jupyter内核来说，支持的Python版本和Jupyter Notebook依赖的Python版本没有关系。

在Linux系统下安装Jupyter Notebook

使用pip安装Jupyter notebook非常简单。如果服务器同时拥有Python2和Python3的pip，注意需要使用pip3来替换命令中的pip。

# 更新pip
pip install --upgrade pip
# 安装jupyter
pip install jupyter
# 检查安装的jupyter
jupyter --version
//输出 notebook  : 6.5.2

4. 配置和启动Jupyter

Jupyter提供了大量的启动参数，用来配置Jupyter Server。我们可以在启动Jupyter服务时，通过命令行参数的方式配置当前启动的服务，但更普遍的方式是使用Jupyter的配置文件。

# 生成配置文件
jupyter notebook --generate-config
// 默认生成的配置文件位置：
/root/.jupyter/jupyter_notebook_config.py

# 修改Jupyter配置文件...

# 启动jupyter
jupyter notebook

Jupyter直接使用一个Python文件来配置Jupyter服务，所有的配置项均通过Python代码来完成。常用的配置项及其说明如下：

5. 使用Jupyter

5.1. 创建Notebook

启动Jupyter 后，在浏览器内输入 ​​http://服务器地址​​:端口/，Jupyter会默认重定向到.default_url指定的工作区目录树地址，默认是工作区目录树的界面。

如果在访问的过程中，使用了默认的token作为其认证方式，那么在首次打开时，需要输入Jupyter Notebook的token值，这个值可以在启动Jupyter时的控制台输出中找到，或者使用Jupyter命令来查询

# 查询运行的jupyter notebook
jupyter notebook list
//返回结果中包含了http://x.x.x.x:8899?token=ABC 的信息，其中的ABC就是我们需要的token

图3 Jupter Notebook的默认工作区目录树页面

Jupyter Notebook通过Jupyter Server提供基于Web的平台无关的工作方式，这使得跨平台开发和协作，代码分享等能力变得比传统IDE更加容易。

在Jupyter 工作区管理界面，用户可以灵活地以类似文件系统的方式管理工作区的数据。可以创建文件和文件夹，编辑文件和文件夹，可以上传和下载文件。通过选择一个Jupyter内核，可以创建一个Notebook文件。

图4 通过Jupyter内核创建一个Notebook

5.2. 使用Notebook

使用Python3内核创建一个Notebook后，我们得到一个xxx.ipynb（IPython Notebook）文件。这个文件是一个json格式的文本文件，其中包含了我们在Notebook中编写的代码和文本内容，也包含了界面上没有显示的元数据信息。通过在工作区目录界面选择一个notebook文件，点击编辑，我们可以查看到ipynb文件的原始内容。

图5 ipynb文件的原始内容

我们可以像使用其它IDE类似的方式来使用Notebook，在使用Notebook上，我们主要关注下Jupyter内核和单元格。

内核是执行单元格代码的核心进程，不同的内核，决定了我们在单元格中能够编写哪些语言的代码，以及对应了指定的编程语言的哪个版本等信息。

单元格是整个Notebook的核心组成部分，我们编写的代码和文本，通过一些列Notebook单元格来组成。Notebook提供了Code，Markdown, Raw NBConvert, Heading四种类型的单元格。

•Code单元格。用来编写内核指定语言的程序代码

•Markdown单元格。使用Markdown编辑器的语法来编辑富文本

•Raw NBConvert单元格。原始的文本，不会被当作代码或markdown被解释执行

•Heading单元格。Heading是Mardown的一个子集，对应了Markdown中的标题编写语法

Jupyter Notebook使用了机器学习中检查点的概念，在我们修改Notebook的过程中，Jupyter会自动保存我们的修改，我们也可以通过【文件】->【保存】来手动保存检查点。检查点文件包含了我们编写的Notebook内容，以及执行代码单元格之后的输出。我们可以在工作空间的“.ipynb_checkpoints”文件夹下，找到这些检查点文件。

图6 使用Jupyter单元格来编写交互式代码

5.3. 分享Notebook

相较于使用传统的IDE编写的代码，基于Web服务的Jupyter Notebook在代码分享上拥有着天然的优势。

在Jupyter Notebook中，我们可以通过两种不同的方式分享我们创作的nootbook。

1. 交互式Notebook文档

传统的技术文档或者说明书，通过静态的文本，配合图片和视频，来描述和讲解特定的技术或功能。有了Jupyter Notebook后，我们仍然可以使用Notebook来编写类似传统的技术文档。在此基础上，我们可以加入更生动的代码交互单元格，用户通过查看文档说明，并与文档中提供的代码进行互动，可以更生动地介绍产品中的功能和技术。每个Jupyter Notebook的ipynb文件，都对应了一个独立的访问地址： ​​http://x.x.x.x:8899/notebooks/my_notebook.ipynb​​ ,通过分享此文件的地址，其他用户可以方便地使用包含了富文本和可执行的代码的交互式Notebook文档。

2. 离线Notebook文档

我们通过逐步执行文档中的所有单元格，得到一个包含了我们编写的说明和代码，以及代码执行的输出结果的完整文档。之后点击【文件】-> 【另存为】，选择一种合适的文件格式。我们可以把文档导出为一份静态文件，通过共享此静态文件，我们实现了Notebook文档的离线分享。

5.4. 魔法函数

Jupyter Notebook提供了一些列魔法函数来增强Jupyter Code单元格的功能，通过魔法函数，我们能够执行javascript脚本，html代码，运行另一个可执行程序等许多额外的功能。

我们可以在Jupyter代码单元格中使用 %lsmagic命令来查看所有的魔法函数，如果要阅读详细的魔法函数的使用说明，可以参考： <​​https://ipython.readthedocs.io/en/stable/interactive/magics.html​​>

魔法函数分为行魔法函数，单元格魔法函数和会话魔法函数。顾名思义，行魔法函数只对当前行起作用，而单元格魔法函数则作用于整个单元格，会话魔法函数则作用于整个会话期间。

一些常用的魔法函数：

6. 管理Jupyter

6.1. 多语言

Jupyter Notebook使用i18n目录下的资源来进行多语言翻译。在Jupyter Notebook启动时，会加载i18n目录下的多语言资源。之后根据http请求指定的语言，为响应数据提供对应的多语言翻译。如果没有对应的翻译，则保留原始的多语言标签值（英文）。如果调整了多语言翻译，需要重新启动Jupyter Notebook才能使用新的语言包。

Jupyter Notebook的翻译资源主要分布在三个po文件中：

•nbjs.po - js文件中的多语言数据

•nbui.po - UI界面中的多语言数据

•notebook.po - notebook中的多语言数据

原始的po文件，需要通过pybabel工具，把po文件编译成mo文件，之后部署在{LANG}/LC_MESSAGES/目录下（$notebook是notebook的安装目录），才能在Jupyter Notebook中作为多语言的资源包来使用。

# 使用pybabel编译多语言po文件
pybabel compile -D notebook -f -l ${LANG} -i ${LANG}/LC_MESSAGES/notebook.po -o ${LANG}/LC_MESSAGES/notebook.mo
pybabel compile -D nbui -f -l ${LANG} -i ${LANG}/LC_MESSAGES/nbui.po -o ${LANG}/LC_MESSAGES/nbui.mo
pybabel compile -D nbjs -f -l ${LANG} -i ${LANG}/LC_MESSAGES/nbjs.po -o ${LANG}/LC_MESSAGES/nbjs.mo

图7 使用了中文语言包后的中文Notebook界面

6.2. 内核管理

内核（kernel）是独立于jupyter服务和界面之外的用来运行Jupyter代码单元格的进程，Jupyter默认提供了ipykernel内核来支持Python开发语言。Jupyter社区提供了jupyterC, IJava，xeus-cling, xeus-sql等众多其它编程语言的内核，用来支持C/C++, Java, SQL等编程语言。

ipykernel默认使用系统环境下的Python来提供服务。我们可以使用ipykernel安装多个Python kernel来提供Python2.x, Python3.x等多个Python内核环境。

安装kernel后，kernel的信息被保存在kernel.json文件中，我们可以在 /usr/local/share/jupyter/kernels 目录，找到Jupyter安装的所有kernel以及对应的kernel.json文件。

kernel可以直接继承自安装kernel的Python指令，也可以使用Python虚拟环境。

# 1.直接继承自Python指令的kernel安装
# 安装ipykernel
pip install ipykernel
# 安装kernel
python -m ipykernel install --name tensorflow2 --display-name "tensorflow2"

# 2. 在Python虚拟环境下的kernel安装
# 激活虚拟环境
source activate myenv
# 安装ipykernel
pip install ipykernel
# 安装kernel
python -m ipykernel install --name myenv --display-name "Python3 (myenv)"

如果需要查看当前的kernel列表，以及删除已经安装的kernel，可以使用如下的Jupyter命令：

# 查看已经安装的kernel列表
jupyter kernelspec list
# 删除列表中指定的kernel
jupyter kernelspec remove kernelname

6.3. REST API

Jupyter提供了REST API接口来和Jupyter server进行交互。借助REST API的能力，我们可以以编程的方式和Jupyter Server进行交互，灵活地管理Jupyter Server。另外REST API为现代化的软件开发提供了一个优秀的能力：自动化。

借助Jupyter Notebook REST API，可以实现文件的上传和下载，检查点管理，会话管理，内核管理，终端管理等一些列管理能力。完整的Jupyter REST API接口列表可以参考： <​​https://jupyter-server.readthedocs.io/en/latest/developers/rest-api.html​​>

要使用REST API，需要在请求中携带认证信息。Jupyter支持直接把token作为query string的方式来认证，也可以使用标准的Http Authorization头信息来完成认证。使用Authorization头来认证的格式如下：

Authrozation: token 527a9f1430ccfed995ebcf15517583a2547c2469bc3c47a6

图8 使用Postman来调用Jupyter REST API接口

6.4. 安全管理与多人协作

Jupyter提供了灵活强大的能力，用以支持在线的交互式文档和代码的编写。但Jupyter项目自身没有提供精细化的安全管理体系，用以支持多用户下灵活地使用Jupyter Notebook的功能。对于文件安全，Jupyter依赖于启动服务的linux用户，合理地配置启动Jupyter的用户的权限，才能保证使用Jupyter的用户，不会对系统或项目造成破坏。Jupyter工作空间的设定，仅起到了方便Jupyter使用者管理必要文件的易用性，不能阻挡用户访问和管理工作空间外的文件系统。另外，配合使用Python虚拟环境，可以防止Jupyter Notebook提供的 pip install ,pip uninstall功能，对现有项目环境造成破坏。

在多人协作方面，JupyterHub项目提供了多人协作Jupyter Notebook和Jupyter lab开发的能力。使用JupyterHub,不同职能的用户可以在自己独立的空间内进行Notebook的编写工作，不同用户间也可以方便地分享各自的Notebook。

7. 扩展Jupyter

7.1. 前端扩展

Jupyter Notebook前端扩展(front end extension)是使用Javascript语言编写的异步模块，可以用来绘制Jupyter界面的仪表盘，Notebook，工具栏等，。定义一个前端扩展必须要实现一个load_ipython_extension方法，当前端控件被加载时，Jupyter client会调用load_ipython_extension方法。

Jupyter Notebook前端扩展能力目前还不是一个稳定的版本，不保证代码能够向后兼容。Jupyter的JS API目前也没有官方的文档，需要通过源代码或者实际加载的JS来查看Jupyter前端脚本的成员和方法。

我们实现一个简单的前端扩展脚本，在jupyter前端的工具条中，添加一个自定义工具，当点击自定义工具时，弹出提示信息。

define([
    'base/js/namespace'
], function(
    Jupyter
) {
    function load_ipython_extension() {

        var handler = function () {
            alert('欢迎使用前端扩展!');
        };

        var action = {
            icon: 'fa-comment-o',
            help    : '前端扩展',
            help_index : 'zz',
            handler : handler
        };
        var prefix = 'my_extension';
        var action_name = 'show-alert';

        var full_action_name = Jupyter.actions.register(action, action_name, prefix); // returns 'my_extension:show-alert'
        Jupyter.toolbar.add_buttons_group([full_action_name]);
    }

    return {
        load_ipython_extension: load_ipython_extension
    };
});

完前端扩展代码后，我们把脚本保存到main.js文件，放置在/opt/my_extension目录下。接下来我们使用jupyter nbextension工具来安装和启用前端扩展

# 安装前端扩展
jupyter nbextension install /opt/my_extension
# 启用前端扩展
jupyter nbextension enable my_extension/main
# 禁用前端扩展
jupyter nbextension disable my_extension/main
# 查看前端扩展列表
jupyter nbextension list
# 卸载前端扩展
jupyter nbextension uninstall my_extension

图9 在Notebook工具条中加入的前端扩展

7.2. 服务端扩展

Jupyter服务端扩展（server extension）是使用Python语言编写的模块，可以用来处理发送到Jupyter Server的Http请求。使用Jupyter服务端扩展，可以更改现有Jupyter请求的数据和行为，也可以为jupyter Server定义新的服务处理程序。

定义一个服务端扩展模块要实现一个load_jupyter_server_extension方法，其中包含一个类型为notebook.notebookapp.NotebookApp的参数serverapp，serverapp的详细属性和方法可以通过Jupyter Notebook源代码中的notebookapp.py文件来查看。当服务端扩展被加载时，Jupyter Server会调用load_jupyter_server_extension方法。在load_jupyter_server_extension方法中，我们可以通过调用serverapp的web_app属性的add_handlers方法来注册处理程序，用来处理特定的服务端请求。处理程序类需要继承自Jupyter的IPythonHandler类。在处理程序的方法中，可以使用Jupyter提供的@web.authenticated装饰器来为方法增加身份认证保护。

通过服务端扩展，还可以与前端扩展联动，实现一个功能丰富的Jupyter Notebook前端控件。

# 定义一个处理程序
from tornado import (
    gen, web,
)
from notebook.base.handlers import IPythonHandler

class HelloWorldHandler(IPythonHandler):
    @web.authenticated
    @gen.coroutine
    def get(self):
        self.finish(f'Hello, world!')


# 实现load_jupyter_server_extension方法并注册处理程序
def load_jupyter_server_extension(serverapp):
    handlers = [
        ('/myextension/hello', HelloWorldHandler)
    ]
    serverapp.web_app.add_handlers('.*$', handlers)

完成服务端扩展代码后，我们把代码保存为__init__.py文件，要在Jupyter Notebook中使用处理程序，我们还需要进行服务端扩展的安装和启用。不同于前端扩展，服务端扩展不能直接使用指令来安装，需要我们手动编写安装程序。此外，Jupyter提供了自动启用服务端扩展和前端扩展的方法，需要我们在脚本的根目录提供启用扩展的配置文件。

jupyter-config/
├── jupyter_notebook_config.d/
│   └── my_server_extension.json
└── nbconfig/
    └── notebook.d/
        └── my_front_extension.json
 setup.py

加入了自动启用扩展的配置，我们的服务端扩展目录结构如下：

hello-extension/
├── __init__.py
jupyter-config/
├── jupyter_notebook_config.d/
    └── hello_extension.json

hello_extension.json文件的内容为：

{
    "ServerApp": {
        "jpserver_extensions": {
            "hello_extension": true
        }
    }
}

接下来我们通过安装程序，安装服务端扩展的信息保存在/root/.jupyter/jupyter_notebook_config.json文件中。在安装完成后，我们可以通过jupyter serverextesion工具来股那里服务端扩展

# 启用服务端扩展
jupyter serverextension enable hello_extension
# 禁用服务端扩展
jupyter serverextension disable hello_extension

# 服务端扩展直接卸载的方法，需要我们通过pip uninstall 卸载安装程序，
# 再通过手工修改/root/.jupyter/jupyter_notebook_config.json文件删除扩展信息来完成卸载

图10 在浏览器中测试安装的服务端扩展程序

7.3. 界面定制

Jupyter没有提供标准的界面定制的能力，但我们可以手工调整jupyter生成的模板视图文件和样式文件，达到整条调整jupyter notebook的界面的能力。

Jupyter Notebook模板文件的位置为：$notebook/templates，样式和脚本定制推荐的方案是使用_{/.jupyter/custom/custom.css和}/.jupyter/custom/custom.js文件。我们可以直接在此基础上对文件进行修改，还可以通过extra_template_paths和extra_static_paths来引入其它位置的模板和其它静态文件。

图11 通过直接调整模板文件加入的界面定制按钮

7.4. 小部件

小部件（Widgets）是Jupyter交互式可视化数据呈现部件。Jupyter Widgets同时包含了访问后端数据和前端呈现的能力，可以用于在Jupyter Notebook上生动地展示服务端的数据和数据变化。

在v6.5.2稳定版本上，我们目前只能使用系统提供的小部件，还不能开发自定义小部件。在Jupyter notebook7.x版本中，开始提供了小部件的自定义开发能力。

# 确保安装了ipywidgets和traitlets
pip install --upgrade traitlets
pip install --upgrade ipywidgets

# 安装和启用小部件
jupyter nbextension install --py widgetsnbextension
jupyter nbextension enable --py widgetsnbextension

在安装和启用了小部件后，我们可以在notebook中直接使用系统提供的小部件。

图12 在Notebook中使用小部件

完整的小部件列表和使用方式可以参考： <​​https://ipywidgets.readthedocs.io/en/7.x/examples/Widget List.html​​>

8. 总结

Jupyter Notebook以其丰富的功能，简单易用，强大的交互能力和扩展能力，成为数据科学和机器学习开发中的神器。目前，Jupyter Notebook支持超过40种编程语言，被应用于Google Colab, Kubeflow, 华为云，kaggle等多个知名项目中，大量机器学习和数据科学的论文中使用到了Jupyter。Jupyter在数据可视化，提升工作效率，改善用户体验和丰富文档功能方面显现了巨大的威力。除此之外，Jupyter还提供的灵活强大的扩展能力，更是为Jupyter的深层次使用提供了更广阔的想象空间。如果你还没有开始接触Jupyter，那么就从现在开始吧。