Создание и управление репозиторием

Hugging Face Hub представляет собой коллекцию git-репозиториев. Git — это широко используемый инструмент в разработке программного обеспечения, позволяющий легко вести версионирование проектов при совместной работе. В этом руководстве показано, как взаимодействовать с репозиториями на Hub, в частности:

• Создание и удаление репозитория.
• Управление ветками и тегами.
• Переименуйте репозиторий.
• Обновите видимость вашего репозитория.
• Управляйте локальной копией вашего репозитория.

Если вы привыкли работать с платформами, такими как GitLab/GitHub/Bitbucket, ваш первый инстинкт может подсказать использовать CLI git для клонирования репозитория (git clone), фиксации изменений (git add, git commit) и их отправки (git push). Это допустимо при работе с Hugging Face Hub. Однако требования и рабочие процессы в области разработки ПО и машинного обучения различаются. Репозитории моделей могут содержать файлы с большими весами моделей для разных фреймворков и инструментов, поэтому клонирование репозитория может привести к созданию локальных папок огромного размера. В результате более эффективным решением может стать использование наших собственных HTTP-методов. Подробнее вы можете узнать на странице Git vs HTTP paradigm.

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

Список ваших репозиториев

Список всех репозиториев (моделей, наборов данных, пространств и хранилищ) для вашей учётной записи или организации можно получить с помощью list_user_repos(). Результаты включают информацию о хранилище и отсортированы по объёму занятого места.

>>> from huggingface_hub import list_user_repos

# List repos for the authenticated user
>>> repos = list(list_user_repos())
>>> for repo in repos[:3]:
...     print(f"{repo.id} ({repo.type}) - {repo.storage} bytes")
username/my-model (model) - 4828692480 bytes
username/my-dataset (dataset) - 598427559 bytes
username/my-space (space) - 120620146 bytes

# List repos from an organization
>>> repos = list(list_user_repos(namespace="my-org"))

Или через CLI (по умолчанию отображаются 30 репозиториев, используйте --limit 0, чтобы получить список всех):

>>> hf repos ls
>>> hf repos ls --namespace my-org --type model
>>> hf repos ls --limit 0 --format json | jq '.[].id'

Создание и удаление репозиториев

Первый шаг — научиться создавать и удалять репозитории. Вы можете управлять только теми репозиториями, которые принадлежат вам (в пространстве имён вашего имени пользователя), или репозиториями из организаций, в которых у вас есть права на запись.

Создать репозиторий

Создайте пустой репозиторий с помощью create_repo() и задайте ему имя с помощью параметра repo_id. repo_id — это ваше пространство имён, за которым следует имя репозитория: username_or_org/repo_name.

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-model")
'https://huggingface.co/lysandre/test-model'

Или через CLI:

>>> hf repos create lysandre/test-model
Successfully created lysandre/test-model on the Hub.
Your repo is now available at https://huggingface.co/lysandre/test-model

По умолчанию create_repo() создаёт репозиторий модели. Но с помощью параметра repo_type можно указать другой тип репозитория. Например, если вы хотите создать репозиторий датасета:

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-dataset", repo_type="dataset")
'https://huggingface.co/datasets/lysandre/test-dataset'

Или через CLI:

>>> hf repos create lysandre/test-dataset --repo-type dataset

При создании репозитория вы можете задать его видимость с помощью параметра visibility:

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-private", visibility="private")

Или через CLI:

>>> hf repos create lysandre/test-private --private

Если вы хотите изменить видимость репозитория позже, вы можете использовать функцию update_repo_settings().

Если вы являетесь частью организации с тарифным планом Enterprise, вы можете создать репозиторий в конкретной группе ресурсов, передав resource_group_id в качестве параметра функции create_repo(). Группы ресурсов — это функция безопасности, позволяющая контролировать, какие члены вашей организации имеют доступ к определённому ресурсу. Идентификатор группы ресурсов можно получить, скопировав его из URL страницы настроек вашей организации на Hub (например, "https://huggingface.co/organizations/huggingface/settings/resource-groups/66670e5163145ca562cb1988" => "66670e5163145ca562cb1988"). Дополнительные сведения о группах ресурсов см. в этом руководстве.

Вы также можете создать репозиторий в определённом облачном регионе, передав region в качестве параметра:

>>> from huggingface_hub import create_repo
>>> create_repo("lysandre/test-model", region="us")

Удаление репозитория

