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

1. Jupyter Notebook介绍



Jupyter Notebook入门指南



图1 Jupter项目整体架构

[docs.jupyter.org/en/latest/p…]

Jupyter Notebook是一套依据web的交互式开发环境。用户能够在线开发和共享包含代码和输出的交互式文档，支撑实时代码，数学方程，可视化和 markdown等。用途包括：数据整理和转化，数值模仿，统计建模，机器学习等等。

Jupyter Notebook内部经过内核维护状况并运转代码片段，浏览器闪现代码片段和其履行的成果。Jupyter Notebook供给了一个用户交互式的开发环境，用户能够经过履行一部分代码片段，并观察履行成果。这种交互式设计，使得Jupyter Notebook十分适宜数据科学和机器学习的开发作业。

留意本文的代码和脚本，均依据Jupyter Notebook v6.5.2安稳版别。

2. Jupyter的作业办法



Jupyter Notebook入门指南



图2 Jupter Notebook作业办法

[docs.jupyter.org/en/latest/p…]

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）项目的首要模块结构如下：

模块 阐明
notebook Notebook功用模块。
terminal 终端模块。为Jupyter供给控制台交互才能。
view 文件可视化模块。比如pdf文件的闪现。
tree 作业区目录树
nbconvert 格局转化模块，能够把Jupyter Notebook转化成html，pdf等格局
kernel Jupyter Notebook 内核
services Jupyter Notebook REST API模块
i18n Jupyter Notebook多言语资源

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代码来完结。常用的装备项及其阐明如下：

名称 默许值 阐明
c.NotebookApp.allow_root False 为了安全，Jupyter默许不答应运用root用户发动。假如需求以root用户的身份发动Jupyter，需求开启此设定
c.NotebookApp.allow_origin ” 当需求Jupyter内嵌到iframe时，能够设置为“*“来避免跨origin的约束
c.NotebookApp.ip localhost 当需求经过外网地址来拜访Jupyter服务时，需求设置一个有效的服务器IP地址。
c.NotebookApp.port 8888 Jupyter server对外服务端口
c.NotebookApp.notebook_dir / Jupyter的作业空间，默许能够拜访服务器上当时用户的一切文件体系
c.NotebookApp.open_browser True 发动服务后是否立即经过浏览器翻开服务地址
c.NotebookApp.default_url /tree Jupyter服务的默许地址
c.NotebookApp.extra_static_paths [] 扩展静态文件目录
c.NotebookApp.extra_template_paths [] 扩展模板文件目录
c.KernelSpecManager.allowed_kernelspecs set() 默许答应运用一切的kernel
c.NotebookApp.nbserver_extensions {} 答应加载的Jupyter Server扩展

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



Jupyter Notebook入门指南



图3 Jupter Notebook的默许作业区目录树页面

Jupyter Notebook经过Jupyter Server供给依据Web的渠道无关的作业办法，这使得跨渠道开发和协作，代码共享等才能变得比传统IDE愈加容易。

在Jupyter 作业区办理界面，用户能够灵敏地以相似文件体系的办法办理作业区的数据。能够创立文件和文件夹，修正文件和文件夹，能够上传和下载文件。经过挑选一个Jupyter内核，能够创立一个Notebook文件。



Jupyter Notebook入门指南



图4 经过Jupyter内核创立一个Notebook

5.2. 运用Notebook

运用Python3内核创立一个Notebook后，咱们得到一个xxx.ipynb（IPython Notebook）文件。这个文件是一个json格局的文本文件，其间包含了咱们在Notebook中编写的代码和文本内容，也包含了界面上没有闪现的元数据信息。经过在作业区目录界面挑选一个notebook文件，点击修正，咱们能够检查到ipynb文件的原始内容。



Jupyter Notebook入门指南



图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”文件夹下，找到这些检查点文件。



Jupyter Notebook入门指南



图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文档。

  1. 离线Notebook文档

咱们经过逐步履行文档中的一切单元格，得到一个包含了咱们编写的阐明和代码，以及代码履行的输出成果的完好文档。之后点击【文件】-> 【另存为】，挑选一种适宜的文件格局。咱们能够把文档导出为一份静态文件，经过共享此静态文件，咱们完结了Notebook文档的离线共享。

5.4. 魔法函数

Jupyter Notebook供给了一些列魔法函数来增强Jupyter Code单元格的功用，经过魔法函数，咱们能够履行javascript脚本，html代码，运转另一个可履行程序等许多额定的功用。

咱们能够在Jupyter代码单元格中运用 %lsmagic指令来检查一切的魔法函数，假如要阅览具体的魔法函数的运用阐明，能够参考： ipython.readthedocs.io/en/stable/i…

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

一些常用的魔法函数：

指令 阐明
%matplotlib 设置matplot绘图的闪现形式
%%javascript 单元格内的代码被识别为javascript代码
%%html 单元格内的代码被识别为html代码
%run 履行外部脚本文件
%pwd 获取当时作业的目录方位（非作业空间目录方位）
%writefile 以文件办法保存当时单元格代码
%timeit 获取本行代码的履行时间
%debug 激活调试形式

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文件，之后部署在notebook/i18n/notebook/i18n/{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



Jupyter Notebook入门指南



图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接口列表能够参考： jupyter-server.readthedocs.io/en/latest/d…

要运用REST API，需求在恳求中携带认证信息。Jupyter支撑直接把token作为query string的办法来认证，也能够运用标准的Http Authorization头信息来完结认证。运用Authorization头来认证的格局如下：

Authrozation: token 527a9f1430ccfed995ebcf15517583a2547c2469bc3c47a6



Jupyter Notebook入门指南



图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



Jupyter Notebook入门指南



图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文件删去扩展信息来完结卸载



Jupyter Notebook入门指南



图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来引进其它方位的模板和其它静态文件。



Jupyter Notebook入门指南



图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中直接运用体系供给的小部件。



Jupyter Notebook入门指南



图12 在Notebook中运用小部件

完好的小部件列表和运用办法能够参考： ipywidgets.readthedocs.io/en/7.x/exam…

8. 总结

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