ClearML Session CLI

clearml-session 是一项功能，允许启动 JupyterLab、VS Code 和 SSH 会话，并在更符合资源需求的远程机器上执行代码。此功能提供本地链接，通过安全加密的 SSH 连接访问远程机器上的 JupyterLab 和 VS Code。默认情况下，JupyterLab 和 VS Code 远程会话分别使用端口 8878 和 8898。

先决条件

clearml 已安装并配置。详细信息请参见ClearML 设置。
在远程主机上至少运行一个 clearml-agent。详细信息请参见安装。
您的机器上安装了 SSH 客户端。要验证，请打开您的终端并执行 ssh。如果未收到错误，则表示正常。

启动 ClearML Session

安装 clearml-session
```
pip install clearml-session
```
运行 clearml-session
```
clearml-session 
```
您可以添加标志来设置容器镜像、远程 SSH 端口、JupyterLab/VS Code 版本等。所有配置选项请参见CLI 选项。

clearml-session 会创建一个新的任务，该任务负责根据您的规范在主机上设置 SSH 和 JupyterLab/VS Code 环境。
按照 clearml-session 设置向导进行操作
1. 选择队列 - 选择 ClearML Session 任务将排入的队列。分配给此队列的代理将设置并启动远程服务器。
2. 启动交互式会话？ - 点击 y 启动交互式会话。
会话任务被添加到选定的队列中，ClearML Agent 拉取并执行该任务。代理下载相应的 IDE 并启动它。
代理完成交互式任务的初始设置后，本地 clearml-session 通过 SSH 连接到主机，并通过 SSH 连接隧道传输 SSH 和 IDE。如果指定了容器，则 IDE 环境在容器内运行。
CLI 输出访问远程 JupyterLab 和 VS Code 会话的链接
```
Interactive session is running:
SSH: ssh root@localhost -p 8022 [password: <password>]
Jupyter Lab URL: http://localhost:8878/?token=<token>
VSCode server available at http://localhost:8898/
```
请注意，链接是 localhost，因为所有与远程服务器本身的通信都是通过安全的 SSH 连接完成的。点击 Jupyter Lab 或 VSCode 链接，或输入 shell 进入 SSH shell。
现在开始编写代码，就像您直接在目标机器上运行一样！

重新启动和关闭会话

如果在本地启动了 clearml-session 并且它仍在远程机器上运行，您可以轻松地重新连接到它。要重新连接到之前的会话，请执行 clearml-session，无需附加任何标志，就会出现重新连接到现有会话的选项

Connect to active session id=c7302b564aa945408aaa40ac5c69399c [Y]/n?

如果从本地机器启动了多个会话并且它们仍处于活动状态，请选择所需的会话

Active sessions:
0*] 2021-05-09 12:24:11 id=ed48fb83ad76430686b1abdbaa6eb1dd
1] 2021-05-09 12:06:48 id=009eb34abde74182a8be82f62af032ea
Connect to session [0-1] or 'N' to skip

要关闭远程会话（这将释放 clearml-agent 并关闭 CLI），请输入“Shutdown”。如果会话已关闭，则无法重新连接到它。

连接到现有会话

如果 clearml-session 正在远程运行，您可以从任何机器上继续使用该会话。当 clearml-session 启动时，它会在 ClearML Server 中初始化一个具有唯一 ID 的任务。

要连接到现有会话

转到 Web UI，找到交互式会话任务（默认情况下，它在项目“DevOps”中）。
通过点击任务页面标题中的 ID 按钮复制唯一 ID。
运行以下命令: clearml-session --attach <session_id>。
点击输出的 JupyterLab / VS Code 链接，或直接连接到 SSH 会话

功能

在容器中运行

要在容器内运行会话，请使用 --docker 标志并输入要在交互式会话中使用的镜像。

Kubernetes 支持

借助 ClearML k8s-glue，您可以直接在 Kubernetes Pod 内启动 ClearML 会话。在 values.yaml 文件的 sessions 部分设置 clearml-session 的网络和 ingress 设置。

确保设置以下值

设置 portModeEnabled: true 以允许会话直接从 Pod 运行
svcType - 将服务类型设置为 NodePort 或 LoadBalancer。请注意，如果设置为 NodePort，则 externalIP 必须设置为其中一个 worker 的 IP。如果设置为 LoadBalancer，则需要在应用 chart 之前提前设置好 LoadBalancer 和外部 IP 地址
externalIP - 定义客户端将连接的外部 IP 地址。请注意，此外部 IP 需要提前设置。
maxServices - 代理将生成的最大会话数