Удалите репозиторий с помощью delete_repo(). Убедитесь, что вы действительно хотите удалить репозиторий, так как этот процесс необратим!

Укажите repo_id репозитория, который вы хотите удалить:

>>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset")

Передайте missing_ok=True, чтобы молча игнорировать вызов, если репозиторий не существует:

>>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset", missing_ok=True)

Или через CLI:

>>> hf repos delete lysandre/my-corrupted-dataset --repo-type dataset

Дублирование репозитория

В некоторых случаях вам может потребоваться скопировать репозиторий другого пользователя, чтобы адаптировать его под свою задачу. Это можно сделать с помощью метода duplicate_repo(). Он создаст полную копию репозитория, сохранив всю историю git. Это работает для моделей, наборов данных и Spaces. Для Spaces вам всё равно придётся настроить собственные параметры (аппаратное обеспечение, время сна, хранилище, переменные и секреты). Подробнее читайте в нашем руководстве Manage your Space.

>>> from huggingface_hub import duplicate_repo

# Duplicate a Space
>>> duplicate_repo("multimodalart/dreambooth-training", repo_type="space", private=False)
RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...)

# Duplicate a dataset
>>> duplicate_repo("openai/gdpval", repo_type="dataset")
RepoUrl('https://huggingface.co/datasets/nateraw/gdpval',...)

Как и create_repo(), duplicate_repo() принимает resource_group_id для создания копии непосредственно внутри ресурсной группы вашей организации Enterprise (--resource-group-id с hf repos duplicate).

История git копируется сразу, но файлы LFS/Xet могут продолжать копироваться в фоновом режиме даже после возврата duplicate_repo(). До завершения копирования загрузка этих файлов из нового репозитория может завершаться ошибкой. Проверьте files_copy_pending в возвращаемом значении, чтобы узнать, продолжается ли копирование:

>>> from huggingface_hub import duplicate_repo
>>> repo_url = duplicate_repo("openai/gdpval", repo_type="dataset")
>>> repo_url.files_copy_pending
True

Поиск по Spaces

Hub предоставляет API семантического поиска для обнаружения Spaces. Вы можете искать с помощью запросов на естественном языке с помощью search_spaces():

>>> from huggingface_hub import search_spaces
>>> results = list(search_spaces("generate image"))
>>> results[0].id
'mrfakename/Z-Image-Turbo'

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

Загрузка и скачивание файлов

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

Эти две темы заслуживают отдельных руководств. Обратитесь к руководствам по загрузке и скачиванию, чтобы узнать, как использовать ваш репозиторий.

Копирование файлов

Используйте copy_files(), чтобы копировать файлы, уже размещённые на Hub, из одного репозитория в другой (или даже внутри одного репозитория) без их скачивания и повторной загрузки. Поддерживаются как отдельные файлы, так и целые папки, а файлы, отслеживаемые с помощью Xet или LFS, копируются на стороне сервера по хэшу.

>>> from huggingface_hub import copy_files

# Copy a single file from one repo to another
>>> copy_files(
...     "hf://username/source-model/config.json",
...     "hf://username/dest-model/config.json",
... )

# Copy an entire folder (a trailing "/" copies the folder *contents*, rsync-style)
>>> copy_files(
...     "hf://datasets/username/my-dataset/data/",
...     "hf://datasets/username/my-dataset-copy/data/",
... )

Или через CLI, с помощью объединённой команды hf cp (также доступна как hf repos cp):

# Copy a single file between repositories
>>> hf cp hf://username/source-model/config.json hf://username/dest-model/config.json

# Copy a file from a repo to your local machine
>>> hf repos cp hf://username/my-model/config.json ./config.json

# Upload a local file to a repository
>>> hf repos cp ./model.safetensors hf://username/my-model/model.safetensors

copy_files (и hf cp) также позволяет копировать файлы из репозитория в Bucket. Копирование из бакета в репозиторий не поддерживается. Подробнее см. в руководстве Buckets.

Копии на стороне сервера работают только в пределах одной и той же области хранения.

Ветки и теги

Репозитории Git часто используют ветки для хранения различных версий одного и того же репозитория. Метки также можно использовать для обозначения конкретного состояния вашего репозитория, например, при выпуске версии. В более общем смысле ветки и метки называют git references.

Создание веток и тегов

Вы можете создать новую ветку и теги с помощью create_branch() и create_tag():

