扩展 notebook 运行时

ArcGIS Notebook Server 包含两个 notebook 运行时（Python 模块的集合）。 这些运行时会通过容器镜像提供给笔记本用户，容器镜像应用于您服务器站点中运行的每个容器。

标准和高级 notebook 运行时都包括 ArcGIS API for Python 和多种 Python 模块，可用于数据科学、空间分析和内容管理。 高级运行时还包括 ArcPy。

请参阅可用 Python 库的列表

在某些情况下，笔记本创作者可能需要这两个运行时中未包含的模块或特定版本的模块。 您可以通过以下方法在 ArcGIS Notebook Server 中访问附加 Python 模块：

• 在 notebook 会话期间安装一个 Python 模块。 该模块即可用于该 notebook。
• 扩展 Esri 容器镜像以在自定义运行时中包含其他 Python 库。 您创建的容器镜像将使您站点中的所有 notebook 创作者都可使用扩展的运行时。

在会话期间安装模块

笔记本创作者可以在笔记本会话期间通过使用 conda 包管理系统安装两个运行时中未包含的 Python 模块或不同版本模块以供使用。 建议您使用 conda，因为 ArcGIS Notebook Server 使用它来管理模块。

该方法将在 notebook 会话期间安装所需模块。 关闭 notebook 或终止属于用户的容器后，该模块将不再可用。 要使用此方法安装模块，必须与 conda 通道建立网络连接。

注：

conda 包含在两个笔记本运行时中。 无需进行安装。

例如，要在会话期间安装 scrapy 包，请使用以下其中一个命令运行 notebook 单元格，具体取决于您所使用的包管理系统：

使用 conda 包管理系统

!conda install --yes scrapy

要在使用中的 notebook 运行时中使用不同版本的 Python 模块，请在命令中指定版本号。

运行 conda 命令之后必须重新启动内核，新包才会可用。

例如，某个软件包在 1.5 版本的两个 notebook 运行时都可用，但您想使用 1.6 版本中引入的工具。 要在 notebook 会话期间使用 1.6 版本的包，请使用以下其中一个命令运行 notebook 单元格，具体取决于您所使用的包管理系统：

使用 conda 包管理系统

!conda install --yes <package name>==1.6

构建自定义容器镜像

要对 notebook 运行时进行持久更改，则可以在站点中构建自定义容器镜像。 以下工作流需要管理权限，可创建自定义镜像并为其使用配置 ArcGIS Notebook Server。

可以使用两个 notebook 运行时之一（标准或高级）作为起点。 构建自定义运行时之后，可以将其注册为站点中的新运行时。

1. 安装并配置 ArcGIS Notebook Server。
2. 以管理员身份登录到 ArcGIS Notebook Server Administrator Directory。

   URL 地址格式为 https://notebookserver.domain.com:11443/arcgis/admin/。

3. 单击 notebooks > runtimes，然后选择要为自定义镜像扩展的 notebook 运行时。

   在运行时的资源页面上，记录该运行时的 imageId 值。 在下一步骤中将使用该值。

4. 创建一个 Dockerfile，将所需 Python 模块添加到自定义镜像。

   Dockerfile 是一个简单的指令文本文件，可用于构建 Docker 容器镜像。 请参阅 Dockerfile 文档了解其详细信息及最佳实践。

   在此示例中，需要向高级 notebook 运行时添加数据可视化 Python 包 graphviz。 Dockerfile 中的以下代码块将控制 Docker 使用其 repository 名称和 tag 访问高级运行时，然后在运行时中安装 graphviz。 您可以在安装运行时的 ArcGIS Notebook Server 计算机上使用 docker images 命令获取 repository 名称和 tag。 要减少文件大小，建议使用 conda clean 命令。

   针对现有 notebook 运行时使用 docker images 命令获取镜像名称（资料档案库）和标签。

   
   docker images
   
   REPOSITORY                        TAG                 IMAGE ID            CREATED             SIZE
   arcgis-notebook-python-advanced   10.8.1.14362        e46a81f69ea0        12 months ago       12.4GB
   arcgis-notebook-python-standard   10.8.1.14362        106a660a4d0b        12 months ago       7.51GB

   通过向高级 notebook 运行时添加数据可视化 Python 包 graphviz 来创建自定义运行时。

   # Specify the existing notebook runtime imageId as FROM
   FROM arcgis-notebook-python-advanced:10.8.1.14362
   
   # Use RUN to issue a command to install, then clean
   RUN conda install graphviz \
     && conda clean -y -a

