Hugging Face's logo

Hub Python Library documentation

Загрузка файлов

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Загрузка файлов

Загрузка одного файла

hf_hub_download

huggingface_hub.hf_hub_download

< >

( repo_id: strfilename: strsubfolder: str | None = Nonerepo_type: str | None = Nonerevision: str | None = Nonelibrary_name: str | None = Nonelibrary_version: str | None = Nonecache_dir: str | pathlib.Path | None = Nonelocal_dir: str | pathlib.Path | None = Noneuser_agent: dict | str | None = Noneforce_download: bool = Falseetag_timeout: float = 10token: bool | str | None = Nonelocal_files_only: bool = Falseheaders: dict[str, str] | None = Noneendpoint: str | None = Nonetqdm_class: type[tqdm.std.tqdm] | None = Nonedry_run: bool = False ) → str or DryRunFileInfo

Параметры

  • repo_id (str) — Имя пользователя или организации и имя репозитория, разделённые символом /.
  • filename (str) — Имя файла в репозитории.
  • subfolder (str, необязательный) — Необязательное значение, соответствующее папке внутри репозитория модели.
  • repo_type (str, необязательный) — установите "dataset", "space" или "kernel", если загрузка выполняется из репозитория датасета, пространства или ядра, None или "model", если загрузка выполняется из репозитория модели. По умолчанию — None.
  • revision (str, необязательный) — Необязательный идентификатор ревизии Git, который может быть именем ветки, тегом или хэшем коммита.
  • library_name (str, необязательный) — Название библиотеки, которой соответствует объект.
  • library_version (str, необязательный) — Версия библиотеки.
  • cache_dir (str, Path, необязательный) — Путь к папке, в которой хранятся кэшированные файлы.
  • local_dir (str или Path, необязательный) — Если указано, загруженный файл будет размещён в этой директории.
  • user_agent (dict, str, необязательный) — Информация о user-agent в виде словаря или строки.
  • force_download (bool, необязательный, по умолчанию False) — Следует ли скачать файл, даже если он уже есть в локальном кэше.
  • etag_timeout (float, необязательный, по умолчанию 10) — При получении ETag, сколько секунд ждать отправки данных сервером, прежде чем прервать ожидание; значение передаётся в httpx2.request.
  • token (str, bool, необязательный) — Токен, используемый для загрузки.
    • Если True, токен читается из папки конфигурации HuggingFace.
    • Если передана строка, она используется в качестве токена аутентификации.
  • local_files_only (bool, необязательный, по умолчанию False) — Если True, не загружать файл, а вернуть путь к локальному кэшированному файлу, если он существует.
  • headers (dict, необязательный) — Дополнительные заголовки, которые будут отправлены вместе с запросом.
  • endpoint (str, необязательный) — Точка входа Hub, на которую отправляется запрос. По умолчанию используется значение HF_ENDPOINT.
  • tqdm_class (tqdm, необязательный) — Если указан, переопределяет поведение полосы прогресса по умолчанию. Передаваемый аргумент должен наследоваться от tqdm.auto.tqdm или как минимум имитировать его поведение. По умолчанию используется собственная полоса прогресса HF, которую можно отключить, установив переменную окружения HF_HUB_DISABLE_PROGRESS_BARS.
  • dry_run (bool, необязательный, по умолчанию False) — Если True, выполняется тестовый прогон без фактической загрузки файла. Возвращает объект DryRunFileInfo с информацией о том, что было бы загружено.

Возвращает

str или DryRunFileInfo

  • Если dry_run=False: локальный путь к файлу или, если сеть отключена, последняя версия файла, кэшированная на диске.
  • Если dry_run=True: объект DryRunFileInfo, содержащий информацию о загрузке.

Исключения

RepositoryNotFoundError или RevisionNotFoundError или ~utils.RemoteEntryNotFoundError или LocalEntryNotFoundError или EnvironmentError или OSError или ValueError

  • RepositoryNotFoundError — Если репозиторий, из которого выполняется загрузка, не найден. Это может быть связано с тем, что он не существует, или с тем, что он установлен как private, и у вас нет к нему доступа.
  • RevisionNotFoundError — Если не удалось найти ревизию для загрузки.
  • ~utils.RemoteEntryNotFoundError — Если файл для загрузки не найден.
  • LocalEntryNotFoundError — Если сеть отключена или недоступна, а файл не найден в кэше.
  • EnvironmentError — если token=True, но токен не найден.
  • OSError — Если ETag не может быть определён.
  • ValueError — Если значение какого-либо параметра недействительно.

