Как решить конфликт argparse с флагами Jupyter в SageMaker

Ошибка «unrecognized arguments» в Jupyter/SageMaker из‑за флагов ядра. Решение для argparse: вызов parse_args("") без sys.argv, обучение остается без изменений.

Argparse часто плохо уживается с рабочими процессами на базе Jupyter. Если вы запускаете обучающий скрипт в AWS SageMaker JupyterLab и видите, что процесс Python завершился с сообщением «unrecognized arguments», значит, скорее всего, вы столкнулись с классическим конфликтом между argparse и флагами самого ядра. Ниже — краткое описание симптома и точное решение, которое сохраняет ваш CLI без переработки обучающего кода.

Как выглядит ошибка

usage: VICReg training script [-h] [--data_path DATA_PATH] [--exp-dir EXP_DIR] [--log-freq-time LOG_FREQ_TIME] [--arch ARCH] [--mlp MLP] [--epochs EPOCHS] [--batch-size BATCH_SIZE] [--base-lr BASE_LR] [--wd WD] [--sim-coeff SIM_COEFF] [--std-coeff STD_COEFF] [--cov-coeff COV_COEFF] [--num-workers NUM_WORKERS] [--device DEVICE] [--world-size WORLD_SIZE] [--local_rank LOCAL_RANK] [--dist-url DIST_URL] [--rank RANK] VICReg training script: error: unrecognized arguments: -f /home/sagemaker-user/.local/share/jupyter/runtime/kernel-299646e9-32c7-47f8-869a-72e80aa9271b.json

Фрагмент «-f …kernel…json» — показательный знак. Ядро Jupyter подмешивает свои параметры командной строки при запуске процесса, а стандартная конфигурация argparse считает их недопустимыми.

Минимальный пример, который воспроизводит проблему

Ниже — типичная настройка парсера для входной точки предобучения в стиле VICReg. Определения сами по себе корректны, но при запуске скрипта внутри блокнота или терминала JupyterLab argparse считывает аргументы ядра и падает.

import argparse
from pathlib import Path
def build_cli_spec():
    cli = argparse.ArgumentParser(
        description="Pretrain a resnet model with VICReg",
        add_help=False
    )
    # Данные
    cli.add_argument(
        "--data_path",
        default='AnnualCrop/',
        type=Path,
        help='dataset path'
    )
    # Чекпоинты
    cli.add_argument(
        "--exp-dir",
        type=Path,
        default="./exp",
        help='Path to the experiment folder, where all logs/checkpoints will be stored'
    )
    cli.add_argument(
        "--log-freq-time",
        type=int,
        default=60,
        help='Print logs to the stats.txt file every [log-freq-time] seconds'
    )
    return cli

Почему так происходит

По умолчанию argparse читает sys.argv. В JupyterLab (включая ноутбуки SageMaker) процесс Python стартует с дополнительными флагами, указывающими на активный файл ядра, что видно в ошибке как «-f /path/to/kernel-...json». Поскольку эти флаги не объявлены в вашем парсере, argparse считает их недопустимыми и завершает работу.

Решение

Заставьте argparse игнорировать аргументы процесса, передав пустую строку в parse_args. Тогда будут использоваться только заявленные значения по умолчанию или те, что вы явно передадите строкой. Остальная логика обучения не меняется.

from pathlib import Path
def run(cfg):
    # точка входа обучения (заглушка)
    pass
if __name__ == "__main__":
    cli_obj = build_cli_spec()
    opts = cli_obj.parse_args("")
    if opts.output_dir:
        Path(opts.output_dir).mkdir(parents=True, exist_ok=True)
    run(opts)

Это повторяет рабочий прием, описанный в других местах, и достаточно для запуска того же обучающего скрипта внутри SageMaker JupyterLab без того, чтобы argparse спотыкался о флаги ядра. За более подробным разбором использования argparse в блокнотах см. ссылку: https://medium.com/@data.scientist/ipython-trick-how-to-use-argparse-in-ipython-notebooks-a07423ab31fc.

Почему стоит держать это под рукой

Эксперименты с самосупервизируемым предобучением часто перемещаются между локальными скриптами и средами блокнотов. Один и тот же CLI может вести себя по‑разному только из‑за способа запуска процесса. Умение нейтрализовать внешний argv в Jupyter избавляет от проверок окружения и дублирования входных точек в кодовой базе.

Выводы

Если при запуске тренера с CLI в SageMaker JupyterLab вы видите «unrecognized arguments: -f …kernel…json», суть в том, что argparse парсит флаги самого Jupyter. Обойдите sys.argv, вызвав parse_args(""), сохраните объявленные опции и продолжайте обучение.