>>> from huggingface_hub import create_branch, create_tag

# Create a branch on a Space repo from `main` branch
>>> create_branch("Matthijs/speecht5-tts-demo", repo_type="space", branch="handle-dog-speaker")

# Create a tag on a Dataset repo from `v0.1-release` branch
>>> create_tag("bigcode/the-stack", repo_type="dataset", revision="v0.1-release", tag="v0.1.1", tag_message="Bump release version.")

Или через CLI:

>>> hf repos branch create Matthijs/speecht5-tts-demo handle-dog-speaker --repo-type space
>>> hf repos tag create bigcode/the-stack v0.1.1 --repo-type dataset --revision v0.1-release -m "Bump release version."

Вы можете использовать функции delete_branch() и delete_tag() аналогичным образом для удаления ветки или тега, а в CLI — команды hf repos branch delete и hf repos tag delete соответственно.

Список всех веток и тегов

Вы также можете получить список существующих git-ссылок из репозитория с помощью list_repo_refs():

>>> from huggingface_hub import list_repo_refs
>>> list_repo_refs("bigcode/the-stack", repo_type="dataset")
GitRefs(
   branches=[
         GitRefInfo(name='main', ref='refs/heads/main', target_commit='18edc1591d9ce72aa82f56c4431b3c969b210ae3'),
         GitRefInfo(name='v1.1.a1', ref='refs/heads/v1.1.a1', target_commit='f9826b862d1567f3822d3d25649b0d6d22ace714')
   ],
   converts=[],
   tags=[
         GitRefInfo(name='v1.0', ref='refs/tags/v1.0', target_commit='c37a8cd1e382064d8aced5e05543c5f7753834da')
   ]
)

Изменение настроек репозитория

Репозитории имеют ряд настроек, которые можно настроить. Как правило, это делается вручную на странице настроек репозитория в браузере. Для настройки репозитория у вас должны быть права на запись (вы являетесь его владельцем или членом организации). В этом разделе мы рассмотрим настройки, которые также можно изменить программно с помощью huggingface_hub.

Некоторые настройки специфичны для Spaces (аппаратное обеспечение, переменные окружения и т. д.). Чтобы настроить их, обратитесь к нашему руководству Управление Spaces.

Обновить видимость

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

>>> from huggingface_hub import update_repo_settings
>>> update_repo_settings(repo_id=repo_id, private=True)

Или через CLI:

>>> hf repos settings lysandre/test-private --private true

Настройка ограниченного доступа

Чтобы предоставить больше контроля над использованием репозиториев, Hub позволяет авторам репозиториев включать запросы на доступ для своих репозиториев. Если эта функция включена, пользователь должен согласиться на передачу своих контактных данных (имени пользователя и адреса электронной почты) авторам репозитория, чтобы получить доступ к файлам. Репозиторий, для которого включены запросы на доступ, называется репозиторием с ограниченным доступом.

Вы можете сделать репозиторий закрытым с помощью update_repo_settings():

>>> from huggingface_hub import HfApi

>>> api = HfApi()
>>> api.update_repo_settings(repo_id=repo_id, gated="auto")  # Set automatic gating for a model

Или через CLI:

>>> hf repos settings lysandre/test-private --gated auto

Переименовать репозиторий

Вы можете переименовать репозиторий на Hub с помощью move_repo(). С помощью этого метода также можно переместить репозиторий от пользователя в организацию. При этом существуют некоторые ограничения, о которых следует знать. Например, вы не можете передать свой репозиторий другому пользователю.

>>> from huggingface_hub import move_repo
>>> move_repo(from_id="Wauplin/cool-model", to_id="huggingface/cool-model")

Или через CLI:

>>> hf repos move Wauplin/cool-model huggingface/cool-model

Репозитории ядер

Hub поддерживает тип репозитория "kernel" для размещения вычислительных ядер. Это не полностью совместимый тип репозитория. Тестирование и официальная поддержка распространяются только на ограниченный набор методов:

• kernel_info()
• hf_hub_download()
• snapshot_download()
• list_repo_refs()
• list_repo_files()
• list_repo_tree()

Обратите внимание, что create_repo() и delete_repo() также поддерживаются, но их использование ограничено небольшим подмножеством разрешённых пользователей и организаций на Hub.

Для создания, публикации и использования репозиториев ядер используйте вместо этого специальный пакет kernels. Подробнее см. в документации Kernels.