Загрузите указанный файл, если он ещё отсутствует в локальном кэше.

Новая структура кэшируемых файлов выглядит так:

  • Каталог кэша содержит одну подпапку для каждого repo_id (с разделением по типу репозитория)
  • внутри каждой папки репозитория:
    • refs — это список последних известных пар ревизия => commit_hash
    • blobs содержит фактические файлы (идентифицируемые по их git-sha или sha256, в зависимости от того, являются ли они файлами LFS или нет)
    • snapshots содержит одну подпапку на каждый коммит, каждый «коммит» содержит подмножество файлов, которые были разрешены на этом конкретном коммите. Имя каждого файла является символьной ссылкой на blob на этом конкретном коммите.
[  96]  .
└── [ 160]  models--julien-c--EsperBERTo-small
    ├── [ 160]  blobs
    │   ├── [321M]  403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
    │   ├── [ 398]  7cb18dc9bafbfcf74629a4b760af1b160957a83e
    │   └── [1.4K]  d7edf6bd2a681fb0175f7735299831ee1b22b812
    ├── [  96]  refs
    │   └── [  40]  main
    └── [ 128]  snapshots
        ├── [ 128]  2439f60ef33a0d46d85da5001d52aeda5b00ce9f
        │   ├── [  52]  README.md -> ../../blobs/d7edf6bd2a681fb0175f7735299831ee1b22b812
        │   └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd
        └── [ 128]  bbc77c8132af1cc5cf678da3f1ddf2de43606d48
            ├── [  52]  README.md -> ../../blobs/7cb18dc9bafbfcf74629a4b760af1b160957a83e
            └── [  76]  pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd

Если указан local_dir, структура файлов из репозитория будет воспроизведена в этом месте. При использовании этого параметра cache_dir не используется, а в корне local_dir создаётся папка .cache/huggingface/ для хранения метаданных, связанных с загруженными файлами. Хотя этот механизм менее надёжен, чем основная система кэширования, он оптимизирован для регулярного получения последней версии репозитория.

hf_hub_url

huggingface_hub.hf_hub_url

< >

( repo_id: strfilename: strsubfolder: str | None = Nonerepo_type: str | None = Nonerevision: str | None = Noneendpoint: str | None = None )

Параметры

  • repo_id (str) — Имя пространства имён (пользователя или организации) и имя репозитория, разделённые символом /.
  • filename (str) — Имя файла в репозитории.
  • subfolder (str, необязательный) — Необязательное значение, соответствующее папке внутри репозитория.
  • repo_type (str, необязательный) — установите "dataset", "space" или "kernel", если загрузка выполняется из репозитория датасета, пространства или ядра, None или "model", если загрузка выполняется из репозитория модели. По умолчанию — None.
  • revision (str, необязательный) — Необязательный идентификатор ревизии Git, который может быть именем ветки, тегом или хэшем коммита.
  • endpoint (str, необязательный) — Точка входа Hub, на которую отправляется запрос. По умолчанию используется значение HF_ENDPOINT.

Сформируйте URL файла на основе предоставленной информации.

Разрешённый адрес может быть как URL, размещённым на huggingface.co, так и ссылкой на Cloudfront (сеть доставки контента, или CDN) для больших файлов размером более нескольких МБ.

Пример:

>>> from huggingface_hub import hf_hub_url

>>> hf_hub_url(
...     repo_id="julien-c/EsperBERTo-small", filename="pytorch_model.bin"
... )
'https://huggingface.co/julien-c/EsperBERTo-small/resolve/main/pytorch_model.bin'

Примечания:

Cloudfront дублируется по всему миру, поэтому загрузка для конечного пользователя значительно быстрее (а также это снижает наши затраты на пропускную способность).

Cloudfront по умолчанию агрессивно кэширует файлы (TTL по умолчанию составляет 24 часа), однако в данном случае это не проблема, так как на huggingface.co мы реализуем систему версионирования на основе git, что означает, что файлы хранятся на S3/Cloudfront с адресацией по содержимому (то есть имя файла является его хэшем). Использование имен файлов с адресацией по содержимому гарантирует, что кэш никогда не будет устаревшим.

Что касается кэширования на стороне клиента в этой библиотеке, мы основываем наше кэширование на метке сущности объекта (ETag), которая является идентификатором конкретной версии ресурса [1]_. ETag объекта: его git-sha1, если он хранится в git, или его sha256, если он хранится в git-lfs.

