torch.hub

Публикация моделей

PyTorch Hub поддерживает публикацию предварительно обученных моделей (определений моделей и предварительно обученных весов) в репозитории GitHub путем добавления простого файла hubconf.py;

hubconf.py может иметь несколько точек входа. Каждая точка входа определяется как функция Python (например, предварительно обученная модель, которую вы хотите опубликовать).

  def entrypoint_name(*args, **kwargs):
      # args & kwargs are optional, for models which take positional/keyword arguments.
      ...

  dependencies = ['torch']
  from torchvision.models.resnet import resnet18 as _resnet18

  # resnet18 is the name of entrypoint
  def resnet18(pretrained=False, **kwargs):
      """ # This docstring shows up in hub.help()
      Resnet18 model
      pretrained (bool): kwargs, load pretrained weights into the model
      """
      # Call the model, load pretrained weights
      model = _resnet18(pretrained=pretrained, **kwargs)
      return model

  if pretrained:
      # For checkpoint saved in local GitHub repo, e.g. <RELATIVE_PATH_TO_CHECKPOINT>=weights/save.pth
      dirname = os.path.dirname(__file__)
      checkpoint = os.path.join(dirname, <RELATIVE_PATH_TO_CHECKPOINT>)
      state_dict = torch.load(checkpoint)
      model.load_state_dict(state_dict)

      # For checkpoint saved elsewhere
      checkpoint = 'https://download.pytorch.org/models/resnet18-5c106cde.pth'
      model.load_state_dict(torch.hub.load_state_dict_from_url(checkpoint, progress=False))

Загрузка моделей из Hub

PyTorch Hub предоставляет удобные API для просмотра всех доступных моделей в Hub с помощью torch.hub.list(), отображения строк документации и примеров с помощью torch.hub.help() и загрузки предварительно обученных моделей с помощью torch.hub.load().

torch.hub.list(github, force_reload=False, skip_validation=False, trust_repo='check', verbose=True) [исходный код]

Вывести список всех вызываемых точек входа, доступных в репозитории, указанном в github.

Параметры:

• github (str) – строка в формате “repo_owner/repo_name[:ref]” с необязательной ссылкой (тегом или веткой). Если ref не указано, предполагается, что веткой по умолчанию является main, если она существует, и master в противном случае. Пример: ‘pytorch/vision:0.10’
• force_reload (bool, optional) – следует ли удалить существующий кэш и принудительно загрузить данные заново. По умолчанию — False.
• skip_validation (bool, optional) – если False, torchhub проверит, что ветка или коммит, указанные аргументом github, действительно принадлежат владельцу репозитория. Для этого будут отправлены запросы к API GitHub; можно указать нестандартный токен GitHub, задав переменную среды GITHUB_TOKEN. По умолчанию — False.

• trust_repo (bool или str) –

  "check", True или False. Этот параметр появился в версии 1.12 и помогает гарантировать, что пользователи запускают код только из репозиториев, которым доверяют.

  • Если False, пользователю будет предложено подтвердить, что репозиторию можно доверять.
  • Если True, репозиторий будет добавлен в список доверенных и загружен без запроса явного подтверждения.
  • Если "check", репозиторий будет проверен по списку доверенных репозиториев в кэше. Если его там нет, поведение будет соответствовать параметру trust_repo=False.

  По умолчанию — "check".

• verbose (bool, optional) – если False, отключить сообщения об обращении к локальному кэшу. Обратите внимание: сообщение о первой загрузке отключить нельзя. По умолчанию — True.

Возвращает:

Доступные вызываемые точки входа

Тип возвращаемого значения:

list

Пример

>>> entrypoints = torch.hub.list("pytorch/vision", force_reload=True)

torch.hub.help(github, model, force_reload=False, skip_validation=False, trust_repo='check') [исходный код]

Показать строку документации точки входа model.

Параметры:

• github (str) – строка в формате <repo_owner/repo_name[:ref]> с необязательной ссылкой (тегом или веткой). Если ref не указано, предполагается, что веткой по умолчанию является main, если она существует, и master в противном случае. Пример: ‘pytorch/vision:0.10’
• model (str) – имя точки входа, определенной в hubconf.py репозитория
• force_reload (bool, optional) – следует ли удалить существующий кэш и принудительно загрузить данные заново. По умолчанию — False.
• skip_validation (bool, optional) – если False, torchhub проверит, что ссылка, указанная аргументом github, действительно принадлежит владельцу репозитория. Для этого будут отправлены запросы к API GitHub; можно указать нестандартный токен GitHub, задав переменную среды GITHUB_TOKEN. По умолчанию — False.

• trust_repo (bool или str) –

  "check", True или False. Этот параметр появился в версии 1.12 и помогает гарантировать, что пользователи запускают код только из репозиториев, которым доверяют.

  • Если False, пользователю будет предложено подтвердить, что репозиторию можно доверять.
  • Если True, репозиторий будет добавлен в список доверенных и загружен без запроса явного подтверждения.
  • Если "check", репозиторий будет проверен по списку доверенных репозиториев в кэше. Если его там нет, поведение будет соответствовать параметру trust_repo=False.

  По умолчанию — "check".

Пример

>>> print(torch.hub.help("pytorch/vision", "resnet18", force_reload=True))

torch.hub.load(repo_or_dir, model, *args, source='github', trust_repo='check', force_reload=False, verbose=True, skip_validation=False, **kwargs) [исходный код]

