Как внести свой вклад в ESPnet

1. Что можно сделать

Если вы хотите внести свой вклад в ESPnet, ваши действия будут относиться к одной из трёх категорий: основные функции, небольшие обновления и рецепты.

1.1 Основные функции

Если вы хотите предложить новую функцию, пожалуйста, сначала создайте новый выпуск с тегом Feature request или напрямую свяжитесь с Синдзи Ватанабэ shinjiw@ieee.org или другими основными разработчиками. Каждая реализация и дизайн функции должны обсуждаться и модифицироваться в соответствии с текущими и будущими работами. Вы можете найти текущие основные планы развития на https://github.com/espnet/espnet/milestones или на https://github.com/espnet/espnet/issues (закреплённые выпуски).

1.2 Небольшие обновления (небольшая функция, исправление ошибки)

Если вы хотите предложить небольшую функцию, обновить существующую небольшую функцию или исправить ошибку, пожалуйста, сначала ознакомьтесь с существующими выпусками и/или запросами на вытягивание. Выберите выпуск и прокомментируйте задачу, над которой вы хотите работать.

Если вам нужна помощь или дополнительная информация для предложения функции, вы можете создать новый выпуск с тегом Discussion и спросить членов ESPnet.

1.3 Рецепты

ESPnet предоставляет и поддерживает множество примеров сценариев, называемых рецептами, демонстрирующих, как использовать инструментарий. Рецепты для ESPnet1 находятся в каталоге egs, а рецепты для ESPnet2 — в каталоге egs2. Как и в Kaldi, каждый подкаталог egs и egs2 соответствует корпусу, для которого у нас есть примеры сценариев.

1.3.1 Рецепты ESPnet1

Рецепты ESPnet1 (egs/X) следуют соглашению от Kaldi и могут полагаться на несколько утилит, доступных в Kaldi. Поэтому перенос нового рецепта из Kaldi в ESPnet является естественным, и пользователь может обратиться к port-kaldi-recipe и другим существующим рецептам для новых дополнений. Для архитектуры рецептов в стиле Kaldi обратитесь к Prepare-Kaldi-Style-Directory.

Для каждого рецепта мы просим вас предоставить результаты экспериментов, информацию об окружающей среде и модели. Для воспроизводимости также может быть добавлена ссылка для загрузки предварительно обученной модели. Вся эта информация должна быть записана в файл Markdown с именем RESULTS.md, который находится в корне рецепта. Вы можете обратиться к tedlium2-example для примера.

Чтобы создать RESULTS.md для рецепта, выполните следующие инструкции:

• Выполните ~/espnet/utils/show_result.sh в корне рецепта (где находится run.sh). Вы получите информацию о среде и результаты оценки для каждого эксперимента в формате Markdown. Отсюда вы можете скопировать или перенаправить текст вывода в RESULTS.md.
• Выполните ~/espnet/utils/pack_model.sh в корне рецепта, чтобы создать упакованную модель ESPnet под названием model.tar.gz и получить информацию о модели. Выполнение утилиты без аргументов даст вам ожидаемые аргументы.
• Добавьте информацию о модели в RESULTS.md и ссылку на модель, если вы используете частное веб-хранилище. Если у вас нет частного веб-хранилища, обратитесь к Синдзи Ватанабэ shinjiw@ieee.org, чтобы получить доступ к хранилищу ESPnet.

1.3.2 Рецепты ESPnet2

Рецептам ESPnet2 соответствуют egs2. В ESPnet2 применяется новая парадигма без зависимостей от двоичных файлов Kaldi, что делает его более лёгким и обобщённым. В случае ESPnet2 мы не рекомендуем подготавливать этапы рецепта для каждого корпуса, но предлагаем использовать общие конвейеры, которые мы предоставили в asr.sh, tts.sh и enh.sh. Для получения подробной информации о создании рецептов ESPnet2 обратитесь к egs2-readme.

Общий конвейер рецептов ESPnet2 позаботится о генерации RESULTS.md, упаковке модели и загрузке. Модели ESPnet2 поддерживаются на Hugging Face и Zenodo (устарело). Вы также можете обратиться к документу по адресу https://github.com/espnet/espnet_model_zoo. Чтобы загрузить свою модель, вам нужно... first (This is currently deprecated, uploading to Huggingface Hub is preferred):

1. Зарегистрируйтесь на Zenodo: https://zenodo.org/.
2. Создайте токен доступа: https://zenodo.org/account/settings/applications/tokens/new/.
3. Настройте окружение: % export ACCESS_TOKEN="<ваш токен>".

Чтобы перенести модели с Zenodo с помощью Hugging Face Hub, выполните следующие шаги:

1. Создайте аккаунт на Hugging Face — https://huggingface.co/.
2. Подайте заявку на добавление в организацию espnet — https://huggingface.co/espnet.
3. Перейдите в egs2/RECIPE/* и запустите ./scripts/utils/upload_models_to_hub.sh "ZENODO_MODEL_NAME".

Для загрузки моделей с использованием Huggingface-cli выполните следующие действия: Вы также можете обратиться к https://huggingface.co/docs/transformers/model_sharing:

1. Создайте аккаунт на Hugging Face — https://huggingface.co/.
2. Подайте заявку на добавление в организацию espnet — https://huggingface.co/espnet.
3. Запустите команду huggingface-cli login (на этом шаге вы можете получить запрос на токен в разделе настройки > Токены доступа > токен espnet).
4. Выполните команду huggingface-cli repo create your-model-name --organization espnet.
5. Выполните git clone https://huggingface.co/username/your-model-name (клонируйте это вне ESPNet, чтобы избежать проблем, так как это репозиторий git).
6. Перейдите в каталог your-model-name.
7. Установите git LFS с помощью команды git lfs install.
8. Скопируйте содержимое из каталога exp рецепта в этот каталог (проверьте другие модели аналогичных задач в ESPNet, чтобы подтвердить структуру вашего каталога).
9. Добавьте файлы с помощью команды git add ..
10. Зафиксируйте изменения с помощью команды git commit -m "Add model files".
11. Отправьте изменения командой git push.
12. Проверьте, успешно ли работает демонстрационный вывод на HF, чтобы убедиться в успешной загрузке.

1.3.3 Дополнительные требования для нового рецепта

• Общие/общие файлы и каталоги, такие как utils, steps, asr.sh и т. д., должны быть связаны с помощью символической ссылки (например, ln -s <source-path> <target-path>). Пожалуйста, обратитесь к существующим рецептам, если вы не знаете, какие файлы/каталоги являются общими. Обратите внимание, что в espnet2 некоторые из них автоматически генерируются с помощью https://github.com/espnet/espnet/blob/master/egs2/TEMPLATE/asr1/setup.sh.
• Конфигурации обучения и декодирования по умолчанию (то есть конфигурация по умолчанию в run.sh) должны называться соответственно train.yaml и decode.yaml и помещаться в conf/. Дополнительные или альтернативные конфигурации должны помещаться в conf/tuning/ и именоваться в соответствии с их различиями.
• Если предлагается рецепт для нового корпуса, вы должны добавить его название и информацию по адресу: https://github.com/espnet/espnet/blob/master/egs/README.md, если это рецепт ESPnet1, или https://github.com/espnet/espnet/blob/master/egs2/README.md + db.sh, если это рецепт ESPnet2.

1.3.4 Контрольный список перед отправкой PR на основе рецепта

• Будьте осторожны с названием рецепта. Рекомендуется следовать соглашениям об именах других рецептов.
• Общие/общие файлы связаны с символической ссылкой (см. раздел 1.3.3).
• Настройки кластера должны быть установлены как по умолчанию (например, cmd.sh conf/slurm.conf conf/queue.conf conf/pbs.conf).
• Обновите egs/README.md или egs2/README.md соответствующими рецептами.
• Добавьте соответствующую запись в egs2/TEMPLATE/db.sh для нового корпуса.
• Постарайтесь упростить конфигурации моделей. Мы рекомендуем иметь только лучшую конфигурацию для начала работы с рецептом. Также следуйте правилу по умолчанию, определённому в разделе 1.3.3.
• Большая метаинформация (например, список ключевых слов) для корпуса должна храниться в другом месте, а не в самом рецепте.
• Также рекомендуется включать результаты и предварительно обученные модели вместе с рецептом. Обратите внимание, что мы рекомендуем пользователям использовать последние версии black и isort для форматирования. Однако эти форматы автоматически выполняются pre-commit.ci и больше не являются обязательными.

2 Pull Request

Если ваша предложенная функция или исправление ошибки готовы, пожалуйста, откройте запрос на вытягивание (PR) по адресу https://github.com/espnet/espnet или используйте кнопку «Pull Request» в вашем разветвлённом репозитории. Если вы не знакомы с процессом, пожалуйста, обратитесь к следующим руководствам:

• http://stackoverflow.com/questions/14680711/how-to-do-a-github-pull-request
• https://help.github.com/articles/creating-a-pull-request/

3 Version policy and development branches

После... ### 4. Модульное тестирование

Модульное тестирование ESPnet находится в папке test/. Вы можете установить дополнительные пакеты для тестирования следующим образом:

$ cd <espnet_root>
$ . ./tools/activate_python.sh
$ pip install -e ".[test]"

Чтобы тщательно протестировать различные модули, необходимо установить несколько модулей и инструментов. Мы рекомендуем вам ознакомиться с содержимым install.sh, так как он включает все модули и библиотеки, необходимые для проверки CI.

4.1 Python

Затем вы можете запустить весь набор тестов с помощью pytest с coverage с помощью команд:

./ci/test_python_espnet1.sh
./ci/test_python_espnet2.sh

Вот несколько полезных советов при использовании pytest:

• Новый тестовый файл должен быть помещён в каталог test/ и назван test_xxx.py. Каждый метод в тестовом файле должен иметь формат def test_yyy(...). Pytest автоматически найдёт и протестирует их.
• Мы рекомендуем добавлять несколько небольших тестовых файлов вместо того, чтобы группировать их в одном большом файле (например, test_e2e_xxx.py). Технически, тестовый файл должен охватывать методы только из одного файла (например, test_transformer_utils.py, чтобы протестировать transformer_utils.py).
• Чтобы отслеживать покрытие тестами и избегать дублирования тестов, мы рекомендуем использовать pytest --cov-report term-missing <test_file|dir>, чтобы выделить покрытые и пропущенные строки. Для получения более подробной информации обратитесь к coverage-test.
• Мы ограничиваем время выполнения теста до 2,0 секунд (см.: pytest-timeouts) для каждого испытания. Поэтому мы рекомендуем использовать небольшие параметры модели и избегать динамического импорта, доступа к файлам и ненужных циклов. Если модульному тесту требуется больше времени на выполнение, вы можете аннотировать свой тест с @pytest.mark.execution_timeout(sec).
• Для инициализации теста (параметры, модули и т. д.) вы можете использовать фикстуры pytest. Обратитесь к pytest fixtures для получения дополнительной информации.

Кроме того, пожалуйста, следуйте PEP 8 для стиля кодирования и Google's convention for docstrings.

4.2 Скрипты Bash

Вы также можете протестировать скрипты в utils с помощью bats-core и shellcheck.

Для тестирования:

./ci/test_shell_espnet1.sh
./ci/test_shell_espnet2.sh

5. Интеграционное тестирование

Напишите новые интеграционные тесты в ci/test_integration_espnet1.sh или ci/test_integration_espnet2.sh, когда вы добавляете новые функции в espnet/bin или espnet2/bin, соответственно. Они используют наш наименьший набор данных egs/mini_an4 или egs2/mini_an4, чтобы протестировать run.sh. Не вызывайте python напрямую в интеграционных тестах. Вместо этого используйте coverage run --append в качестве интерпретатора Python. В частности, run.sh должен поддерживать --python ${python}, чтобы вызывать пользовательский интерпретатор.

# ci/test_integration_espnet{1,2}.sh

python="coverage run --append"

cd egs/mini_an4/your_task
./run.sh --python "${python}"

5.1 Конфигурационные файлы

• setup.cfg настраивает pytest, black и flake8.
• .github/workflows настраивает Github Actions (модульные тесты, интеграционные тесты).
• codecov.yml настраивает CodeCov (покрытие кода).

5.2 Интеграционное тестирование локально (Github Actions локально)

Вы можете проверить, соответствует ли ваш PR интеграционным тестам, перед отправкой нового обновления с помощью act. 5.2.1 Установка

Чтобы выполнить действие:

1. Сначала необходимо установить Docker на локальный ПК. Не забудьте авторизоваться в Docker с помощью команды docker login.

2. Установите Github CLI. Инструкции будут меняться в зависимости от вашей ОС. Для Linux вы можете использовать официальные источники для установки соответствующего пакета.

3. Наконец, установите act через менеджеры пакетов или используя Github CLI. Для Linux можно использовать команду: gh extension install https://github.com/nektos/gh-act

5.2.2 Использование

В командной консоли:

cd <root_dir_espnet_clone>  # перейдите в корневой каталог вашего клона
gh act

Программа начнёт выполнять все тесты CI, которые будут выполняться на сервере GitHub Action.

Для конкретных заданий/рабочих процессов можно использовать:

# Для заданий:
gh act -j <jobID>  # Где jobID — это строка.

# Для рабочих процессов:
gh act -W <workflowID>
gh act -W .github/workflows/<filename>.yml

Список доступных jobID/workflowID можно получить с помощью команды: gh act -l. Список файлов рабочих процессов можно получить командой ls .github/workflows.

6 Создание новых инструментов

Вы можете разместить свои новые инструменты в: — espnet/bin или espnet2/bin: тяжёлые и большие (например, связанные с нейронными сетями) основные инструменты. — utils: лёгкие, автономные скрипты Python/Bash.

Для скриптов utils не забудьте добавить сообщения помощи и тестовые скрипты в test_utils.

6.1 Руководство по инструментам Python

Чтобы создать документацию, не забудьте использовать def get_parser(): -> ArgumentParser в основном файле.

#!/usr/bin/env python3
# Copyright XXX
#  Apache 2.0  (http://www.apache.org/licenses/LICENSE-2.0)
import argparse

# NOTE: do not forget this
def get_parser():
    parser = argparse.ArgumentParser(
        description="awsome tool",  # DO NOT forget this
    )
    ...
    return parser

if __name__ == '__main__':
    args = get_parser().parse_args()
    ...

6.2 Руководство по инструментам Bash

Чтобы создать документацию, поддержите --help, чтобы показать её использование. Если вы используете utils/parse_option.sh Kaldi, определите help_message="Usage: $0 ...".

7 Создание документации

См. doc.

8 При сбое CI

Github Actions

1. Прочитайте журнал из PR-проверок > подробности.

8.2 Codecov

1. Напишите больше тестов, чтобы увеличить покрытие.
2. Объясните рецензентам, почему вы не можете увеличить покрытие.