Ссылки:

Скачать снимок репозитория

huggingface_hub.snapshot_download

< >

( repo_id: strrepo_type: str | None = Nonerevision: str | None = Nonecache_dir: str | pathlib.Path | None = Nonelocal_dir: str | pathlib.Path | None = Nonelibrary_name: str | None = Nonelibrary_version: str | None = Noneuser_agent: dict | str | None = Noneetag_timeout: float = 10force_download: bool = Falsetoken: bool | str | None = Nonelocal_files_only: bool = Falseallow_patterns: list[str] | str | None = Noneignore_patterns: list[str] | str | None = Nonemax_workers: int = 8tqdm_class: type[tqdm.asyncio.tqdm_asyncio] | None = Noneheaders: dict[str, str] | None = Noneendpoint: str | None = Nonedry_run: bool = False ) → str or list of DryRunFileInfo

Параметры

  • repo_id (str) — Имя пользователя или организации и имя репозитория, разделённые символом /.
  • repo_type (str, необязательный) — установите "dataset", "space" или "kernel", если загрузка выполняется из репозитория датасета, пространства или ядра, None или "model", если загрузка выполняется из репозитория модели. По умолчанию — None.
  • revision (str, необязательный) — Необязательный идентификатор ревизии Git, который может быть именем ветки, тегом или хэшем коммита.
  • cache_dir (str, Path, необязательный) — Путь к папке, в которой хранятся кэшированные файлы.
  • local_dir (str или Path, необязательный) — Если указано, загруженные файлы будут размещены в этой директории.
  • library_name (str, необязательный) — Название библиотеки, которой соответствует объект.
  • library_version (str, необязательный) — Версия библиотеки.
  • user_agent (str, dict, необязательный) — Информация о user-agent в виде словаря или строки.
  • etag_timeout (float, необязательный, по умолчанию 10) — При получении ETag, сколько секунд ждать отправки данных сервером, прежде чем прервать ожидание; значение передаётся в httpx2.request.
  • force_download (bool, необязательный, по умолчанию False) — Следует ли скачать файл, даже если он уже есть в локальном кэше.
  • token (str, bool, необязательный) — Токен, используемый для загрузки.
    • Если True, токен читается из папки конфигурации HuggingFace.
    • Если передана строка, она используется в качестве токена аутентификации.
  • headers (dict, необязательный) — Дополнительные заголовки, которые нужно включить в запрос. Эти заголовки имеют приоритет над остальными.
  • endpoint (str, необязательный) — Точка входа Hub, на которую отправляется запрос. По умолчанию используется значение HF_ENDPOINT.
  • local_files_only (bool, необязательный, по умолчанию False) — Если True, не загружать файлы, даже если их нет в cache_dir или local_dir.
  • allow_patterns (list[str] или str, необязательный) — Если указано, загружаются только файлы, соответствующие хотя бы одному шаблону.
  • ignore_patterns (list[str] или str, необязательный) — Если указано, файлы, соответствующие любому из шаблонов, не загружаются.
  • max_workers (int, необязательный) — Количество параллельных потоков для загрузки файлов (1 поток = 1 файл). По умолчанию: 8.
  • tqdm_class (tqdm, необязательный) — Если указан, переопределяет поведение полосы прогресса по умолчанию. Передаваемый аргумент должен наследоваться от tqdm.auto.tqdm или как минимум имитировать его поведение. Обратите внимание, что tqdm_class не передается для каждой отдельной загрузки. По умолчанию используется собственная полоса прогресса HF, которую можно отключить, установив переменную окружения HF_HUB_DISABLE_PROGRESS_BARS.
  • dry_run (bool, необязательный, по умолчанию False) — Если True, выполняется тестовый прогон без фактической загрузки файлов. Возвращает список объектов DryRunFileInfo с информацией о том, какие файлы были бы загружены.

Возвращает

str или список DryRunFileInfo

  • Если dry_run=False: локальный путь к снимку.
  • Если dry_run=True: список объектов DryRunFileInfo с информацией о загрузке.

Исключения