例如

# -- Sessions internal service configuration
sessions:
  # -- Enable/Disable sessions portmode WARNING: only one Agent deployment can have this set to true
  portModeEnabled: true
  # -- specific annotations for session services
  svcAnnotations: {}
  # -- service type ("NodePort" or "ClusterIP" or "LoadBalancer")
  svcType: "NodePort"
  # -- External IP sessions clients can connect to
  externalIP: 0.0.0.0
  # -- starting range of exposed NodePorts
  startingPort: 30000
  # -- maximum number of NodePorts exposed
  maxServices: 20

更多信息请参见Kubernetes。

安装依赖

clearml-session 可以在设置远程环境时安装所需的 Python 包。通过以下任一方式指定依赖

使用 --requirements </file/location.txt> 标志将 requirements.txt 文件附加到命令。
使用 --packages "<package_name>" 手动指定包（例如 --packages "keras" "clearml"），它们将自动安装。

访问 Git 仓库

要远程访问 Git 仓库，请添加 --git-credentials 标志并将其设置为 true，以便将本地 .git-credentials 文件发送到交互式会话。这对于处理私有 Git 仓库非常有用，并且允许无缝克隆和跟踪 Git 引用，包括未跟踪的更改。

将本地文件上传到远程会话

您可以通过使用 --upload-files <file_path> 指定本地文件和目录的路径，将它们从本地机器上传到远程会话。目录或文件的全部内容将复制到您的远程 clearml-session 容器的 ~/session-files/ 目录下。

clearml-session --upload-files /mnt/data/stuff

您可以将文件与 --store-workspace 选项结合使用，以便在本地开发机器和远程机器之间轻松移动工作负载，并实现持久的工作区同步。请参见存储和同步工作区。

启动调试会话

您可以在远程交互式会话中调试 ClearML 系统中注册的先前执行的任务。向 clearml-session 输入要调试的任务 ID，然后 clearml-session 将克隆该任务的 Git 仓库并在远程机器上复制环境。然后可以在 JupyterLab / VS Code 上交互式地执行和调试代码。

注意

任务必须连接到 Git 仓库，因为目前不支持单个脚本调试。

在 ClearML Web UI 中，找到需要调试的任务。
通过点击任务页面标题中的 ID 按钮复制唯一 ID。
输入以下命令: clearml-session --debugging-session <task_id>
点击 JupyterLab / VS Code 链接，或直接连接到 SSH 会话。
在 JupyterLab / VS Code 中，访问 environment/task_repository 文件夹中的任务仓库。

存储和同步工作区

您可以使用 --store-workspace 选项存储和同步您的交互式会话工作区。关闭会话时，clearml-session 会自动创建整个工作区的快照，并在之后在任何远程机器上的新会话中恢复。

通过在命令行中添加 --store-workspace <workspace_root_folder> 来指定远程工作区根文件夹。在远程会话容器中，将您的所有代码和数据放在 <workspace_root_folder> 目录下。当您的会话关闭时，工作区文件夹将自动打包并存储在 ClearML 文件服务器上。

clearml-session --store-workspace ~/workspace

在您下一次执行 clearml-session 时，再次指定 --store-workspace <workspace_root_folder>，clearml-session 将获取之前的工作区快照并将其恢复到新的远程容器的 <workspace_root_folder> 目录中。

clearml-session --store-workspace ~/workspace

要继续特定会话并恢复其工作区，请使用 --continue-session <session_id> 指定会话 ID

clearml-session --continue-session <session_id> --store-workspace ~/workspace

命令行选项

