169 lines
4.7 KiB
ReStructuredText
169 lines
4.7 KiB
ReStructuredText
:orphan:
|
|
|
|
#################################################
|
|
Configure hyperparameters from the CLI (Advanced)
|
|
#################################################
|
|
**Audience:** Users looking to modularize their code for a professional project.
|
|
|
|
**Pre-reqs:** You must have read :doc:`(Mix models and datasets) <lightning_cli_intermediate_2>`.
|
|
|
|
As a project becomes more complex, the number of configurable options becomes very large, making it inconvenient to
|
|
control through individual command line arguments. To address this, CLIs implemented using
|
|
:class:`~pytorch_lightning.cli.LightningCLI` always support receiving input from configuration files. The default format
|
|
used for config files is YAML.
|
|
|
|
.. tip::
|
|
|
|
If you are unfamiliar with YAML, it is recommended that you first read :ref:`what-is-a-yaml-config-file`.
|
|
|
|
|
|
----
|
|
|
|
***********************
|
|
Run using a config file
|
|
***********************
|
|
To run the CLI using a yaml config, do:
|
|
|
|
.. code:: bash
|
|
|
|
python main.py fit --config config.yaml
|
|
|
|
Individual arguments can be given to override options in the config file:
|
|
|
|
.. code:: bash
|
|
|
|
python main.py fit --config config.yaml --trainer.max_epochs 100
|
|
|
|
----
|
|
|
|
************************
|
|
Automatic save of config
|
|
************************
|
|
|
|
To ease experiment reporting and reproducibility, by default ``LightningCLI`` automatically saves the full YAML
|
|
configuration in the log directory. After multiple fit runs with different hyperparameters, each one will have in its
|
|
respective log directory a ``config.yaml`` file. These files can be used to trivially reproduce an experiment, e.g.:
|
|
|
|
.. code:: bash
|
|
|
|
python main.py fit --config lightning_logs/version_7/config.yaml
|
|
|
|
The automatic saving of the config is done by the special callback :class:`~pytorch_lightning.cli.SaveConfigCallback`.
|
|
This callback is automatically added to the ``Trainer``. To disable the save of the config, instantiate ``LightningCLI``
|
|
with ``save_config_callback=None``.
|
|
|
|
----
|
|
|
|
*********************************
|
|
Prepare a config file for the CLI
|
|
*********************************
|
|
The ``--help`` option of the CLIs can be used to learn which configuration options are available and how to use them.
|
|
However, writing a config from scratch can be time-consuming and error-prone. To alleviate this, the CLIs have the
|
|
``--print_config`` argument, which prints to stdout the configuration without running the command.
|
|
|
|
For a CLI implemented as ``LightningCLI(DemoModel, BoringDataModule)``, executing:
|
|
|
|
.. code:: bash
|
|
|
|
python main.py fit --print_config
|
|
|
|
generates a config with all default values like the following:
|
|
|
|
.. code:: bash
|
|
|
|
seed_everything: null
|
|
trainer:
|
|
logger: true
|
|
...
|
|
model:
|
|
out_dim: 10
|
|
learning_rate: 0.02
|
|
data:
|
|
data_dir: ./
|
|
ckpt_path: null
|
|
|
|
Other command line arguments can be given and considered in the printed configuration. A use case for this is CLIs that
|
|
accept multiple models. By default, no model is selected, meaning the printed config will not include model settings. To
|
|
get a config with the default values of a particular model would be:
|
|
|
|
.. code:: bash
|
|
|
|
python main.py fit --model DemoModel --print_config
|
|
|
|
which generates a config like:
|
|
|
|
.. code:: bash
|
|
|
|
seed_everything: null
|
|
trainer:
|
|
...
|
|
model:
|
|
class_path: pytorch_lightning.demos.boring_classes.DemoModel
|
|
init_args:
|
|
out_dim: 10
|
|
learning_rate: 0.02
|
|
ckpt_path: null
|
|
|
|
.. tip::
|
|
|
|
A standard procedure to run experiments can be:
|
|
|
|
.. code:: bash
|
|
|
|
# Print a configuration to have as reference
|
|
python main.py fit --print_config > config.yaml
|
|
# Modify the config to your liking - you can remove all default arguments
|
|
nano config.yaml
|
|
# Fit your model using the edited configuration
|
|
python main.py fit --config config.yaml
|
|
|
|
----
|
|
|
|
********************
|
|
Compose config files
|
|
********************
|
|
Multiple config files can be provided, and they will be parsed sequentially. Let's say we have two configs with common
|
|
settings:
|
|
|
|
.. code:: yaml
|
|
|
|
# config_1.yaml
|
|
trainer:
|
|
num_epochs: 10
|
|
...
|
|
|
|
# config_2.yaml
|
|
trainer:
|
|
num_epochs: 20
|
|
...
|
|
|
|
The value from the last config will be used, ``num_epochs = 20`` in this case:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ python main.py fit --config config_1.yaml --config config_2.yaml
|
|
|
|
----
|
|
|
|
*********************
|
|
Use groups of options
|
|
*********************
|
|
Groups of options can also be given as independent config files. For configs like:
|
|
|
|
.. code:: yaml
|
|
|
|
# trainer.yaml
|
|
num_epochs: 10
|
|
|
|
# model.yaml
|
|
out_dim: 7
|
|
|
|
# data.yaml
|
|
data_dir: ./data
|
|
|
|
a fit command can be run as:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ python main.py fit --trainer trainer.yaml --model model.yaml --data data.yaml [...]
|