RepositoryNotFoundError или RevisionNotFoundError или IncompleteSnapshotError или EnvironmentError или OSError или ValueError

  • RepositoryNotFoundError — Если репозиторий, из которого выполняется загрузка, не найден. Это может быть связано с тем, что он не существует или с тем, что он установлен как private, и у вас нет к нему доступа.
  • RevisionNotFoundError — Если не удалось найти ревизию для загрузки.
  • IncompleteSnapshotError — Если Hub недоступен (офлайн, проблема с подключением или local_files_only=True), а в кэшированном снимке отсутствуют некоторые из запрошенных файлов.
  • EnvironmentError — если token=True и токен не найден.
  • OSError — если ETag не может быть определён.
  • ValueError — Если значение какого-либо параметра недействительно.

Скачайте файлы репозитория.

Скачайте весь снимок файлов репозитория с указанной ревизией. Это полезно, когда вам нужны все файлы из репозитория, потому что вы не знаете заранее, какие именно из них понадобятся a priori. Все файлы размещаются во вложенной папке, чтобы сохранить их путь и имя файла относительно этой папки. Вы также можете отфильтровать файлы для скачивания с помощью allow_patterns и ignore_patterns.

Если указан local_dir, структура файлов из репозитория будет воспроизведена в этом месте. При использовании этого параметра cache_dir не используется, а в корне local_dir создаётся папка .cache/huggingface/ для хранения метаданных, связанных с загруженными файлами. Хотя этот механизм менее надёжен, чем основная система кэширования, он оптимизирован для регулярного получения последней версии репозитория.

Альтернативный вариант — клонировать репозиторий, но для этого необходимо установить и правильно настроить git и git-lfs. Кроме того, при клонировании репозитория с помощью git невозможно отфильтровать, какие именно файлы нужно скачать.

Чтение кэшированного дерева репозитория

huggingface_hub.get_cached_repo_tree

< >

( repo_id: strrepo_type: str | None = Nonerevision: str | None = Nonecache_dir: str | pathlib.Path | None = Nonelocal_dir: str | pathlib.Path | None = None ) → list[RepoFile]

Параметры

  • repo_id (str) — Имя пользователя или организации и имя репозитория, разделённые символом /.
  • repo_type (str, необязательный) — Установите "dataset", "space" или "kernel", если вы перечисляете элементы из репозитория датасета, пространства или ядра, None или "model", если вы перечисляете элементы из репозитория модели. По умолчанию — None.
  • revision (str, необязательный) — Необязательный идентификатор ревизии Git, который может быть именем ветки, тегом или хэшем коммита. По умолчанию используется ветка по умолчанию. Имена веток/тегов разрешаются в хэш коммита с использованием локального кэша (refs/).
  • cache_dir (str, Path, необязательный) — Путь к папке, в которой хранятся кэшированные файлы. По умолчанию используется значение HF_HUB_CACHE.
  • local_dir (str или Path, необязательный) — Если указано, читать список дерева, закэшированный при загрузке в local_dir (из local_dir/.cache/huggingface/), вместо основного кэша. Ревизии веток/тегов по-прежнему решаются в хэш коммита с использованием основного кэша (cache_dir).

Возвращает

list[RepoFile]

Список объектов RepoFile, закэшированных для этой ревизии.

Исключения

CachedRepoTreeNotFoundError

  • CachedRepoTreeNotFoundError — Если для запрошенной ревизии не кэширован список дерева (например, репозиторий никогда не скачивался в этой ревизии).

Возвращает кэшированный список файлов репозитория для указанной ревизии без обращения к сети.

Список дерева представляет собой набор файлов (с метаданными для загрузки) репозитория на определённом коммите. Он формируется на диске как побочный эффект вызова snapshot_download() (см. файлы кэша trees/<commit_hash>.json) и используется для пропуска сетевых запросов при последующих загрузках. Данная функция предоставляет прямой доступ к этому кэшу.

Если вам нужен текущий список файлов в репозитории на Hub, используйте list_repo_tree().

Пример:

>>> from huggingface_hub import get_cached_repo_tree
>>> files = get_cached_repo_tree("openai-community/gpt2")
>>> [f.path for f in files]
['.gitattributes', 'config.json', 'model.safetensors', ...]

Разрешить ревизию

Разрешите имя ветки/тега в хеш коммита один раз, затем передавайте результат, чтобы зафиксировать все загрузки на одном и том же коммите. См. HfApi.resolve_revision() и руководство по системе кэширования.

ResolvedRevision

класс huggingface_hub.ResolvedRevision

< >

( resolved: strinitial: str | None = Nonerepo_id: str | None = Nonerepo_type: str | None = None )