5. 将 Dockerfile 保存于计算机上只包含 Dockerfile 的新文件夹。
6. 使用 Docker 命令构建自定义容器镜像。

   该镜像将包含 Dockerfile 中指定的新运行时。 打开命令提示符窗口并使用以下语法运行命令：

   cd C:\DockerfileDir
   docker build -t arcgis-notebook-python-advanced-custom:10.8.1.14362 -f Dockerfile .

   注：

   请确保命令以句点结尾。

   运行命令后，Docker 将构建新的容器镜像。 命令输出中的最后一行为 Successfully built <imageId>，其中包含新镜像的简化 ID 值。 您必须为 ArcGIS Notebook Server 站点提供其完整 imageId 值。

7. 在命令提示符窗口中运行以下命令以获取镜像 ID 值：

   docker inspect <imageId>

   如果您拥有单机 Notebook Server 站点，可以跳过步骤 8 到步骤 10。 如果您拥有多机 Notebook Server 站点，请完成步骤 8 到步骤 10。

8. 使用 docker save 将自定义 Docker 镜像另存为 *.tar 文件。

   在安装自定义运行时镜像的 Notebook Server 计算机上打开命令窗口并运行以下命令以将自定义运行时镜像另存为 *.tar 文件。

    docker save arcgis-notebook-python-advanced-custom:10.8.1.14362 > arcgis-notebook-python-advanced-custom.tar

9. 在安装 Notebook Server 的每台计算机上，使用 ArcGIS Notebook Server 安装后配置实用程序加载自定义运行时镜像。
   1. 以管理员身份启动命令提示符。
   2. 将目录更改为 ArcGIS Notebook Server 安装后配置实用程序文件夹。

      默认路径为 C:\Program Files\ArcGIS\NotebookServer\tools\postInstallUtility

   3. 通过指定文件路径安装自定义 Docker 镜像。

       PostInstallUtility.bat -l <path of .tar Custom Docker image>

10. 在参与 ArcGIS Notebook Server 站点的每台计算机上重复步骤 9。

您的自定义镜像现已构建，并且您拥有完整的 imageId 值，您可以使用该值将自定义镜像注册到下一部分中的 ArcGIS Notebook Server 站点。

在 Manager 中注册新的运行时

自 10.8 起，您可以使用 ArcGIS Notebook Server Manager 注册您已经创建的自定义运行时。

1. 以管理员身份登录到您的 ArcGIS Enterprise 门户，然后打开 ArcGIS Notebook Server Manager。
2. 打开设置页面并单击运行时。
3. 单击注册运行时以打开注册对话框。
4. 指定适当的值以完成注册。

   参数	详细信息
   名称	表示新运行时的字符串，例如 "Notebook Custom Runtime Python 3"。
   容器类型	唯一有效值为 docker。
   最大 CPU	每个容器使用的最大 CPU 单元数。
   需要高级权限	如果运行时需要高级笔记本权限，请打开该切换按钮。
   镜像 ID	构建镜像时新 Docker 镜像的完整（非截断）ID。
   Docker 运行时	在 Linux 环境中仅适用于 GPU 运行时。
   最大内存	每个容器使用的内存上限值。
   最大内存单元	maxMemory 参数指定的单位。
   最大交换内存	每个容器达到 maxMemory 限制时可用的交换内存上限值。
   最大交换内存单元	maxSwapMemory 参数指定的单位。
   共享内存	每个容器可用的共享内存量。
   共享内存单元	sharedMemory 参数指定的单位。
   库清单	包含运行时中 Python 库列表的 *.json 文件（采用 UTF-8 或 ANSI 编码）。

   注：

   要创建 manifest.json 文件，请在安装自定义笔记本运行时镜像的 ArcGIS Notebook Server 计算机上打开一个 PowerShell 窗口，并根据您使用的是 Windows 还是 Linux 容器运行以下命令之一。

   在 Windows 容器上，使用以下命令：

   $ID = docker run -d -it <custom_runtime_image_ID> cmd; docker exec -it $ID powershell "conda list --json >> C:\arcgis\home\manifest.json"; docker cp $ID/:C:\arcgis\home\manifest.json <existing_folder_path>; docker kill $ID; docker rm -f $ID;

   在 Linux 容器上，使用以下命令：

   $ID = docker container run -d --rm -it -v /:/host <custom_runtime_image_ID> /bin/bash; docker exec -it $ID /opt/conda/bin/conda list --json >> ~\Desktop\manifest.json; docker kill $ID