命令行选项	描述	默认值
`--attach`	附加到正在运行的交互式会话	之前的会话
`--base-task-id`	传入将成为基础任务的任务 ID，以便会话使用其配置	`none` 或之前输入的基础任务
`--config-file`	指定 `clearml-session` 存储其先前状态的另一个配置文件的路径	`.clearml_session.json` 或之前输入的配置文件
`--continue-session`	传入之前会话的 ID 以继续，恢复您的工作区（参见 `--store-workspace`）	`无`
`--debugging-session`	传入现有任务 ID，在远程机器上创建任务副本，并启动 Jupyter/SSH 进行交互式访问。示例 `--debugging-session <task_id>`	`无`
`--disable-fingerprint-check`	如果设置，跳过远程 SSH 服务器指纹验证过程	`无`
`--disable-session-cleanup`	如果为 `True`，则不会删除之前的交互式会话	`false`
`--disable-store-defaults`	如果设置，则不将当前设置存储为新的默认配置	`无`
`--docker`	选择要在交互式会话中使用的镜像	`nvidia/cuda:11.6.2-runtime-ubuntu20.04` 或之前使用的镜像
`--docker-args`	添加要在交互式会话中使用的 docker 镜像的附加参数	`none` 或之前使用的 `docker-args`
`--force_dropbear`	强制使用 `dropbear` 而非 SSHd	`无`
`--git-credentials`	如果为 `True`，则将本地 `.git-credentials` 文件发送到交互式会话。	`false`
`--init-script`	指定在设置交互式会话时要执行的 BASH 初始化脚本文件	`none` 或之前输入的 BASH 脚本
`--jupyter-lab`	在交互式会话中安装 JupyterLab	`true`
`--keepalive`	如果设置，启用透明代理以保持 socket 处于活动状态，从而维护与远程资源的连接	`false` - 不使用透明 socket 来缓解连接中断
`--packages`	要添加的附加包。支持版本号。示例: `--packages torch==1.7 tqdm`	之前添加的包。
`--password`	为交互式会话设置您自己的 SSH 密码	随机生成的密码或之前使用的密码
`--project`	为交互式会话任务设置项目名称	`DevOps`
`--public-ip`	如果为 `true`，则注册远程机器的公共 IP（如果您在公有云上运行会话）	`false` - 会话在执行该会话的代理所在的机器上运行
`--queue`	选择要在其上启动交互式会话的队列	之前使用的队列
`--queue-excluded-tag`	队列选项列表将排除带有指定标签的队列。参见 queues.create API 调用中的 `tags` 参数	`无`
`--queue-include-tag`	队列选项列表将仅包含带有指定标签的队列。参见 queues.create API 调用中的 `tags` 参数	`无`
`--randomize`	为交互式会话生成新的随机 SSH 密码。传入 `--randomize` 为当前会话创建随机密码。传入 `--randomize always` 为您启动的每个会话生成新的随机密码。	`false`
`--remote-gateway`	指定要传递给交互式会话的网关 IP，如果需要访问外部地址	`无`
`--remote-ssh-port`	设置在代理机器上运行的远程 SSH 服务器端口	10022
`--requirements`	指定设置交互式会话时要安装的 `requirements.txt` 文件。	`none` 或之前使用的依赖（可以通过调用 `--packages` 覆盖）
`--session-name`	设置交互式会话任务的名称	`无`
`--session-tags`	为交互式会话添加标签以提高可见性	`无`
`--shell`	直接打开 SSH 会话。请注意，退出 SSH 会话不会关闭远程会话	`无`
`--shutdown`, `-S`	关闭活动会话	之前的会话
`--skip-docker-network`	不要将 `--network host` 标志传递给启动远程会话的 Docker。参见使用主机网络进行网络连接	`false`
`--store-workspace`	上传/恢复远程工作区文件夹并将其提取到下一个会话。与 `--continue-session` 一起使用，以从您精确的容器状态继续之前的工作	`无`
`--upload-files`	指定要上传到远程会话的本地文件/文件夹	`无`
`--user-folder`	指定会话远程基础文件夹的路径	主文件夹(`~/`) 或之前输入的用户文件夹路径
`--username`	为交互式会话设置您自己的 SSH 用户名	`root` 或之前使用的用户名
`--verbose`	增加日志记录的详细程度	`无`
`--version`	显示 clearml-session 实用工具版本	不适用
`--vscode-extensions`	安装附加的 VSCode 扩展和 VSCode Python 扩展（示例: `ms-python.python,ms-python.black-formatter,ms-python.pylint,ms-python.flake8`）	`无`
`--vscode-server`	在交互式会话中安装 VSCode	`true`
`--vscode-version`	设置 VSCode server (code-server) 版本，以及 VSCode Python 扩展版本 `<vscode:python-ext>`（示例: "3.7.4:2020.10.332292344"）	`4.14.1:2023.12.0`
`--yes`, `-y`	自动对提示回答“是”；假设对所有提示的回答都是“是”，并以非交互模式运行	不适用

先决条件​

启动 ClearML Session​

重新启动和关闭会话​

连接到现有会话​

功能​

在容器中运行​

Kubernetes 支持​

安装依赖​

访问 Git 仓库​

将本地文件上传到远程会话​

启动调试会话​

存储和同步工作区​

命令行选项​