Параметры

  • initial (str или None) — Ревизия, изначально запрошенная пользователем. Если None, строковое значение по умолчанию равно "main".
  • resolved (str) — Хеш коммита, к которому разрешается initial.

Ревизия git, которая уже была разрешена в хеш коммита.

ResolvedRevision является подклассом str, поэтому его можно передавать в любой метод huggingface_hub, принимающий аргумент revision. Его строковое значение — это исходно запрошенная пользователем ревизия (например, "main", "refs/pr/4"), что делает URL и сообщения об ошибках читаемыми, тогда как .resolved содержит хеш коммита, на который она указывает.

Экземпляры создаются с помощью HfApi.resolve_revision(), который также кэширует сопоставление revision -> commit hash в локальном кэше (папка refs/).

Хеш коммита имеет значение только для того репозитория, относительно которого он был разрешён, поэтому экземпляр также запоминает этот репозиторий. Повторное разрешение для другого репозитория не является ошибкой: снова разрешается изначально запрошенная ревизия (см. HfApi.resolve_revision()).

Пример:

>>> from huggingface_hub import resolve_revision
>>> revision = resolve_revision("openai-community/gpt2")
>>> revision
ResolvedRevision(initial=None, resolved='607a30d783dfa663caf39e06633721c8d4cfcd7e')
>>> revision == "main"  # it's a string
True
>>> revision.resolved
'607a30d783dfa663caf39e06633721c8d4cfcd7e'

Получить метаданные файла

get_hf_file_metadata

huggingface_hub.get_hf_file_metadata

< >

( url: strtoken: bool | str | None = Nonetimeout: float | None = 10library_name: str | None = Nonelibrary_version: str | None = Noneuser_agent: dict | str | None = Noneheaders: dict[str, str] | None = Noneendpoint: str | None = Noneretry_on_errors: bool = False )

Параметры

  • url (str) — URL файла, например, возвращаемый hf_hub_url().
  • token (str или bool, необязательный) — Токен, используемый для загрузки. Если True, токен читается из папки конфигурации HuggingFace. Если False или None, токен не предоставляется. Если строка, она используется как токен аутентификации.
    • Если True, токен читается из папки конфигурации HuggingFace.
    • Если False или None, то токен не предоставляется.
    • Если передана строка, она используется в качестве токена аутентификации.
  • timeout (float, необязательный, по умолчанию 10) — Сколько секунд ждать отправки метаданных сервером, прежде чем прервать ожидание.
  • library_name (str, необязательный) — Название библиотеки, которой соответствует объект.
  • library_version (str, необязательный) — Версия библиотеки.
  • user_agent (dict, str, необязательный) — Информация о user-agent в виде словаря или строки.
  • headers (dict, необязательный) — Дополнительные заголовки, которые будут отправлены вместе с запросом.
  • endpoint (str, необязательный) — Endpoint Hub. По умолчанию https://huggingface.co.
  • retry_on_errors (bool, необязательный, по умолчанию False) — Повторять ли попытки при ошибках (429, 5xx, таймаут, сетевые ошибки). Если False, повторные попытки не выполняются для быстрого перехода к локальному кэшу.

Получить метаданные файла, версионируемого на Hub, для заданного URL.

HfFileMetadata

класс huggingface_hub.HfFileMetadata

< >

( commit_hash: str | Noneetag: str | Nonelocation: strsize: int | Nonexet_file_data: huggingface_hub.utils._xet.XetFileData | None )

Параметры

  • commit_hash (str, необязательный) — commit_hash, связанный с файлом.
  • etag (str, необязательный) — Etag файла на сервере.
  • location (str) — Место для загрузки файла. Может быть URL Hub или нет (CDN).
  • size (size) — Размер файла. Для файла LFS содержит размер фактического файла LFS, а не указателя.
  • xet_file_data (XetFileData, необязательный) — Информация Xet для файла. Задается только в том случае, если файл хранится в хранилище Xet.

Структура данных, содержащая информацию о версии файла, размещенного на Hub.

Возвращается get_hf_file_metadata() на основе URL.

Кэширование

Методы, показанные выше, предназначены для работы с системой кэширования, которая предотвращает повторную загрузку файлов. Система кэширования была обновлена в v0.8.0 и стала центральной системой кэширования, общей для всех библиотек, зависящих от Hub.

Ознакомьтесь с руководством по системе кэширования, чтобы получить подробное описание кэширования на HF.

Update on GitHub

←CLI Миксины и методы сериализации→