5. 准备就绪后，单击保存以注册新的运行时。
6. 打开新的 notebook 以测试此更新。 确认您添加到自定义镜像的模块或模块版本在 notebook 中可用。

针对离线环境创建包含 ArcGIS 深度学习主干包的自定义运行时镜像

ArcGIS API for Python 支持训练多个深度学习模型的功能，每个模型都支持其自己的基本模型（主干）。 arcgis_dl_backbones conda 元包通过自动将主干放置在必要的位置来为离线用户提供支持，从而在使用 ArcGIS 训练深度学习模型时，无需从 Internet 下载主干。 请按照以下步骤创建包含 arcgis_dl_backbones conda 元包的自定义运行时镜像。

1. 在您的 ArcGIS Notebook Server 计算机上创建一个新文件夹。

   示例位置为 /data/custom

2. 下载 arcgis_dl_backbones 包。

   有关详细信息，请参阅断开连接环境的附加安装。

3. 将包 arcgis_dl_backbones-2.0.1-py_0.tar.bz2 解压到已创建的文件夹中。
4. 在已创建的文件夹中创建包含以下内容的 Docker 文件。
   FROM arcgis-notebook-python-standard:11.1.0.42869
   USER root
   RUN mkdir -p /home/user/DUMP/arcgis_dl_backbones-2.0.1
   USER $NB_UID
   WORKDIR /home/user/DUMP/arcgis_dl_backbones-2.0.1
   COPY arcgis_dl_backbones-2.0.1-py_0.tar.bz2 /home/user/DUMP/arcgis_dl_backbones-2.0.1
   RUN conda install --offline arcgis_dl_backbones-2.0.1-py_0.tar.bz2 -y
   RUN conda clean -y -a
   WORKDIR $HOME

5. 转至已创建的文件夹并使用以下 Docker 命令构建自定义容器镜像。
   docker build -t arcgis-notebook-python-standard-custom:11.1.0.42869 -f /data/custom/Dockerfile .

6. 按照以上在 Manager 中注册新的运行时部分中的步骤 7-10 在您的 Notebook Server 计算机上安装此自定义运行时镜像。

在升级 ArcGIS Notebook Server 后更新自定义运行时

按照以下步骤在升级 ArcGIS Notebook Server 后更新自定义运行时。

1. 使用新版本笔记本运行时镜像构建自定义运行时镜像。
2. 使用 Notebook Server 安装后实用程序在每个 Notebook Server 计算机上安装新的运行时镜像。
3. 使用 ArcGIS Notebook Server Manager 注册新的运行时。
4. 在使用自定义运行时的每个笔记本的项目详细信息页面上，单击设置。
5. 验证运行时并使用自定义运行时针对每个计算机将其更新为新注册的自定义运行时。
6. 在确认新运行时镜像起作用后，弃用先前版本的自定义运行时，方法为取消注册运行时并从每个 Notebook Server 计算机中移除运行时镜像。

要将 ArcGIS Notebook Server 站点中的运行时恢复为原始设置，请使用 Administrator Directory 中的恢复出厂运行时操作。 该操作在 https://notebookserver.domain.com:11443/arcgis/admin/notebooks/runtimes/restore 中提供，并且只会恢复当前站点版本的工厂运行时。