Настройка предобученной модели
==============================

В данном разделе описана настройка предобученной модели на примере классификации текстов.

Формат датасета
---------------

Датасет должен состоять из файлов ``train.csv``, ``dev.csv`` и директории ``data``, содержащей тексты.
Первая колонка в этих файлах является идентификатором документа.
Этот идентификатор будет конкатенирован с полным путем директории ``data``.
Полученный путь должен указывать на файл с текстом.
Вторая колонка является меткой, которая обозначает класс, которому принадлежит текст.
Тексты должны быть предварительно сегментированы.


Запуск настройки
----------------

Для запуска нужно подготовить данные и конфигурацию.
В текущей директории необходимо создать директорию ``finetune-data``,
в которой должен лежать датасет, согласующийся с форматом, описанным в предыдущей секции.
Для тестирования можно воспользоваться примером `датасета <http://dn11.isa.ru:8080/doc-enc-data/datasets.classif.pat-en-mini.v1.tar.xz>`_.
Ниже приведена команда для настройки окружения

.. code-block:: bash

  mkdir -p finetune-data/models && \
  (cd finetune-data && wget -q -O -  'http://dn11.isa.ru:8080/doc-enc-data/datasets.classif.pat-en-mini.v1.tar.xz'  | tar Jxf -) && \
  (cd finetune-data/models && wget 'http://dn11.isa.ru:8080/doc-enc-data/models.def.pt' -O model.pt)

Конфигурационные файлы можно скачать из `репозитория проекта <https://gitlab.com/semvectors/doc_enc/-/tree/master/finetune/conf>`_,
при необходимости отредактировать и положить в ``finetune-data/conf``.
Команда запуска обучения:

.. code-block:: bash

	docker run --gpus=1  --rm  -v $(pwd)/finetune-data/:/train/ \
	semvectors/doc_enc_train:0.1.2 \
	fine_tune_classif \
	--config-path=/train/conf +personal/common=quick

Результаты будут сохранены в папку ``finetune-data/outputs``.
Для каждого запуска там будут создаваться отдельная директория,
в которой будет сохранена настроенная модель ``model.pt``.
Эту модель можно использовать для преобразования документов в векторное пространство,
кроме того она содержит веса обученного слоя классификации (ключ ``classif_layer``).

Основные параметры настройки модели
"""""""""""""""""""""""""""""""""""

* ``model_path`` - путь к предобученной модели (по умолчанию ``/train/models/model.pt``).
* ``use_gpu`` - номер GPU, на которой будет проходить обучение (по умолчанию 0).
* ``async_batch_gen`` - количество асинхронных процессов, которые будут задействованы в подготовки мини-батчей для обучения (по умолчанию 2).
* ``max_sents`` - максимальное количество предложений в мини-батче (по умолчанию 2048).
* ``max_tokens`` - максимальное количество токенов в мини-батче (по умолчанию 96_000).
* ``train_meta_path``, ``dev_meta_path``, ``test_meta_path`` - пути к файлам, в которых содержатся идентификаторы текстов и соответствующие им метки.
    По умолчанию ``/train/classif/train.csv`` и ``/train/classif/dev.csv`` соответственно.
    ``test_meta_path`` по умолчанию не задан.
* ``data_dir`` - директория, содержащая тексты документов (По умолчанию ``/train/classif/data/``).
* ``save_path`` - директория, в которую будут сохранены настроенная модель, логи обучения и пр. По умолчанию используется текущая рабочая директория.
* ``max_updates`` - максимальное количество шагов обучения (по умолчанию 5000).
* ``lr`` - скорость обучения (по умолчанию 0.0002). Рекомендуется подбирать значение данного параметра индивидуально для каждого датасета.
* ``dropout`` - вероятность дропаута эмбеддингов документов перед подачей в линейный слой классификации.
* ``only_eval_test`` - Произвести оценку модели на датасете ``test_meta_path``, не выполняя обучения.
* ``validation_metric`` - метрика, на основе которой будет определятся качество обучения модели на валидационном датасете (по умолчанию аккуратность).
* ``nlabels`` - количество меток в обучающей выборке. Если не задано, то количество меток будет вычислено автоматически на основе обучающих данных.


Пример использования настроенной модели
"""""""""""""""""""""""""""""""""""""""

Файл ``src/classif.py``:

.. code-block:: python

  #!/usr/bin/env python3

  from doc_enc.doc_encoder import DocEncoderConf
  from doc_enc.classif_doc import ClassifDoc


  conf = DocEncoderConf(model_path='/work/classif_model.pt', use_gpu=0)
  doc_encoder = ClassifDoc(conf)

  docs = [
      ['simple sentence', 'second sentence'],
      ['Sentences are already segmented'],
      ['Spam spam spam', 'Span Spam Spam'],
  ]

  result = doc_encoder.predict_docs(docs)
  print(result)



В текущей директории должна лежать настроенная модель ``classif_model.pt``.
Запуск вывода:

.. code-block:: bash

  docker run --gpus=1  --rm  -v $(pwd):/work/  -w /work semvectors/doc_enc_train:0.1.2 python src/classif.py


Настройка произвольной задачи
-----------------------------

При необходимости настроить модель под иную задачу можно взять за основу код настройки из `репозитория <https://gitlab.com/semvectors/doc_enc/-/blob/master/doc_enc/finetune_classif.py>`_.
Изменить модель ``DocClassifier`` и при необходимости ``ClassifBatchIterator``.
Предполагается, что файл с новой задачей настройки называется  ``new-finetune.py`` и лежит в папке ``src``.

.. code-block:: console

   $ docker run -v /path/to/finetune-data/:/train/ \
     --gpus=1  --rm \
     semvectors/doc_enc_train:0.1.2 \
     python src/new-finetune.py --config-path=/train/conf