Загрузить модель из репозитория GitHub или локального каталога.

Примечание: загрузка модели — наиболее типичный вариант использования, но этот метод также можно применять для загрузки других объектов, например токенизаторов, функций потерь и т. д.

Если source — ‘github’, ожидается, что repo_or_dir будет иметь формат repo_owner/repo_name[:ref] с необязательной ссылкой (тегом или веткой).

Если source — ‘local’, ожидается, что repo_or_dir будет путем к локальному каталогу.

Параметры:

• repo_or_dir (str) – если source — ‘github’, здесь должен быть указан репозиторий GitHub в формате repo_owner/repo_name[:ref] с необязательной ссылкой (тегом или веткой), например ‘pytorch/vision:0.10’. Если ref не указано, предполагается, что веткой по умолчанию является main, если она существует, и master в противном случае. Если source — ‘local’, здесь должен быть указан путь к локальному каталогу.
• model (str) – имя вызываемого объекта (точки входа), определенного в hubconf.py репозитория или каталога.
• *args (optional) – соответствующие позиционные аргументы для вызываемого объекта model.
• source (str, optional) – ‘github’ или ‘local’. Определяет, как интерпретировать repo_or_dir. По умолчанию — ‘github’.

• trust_repo (bool или str) –

  "check", True или False. Этот параметр появился в версии 1.12 и помогает гарантировать, что пользователи запускают код только из репозиториев, которым доверяют.

  • Если False, пользователю будет предложено подтвердить, что репозиторию можно доверять.
  • Если True, репозиторий будет добавлен в список доверенных и загружен без запроса явного подтверждения.
  • Если "check", репозиторий будет проверен по списку доверенных репозиториев в кэше. Если его там нет, поведение будет соответствовать параметру trust_repo=False.

  По умолчанию — "check".

• force_reload (bool, optional) – следует ли безусловно принудительно загрузить репозиторий GitHub заново. Не действует, если source = 'local'. По умолчанию — False.
• verbose (bool, optional) – если False, отключить сообщения об обращении к локальному кэшу. Обратите внимание: сообщение о первой загрузке отключить нельзя. Не действует, если source = 'local'. По умолчанию — True.
• skip_validation (bool, optional) – если False, torchhub проверит, что ветка или коммит, указанные аргументом github, действительно принадлежат владельцу репозитория. Для этого будут отправлены запросы к API GitHub; можно указать нестандартный токен GitHub, задав переменную среды GITHUB_TOKEN. По умолчанию — False.
• **kwargs (optional) – соответствующие именованные аргументы для вызываемого объекта model.

Возвращает:

Результат вызова вызываемого объекта model с заданными *args и **kwargs.

Пример

>>> # from a github repo
>>> repo = "pytorch/vision"
>>> model = torch.hub.load(
...     repo, "resnet50", weights="ResNet50_Weights.IMAGENET1K_V1"
... )
>>> # from a local directory
>>> path = "/some/local/path/pytorch/vision"
>>> model = torch.hub.load(path, "resnet50", weights="ResNet50_Weights.DEFAULT")

torch.hub.download_url_to_file(url, dst, hash_prefix=None, progress=True) [исходный код]

Загрузить объект по указанному URL-адресу в локальный путь.

Параметры:

• url (str) – URL-адрес загружаемого объекта
• dst (str) – полный путь для сохранения объекта, например /tmp/temporary_file
• hash_prefix (str, optional) – если значение не равно None, имя загруженного файла SHA256 должно начинаться с hash_prefix. По умолчанию: None
• progress (bool, optional) – отображать ли индикатор выполнения в stderr. По умолчанию: True

Пример

>>> torch.hub.download_url_to_file(
...     "https://s3.amazonaws.com/pytorch/models/resnet18-5c106cde.pth",
...     "/tmp/temporary_file",
... )

torch.hub.load_state_dict_from_url(url, model_dir=None, map_location=None, progress=True, check_hash=False, file_name=None, weights_only=False) [исходный код]

Загружает сериализованный объект Torch по указанному URL-адресу.

Если загруженный файл является ZIP-архивом, он будет автоматически распакован.

Если объект уже находится в model_dir, он десериализуется и возвращается. Значение по умолчанию для model_dir — <hub_dir>/checkpoints, где hub_dir — каталог, возвращаемый функцией get_dir().

Параметры:

• url (str) – URL-адрес загружаемого объекта
• model_dir (str, optional) – каталог для сохранения объекта
• map_location (optional) – функция или словарь, задающие способ переназначения мест хранения (см. torch.load)
• progress (bool, optional) – отображать ли индикатор выполнения в stderr. По умолчанию: True
• check_hash (bool, optional) – если True, часть URL-адреса с именем файла должна соответствовать соглашению об именовании filename-<sha256>.ext, где <sha256> — первые восемь или более цифр хеша SHA256 содержимого файла. Хеш используется для обеспечения уникальности имен и проверки содержимого файла. По умолчанию: False
• file_name (str, optional) – имя загруженного файла. Если параметр не задан, будет использоваться имя файла из url.
• weights_only (bool, optional) – если True, будут загружены только веса, без сложных объектов, сериализованных с помощью pickle. Рекомендуется для ненадежных источников. Подробнее см. load().

Тип возвращаемого значения:

dict[str, Any]

Пример

>>> state_dict = torch.hub.load_state_dict_from_url(
...     "https://s3.amazonaws.com/pytorch/models/resnet18-5c106cde.pth"
... )