Hugging Face's logo

Hub Python Library documentation

API файловой системы

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

API файловой системы

Класс HfFileSystem предоставляет интерфейс для работы с файлами в стиле Python для Hugging Face Hub на основе fsspec.

HfFileSystem

HfFileSystem основана на fsspec, поэтому она совместима с большинством API, которые предоставляет эта библиотека. Подробнее см. в нашем руководстве и в справочнике API fsspec.

класс huggingface_hub.HfFileSystem

< >

( *args**kwargs )

Параметры

  • endpoint (str, необязательный) — Endpoint Hub. По умолчанию https://huggingface.co.
  • token (bool or str, необязательный) — Действительный токен доступа пользователя (строка). По умолчанию используется локально сохранённый токен, что является рекомендуемым способом аутентификации (см. https://huggingface.co/docs/huggingface_hub/quick-start#authentication). Чтобы отключить аутентификацию, передайте False.
  • block_size (int, необязательный) — Размер блока для чтения и записи файлов.
  • expand_info (bool, необязательный) — Определяет, следует ли расширять информацию о файлах.
  • max_workers (int, необязательный) — Максимальное количество одновременных запросов, используемых для параллельного получения списка содержимого больших каталогов (см. find()). По умолчанию равно 16. Установите значение 1, чтобы отключить параллельное получение списков.
  • live_follow (bool, необязательный) — Определяет, следует ли за изменениями файлов в бакетах по мере их появления на Hub, чтобы кэшированные списки оставались актуальными без ручных вызовов HfFileSystem.invalidate_cache(). При включении этого параметра получение списка бакета открывает фоновое соединение с потоком событий Hub для данного бакета. Не влияет на репозитории моделей, датасетов и пространств (Hub не предоставляет изменения для них).
  • **storage_options (dict, необязательный) — Дополнительные параметры для файловой системы. См. документацию fsspec.

Доступ к удалённому репозиторию Hugging Face Hub как к локальной файловой системе.

HfFileSystem обеспечивает совместимость с fsspec, что полезно для библиотек, требующих её (например, для прямого чтения наборов данных Hugging Face с помощью pandas). Однако этот слой совместимости вносит дополнительные накладные расходы. Для лучшей производительности и надёжности рекомендуется по возможности использовать методы HfApi.

Файловая система поддерживает пути для протокола hf://, который следует этим схемам URL:

  • Репозитории моделей, наборов данных и Spaces:
hf://<repo-id>[@<revision>]/<path/in/repo>
hf://datasets/<repo-id>[@<revision>]/<path/in/repo>
hf://spaces/<repo-id>[@<revision>]/<path/in/repo>
  • Бакеты (универсальное хранилище):
hf://buckets/<bucket-id>/<path/in/bucket>

Примечание: при использовании HfFileSystem напрямую указание префикса протокола hf:// в путях является необязательным.

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

>>> from huggingface_hub import hffs

>>> # List files
>>> hffs.glob("my-username/my-model/*.bin")
['my-username/my-model/pytorch_model.bin']
>>> hffs.ls("datasets/my-username/my-dataset", detail=False)
['datasets/my-username/my-dataset/.gitattributes', 'datasets/my-username/my-dataset/README.md', 'datasets/my-username/my-dataset/data.json']

>>> # Read/write files
>>> with hffs.open("my-username/my-model/pytorch_model.bin") as f:
...     data = f.read()
>>> with hffs.open("my-username/my-model/pytorch_model.bin", "wb") as f:
...     f.write(data)

Укажите токен для аутентификации:

>>> from huggingface_hub import HfFileSystem
>>> hffs = HfFileSystem(token=token)

cp_file

< >

( path1: strpath2: strrevision: str | None = None**kwargs )

Параметры

  • path1 (str) — Исходный путь для копирования.
  • path2 (str) — Путь назначения для копирования.
  • revision (str, необязательный) — Git-ревизия, из которой выполняется копирование.

Скопируйте файл внутри репозитория, между репозиториями или в бакет.

Примечание: по возможности используйте HfApi.upload_file() для лучшей производительности.

существует

< >

( path**kwargs ) → bool

Параметры

  • path (str) — Путь для проверки.

Возвращает

bool

True, если файл существует, иначе False.

Проверьте, существует ли файл.

Для получения подробной информации обратитесь к документации fsspec.

Примечание: по возможности используйте HfApi.file_exists() для лучшей производительности.

find

< >

( path: strmaxdepth: int | None = Nonewithdirs: bool = Falsedetail: bool = Falserefresh: bool = Falserevision: str | None = None**kwargs ) → Union[list[str], dict[str, dict[str, Any]]]

Параметры

  • path (str) — Корневой путь для получения списка файлов.
  • maxdepth (int, необязательный) — Максимальная глубина, на которую следует спускаться в подкаталоги.
  • withdirs (bool, необязательный) — Включать пути к каталогам в вывод. По умолчанию False.
  • detail (bool, необязательный) — Если True, возвращает словарь, сопоставляющий пути с информацией о файлах. По умолчанию False.
  • refresh (bool, необязательный) — Если True, обходит кэш и загружает последние данные. По умолчанию False.
  • revision (str, необязательный) — Git-ревизия, из которой нужно получить список.

Возвращает

Union[list[str], dict[str, dict[str, Any]]]

Список путей или словарь с информацией о файлах.

Список всех файлов ниже по пути.

Для получения подробной информации обратитесь к документации fsspec.

Крупные репозитории перечисляются по каталогам параллельно, чтобы обойти пагинацию на основе курсора в эндпоинте tree Hub. Настройте это с помощью аргумента max_workers класса HfFileSystem.

get_file

< >

( rpathlpath = Nonecallback = <fsspec.callbacks.NoOpCallback object at 0x7f9673955c90>outfile = None**kwargs )

Параметры

  • rpath (str) — Удалённый путь для загрузки.
  • lpath (str, необязательный) — Локальный путь для загрузки. Можно опустить, если указан outfile.
  • callback (Callback, необязательный) — Необязательный callback для отслеживания прогресса загрузки. По умолчанию callback не используется.
  • outfile (IO, необязательный) — Необязательный объект, похожий на файл, для записи. Если указан, lpath игнорируется.

Копирование одного удалённого файла на локальный.

Примечание: по возможности используйте HfApi.hf_hub_download() или HfApi.download_bucket_files для лучшей производительности.

glob

< >

( path: strmaxdepth: int | None = None**kwargs ) → list[str]

Параметры

  • path (str) — Шаблон пути для сопоставления.
  • maxdepth (int, необязательный) — Максимальная глубина, на которую следует спускаться в каталоги. По умолчанию ограничение отсутствует.

Возвращает

list[str]

Список путей, соответствующих шаблону.

Найдите файлы с помощью glob-сопоставления.

Для получения подробной информации обратитесь к документации fsspec.

информация

< >

( path: strrefresh: bool = Falserevision: str | None = None**kwargs ) → dict[str, Any]

Параметры

  • path (str) — Путь, для которого нужно получить информацию.
  • refresh (bool, необязательный) — Если True, обходит кэш и загружает последние данные. По умолчанию False.
  • revision (str, необязательный) — Git-ревизия, из которой нужно получить информацию.

Возвращает

dict[str, Any]

Словарь, содержащий информацию о файле (тип, размер, сведения о коммите и т. д.).

Получить информацию о файле или каталоге.

Для получения подробной информации обратитесь к документации fsspec.

Примечание: по возможности используйте HfApi.get_paths_info() или HfApi.repo_info() для лучшей производительности (или HfApi.get_bucket_paths_info() или HfApi.bucket_info() для бакетов)

invalidate_cache

< >

( path: str | None = None )

Параметры

  • path (str, необязательный) — Путь для очистки из кэша. Если не указан, очищается весь кэш.

Очистить кэш для указанного пути.

Для получения подробной информации обратитесь к документации fsspec.

isdir

< >

( path ) → bool

Параметры

  • path (str) — Путь для проверки.

Возвращает

bool

True, если path является каталогом, иначе False.

Проверка, является ли путь каталогом.

Для получения подробной информации обратитесь к документации fsspec.

isfile

< >

( path ) → bool

Параметры

  • path (str) — Путь для проверки.

Возвращает

bool

True, если path является файлом, иначе False.

Проверка, является ли путь файлом.

Для получения подробной информации обратитесь к документации fsspec.

ls

< >

( path: strdetail: bool = Truerefresh: bool = Falserevision: str | None = None**kwargs ) → list[Union[str, dict[str, Any]]]

Параметры

  • path (str) — Путь к каталогу.
  • detail (bool, необязательный) — Если True, возвращает список словарей с информацией о файлах. Если False, возвращает список путей к файлам. По умолчанию True.
  • refresh (bool, необязательный) — Если True, обходит кэш и загружает последние данные. По умолчанию False.
  • revision (str, необязательный) — Git-ревизия, из которой нужно получить список.

Возвращает

list[Union[str, dict[str, Any]]]

Список путей к файлам (если detail=False) или список словарей с информацией о файлах (если detail=True).

Просмотрите содержимое каталога.

Для получения подробной информации обратитесь к документации fsspec.

Примечание: по возможности используйте HfApi.list_repo_tree() для лучшей производительности.

изменено

< >

( path: str**kwargs ) → datetime

Параметры

  • path (str) — Путь к файлу.

Возвращает

datetime

Время последнего изменения файла.

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

Для получения подробной информации обратитесь к документации fsspec.

resolve_path

< >

( path: strrevision: str | None = None ) → HfFileSystemResolvedPath

Параметры

  • path (str) — Путь для разрешения.
  • revision (str, необязательный) — Ревизия репозитория для разрешения. По умолчанию используется ревизия, указанная в пути.

Возвращает

HfFileSystemResolvedPath

Информация о разрешённом пути, содержащая repo_type, repo_id, revision и path_in_repo.

Исключения

ValueError или NotImplementedError

  • ValueError — если в path содержится противоречивая информация о ревизии.
  • NotImplementedError — при попытке получить список репозиториев.

Разобрать путь файловой системы Hugging Face на его компоненты.

rm

< >

( path: strrecursive: bool = Falsemaxdepth: int | None = Nonerevision: str | None = None**kwargs )

Параметры

  • path (str) — Путь для удаления.
  • recursive (bool, необязательный) — Если True, удаляет каталог и всё его содержимое. По умолчанию False.
  • maxdepth (int, необязательный) — Максимальное количество подкаталогов, которые нужно посетить при рекурсивном удалении.
  • revision (str, необязательный) — Git-ревизия, от которой выполняется удаление.

Удаление файлов из репозитория.

Для получения подробной информации обратитесь к документации fsspec.

Примечание: По возможности используйте HfApi.delete_file() для лучшей производительности.

url

< >

( path: str ) → str

Параметры

  • path (str) — Путь, для которого нужно получить URL.

Возвращает

str

HTTP URL для доступа к файлу или каталогу на Hub.

Получите HTTP-URL для указанного пути.

walk

< >

( path: str*args**kwargs ) → Iterator[tuple[str, list[str], list[str]]]

Параметры

  • path (str) — Корневой путь для получения списка файлов.

Возвращает

Iterator[tuple[str, list[str], list[str]]]

Итератор кортежей (путь, список имён каталогов, список имён файлов).

Возвращает все файлы ниже указанного пути.

Для получения подробной информации обратитесь к документации fsspec.

Update on GitHub

←MCP-клиент HF URI→