Clarify ClearML Agent modes (#685)

This commit is contained in:
pollfly 2023-10-03 10:44:37 +03:00 committed by GitHub
parent ffb1d51072
commit 61806b5178
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 35 additions and 36 deletions

View File

@ -340,40 +340,37 @@ Run a `clearml-agent` daemon in foreground mode, sending all output to the conso
clearml-agent daemon --queue default --foreground clearml-agent daemon --queue default --foreground
``` ```
## Execution Environments ## Execution Environments
ClearML Agent supports executing tasks in multiple environments. ClearML Agent has two primary execution modes: [Virtual Environment Mode](#virtual-environment-mode) and [Docker Mode](#docker-mode).
### PIP Mode ### Virtual Environment Mode
By default, ClearML Agent works in PIP Mode, in which it uses [pip](https://en.wikipedia.org/wiki/Pip_(package_manager))
as the package manager. When ClearML runs, it will create a virtual environment
(or [reuse an existing one](clearml_agent.md#virtual-environment-reuse)).
Task dependencies (Python packages) will be installed in the virtual environment.
### Conda Mode In Virtual Environment Mode, the agent creates a virtual environment for the experiment, installs the required Python
This mode is similar to the PIP mode but uses [Conda](https://docs.conda.io/en/latest/) as the package packages based on the task specification, clones the code repository, applies the uncommitted changes and finally
manager. To enable Conda mode, edit the `clearml.conf` file, and modify the `type: pip` to `type: conda` in the “package_manager” section. executes the code while monitoring it. This mode uses smart caching so packages and environments can be reused over
If extra conda channels are needed, look for “conda_channels” under “package_manager”, and add the missing channel. multiple tasks (see [Virtual Environment Reuse](#virtual-environment-reuse)).
### Poetry Mode ClearML Agent supports working with one of the following package managers:
This mode is similar to the PIP mode but uses [Poetry](https://python-poetry.org/) as the package manager. * [`pip`](https://en.wikipedia.org/wiki/Pip_(package_manager)) (default)
To enable Poetry mode, edit the `clearml.conf` file, and modify the `type: pip` to `type: poetry` in the “package_manager” * [`conda`](https://docs.conda.io/en/latest/)
section. * [`poetry`](https://python-poetry.org/)
To change the package manager used by the agent, edit the [`package_manager.type`](configs/clearml_conf.md#agentpackagemanager)
field in the of the `clearml.conf`. If extra channels are needed for `conda`, add the missing channels in the
`package_manager.conda_channels` field in the `clearml.conf`.
:::note Using Poetry with Pyenv :::note Using Poetry with Pyenv
Some versions of poetry (using `install-poetry.py`) do not respect `pyenv global`. Some versions of poetry (using `install-poetry.py`) do not respect `pyenv global`.
If you are using pyenv to control the environment where you use ClearML Agent, you can: If you are using pyenv to control the environment where you use ClearML Agent, you can:
* Use poetry v1.2 and above (which [fixes this issue](https://github.com/python-poetry/poetry/issues/5077)) * Use poetry v1.2 and above (which fixes [this issue](https://github.com/python-poetry/poetry/issues/5077))
* Install poetry with the deprecated `get-poetry.py` installer * Install poetry with the deprecated `get-poetry.py` installer
::: :::
### Docker Mode ### Docker Mode
:::note :::note notes
Docker Mode is only supported in linux.<br/> * Docker Mode is only supported in linux.
Docker Mode requires docker service v19.03 or higher installed. * Docker Mode requires docker service v19.03 or higher installed.
::: :::
When executing the ClearML Agent in Docker mode, it will: When executing the ClearML Agent in Docker mode, it will:
@ -401,7 +398,7 @@ clearml-agent daemon --queue <execution_queue_to_pull_from> --docker [optional d
``` ```
To use the current `clearml-agent` version in the Docker container, instead of the latest `clearml-agent` version that is To use the current `clearml-agent` version in the Docker container, instead of the latest `clearml-agent` version that is
automatically installed, run: automatically installed, pass the `--force-current-version` flag:
```bash ```bash
clearml-agent daemon --queue default --docker --force-current-version clearml-agent daemon --queue default --docker --force-current-version
``` ```

View File

@ -77,21 +77,23 @@ reuse machines without the need for any dedicated containers or images.
Agents can be deployed bare-metal, with multiple instances allocating Agents can be deployed bare-metal, with multiple instances allocating
specific GPUs to the agents. They can also be deployed as dockers in a Kubernetes cluster. specific GPUs to the agents. They can also be deployed as dockers in a Kubernetes cluster.
The Agent has three running modes: The Agent supports the following running modes:
- Docker Mode: The agent spins a docker image based on the Tasks definition then inside the docker the agent will clone * **Virtual Environment Mode** - The agent creates a new virtual environment for the experiment, installs the required
the specified repository/code, apply the original executions uncommitted changes, install the required python packages python packages based on the Task specification, clones the code repository, applies the uncommitted changes and
and start executing the code while monitoring it. finally executes the code while monitoring it. This mode uses smart caching so packages and environments can be reused
- Virtual Environment Mode: The agent creates a new virtual environment for the experiment, installs the required python over multiple tasks (see [Virtual Environment Reuse](../clearml_agent.md#virtual-environment-reuse)).
packages based on the Task specification, clones the code repository, applies the uncommitted changes and finally
executes the code while monitoring it.
- Conda Environment Mode: Similar to the Virtual Environment mode, only instead of using pip, it uses conda install and
pip combination. Notice this mode is quite brittle due to the Conda package version support table.
:::tip Agents and virtual environments ClearML Agent supports using the following package managers: `pip` (default), `conda`, `poetry`.
An agent that runs in Virtual Environment Mode or Conda Environment Mode needs to create virtual environments, and
it can't do that when running from a virtual environment. You can run agents in these modes with :::tip Agents and virtual environments
system Python. An agent that runs in Virtual Environment Mode needs to create virtual environments, and
::: it can't do that when running from a virtual environment. You can run agents in these modes with
system Python.
:::
* **Docker Mode** - The agent spins a Docker image based on the Task's definitions. Inside the Docker the agent clones
the specified repository/code, applies the original execution's uncommitted changes, sets up the Python environment and
required packages, and starts executing the code while monitoring it.
## Services Mode ## Services Mode