MMOCR mainly uses Python files as configuration files. The design of its configuration file system integrates the ideas of modularity and inheritance to facilitate various experiments.
This section is recommended to be read together with the primary usage in MMEngine: Config.
There are three most common operations in MMOCR: inheritance of configuration files, reference to
_base_ variables, and modification of
_base_ variables. Config provides two syntaxes for inheriting and modifying
_base_, one for Python, Json, and Yaml, and one for Python configuration files only. In MMOCR, we prefer the Python-only syntax, so this will be the basis for further description.
configs/textdet/dbnet/dbnet_resnet18_fpnc_1200e_icdar2015.py is used as an example to illustrate the three common uses.
_base_ = [ '_base_dbnet_resnet18_fpnc.py', '../_base_/datasets/icdar2015.py', '../_base_/default_runtime.py', '../_base_/schedules/schedule_sgd_1200e.py', ] # dataset settings icdar2015_textdet_train = _base_.icdar2015_textdet_train icdar2015_textdet_train.pipeline = _base_.train_pipeline icdar2015_textdet_test = _base_.icdar2015_textdet_test icdar2015_textdet_test.pipeline = _base_.test_pipeline train_dataloader = dict( batch_size=16, num_workers=8, persistent_workers=True, sampler=dict(type='DefaultSampler', shuffle=True), dataset=icdar2015_textdet_train) val_dataloader = dict( batch_size=1, num_workers=4, persistent_workers=True, sampler=dict(type='DefaultSampler', shuffle=False), dataset=icdar2015_textdet_test)
There is an inheritance mechanism for configuration files, i.e. one configuration file A can use another configuration file B as its base and inherit all the fields directly from it, thus avoiding a lot of copy-pasting.
dbnet_resnet18_fpnc_1200e_icdar2015.py you can see that
_base_ = [ '_base_dbnet_resnet18_fpnc.py', '../_base_/datasets/icdar2015.py', '../_base_/default_runtime.py', '../_base_/schedules/schedule_sgd_1200e.py', ]
The above statement reads all the base configuration files in the list, and all the fields in them are loaded into
dbnet_resnet18_fpnc_1200e_icdar2015.py. We can see the structure of the configuration file after it has been parsed by running the following statement in a Python interpretation.
from mmengine import Config db_config = Config.fromfile('configs/textdet/dbnet/dbnet_resnet18_fpnc_1200e_icdar2015.py') print(db_config)
It can be found that the parsed configuration contains all the fields and information in the base configuration.
Variables with the same name cannot exist in each
_base_ Variable References¶
Sometimes we may need to reference some fields in the
_base_ configuration directly in order to avoid duplicate definitions. Suppose we want to get the variable
pseudo in the
_base_ configuration, we can get the variable in the
_base_ configuration directly via
This syntax has been used extensively in the configuration of MMOCR, and the dataset and pipeline configurations for each model in MMOCR are referenced in the base configuration. For example,
icdar2015_textdet_train = _base_.icdar2015_textdet_train # ... train_dataloader = dict( # ... dataset=icdar2015_textdet_train)
_base_ Variable Modification¶
In MMOCR, different algorithms usually have different pipelines in different datasets, so there are often scenarios to modify the
pipeline in the dataset. There are also many scenarios where you need to modify variables in the
_base_ configuration, for example, modifying the training strategy of an algorithm, replacing some modules of an algorithm(backbone, etc.). Users can directly modify the referenced
_base_ variables using Python syntax. For dict, we also provide a method similar to class attribute modification to modify the contents of the dictionary directly.
Here is an example of modifying
pipelinein a dataset.
The dictionary can be modified using Python syntax:
# Get the dataset in _base_ icdar2015_textdet_train = _base_.icdar2015_textdet_train # You can modify the variables directly with Python's update icdar2015_textdet_train.update(pipeline=_base_.train_pipeline)
It can also be modified in the same way as changing Python class attributes.
# Get the dataset in _base_ icdar2015_textdet_train = _base_.icdar2015_textdet_train # The class property method is modified icdar2015_textdet_train.pipeline = _base_.train_pipeline
Suppose the variable
pseudo = [1, 2, 3]in the
_base_configuration needs to be modified to
[1, 2, 4]:
# pseudo.py pseudo = [1, 2, 3]
Can be rewritten directly as.
_base_ = ['pseudo.py'] pseudo = [1, 2, 4]
Or modify the list using Python syntax:
_base_ = ['pseudo.py'] pseudo = _base_.pseudo pseudo = 4
Command Line Modification¶
Sometimes we only want to fix part of the configuration and do not want to modify the configuration file itself. For example, if you want to change the learning rate during an experiment but do not want to write a new configuration file, you can pass in parameters on the command line to override the relevant configuration.
We can pass
--cfg-options on the command line and modify the corresponding fields directly with the arguments after it. For example, we can run the following command to modify the learning rate temporarily for this training session.
python tools/train.py example.py --cfg-options optim_wrapper.optimizer.lr=1
For more detailed usage, refer to MMEngine: Command Line Modification.
With config files and Registry, MMOCR can modify the training parameters as well as the model configuration without invading the code. Specifically, users can customize the following modules in the configuration file: environment configuration, hook configuration, log configuration, training strategy configuration, data-related configuration, model-related configuration, evaluation configuration, and visualization configuration.
This document will take the text detection algorithm
DBNet and the text recognition algorithm
CRNN as examples to introduce the contents of Config in detail.
default_scope = 'mmocr' env_cfg = dict( cudnn_benchmark=True, mp_cfg=dict(mp_start_method='fork', opencv_num_threads=0), dist_cfg=dict(backend='nccl')) randomness = dict(seed=None)
There are three main components:
Set the default
scopeof all registries to
mmocr, ensuring that all modules are searched first from the
MMOCRcodebase. If the module does not exist, the search will continue from the upstream algorithm libraries
MMCV, see MMEngine: Registry for more details.
env_cfgconfigures the distributed environment, see MMEngine: Runner for more details.
randomness: Some settings to make the experiment as reproducible as possible like seed and deterministic. See MMEngine: Runner for more details.
Hooks are divided into two main parts, default hooks, which are required for all tasks to run, and custom hooks, which generally serve specific algorithms or specific tasks (there are no custom hooks in MMOCR so far).
default_hooks = dict( timer=dict(type='IterTimerHook'), # Time recording, including data time as well as model inference time logger=dict(type='LoggerHook', interval=1), # Collect logs from different components param_scheduler=dict(type='ParamSchedulerHook'), # Update some hyper-parameters in optimizer checkpoint=dict(type='CheckpointHook', interval=1),# Save checkpoint. `interval` control save interval sampler_seed=dict(type='DistSamplerSeedHook'), # Data-loading sampler for distributed training. sync_buffer=dict(type='SyncBuffersHook'), # Synchronize buffer in case of distributed training visualization=dict( # Visualize the results of val and test type='VisualizationHook', interval=1, enable=False, show=False, draw_gt=False, draw_pred=False)) custom_hooks = 
Here is a brief description of a few hooks whose parameters may be changed frequently. For a general modification method, refer to Modify configuration.
LoggerHook: Used to configure the behavior of the logger. For example, by modifying
intervalyou can control the interval of log printing, so that the log is printed once per
intervaliteration, for more settings refer to LoggerHook API.
CheckpointHook: Used to configure checkpoint-related behavior, such as saving optimal and/or latest weights. You can also modify
intervalto control the checkpoint saving interval. More settings can be found in CheckpointHook API
VisualizationHook: Used to configure visualization-related behavior, such as visualizing predicted results during validation or testing. Default is off. This Hook also depends on Visualization Configuration. You can refer to Visualizer for more details. For more configuration, you can refer to VisualizationHook API.
If you want to learn more about the configuration of the default hooks and their functions, you can refer to MMEngine: Hooks.
This section is mainly used to configure the log level and the log processor.
log_level = 'INFO' # Logging Level log_processor = dict(type='LogProcessor', window_size=10, by_epoch=True)
The logging severity level is the same as that of Python: logging
The log processor is mainly used to control the format of the output, detailed functions can be found in MMEngine: logging.
by_epoch=Trueindicates that the logs are output in accordance to “epoch”, and the log format needs to be consistent with the
train_cfg. For example, if you want to output logs by iteration number, you need to set
window_sizeindicates the smoothing window of the loss, i.e. the average value of the various losses for the last
window_sizeiterations. the final loss value printed in logger is the average of all the losses.
Training Strategy Configuration¶
This section mainly contains optimizer settings, learning rate schedules and
Training strategies usually vary for different tasks (text detection, text recognition, key information extraction). Here we explain the example configuration in
CRNN, which is a text recognition model.
# optimizer optim_wrapper = dict( type='OptimWrapper', optimizer=dict(type='Adadelta', lr=1.0)) param_scheduler = [dict(type='ConstantLR', factor=1.0)] train_cfg = dict(type='EpochBasedTrainLoop', max_epochs=5, # train epochs val_interval=1) # val interval val_cfg = dict(type='ValLoop') test_cfg = dict(type='TestLoop')
optim_wrapper: It contains two main parts, OptimWrapper and Optimizer. Detailed usage information can be found in MMEngine: Optimizer Wrapper.
The Optimizer wrapper supports different training strategies, including mixed-accuracy training (AMP), gradient accumulation, and gradient truncation.
All PyTorch optimizers are supported in the optimizer settings. All supported optimizers are available in PyTorch Optimizer List.
param_scheduler: learning rate tuning strategy, supports most of the learning rate schedulers in PyTorch, such as
MultiStepLR, etc., and is used in much the same way, see scheduler interface, and more features can be found in the MMEngine: Optimizer Parameter Tuning Strategy.
train/test/val_cfg: the execution flow of the task, MMEngine provides four kinds of flow:
TestLoopMore can be found in MMEngine: loop controller.