Hub Python Library documentation
Интерфейс командной строки (CLI)
Интерфейс командной строки (CLI)
Пакет huggingface_hub для Python включает встроенную CLI-утилиту hf. С её помощью можно взаимодействовать с Hugging Face Hub прямо из терминала. Например, вы можете войти в свой аккаунт, создать репозиторий, загрузить и скачать файлы и т. д. Утилита также предлагает удобные функции для настройки вашей машины и управления кэшем. В этом руководстве мы рассмотрим основные возможности CLI и способы их использования.
В этом руководстве описаны основные возможности CLI
hf. Полный справочник по всем командам и опциям см. в справочнике CLI.
Используете
hfCLI с ИИ-агентами? Установите Skill и ознакомьтесь с руководством Hugging Face CLI for AI Agents.# works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills` hf skills addАвтономный установщик устанавливает его за вас (см. ниже), а
hf updateобновляет.
Начало работы
Автономный установщик (рекомендуется)
Вы можете установить CLI hf одной командой:
На macOS и Linux:
>>> curl -LsSf https://hf.co/cli/install.sh | bashВ Windows:
>>> powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"Установщик также глобально устанавливает навык hf-cli для Claude Code и любого агента, читающего ~/.agents/skills. Передайте --exclude-skill, чтобы пропустить его:
>>> curl -LsSf https://hf.co/cli/install.sh | bash -s -- --exclude-skill>>> powershell -ExecutionPolicy ByPass -c "& ([scriptblock]::Create((irm https://hf.co/cli/install.ps1))) -ExcludeSkill"После установки вы можете проверить, что CLI настроен правильно:
>>> hf --help
Usage: hf [OPTIONS] COMMAND [ARGS]...
Hugging Face Hub CLI
Options:
--skills Print the `hf-cli` SKILL.md to stdout (alias for `hf skills preview`).
--install-completion Install completion for the current shell.
--show-completion Show completion for the current shell, to copy it or customize the installation.
-h, --help Show this message and exit.
Main commands:
auth Manage authentication (login, logout, etc.).
buckets Commands to interact with buckets.
cache Manage local cache directory.
collections Interact with collections on the Hub.
datasets Interact with datasets on the Hub.
download Download files from the Hub.
endpoints Manage Hugging Face Inference Endpoints.
extensions Manage hf CLI extensions.
jobs Run and manage Jobs on the Hub.
models Interact with models on the Hub.
papers Interact with papers on the Hub.
repos Manage repos on the Hub.
skills Manage skills for AI assistants.
spaces Interact with spaces on the Hub.
sync Sync files between local directory and a bucket.
upload Upload a file or a folder to the Hub.
Help commands:
env Print information about the environment.
version Print information about the hf version.Если CLI установлен корректно, вы должны увидеть список всех доступных в CLI опций. Если вы получаете сообщение об ошибке, например command not found: hf, обратитесь к руководству по Установке.
Опция
--helpочень удобна для получения подробной информации о команде. Вы можете использовать её в любой момент, чтобы получить список всех доступных опций и их описаний. Например,hf upload --helpпредоставляет дополнительную информацию о том, как загружать файлы с помощью CLI.
Использование uv
Самый простой способ использовать CLI hf — через uvx. Он всегда запускает последнюю версию в изолированной среде — установка не требуется!
Убедитесь, что uv установлен. Инструкции см. в руководстве по установке uv.
Затем используйте CLI напрямую:
>>> uvx hf auth login
>>> uvx hf download
>>> uvx hf ...
uvx hfиспользует пакетhfс PyPI.
Установка с помощью pip
CLI также поставляется в составе основного пакета huggingface_hub:
>>> pip install -U "huggingface_hub"Использование Homebrew
Вы также можете установить CLI с помощью Homebrew:
>>> brew install hfПодробнее о Homebrew huggingface можно узнать здесь.
Обновление
Для обновления до последней версии выполните:
>>> hf updateЭта команда определяет способ установки hf (Homebrew, автономный установщик или pip) и выполняет соответствующую команду обновления. Если навык hf-cli установлен глобально, он также обновляется, чтобы агенты видели новый набор команд. Если же он не установлен, он остаётся удалённым: обновление не возвращает его, если вы пропустили его установку или удалили.
По умолчанию CLI также выводит однострочное жёлтое предупреждение в stderr, если на PyPI доступна более новая версия. Чтобы отключить его (например, в офлайн-CI), установите HF_HUB_DISABLE_UPDATE_CHECK=1.
Формат вывода
Большинство команд hf принимают один и тот же набор глобальных флагов форматирования. Они описаны в отдельном разделе Formatting options на каждой странице --help и могут быть добавлены к любой команде без необходимости объявлять их для каждой команды отдельно:
| Флаг | Эквивалент | Описание |
|---|---|---|
--format <value> | — | Явно укажите формат вывода. Допустимые значения: auto (по умолчанию), human, agent, json, quiet. |
--json | --format json | Вывод структурированного JSON. Полезно для передачи в jq или другие скрипты. |
-q, --quiet | --format quiet | Выводить только идентификаторы (по одному в строке). Полезно для передачи идентификаторов в другие команды. |
--no-truncate | — | Показывать полные значения в таблицах для человека, а не сокращать длинные значения с помощью .... Таблица может выйти за ширину терминала. Используйте --format json для структурированного вывода столбцов list/dict. |
auto (значение по умолчанию) выбирает human для интерактивного терминала и agent, когда CLI вызывается ИИ-агентом. human добавляет цвета и аккуратные таблицы; agent выводит значения, разделённые табуляцией, без усечения; json формирует компактный объект или массив JSON. Использование двух флагов режима вывода одновременно (например, --json вместе с --format table) приводит к ошибке использования.
Человеческие таблицы автоматически подстраиваются под ширину вашего терминала: самые широкие столбцы укорачиваются только в том случае, если их естественная ширина превышает ширину экрана (поэтому в широком терминале вы обычно видите полные значения без ...). Передайте --no-truncate, чтобы принудительно отображать полные значения независимо от ширины; используйте --format json для структурированного вывода столбцов типа list/dict.
# JSON output for scripting
>>> hf models ls --search bert --limit 2 --json | jq '.[].id'
# IDs only, one per line
>>> hf collections ls --owner nvidia -q
nvidia/nemotron-supervised-fine-tuning-69eab9824c9120a3a3b1e25e
nvidia/nvidia-nemotron-v3-69388dda16167bb1607171eahf auth login
Во многих случаях для взаимодействия с Hub (загрузка частных репозиториев, загрузка файлов, создание PR и т. д.) необходимо войти в аккаунт Hugging Face. Для этого выполните следующую команду в терминале:
>>> hf auth loginЕсли вы уже вошли в систему, эта команда пропустит запрос и отобразит сообщение. Чтобы принудительно выполнить повторный вход (например, для переключения токенов), используйте --force:
>>> hf auth login --forceПо умолчанию команда выполняет вход через браузер: она выводит URL и короткий код. Откройте URL, введите код, подтвердите запрос, и CLI получит и сохранит токен доступа на вашем компьютере. Токен истекает через некоторое время, но автоматически обновляется, пока вы продолжаете его использовать.
? How would you like to log in? [Use arrows, Enter to confirm]
> Log in with your browser
Paste an access token
Open this URL in your browser:
https://huggingface.co/oauth/device
And enter the code: ABCD-EFGH
Waiting for authorization...
Token is valid.
The token `oauth-wauplin` has been saved to /home/wauplin/.cache/huggingface/stored_tokens
Your token has been saved to /home/wauplin/.cache/huggingface/token
Login successful.Вы также можете вставить User Access Token, созданный на странице Settings, в интерактивном режиме (выберите Paste an access token) или напрямую из командной строки. Для большей безопасности мы рекомендуем передавать токен как переменную окружения, чтобы не оставлять его в истории команд.
# Or using an environment variable
>>> hf auth login --token $HF_TOKEN --add-to-git-credential
Token is valid (permission: write).
The token `token_name` has been saved to /home/wauplin/.cache/huggingface/stored_tokens
Your token has been saved in your configured git credential helpers (store).
Your token has been saved to /home/wauplin/.cache/huggingface/token
Login successful
The current active token is: `token_name`При запуске агентом ИИ (автоматически определяемым или с флагом --format agent) команда никогда не запрашивает подтверждение: она выполняет браузерный сценарий и выводит простые инструкции, которые агент может передать пользователю, после чего ожидает авторизации:
>>> hf auth login --format agent
Ask the user to open https://huggingface.co/oauth/device in a browser and enter the code ABCD-EFGH. The code expires in 900 seconds. Waiting for authorization...
Login successful: logged in as wauplin (token saved as 'oauth-wauplin').hf auth login — интерактивная команда, поэтому --format json и --format quiet не поддерживаются: для автоматизированного, неинтерактивного входа передавайте --token.
Для получения подробной информации об аутентификации обратитесь к этому разделу.
hf auth whoami
Если вы хотите узнать, выполнен ли вход, используйте hf auth whoami. Эта команда не имеет опций и просто выводит ваше имя пользователя и организации, участником которых вы являетесь на Hub:
hf auth whoami
Wauplin
orgs: huggingface,eu-test,OAuthTesters,hf-accelerate,HFSmolClusterЕсли вы не вошли в систему, будет выведено сообщение об ошибке.
hf auth logout
Эта команда завершает сеанс. На практике она удаляет все токены, сохранённые на вашем компьютере. Если вы хотите удалить конкретный токен, укажите его имя в качестве аргумента.
Эта команда не завершит сеанс, если вы вошли с помощью переменной окружения HF_TOKEN (см. справку). В этом случае необходимо сбросить эту переменную в конфигурации вашей системы.
hf download
Используйте команду hf download для скачивания файлов с Hub напрямую. Внутри она использует те же помощники hf_hub_download() и snapshot_download(), которые описаны в руководстве Download, и выводит возвращаемый путь в терминал. В примерах ниже мы разберем наиболее частые сценарии использования. Чтобы увидеть полный список доступных опций, выполните:
hf download --helpЗагрузка одного файла
Чтобы скачать один файл из репозитория, просто укажите repo_id и имя файла следующим образом:
>>> hf download gpt2 config.json
downloading https://huggingface.co/gpt2/resolve/main/config.json to /home/wauplin/.cache/huggingface/hub/tmpwrq8dm5o
(…)ingface.co/gpt2/resolve/main/config.json: 100%|██████████████████████████████████| 665/665 [00:00<00:00, 2.49MB/s]
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.jsonКоманда всегда выводит на последней строке путь к файлу на вашем локальном компьютере.
Чтобы скачать файл, расположенный в подкаталоге репозитория, укажите путь к файлу в репозитории в формате posix, как показано ниже:
>>> hf download HiDream-ai/HiDream-I1-Full text_encoder/model.safetensorsСкачать весь репозиторий
В некоторых случаях вам нужно просто скачать все файлы из репозитория. Это можно сделать, просто указав идентификатор репозитория:
>>> hf download HuggingFaceH4/zephyr-7b-beta
Fetching 23 files: 0%| | 0/23 [00:00<?, ?it/s]
...
...
/home/wauplin/.cache/huggingface/hub/models--HuggingFaceH4--zephyr-7b-beta/snapshots/3bac358730f8806e5c3dc7c7e19eb36e045bf720Загрузка нескольких файлов
Вы также можете загрузить подмножество файлов из репозитория одной командой. Это можно сделать двумя способами. Если у вас уже есть точный список файлов, которые вы хотите загрузить, вы можете просто указать их последовательно:
>>> hf download gpt2 config.json model.safetensors
Fetching 2 files: 0%| | 0/2 [00:00<?, ?it/s]
downloading https://huggingface.co/gpt2/resolve/11c5a3d5811f50298f278a704980280950aedb10/model.safetensors to /home/wauplin/.cache/huggingface/hub/tmpdachpl3o
(…)8f278a7049802950aedb10/model.safetensors: 100%|██████████████████████████████| 8.09k/8.09k [00:00<00:00, 40.5MB/s]
Fetching 2 files: 100%|████████████████████████████████████████████████████████████████| 2/2 [00:00<00:00, 3.76it/s]
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10Другой подход — указать шаблоны для фильтрации файлов, которые вы хотите скачать, с помощью --include и --exclude. Например, если вы хотите скачать все файлы safetensors из stabilityai/stable-diffusion-xl-base-1.0, кроме файлов с точностью FP16:
>>> hf download stabilityai/stable-diffusion-xl-base-1.0 --include "*.safetensors" --exclude "*.fp16.*"*
Fetching 8 files: 0%| | 0/8 [00:00<?, ?it/s]
...
...
Fetching 8 files: 100%|█████████████████████████████████████████████████████████████████████████| 8/8 (...)
/home/wauplin/.cache/huggingface/hub/models--stabilityai--stable-diffusion-xl-base-1.0/snapshots/462165984030d82259a11f4367a4eed129e94a7bЗагрузить набор данных, Space или ядро
Приведённые выше примеры показывают, как загрузить данные из репозитория модели. Чтобы загрузить датасет, Space или ядро, используйте опцию --repo-type:
# https://huggingface.co/datasets/HuggingFaceH4/ultrachat_200k
>>> hf download HuggingFaceH4/ultrachat_200k --repo-type dataset
# https://huggingface.co/spaces/HuggingFaceH4/zephyr-chat
>>> hf download HuggingFaceH4/zephyr-chat --repo-type space
...Загрузка конкретного ревизии
Приведённые выше примеры показывают, как загрузить данные из последнего коммита ветки main. Чтобы загрузить данные из конкретного ревизии (хеша коммита, имени ветки или тега), используйте опцию --revision:
>>> hf download bigcode/the-stack --repo-type dataset --revision v1.1
...Используйте URI в формате hf://
Вместо передачи типа репозитория, ревизии и пути к файлу в виде отдельных аргументов и опций можно указать единый URI hf://. URI кодирует всю информацию сразу, следуя грамматике hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] (см. справочник по HF URIs для полного синтаксиса):
# Equivalent to: hf download bigcode/the-stack --repo-type dataset --revision v1.1
>>> hf download hf://datasets/bigcode/the-stack@v1.1
# Download a single file from a specific revision
>>> hf download hf://datasets/HuggingFaceM4/FineVision@refs/pr/1/data/train.parquet
# Download a subfolder (note the trailing slash)
>>> hf download hf://datasets/HuggingFaceM4/FineVision/art/
# A bare id still works and defaults to a model repo
>>> hf download hf://openai-community/gpt2/config.jsonЕсли указан URI, параметры --repo-type и --revision также нельзя задавать, поскольку они уже являются частью URI (иначе возникает ошибка), а путь к файлу, встроенный в URI, нельзя совмещать с позиционными именами файлов. Завершающий символ / в пути обозначает подпапку (как и в случае с позиционным аргументом). Имена веток, содержащие символ /, должны быть закодированы в URL как %2F (например, hf://my-org/my-model@feature%2Ffoo).
Скачать в локальную папку
Рекомендуемый (и используемый по умолчанию) способ загрузки файлов с Hub — использование системы кэширования. Однако в некоторых случаях вы можете захотеть скачать файлы и переместить их в конкретную папку. Это полезно, чтобы приблизить рабочий процесс к тому, что предлагают команды git. Вы можете сделать это с помощью опции --local-dir.
В корне вашего локального каталога создаётся папка .cache/huggingface/, содержащая метаданные о загруженных файлах. Это предотвращает повторную загрузку файлов, если они уже актуальны. Если метаданные изменились, загружается новая версия файла. Благодаря этому local-dir оптимизирован для получения только последних изменений.
Подробнее о том, как работает загрузка в локальный файл, читайте в руководстве download.
>>> hf download adept/fuyu-8b model-00001-of-00002.safetensors --local-dir fuyu
...
fuyu/model-00001-of-00002.safetensorsРежим предварительного запуска
В некоторых случаях вы можете захотеть проверить, какие файлы будут загружены, прежде чем начать фактическую загрузку. Вы можете сделать это с помощью параметра --dry-run. Он выводит список всех файлов для загрузки в репозитории и проверяет, были ли они уже загружены. Это позволяет понять, сколько файлов необходимо загрузить и каков их размер.
>>> hf download openai-community/gpt2 --dry-run
[dry-run] Fetching 26 files: 100%|█████████████| 26/26 [00:04<00:00, 6.26it/s]
[dry-run] Will download 11 files (out of 26) totalling 5.6G.
File Bytes to download
--------------------------------- -----------------
.gitattributes -
64-8bits.tflite 125.2M
64-fp16.tflite 248.3M
64.tflite 495.8M
README.md -
config.json -
flax_model.msgpack 497.8M
generation_config.json -
merges.txt -
model.safetensors 548.1M
onnx/config.json -
onnx/decoder_model.onnx 653.7M
onnx/decoder_model_merged.onnx 655.2M
onnx/decoder_with_past_model.onnx 653.7M
onnx/generation_config.json -
onnx/merges.txt -
onnx/special_tokens_map.json -
onnx/tokenizer.json -
onnx/tokenizer_config.json -
onnx/vocab.json -
pytorch_model.bin 548.1M
rust_model.ot 702.5M
tf_model.h5 497.9M
tokenizer.json -
tokenizer_config.json -
vocab.json -Подробнее — в руководстве по загрузке.
Укажите каталог кэша
Если не использовать --local-dir, все файлы по умолчанию будут загружены в каталог кэша, определённый переменной окружения HF_HOME environment variable. Вы можете указать собственный кэш с помощью --cache-dir:
>>> hf download adept/fuyu-8b --cache-dir ./path/to/cache
...
./path/to/cache/models--adept--fuyu-8b/snapshots/ddcacbcf5fdf9cc59ff01f6be6d6662624d9c745Укажите токен
Для доступа к частным или закрытым репозиториям необходимо использовать токен. По умолчанию используется токен, сохранённый локально (с помощью hf auth login). Если вы хотите выполнить аутентификацию явно, используйте параметр --token:
>>> hf download gpt2 config.json --token=hf_****
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.jsonТихий режим
По умолчанию команда hf download выводит подробную информацию: предупреждения, сведения о загруженных файлах и индикаторы прогресса. Чтобы отключить весь этот вывод, используйте параметр --quiet. В этом случае печатается только последняя строка, то есть путь к загруженным файлам. Это может быть полезно, если вы хотите передать результат в другую команду в скрипте.
>>> hf download gpt2 --quiet
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10Тайм-аут загрузки
На машинах с медленным соединением могут возникать проблемы с таймаутом, например, такие:
`httpx2.TimeoutException: (TimeoutException("HTTPSConnectionPool(host='cdn-lfs-us-1.huggingface.co', port=443): Read timed out. (read timeout=10)"), '(Request ID: a33d910c-84c6-4514-8362-c705e2039d38)')`Чтобы устранить эту проблему, вы можете установить переменную окружения HF_HUB_DOWNLOAD_TIMEOUT в более высокое значение (по умолчанию — 10):
export HF_HUB_DOWNLOAD_TIMEOUT=30Подробнее см. в справочнике по переменным окружения. Затем повторите команду загрузки.
hf upload
Используйте команду hf upload для прямой загрузки файлов в Hub. Внутри она использует те же помощники upload_file() и upload_folder(), которые описаны в руководстве Upload. В примерах ниже мы рассмотрим наиболее распространённые сценарии использования. Чтобы получить полный список доступных опций, выполните:
>>> hf upload --helpЗагрузка всей папки
По умолчанию эта команда используется следующим образом:
# Usage: hf upload [repo_id] [local_path] [path_in_repo]Чтобы загрузить текущий каталог в корень репозитория, используйте:
>>> hf upload my-cool-model . .
https://huggingface.co/Wauplin/my-cool-model/tree/main/Если репозиторий ещё не существует, он будет создан автоматически.
Вы также можете загрузить конкретную папку:
>>> hf upload my-cool-model ./models .
https://huggingface.co/Wauplin/my-cool-model/tree/main/Наконец, вы можете загрузить папку в конкретное место в репозитории:
>>> hf upload my-cool-model ./path/to/curated/data /data/train
https://huggingface.co/Wauplin/my-cool-model/tree/main/data/trainЗагрузка одного файла
Вы также можете загрузить один файл, указав в local_path путь к файлу на вашем компьютере. В этом случае path_in_repo является необязательным и по умолчанию принимает значение имени локального файла:
>>> hf upload Wauplin/my-cool-model ./models/model.safetensors
https://huggingface.co/Wauplin/my-cool-model/blob/main/model.safetensorsЕсли вы хотите загрузить один файл в конкретный каталог, установите path_in_repo соответствующим образом:
>>> hf upload Wauplin/my-cool-model ./models/model.safetensors /vae/model.safetensors
https://huggingface.co/Wauplin/my-cool-model/blob/main/vae/model.safetensorsЗагрузка нескольких файлов
Чтобы загрузить несколько файлов из папки сразу, не загружая всю папку целиком, используйте паттерны --include и --exclude. Это также можно объединить с опцией --delete, чтобы удалять файлы в репозитории при загрузке новых. В примере ниже мы синхронизируем локальный Space, удаляя удалённые файлы и загружая все файлы, кроме тех, что находятся в /logs:
# Sync local Space with Hub (upload new files except from logs/, delete removed files)
>>> hf upload Wauplin/space-example --repo-type=space --exclude="/logs/*" --delete="*" --commit-message="Sync local Space with Hub"
...Загрузка в набор данных или Space
Чтобы загрузить в набор данных или Space, используйте параметр --repo-type:
>>> hf upload Wauplin/my-cool-dataset ./data /train --repo-type=dataset
...Загрузка в организацию
Чтобы загрузить содержимое в репозиторий, принадлежащий организации, а не личный репозиторий, необходимо явно указать это в repo_id:
>>> hf upload MyCoolOrganization/my-cool-model . .
https://huggingface.co/MyCoolOrganization/my-cool-model/tree/main/Загрузка в конкретную ревизию
По умолчанию файлы загружаются в ветку main. Если вы хотите загрузить файлы в другую ветку или ссылку, используйте опцию --revision:
# Upload files to a PR
>>> hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104
...Примечание: если revision не существует и --create-pr не задан, ветка будет создана автоматически из ветки main.
Используйте URI в формате hf://
Как и в случае с hf download, назначение можно указать в виде одного URI hf:// в соответствии с грамматикой hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] (полный синтаксис описан в справочнике по HF URI). Тип репозитория, ревизия и path_in_repo извлекаются из URI:
# Equivalent to: hf upload Wauplin/my-cool-dataset ./train.csv data/train.csv --repo-type dataset --revision my-branch
>>> hf upload hf://datasets/Wauplin/my-cool-dataset@my-branch/data/train.csv ./train.csv
# Upload a whole folder to the root of a model repo
>>> hf upload hf://Wauplin/my-cool-model ./modelsЕсли указан URI, параметры --repo-type и --revision также нельзя задать, поскольку они уже являются частью URI (иначе будет выброшена ошибка), а путь, встроенный в URI, нельзя использовать вместе с аргументом path_in_repo.
Загрузить и создать PR
Если у вас нет прав на отправку в репозиторий, вам необходимо открыть PR и сообщить авторам о желаемых изменениях. Это можно сделать, установив опцию --create-pr:
# Create a PR and upload the files to it
>>> hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104
https://huggingface.co/datasets/bigcode/the-stack/blob/refs%2Fpr%2F104/Загрузка через равные промежутки времени
В некоторых случаях может потребоваться отправлять регулярные обновления в репозиторий. Например, это полезно, если вы обучаете модель и хотите загружать папку с журналами каждые 10 минут. Для этого можно использовать опцию --every:
# Upload new logs every 10 minutes
hf upload training-model logs/ --every=10Укажите сообщение коммита
Используйте --commit-message и --commit-description, чтобы задать собственное сообщение и описание для коммита вместо значений по умолчанию
>>> hf upload Wauplin/my-cool-model ./models . --commit-message="Epoch 34/50" --commit-description="Val accuracy: 68%. Check tensorboard for more details."
...
https://huggingface.co/Wauplin/my-cool-model/tree/mainУкажите токен
Для загрузки файлов необходимо использовать токен. По умолчанию используется токен, сохранённый локально (с помощью hf auth login). Если вы хотите выполнить аутентификацию явно, используйте опцию --token:
>>> hf upload Wauplin/my-cool-model ./models . --token=hf_****
...
https://huggingface.co/Wauplin/my-cool-model/tree/mainТихий режим
По умолчанию команда hf upload выводит подробную информацию: предупреждения, сведения о загруженных файлах и индикаторы прогресса. Чтобы отключить весь этот вывод, используйте параметр --quiet. В этом случае печатается только последняя строка, то есть URL загруженных файлов. Это может быть полезно, если вы хотите передать вывод другой команде в скрипте.
>>> hf upload Wauplin/my-cool-model ./models . --quiet
https://huggingface.co/Wauplin/my-cool-model/tree/mainhf buckets
Используйте hf buckets для управления бакетами на Hugging Face Hub. Бакеты предоставляют объектное хранилище, похожее на S3, на Hugging Face, работающее на базе системы хранения Xet. В отличие от репозиториев (которые основаны на git и отслеживают историю файлов), бакеты представляют собой удалённые контейнеры объектного хранилища, предназначенные для работы с файлами большого размера с дедупликацией на основе контрольных сумм содержимого. Они созданы для сценариев, где требуется простое, быстрое и изменяемое хранилище, например, для сохранения контрольных точек обучения, журналов, промежуточных артефактов или любых больших коллекций файлов, не требующих контроля версий. В примерах ниже мы рассмотрим наиболее распространённые сценарии использования. Полное руководство см. в руководстве по бакетам.
Создать бакет
Чтобы создать новое хранилище, используйте hf buckets create. По умолчанию хранилище будет создано в вашем пространстве имён:
>>> hf buckets create my-bucketВы также можете создать приватный бакет с помощью флага --private:
>>> hf buckets create my-bucket --privateПросмотр и проверка бакетов
Чтобы получить список всех ваших бакетов, используйте hf buckets list (или его сокращённую форму hf buckets ls). Также можно получить список бакетов в конкретной организации:
>>> hf buckets list
ID PRIVATE SIZE TOTAL_FILES CREATED_AT
-------------------- ------- ---------- ----------- ----------
username/my-bucket 32 5 2026-02-16
username/checkpoints 117609095 700 2026-02-13
username/logs 321757477 2000 2026-02-13
# Human-readable sizes
>>> hf buckets list -h
ID PRIVATE SIZE TOTAL_FILES CREATED_AT
-------------------- ------- -------- ----------- ----------
username/my-bucket 32 B 5 2026-02-16
username/checkpoints 117.6 MB 700 2026-02-13
username/logs 321.8 MB 2000 2026-02-13
# List buckets in a specific namespace
>>> hf buckets ls my-org
# Filter buckets by name
>>> hf buckets list --search "checkpoint"Чтобы получить подробную информацию о конкретном бакете (возвращается в формате JSON), используйте hf buckets info:
>>> hf buckets info username/my-bucket
{
"id": "username/my-bucket",
"private": false,
"created_at": "2026-02-16T15:28:32+00:00",
"size": 32,
"total_files": 5
}Изменение видимости хранилища
Чтобы переключить бакет между приватным и публичным, используйте hf buckets settings:
# Make a bucket private
>>> hf buckets settings username/my-bucket --private
# Make it public again
>>> hf buckets settings username/my-bucket --publicУдаление хранилища
Чтобы удалить бакет, используйте hf buckets delete. Вас попросят подтвердить действие, если не передать --yes:
>>> hf buckets delete username/my-bucket --yesУдалить файлы
Используйте hf buckets remove (или его сокращённую форму hf buckets rm), чтобы удалить файлы из бакета.
Чтобы удалить один файл, укажите его путь:
>>> hf buckets rm username/my-bucket/old-model.binЧтобы удалить все файлы по префиксу, используйте --recursive:
>>> hf buckets rm username/my-bucket/logs/ --recursiveВы также можете указать все файлы в бакете без префикса:
>>> hf buckets rm username/my-bucket --recursive --include "*.tmp"Используйте --dry-run, чтобы просмотреть, что будет удалено, без фактического удаления:
>>> hf buckets rm username/my-bucket/checkpoints/ --recursive --dry-runПросмотр файлов
Используйте hf buckets list с идентификатором бакета, чтобы получить список файлов в бакете:
>>> hf buckets list username/my-bucket
2048 2026-01-15 10:30:00 big.bin
5 2026-01-15 10:30:00 file.txt
2026-01-15 10:30:00 sub/Добавьте -R для рекурсивного списка и -h для отображения размеров файлов в человекочитаемом формате и кратких дат. Также можно отобразить дерево в формате ASCII с помощью --tree или использовать --tree --quiet для чистого дерева без метаданных:
# Recursive with human-readable sizes
>>> hf buckets list username/my-bucket -R -h
2.0 KB Jan 15 10:30 big.bin
5 B Jan 15 10:30 file.txt
14 B Jan 15 10:30 sub/nested.txt
4 B Jan 15 10:30 sub/deep/file.txt
# Tree with human-readable sizes
>>> hf buckets list username/my-bucket --tree -h -R
2.0 KB Jan 15 10:30 ├── big.bin
5 B Jan 15 10:30 ├── file.txt
└── sub/
├── deep/
4 B Jan 15 10:30 │ └── file.txt
14 B Jan 15 10:30 └── nested.txt
# Clean tree without metadata
>>> hf buckets list username/my-bucket --tree --quiet -R
├── big.bin
├── file.txt
└── sub/
├── deep/
│ └── file.txt
└── nested.txtЧтобы отфильтровать по префиксу, добавьте префикс к пути к бакету:
>>> hf buckets list username/my-bucket/sub -RКопирование файлов
Используйте hf cp для копирования одного файла между локальным компьютером, репозиториями и бакетами. Исходный и целевой объекты могут быть локальным путём, URI hf:// (репозиторий или бакет) или - (stdin/stdout).
hf cpтакже доступен какhf repos cpиhf buckets cp— все три команды полностью идентичны. Используйте ту, которая лучше подходит для вашего рабочего процесса.
Для загрузки файла (локально → репозиторий или бакет):
# To a repository
>>> hf cp ./model.safetensors hf://username/my-model/model.safetensors
# To a bucket (uses the local filename when the destination ends with /)
>>> hf cp ./data.csv hf://buckets/username/my-bucket/logs/Для загрузки файла (репозиторий или бакет → локально):
# From a repository
>>> hf cp hf://datasets/username/my-dataset@refs/pr/1/data.csv ./data.csv
# From a bucket, to the current directory (destination omitted)
>>> hf cp hf://buckets/username/my-bucket/config.jsonВы также можете передавать данные в stdout или из stdin с помощью -:
# Download to stdout
>>> hf cp hf://buckets/username/my-bucket/config.json - | jq .
# Upload from stdin
>>> echo "hello" | hf cp - hf://username/my-model/hello.txtЧтобы скопировать данные между двумя местоположениями на Hub (repo/bucket → repo/bucket):
# Repo to repo
>>> hf cp hf://username/source-model/config.json hf://username/dest-model/config.json
# Repo to bucket
>>> hf cp hf://datasets/username/my-dataset/data/train/ hf://buckets/username/my-bucket/datasets/train/
# Bucket to bucket
>>> hf cp hf://buckets/username/source-bucket/logs/ hf://buckets/username/archive-bucket/logs/При копировании папок между двумя расположениями в Hub завершающий / в исходном пути определяет, будет ли скопирована сама папка (с вложенностью) или только её содержимое (в стиле rsync):
# Without trailing slash: "logs" dir is nested => archive/logs/...
>>> hf cp hf://buckets/username/my-bucket/logs hf://buckets/username/archive-bucket/
# With trailing slash: only contents of "logs" are copied => archive/...
>>> hf cp hf://buckets/username/my-bucket/logs/ hf://buckets/username/archive-bucket/Примечания:
hf cpкопирует один файл, если в операции участвует локальный путь. Чтобы копировать целые каталоги из локальной системы или в неё, используйтеhf upload/hf download(для репозиториев) илиhf buckets sync(для бакетов).- Копирование из бакета в репозиторий пока не поддерживается.
- Копирование из локального в локальное хранилище не поддерживается (используйте команду
cpвашей оболочки). - Копирование между двумя расположениями в Hub работает только в пределах одной и той же области хранения.
Синхронизация каталогов
Используйте hf buckets sync для синхронизации каталогов между локальной машиной и бакетом. Команда сравнивает исходный и целевой каталоги и передаёт только изменённые файлы.
Чтобы загрузить локальный каталог в бакет:
>>> hf buckets sync ./data hf://buckets/username/my-bucketДля загрузки из хранилища в локальный каталог:
>>> hf buckets sync hf://buckets/username/my-bucket ./dataИспользуйте --delete, чтобы удалить файлы в пункте назначения, отсутствующие в источнике:
>>> hf buckets sync ./data hf://buckets/username/my-bucket --deleteВы можете отфильтровать файлы для синхронизации с помощью паттернов --include и --exclude:
>>> hf buckets sync ./data hf://buckets/username/my-bucket --include "*.safetensors" --exclude "*.tmp"Чтобы обновлять только существующие файлы (пропуская новые), используйте --existing. Чтобы создавать только новые файлы (пропуская существующие), используйте --ignore-existing:
>>> hf buckets sync ./data hf://buckets/username/my-bucket --existing
>>> hf buckets sync ./data hf://buckets/username/my-bucket --ignore-existingДля дополнительной безопасности вы можете сгенерировать план для проверки перед выполнением, а затем применить его:
# Generate a plan
>>> hf buckets sync ./data hf://buckets/username/my-bucket --plan sync-plan.jsonl
# Review and apply the plan
>>> hf buckets sync --apply sync-plan.jsonlИспользуйте --dry-run, чтобы вывести план синхронизации в формате JSONL в стандартный вывод без выполнения каких-либо действий. Это удобно для передачи в jq или другие инструменты:
>>> hf buckets sync ./data hf://buckets/username/my-bucket --dry-run | jq .
hf sync— это удобный верхнеуровневый псевдоним дляhf buckets sync. Полные сведения обо всех параметрах синхронизации см. в руководстве по бакетам.
hf models
Используйте hf models, чтобы получить список моделей на Hub и подробную информацию о конкретной модели.
Список моделей
# List trending models
>>> hf models ls
# Search for models
>>> hf models ls --search "lora"
# Filter by author
>>> hf models ls --author Qwen
# Filter by pipeline tag
>>> hf models ls --pipeline-tag summarization
# Filter by parameter count
>>> hf models ls --num-parameters min:6B,max:128B
# Only non-gated models
>>> hf models ls --no-gated --author google
# Only models runnable by a given app
>>> hf models ls --apps llama.cpp
# Sort by downloads
>>> hf models ls --sort downloads --limit 10При вызове с идентификатором модели hf models ls выводит список файлов в репозитории этой модели:
# List files in a model repo
>>> hf models ls meta-llama/Llama-3.2-1B-Instruct
# List files recursively
>>> hf models ls meta-llama/Llama-3.2-1B-Instruct -R
# Tree view with human-readable sizes
>>> hf models ls meta-llama/Llama-3.2-1B-Instruct --tree -h
# List files at a specific revision
>>> hf models ls meta-llama/Llama-3.2-1B-Instruct --revision mainПолучить информацию о модели
>>> hf models info Lightricks/LTX-2Используйте --expand, чтобы получить дополнительные свойства, такие как downloads, likes, tags и т. д.
Получить карточку модели
Используйте hf models card для получения карточки модели (README). По умолчанию полный текст карточки выводится в stdout.
# Full card (metadata + text)
>>> hf models card google/gemma-4-31B-it
# Just the metadata (from the YAML frontmatter)
>>> hf models card google/gemma-4-31B-it --metadata
# Metadata as JSON (useful for scripting and agents)
>>> hf models card google/gemma-4-31B-it --metadata --format json
# Just the text body (no YAML frontmatter)
>>> hf models card google/gemma-4-31B-it --texthf datasets
Используйте hf datasets, чтобы получить список датасетов на Hub и подробную информацию о конкретном датасете.
Список наборов данных
# List trending datasets
>>> hf datasets ls
# Search for datasets
>>> hf datasets ls --search "code"
# List official benchmark datasets
>>> hf datasets ls --filter benchmark:official
# Sort by downloads
>>> hf datasets ls --sort downloads --limit 10При вызове с идентификатором набора данных hf datasets ls выводит список файлов в репозитории этого набора данных:
# List files in a dataset repo
>>> hf datasets ls HuggingFaceFW/fineweb
# List files recursively with human-readable sizes
>>> hf datasets ls HuggingFaceFW/fineweb -R -h
# Tree view
>>> hf datasets ls HuggingFaceFW/fineweb --treeСписок лидеров набора данных
Используйте hf datasets leaderboard, чтобы просмотреть оценки моделей, отправленные для бенчмарк-датасета, и найти лучшие модели для задачи или сравнить модели по результатам бенчмарков.
>>> hf datasets leaderboard SWE-bench/SWE-bench_Verified
>>> hf datasets leaderboard SWE-bench/SWE-bench_Verified --limit 5 --format jsonПолучить информацию о наборе данных
>>> hf datasets info HuggingFaceFW/finewebПолучить карточку набора данных
Используйте hf datasets card, чтобы получить карточку набора данных (README). По умолчанию полный текст карточки выводится в стандартный поток вывода.
# Full card (metadata + text)
>>> hf datasets card HuggingFaceFW/fineweb
# Just the metadata (from the YAML frontmatter)
>>> hf datasets card HuggingFaceFW/fineweb --metadata
# Metadata as JSON (useful for scripting and agents)
>>> hf datasets card HuggingFaceFW/fineweb --metadata --format json
# Just the text body (no YAML frontmatter)
>>> hf datasets card HuggingFaceFW/fineweb --textСписок URL-адресов parquet
Используйте hf datasets parquet, чтобы получить URL-адреса файлов Parquet для набора данных перед написанием SQL-запросов.
Наборы данных на Hub автоматически конвертируются в Parquet на стороне сервера сервисом Dataset Viewer (для поддерживаемых наборов данных).
Подробнее см. в руководстве по конвертации в Parquet.
>>> hf datasets parquet cfahlgren1/hub-stats
>>> hf datasets parquet cfahlgren1/hub-stats --subset models
>>> hf datasets parquet cfahlgren1/hub-stats --split train
>>> hf datasets parquet cfahlgren1/hub-stats --format jsonПо умолчанию вывод таблицы включает подмножество, разбиение и URL-адрес файла parquet из Hub API.
Выполнение SQL на датасете parquet
Используйте hf datasets sql для выполнения запросов на сыром SQL с помощью DuckDB по URL-адресам файлов parquet датасета.
Сначала найдите URL-адреса с помощью hf datasets parquet, а затем выполните по ним запросы напрямую с помощью read_parquet(...).
>>> hf datasets sql "SELECT COUNT(*) AS rows FROM read_parquet('https://huggingface.co/api/datasets/cfahlgren1/hub-stats/parquet/models/train/0.parquet')"
>>> hf datasets sql "SELECT * FROM read_parquet('https://huggingface.co/api/datasets/cfahlgren1/hub-stats/parquet/models/train/0.parquet') LIMIT 5" --format jsonПри необходимости сначала установите DuckDB:
# Python package
>>> pip install duckdb
# or standalone DuckDB CLI (Homebrew: macOS/Linux)
>>> brew install duckdbhf spaces
Используйте hf spaces для получения списка Spaces на Hub и подробной информации о конкретном Space.
Список Spaces
# List trending Spaces
>>> hf spaces ls
# Search for Spaces
>>> hf spaces ls --search "3d"
# Sort by likes
>>> hf spaces ls --sort likes --limit 10При вызове с идентификатором Space команда hf spaces ls выводит список файлов в репозитории этого Space:
# List files in a Space repo
>>> hf spaces ls victor/deepsite
# List files recursively with tree view
>>> hf spaces ls victor/deepsite --tree -R -hПолучить информацию о Space
>>> hf spaces info victor/deepsiteПолучить карточку Space
Используйте hf spaces card для получения карточки Space (README) для Space. По умолчанию полный текст карточки выводится в stdout.
# Full card (metadata + text)
>>> hf spaces card mteb/leaderboard
# Just the card metadata (from the YAML frontmatter)
>>> hf spaces card mteb/leaderboard --metadata
# Card metadata as JSON
>>> hf spaces card mteb/leaderboard --metadata --format json
# Just the text body (no YAML frontmatter)
>>> hf spaces card mteb/leaderboard --textПриостановка или перезапуск Space приводит к удалению его контейнера, поэтому все данные, записанные во временную файловую систему, теряются. Чтобы сохранить данные между перезапусками, смонтируйте Volume или bucket с помощью
hf spaces volumes set(подробности — вhf spaces volumes --help).
Приостановка Space
Используйте hf spaces pause, чтобы приостановить работу Space, когда вы им не пользуетесь (время простоя не тарифицируется). Позже вы можете запустить его снова с помощью hf spaces restart.
>>> hf spaces pause username/my-spaceПерезапуск Space
Используйте hf spaces restart для перезапуска Space. Передайте --factory-reboot, чтобы пересобрать Space с нуля без использования кэша сборки.
>>> hf spaces restart username/my-space
>>> hf spaces restart username/my-space --factory-rebootОжидание Space
Используйте hf spaces wait, чтобы заблокировать выполнение до завершения сборки/запуска Space и достижения им стабильного состояния. Команда завершается с кодом 0, если Space находится в состоянии RUNNING, и с ненулевым кодом в противном случае (например, BUILD_ERROR). Удобно для использования в скриптах после перезапуска или смены оборудования.
>>> hf spaces wait username/my-space
# With a timeout
>>> hf spaces wait username/my-space --timeout 5m
# Chain with restart
>>> hf spaces restart username/my-space && hf spaces wait username/my-spaceСписок доступного оборудования
Используйте hf spaces hardware, чтобы получить список всех доступных вариантов аппаратного обеспечения для Spaces, включая цены.
>>> hf spaces hardwareПроверьте вашу квоту ZeroGPU
Используйте hf spaces zero-gpu quota, чтобы проверить, сколько осталось вашей квоты ZeroGPU и когда она обновится. Это полезно для отслеживания использования при вызове ZeroGPU Spaces из скриптов, приложений или агентов.
>>> hf spaces zero-gpu quota
✓ ZeroGPU quota (in GPU-seconds)
remaining: 1810
base: 2400
resets_at: 2026-09-30T18:12:03+00:00
overquota_used: 0
>>> hf spaces zero-gpu quota --format json
{"remaining": 1810, "base": 2400, "resets_at": "2026-09-30T18:12:03+00:00", "overquota_used": 0}Если ваша квота на исходе, команда предлагает приобрести кредиты в настройках биллинга, чтобы продолжать использовать ZeroGPU за пределами дневной квоты (только для пользователей PRO, Team и Enterprise).
Обновление настроек Space
Используйте hf spaces settings для обновления настроек Space.
>>> hf spaces settings username/my-space --sleep-time 3600
>>> hf spaces settings username/my-space --hardware t4-medium--sleep-time: время простоя в секундах, после которого Space переходит в спящий режим. Используйте-1, чтобы Space никогда не засыпал. Доступно только на улучшенном оборудовании (см. документацию о времени сна Spaces).--hardware: тип аппаратного обеспечения (например,cpu-basic,t4-medium,l4x4). Выполнитеhf spaces hardware, чтобы увидеть все варианты.
Управление секретами Space
Используйте hf spaces secrets ls для вывода списка секретов в Space, hf spaces secrets add для добавления или обновления одного или нескольких секретов и hf spaces secrets delete для удаления. Передайте --secrets-file PATH, чтобы загрузить секреты из файла в формате .env. Существующие ключи будут перезаписаны.
>>> hf spaces secrets ls username/my-space
>>> hf spaces secrets add username/my-space -s OPENAI_API_KEY=sk-...
>>> hf spaces secrets add username/my-space --secrets-file .env.secrets
>>> hf spaces secrets delete username/my-space OPENAI_API_KEY --yesСекретные значения доступны только для записи, поэтому
hf spaces secrets lsотображает ключи, описания и метки времени обновления, но никогда не показывает сами секретные значения.
Управление переменными окружения Space
Используйте hf spaces variables для управления переменными окружения, не являющимися секретами, на Space. В отличие от секретов, переменные доступны для чтения, поэтому ls отображает и ключи, и значения. Передайте --env-file PATH при выполнении add, чтобы загрузить значения из файла в формате .env.
>>> hf spaces variables ls username/my-space
>>> hf spaces variables add username/my-space -e MODEL_ID=gpt2 -e MAX_TOKENS=512
>>> hf spaces variables add username/my-space --env-file .env
>>> hf spaces variables delete username/my-space MAX_TOKENS --yesПодключение к Space по SSH (режим разработки)
Используйте hf spaces ssh для открытия SSH-сессии в контейнере Dev Mode пространства. Если Dev Mode не включен, CLI предложит его включить (или используйте --auto, чтобы пропустить запрос).
Ваш публичный SSH-ключ должен быть зарегистрирован в настройках. Дополнительные сведения см. в документации по Dev Mode.
# SSH into a Space
>>> hf spaces ssh username/my-space
# Print the SSH command without running it
>>> hf spaces ssh username/my-space --dry-run
# Auto-enable Dev Mode if disabled
>>> hf spaces ssh username/my-space --auto
# Use a specific SSH key
>>> hf spaces ssh username/my-space -i ~/.ssh/id_ed25519hf papers
Используйте hf papers для получения списка, поиска, просмотра структурированной информации и чтения содержимого статей в формате Markdown на Hub.
Список статей
# List most recent daily papers
>>> hf papers ls
# List trending papers
>>> hf papers ls --sort=trending
# List papers from a specific date
>>> hf papers ls --date=2025-01-23
# List today's papers
>>> hf papers ls --date=today
# List papers from a specific week
>>> hf papers ls --week=2025-W09
# List papers from a specific month
>>> hf papers ls --month=2025-02
# List papers submitted by a specific user
>>> hf papers ls --submitter=akhaliq
# Limit results
>>> hf papers ls --sort=trending --limit=5Поиск статей
# Search papers by keyword
>>> hf papers search "vision language"
# Limit search results
>>> hf papers search "diffusion models" --limit=10
# Output as JSON
>>> hf papers search "attention" --format=jsonПолучить информацию о статье
# Get structured metadata for a paper (returns JSON)
>>> hf papers info 2601.15621Чтение статьи в формате Markdown
# Read the full paper content as markdown
>>> hf papers read 2601.15621hf discussions
Используйте hf discussions для управления обсуждениями и pull request в репозиториях Hub прямо из терминала. Вы можете просматривать список, открывать, создавать, комментировать, закрывать, повторно открывать и объединять как обсуждения, так и PR. Полное руководство по работе с функциями сообщества Hub см. в руководстве по обсуждениям и pull request.
Список обсуждений
Чтобы получить список открытых обсуждений и PR в репозитории, передайте ID репозитория в hf discussions list (или его сокращённую форму hf discussions ls):
>>> hf discussions list username/my-modelВы можете сузить результаты по типу (discussion или pull_request), статусу (open, closed, merged или all) или автору:
>>> hf discussions list username/my-model --kind pull_request --status merged
>>> hf discussions list username/my-model --author aliceДля скриптов используйте --format json, чтобы получить структурированный вывод, или --quiet, чтобы вывести только номера обсуждений (по одному в строке):
>>> hf discussions list username/my-model --format json
>>> hf discussions ls username/my-model --quietПолучить информацию о дискуссии или PR
Чтобы просмотреть конкретное обсуждение или PR, передайте идентификатор репозитория и номер обсуждения:
>>> hf discussions info username/my-model 5Вывод содержит метаданные обсуждения (название, статус, автор и т. д.) вместе со полным списком событий разговора. Чтобы отобразить дифф pull request, используйте hf discussions diff.
Используйте --format json для вывода в машиночитаемом формате, а для удаления ANSI-цветов при передаче данных в другие инструменты задайте переменную NO_COLOR=1.
Создайте обсуждение или PR
Чтобы начать новое обсуждение, укажите заголовок с помощью --title. При необходимости вы можете добавить описание в командной строке с помощью --body или загрузить его из файла с помощью --body-file:
>>> hf discussions create username/my-model --title "Bug report"
>>> hf discussions create username/my-model --title "Feature request" --body "Please add X"
>>> hf discussions create username/my-model --title "Report" --body-file report.mdЧтобы создать pull request вместо обычного обсуждения, добавьте флаг --pull-request:
>>> hf discussions create username/my-model --title "Fix typo" --pull-requestКомментарий к обсуждению или PR
Добавьте комментарий к существующей дискуссии или PR, указав её номер. Текст комментария можно передать напрямую с помощью --body, прочитать из файла с помощью --body-file или передать из stdin с помощью --body-file -:
>>> hf discussions comment username/my-model 5 --body "Thanks for reporting!"
>>> hf discussions comment username/my-model 5 --body-file review.md
>>> echo "LGTM" | hf discussions comment username/my-model 5 --body-file -Редактировать комментарий
Чтобы отредактировать существующий комментарий на месте, передайте номер обсуждения и ID комментария. ID комментариев можно получить с помощью hf discussions info:
>>> hf discussions edit username/my-model 5 abc123 --body "Updated comment."
>>> hf discussions edit username/my-model 5 abc123 --body-file fixed.mdПодключение изображений и видео
Передайте --attach в hf discussions create, comment или edit, чтобы загрузить файл изображения, видео или аудио и вставить его в текст, как при перетаскивании файла в поле комментария на Hub. Если в тексте уже есть ссылка на файл, например , то эта ссылка будет указывать на загруженный файл. В противном случае файл будет добавлен в конец текста. Чтобы задать альтернативный текст для добавленного изображения, добавьте его после символа #:
>>> hf discussions create username/my-model --title "Fix rendering" --pr --body "Before: " --attach ./before.png --attach "./after.png#After the fix"
>>> hf discussions comment username/my-model 5 --body "Here is a demo:" --attach demo.mp4Поддерживаемые форматы: PNG, JPEG, GIF, WebP, MP4, MOV, WebM, MP3 и WAV, до 10 МБ (до 50 МБ для видео).
Закрытие, повторное открытие и слияние
Вы можете закрыть обсуждение или PR с помощью hf discussions close. По умолчанию система запросит подтверждение. Передайте --yes, чтобы пропустить запрос, и --comment, чтобы оставить сообщение при закрытии:
>>> hf discussions close username/my-model 5
>>> hf discussions close username/my-model 5 --yes --comment "Resolved"Чтобы повторно открыть ранее закрытое обсуждение, используйте hf discussions reopen:
>>> hf discussions reopen username/my-model 5 --yesЧтобы объединить pull request, используйте hf discussions merge:
>>> hf discussions merge username/my-model 5 --yesПереименование и сравнение
Вы можете переименовать обсуждение, указав новый заголовок:
>>> hf discussions rename username/my-model 5 "Updated title"Чтобы просмотреть diff pull request непосредственно в терминале, используйте hf discussions diff:
>>> hf discussions diff username/my-model 5hf repos
hf repos позволяет просматривать список, создавать, дублировать, удалять и перемещать репозитории, а также обновлять их настройки и удалять файлы на Hugging Face Hub. Включает подкоманды для управления ветками и тегами.
Список репозиториев
Используйте hf repos ls, чтобы получить список всех ваших репозиториев (моделей, наборов данных, spaces и buckets) с информацией о хранилище, отсортированных по объему занятого места. По умолчанию отображаются только первые 30 репозиториев:
# List all your repos (first 30)
>>> hf repos ls
REPOSITORY TYPE UPDATED VISIBILITY STORAGE % OF TOTAL
------------------------ ------- ---------- ---------- -------- ----------
username/bucket-raw bucket 2026-04-29 public 1.7 TB 72.3%
username/my-model model 2026-05-06 public 4.8 GB 18.1%
username/my-dataset dataset 2024-09-14 private 598.4 MB 5.2%
Hint: Showing 30 of 42 repos. Use `--limit 0` to list all.Фильтруйте по типу репозитория, ищите по имени или измените лимит:
# List only models
>>> hf repos ls --type model
# Search by name
>>> hf repos ls --search "bert"
# List repos from an organization
>>> hf repos ls --namespace my-org
# Combine filters
>>> hf repos ls --namespace my-org --type dataset --search "train"
# List all repos (no limit)
>>> hf repos ls --limit 0Используйте --format json для скриптов или -q для вывода только идентификаторов. При передаче данных через конвейер используйте --limit 0, чтобы экспортировать все репозитории:
>>> hf repos ls --limit 0 --format json | jq '.[].id'
>>> hf repos ls -qСоздать репозиторий
>>> hf repos create Wauplin/my-cool-model
Successfully created Wauplin/my-cool-model on the Hub.
Your repo is now available at https://huggingface.co/Wauplin/my-cool-modelСоздайте приватный набор данных или Space:
>>> hf repos create my-cool-dataset --repo-type dataset --private
>>> hf repos create my-gradio-space --repo-type space --sdk gradioИспользуйте --exist-ok, если репозиторий может уже существовать, и --resource-group-id, чтобы указать целевую группу ресурсов Enterprise.
Создание репозитория в определённом регионе:
>>> hf repos create my-model --region usДублирование репозитория
Используйте hf repos duplicate, чтобы скопировать существующую модель, набор данных или Space в ваш аккаунт (или в организацию). Копирование выполняется на сервере и сохраняет историю git:
>>> hf repos duplicate openai/gdpval --type dataset
>>> hf repos duplicate openai/gdpval myorg/my-gdpval --type dataset --privateФайлы LFS/Xet нового репозитория могут продолжать копироваться в фоновом режиме после завершения выполнения команды. В этом случае выводится предупреждение, и загрузка этих файлов из нового репозитория может завершаться ошибкой до завершения копирования.
Удаление репозитория
>>> hf repos delete Wauplin/my-cool-modelНаборы данных и Spaces:
>>> hf repos delete my-cool-dataset --repo-type dataset
>>> hf repos delete my-gradio-space --repo-type spaceПереместить репозиторий
>>> hf repos move old-namespace/my-model new-namespace/my-modelОбновить настройки репозитория
>>> hf repos settings Wauplin/my-cool-model --gated auto
>>> hf repos settings Wauplin/my-cool-model --private true
>>> hf repos settings Wauplin/my-cool-model --private false--gated: одно из значенийauto,manual,false--private true|false: задаёт приватность репозитория
Удаление файлов из репозитория
Подкоманда hf repos delete-files <repo_id> позволяет удалять файлы из репозитория. Ниже приведены примеры использования.
Удалить папку:
>>> hf repos delete-files Wauplin/my-cool-model folder/
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...Удаление нескольких файлов:
>>> hf repos delete-files Wauplin/my-cool-model file.txt folder/pytorch_model.bin
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...Используйте шаблоны с подстановочными символами для удаления наборов файлов. Шаблоны представляют собой стандартные подстановочные символы (globbing-шаблоны), описанные здесь. Соответствие шаблонам основано на fnmatch.
Обратите внимание, что
fnmatchсопоставляет*через границы путей, в отличие от традиционного глоббинга в Unix-оболочке. Например,"data/*.json"будет соответствовать какdata/file.jsonтак иdata/subdir/file.json. Чтобы сопоставлять только файлы в текущей директории, необходимо перечислить их явно или использовать более специфичные шаблоны.
>>> hf repos delete-files Wauplin/my-cool-model "*.txt" "folder/*.bin"
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...Для удаления файлов из репозитория необходимо пройти аутентификацию и получить соответствующие права доступа. По умолчанию используется токен, сохранённый локально (с помощью hf auth login). Если вы хотите выполнить аутентификацию явно, используйте параметр --token:
>>> hf repos delete-files --token=hf_**** Wauplin/my-cool-model file.txthf repos branch
Используйте hf repos branch для создания и удаления ветвей в репозиториях на Hub.
# Create a branch
>>> hf repos branch create Wauplin/my-cool-model dev
# Create a branch from a specific revision
>>> hf repos branch create Wauplin/my-cool-model release-1 --revision refs/pr/104
# Delete a branch
>>> hf repos branch delete Wauplin/my-cool-model devВсе команды принимают
--repo-type(одно из значенийmodel,dataset,space) и--token, если требуется явная аутентификация. Используйте--helpдля любой команды, чтобы увидеть все параметры.
hf cache
Используйте hf cache для управления локальным каталогом кэша Hugging Face. В кэше хранятся модели, наборы данных, Spaces и ядра, загруженные с Hub.
# List cached repositories
>>> hf cache ls
# List cached revisions
>>> hf cache ls --revisions
# Remove specific items from cache
>>> hf cache rm model/gpt2
# Remove unreferenced revisions
>>> hf cache prune
# Verify cached file checksums
>>> hf cache verify gpt2hf cache ls
Используйте hf cache ls, чтобы просмотреть содержимое локального кэша Hugging Face. По умолчанию информация группируется по репозиториям:
>>> hf cache ls
ID SIZE LAST_ACCESSED LAST_MODIFIED REFS
--------------------------- -------- ------------- ------------- -----------
dataset/nyu-mll/glue 157.4M 2 days ago 2 days ago main script
model/LiquidAI/LFM2-VL-1.6B 3.2G 4 days ago 4 days ago main
model/microsoft/UserLM-8b 32.1G 4 days ago 4 days ago main
Found 3 repo(s) for a total of 5 revision(s) and 35.5G on disk.Добавьте --revisions, чтобы перейти к конкретным снимкам, и объединяйте фильтры, чтобы сосредоточиться на главном:
>>> hf cache ls --filter "size>30g" --revisions
ID REVISION SIZE LAST_MODIFIED REFS
------------------------- ---------------------------------------- -------- ------------- ----
model/microsoft/UserLM-8b be8f2069189bdf443e554c24e488ff3ff6952691 32.1G 4 days ago main
Found 1 repo(s) for a total of 1 revision(s) and 32.1G on disk.Команда поддерживает несколько форматов вывода для скриптов: --format json выводит структурированные объекты, --format csv записывает строки, разделённые запятыми, а --quiet выводит только идентификаторы. Используйте --sort, чтобы упорядочить записи по accessed, modified, name или size (добавьте :asc или :desc, чтобы задать порядок сортировки), а --limit — чтобы ограничить результат первыми N записями. Сочетайте эти параметры с --cache-dir, чтобы указать альтернативные расположения кэша. См. руководство Управление кэшем для продвинутых сценариев.
Удалите записи кэша, выбранные с помощью hf cache ls --q, передав их идентификаторы в hf cache rm:
>>> hf cache rm $(hf cache ls --filter "accessed>1y" -q) -y
About to delete 2 repo(s) totalling 5.31G.
- model/meta-llama/Llama-3.2-1B-Instruct (entire repo)
- model/hexgrad/Kokoro-82M (entire repo)
Deleted 2 repo(s) and 2 revision(s); freed 5.31G.hf cache rm
hf cache rm удаляет кэшированные репозитории, отдельные ревизии или отдельные файлы. Передайте один или несколько идентификаторов репозиториев (model/bert-base-uncased), URI hf:// или хеши ревизий:
>>> hf cache rm model/LiquidAI/LFM2-VL-1.6B
About to delete 1 repo(s) totalling 3.2G.
- model/LiquidAI/LFM2-VL-1.6B (entire repo)
Proceed with deletion? [y/N]: y
Deleted 1 repo(s) and 2 revision(s); freed 3.2G.Также поддерживаются URI уровня репозитория hf://:
>>> hf cache rm hf://models/openai-community/gpt2 --dry-run
About to delete 1 repo(s) totalling 1.1G.
- model/openai-community/gpt2 (entire repo)
Dry run: no files were deleted.Чтобы удалить один файл, а не весь репозиторий, например, одну GGUF-квантизацию, передайте URI файла hf://. Файл удаляется из всех кэшированных ревизий репозитория, а его blob удаляется только если на него больше не ссылаются другие кэшированные файлы:
>>> hf cache rm hf://models/unsloth/gemma-3-27b-it-GGUF/gemma-3-27b-it-Q4_K_M.gguf --dry-run
About to delete 1 file(s) totalling 16.5G.
- model/unsloth/gemma-3-27b-it-GGUF@3f4b5c1d2e6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c/gemma-3-27b-it-Q4_K_M.gguf
Dry run: no files were deleted.Ревизия остаётся доступной, а удалённый файл будет скачан повторно в следующий раз, когда он понадобится. Пути должны совпадать точно: папки и глобальные шаблоны не поддерживаются, а файловые цели нельзя смешивать с репозиториями или ревизиями в одном вызове.
Смешивайте репозитории и конкретные ревизии в одном вызове. Используйте --dry-run, чтобы просмотреть влияние, или --yes, чтобы пропустить запрос подтверждения — удобно в автоматизированных скриптах:
>>> hf cache rm model/t5-small 8f3ad1c --dry-run
About to delete 1 repo(s) and 1 revision(s) totalling 1.1G.
- model/t5-small:
8f3ad1c [main] 1.1G
Dry run: no files were deleted.При работе вне расположения кэша по умолчанию используйте команду в паре с --cache-dir PATH.
hf cache prune
hf cache prune — это удобная команда, освобождающая место, занятое мусором в кэше: все отсоединённые (неиспользуемые) ревизии (сохраняются только те, которые по-прежнему доступны через ветку или тег), оставшиеся файлы .incomplete от прерванных загрузок, а также общие блоки данных, на которые больше не ссылаются ни один из кэшированных репозиториев:
>>> hf cache prune
About to delete 3 unreferenced revision(s) and 2 incomplete download(s) (2.4G total).
- model/t5-small:
1c610f6b [refs/pr/1] 820.1M
d4ec9b72 [(detached)] 640.5M
- dataset/google/fleurs:
2b91c8dd [(detached)] 937.6M
Proceed? [y/N]: y
Deleted 3 unreferenced revision(s) and 2 incomplete download(s); freed 2.4G.Файлы .incomplete — это частичные загрузки, оставшиеся после прерывания скачивания. Они не отслеживаются командами hf cache ls/rm (которые работают на уровне ревизий), поэтому hf cache ls указывает на них с подсказкой, а hf cache prune удаляет их автоматически.
Как и в случае с другими командами кэша, доступны параметры --dry-run, --yes и --cache-dir. Дополнительные примеры приведены в руководстве Управление кэшем.
hf cache verify
Используйте hf cache verify для проверки локальных файлов по их контрольным суммам на Hub. Можно проверить как снимок кэша, так и обычную локальную директорию.
Примеры:
# Verify main revision of a model in cache
>>> hf cache verify deepseek-ai/DeepSeek-OCR
# Verify a specific revision
>>> hf cache verify deepseek-ai/DeepSeek-OCR --revision refs/pr/5
>>> hf cache verify deepseek-ai/DeepSeek-OCR --revision ef93bf4a377c5d5ed9dca78e0bc4ea50b26fe6a4
# Verify a private repo
>>> hf cache verify me/private-model --token hf_***
# Verify a dataset
>>> hf cache verify karpathy/fineweb-edu-100b-shuffle --repo-type dataset
# Verify files in a local directory
>>> hf cache verify deepseek-ai/DeepSeek-OCR --local-dir /path/to/repoПо умолчанию команда предупреждает об отсутствующих или лишних файлах. Используйте флаги, чтобы превратить эти предупреждения в ошибки:
>>> hf cache verify deepseek-ai/DeepSeek-OCR --fail-on-missing-files --fail-on-extra-filesПри успешном выполнении вы увидите сводку:
✅ Verified 13 file(s) for 'deepseek-ai/DeepSeek-OCR' (model) in ~/.cache/huggingface/hub/models--meta-llama--Llama-3.2-1B-Instruct/snapshots/9213176726f574b556790deb65791e0c5aa438b6 All checksums match.
Если обнаруживаются несоответствия, команда выводит подробный список и завершается с ненулевым кодом состояния.
hf repos tag
Используйте hf repos tag для создания, просмотра и удаления тегов репозиториев на Hub.
# Create a tag
>>> hf repos tag create my-model v1.0
# List tags
>>> hf repos tag list my-model
# Delete a tag
>>> hf repos tag delete my-model v1.0Добавить метку к модели
Чтобы добавить тег к репозиторию, необходимо указать repo_id и имя тега tag:
>>> hf repos tag create Wauplin/my-cool-model v1.0
You are about to create tag v1.0 on model Wauplin/my-cool-model
Tag v1.0 created on Wauplin/my-cool-modelДобавление тега модели для конкретного ревизии
Если вы хотите отметить конкретную ревизию, используйте параметр --revision. По умолчанию тег будет создан на ветке main:
>>> hf repos tag create Wauplin/my-cool-model v1.0 --revision refs/pr/104
You are about to create tag v1.0 on model Wauplin/my-cool-model
Tag v1.0 created on Wauplin/my-cool-modelДобавить метку к набору данных или Space
Если вы хотите добавить метки к набору данных или Space, необходимо указать параметр --repo-type:
>>> hf repos tag create bigcode/the-stack v1.0 --repo-type dataset
You are about to create tag v1.0 on dataset bigcode/the-stack
Tag v1.0 created on bigcode/the-stackСписок тегов
Чтобы получить список всех тегов репозитория, используйте подкоманду list (или ls):
>>> hf repos tag list Wauplin/gradio-space-ci --repo-type space
Tags for space Wauplin/gradio-space-ci:
0.2.2
0.2.1
0.2.0
0.1.2
0.0.2
0.0.1Удалить тег
Чтобы удалить тег, используйте подкоманду delete:
>>> hf repos tag delete Wauplin/my-cool-model v1.0
You are about to delete tag v1.0 on model Wauplin/my-cool-model
Proceed? [Y/n] y
Tag v1.0 deleted on Wauplin/my-cool-modelВы также можете передать -y, чтобы пропустить шаг подтверждения.
hf env
Команда hf env выводит сведения о конфигурации вашей системы. Это полезно при создании обращения на GitHub, чтобы помочь разработчикам разобраться в вашей проблеме.
>>> hf env
Copy-and-paste the text below in your GitHub issue.
- huggingface_hub version: 1.0.0.rc6
- Platform: Linux-6.8.0-85-generic-x86_64-with-glibc2.35
- Python version: 3.11.14
- Running in iPython ?: No
- Running in notebook ?: No
- Running in Google Colab ?: No
- Running in Google Colab Enterprise ?: No
- Token path ?: /home/wauplin/.cache/huggingface/token
- Has saved token ?: True
- Who am I ?: Wauplin
- Configured git credential helpers: store
- Installation method: unknown
- Torch: N/A
- httpx2: 2.0.0
- hf_xet: 1.1.10
- gradio: 5.41.1
- tensorboard: N/A
- pydantic: 2.11.7
- ENDPOINT: https://huggingface.co
- HF_HUB_CACHE: /home/wauplin/.cache/huggingface/hub
- HF_ASSETS_CACHE: /home/wauplin/.cache/huggingface/assets
- HF_TOKEN_PATH: /home/wauplin/.cache/huggingface/token
- HF_STORED_TOKENS_PATH: /home/wauplin/.cache/huggingface/stored_tokens
- HF_HUB_OFFLINE: False
- HF_HUB_DISABLE_TELEMETRY: False
- HF_HUB_DISABLE_PROGRESS_BARS: None
- HF_HUB_DISABLE_SYMLINKS_WARNING: False
- HF_HUB_DISABLE_EXPERIMENTAL_WARNING: False
- HF_HUB_DISABLE_IMPLICIT_TOKEN: False
- HF_HUB_DISABLE_XET: False
- HF_HUB_DISABLE_SHARED_BLOBS: False
- HF_HUB_ETAG_TIMEOUT: 10
- HF_HUB_DOWNLOAD_TIMEOUT: 10hf jobs
Запускайте вычислительные задачи на инфраструктуре Hugging Face с привычным интерфейсом, похожим на Docker.
hf jobs — это инструмент командной строки, позволяющий запускать любые задачи на инфраструктуре Hugging Face (включая GPU и TPU!) с помощью простых команд. Представьте себе docker run, но для выполнения кода на A100.
Общий обзор Jobs и ценообразования см. в документации Hub Jobs. Использование Python API наряду с CLI описано в руководстве по запуску и управлению Jobs.
# Directly run Python code
>>> hf jobs run --name hello-world python:3.12 python -c 'print("Hello from the cloud!")'
# Use GPUs without any setup
>>> hf jobs run --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
... python -c "import torch; print(torch.cuda.get_device_name())"
# Run in an organization account
>>> hf jobs run --namespace my-org-name python:3.12 python -c 'print("Running in an org account")'
# Run from Hugging Face Spaces
>>> hf jobs run hf.co/spaces/lhoestq/duckdb duckdb -c 'select "hello world"'
# Run a Python script with `uv` (experimental)
>>> hf jobs uv run --name my-script my_script.pyHugging Face Jobs доступны любому пользователю или организации с предоплаченными кредитами.
Быстрый старт
1. Запустите первую задачу
# Run a simple Python script
>>> hf jobs run python:3.12 python -c 'print("Hello from HF compute!")'Эта команда запускает задание и выводит журналы. Вы можете передать --detach, чтобы запустить Job в фоновом режиме и вывести только идентификатор Job. Добавьте -q, чтобы вывести только идентификатор Job, что удобно для его сохранения в скрипте:
>>> JOB_ID=$(hf jobs run -dq python:3.12 python train.py)
>>> hf jobs wait "$JOB_ID"2. Проверьте статус задания
# List your running jobs
>>> hf jobs ls
# List all jobs
>>> hf jobs ls -a
# Inspect the status of a job
>>> hf jobs inspect <job_id>
# View logs from a job
>>> hf jobs logs <job_id>
# View resources usage stats and metrics of running jobs
>>> hf jobs stats
# View resources usage stats and metrics of some jobs
>>> hf jobs stats [job_ids]...
# Follow live stats until the jobs complete
>>> hf jobs stats -f [job_ids]...
# Cancel a job
>>> hf jobs cancel <job_id>
# Wait until one or more jobs finish (exit code 0 only if all jobs completed successfully)
>>> hf jobs wait <job_id> [<job_id>...]
# Wait for all currently running jobs
>>> hf jobs ls -q | xargs hf jobs waitНеотсоединённые hf jobs run и hf jobs wait завершаются с ненулевым кодом, если Job завершается с ошибкой, поэтому вы можете объединять команды с помощью &&:
>>> hf jobs run python:3.12 python train.py && echo "training succeeded"3. Запуск на GPU
Вы также можете запускать задания на GPU или TPU с помощью опции --flavor. Например, чтобы запустить задание PyTorch на GPU A10G:
# Use an A10G GPU to check PyTorch CUDA
>>> hf jobs run --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
... python -c 'import torch; print(f"This code ran with the following GPU: {torch.cuda.get_device_name()}")'При запуске этого кода вы увидите следующий вывод!
This code ran with the following GPU: NVIDIA A10G
Используйте --, чтобы отделить опции Jobs от аргументов, передаваемых вашей команде или скрипту.
Jobs не интерпретирует опции после --.
>>> hf jobs run --flavor cpu-basic python:3.12 -- python --helpВсё готово! Теперь вы запускаете код на инфраструктуре Hugging Face.
Частые сценарии использования
- Обучение моделей: дообучение или обучение моделей на GPU (T4, A10G, A100) без управления инфраструктурой
- Генерация синтетических данных: создание наборов данных большого масштаба с помощью LLM на мощном оборудовании
- Обработка данных: обработка массивных наборов данных с конфигурациями с высокой загрузкой CPU для параллельных задач
- Пакетный вывод: Запуск офлайн-вывода на тысячах образцов с использованием оптимизированных GPU-конфигураций
- Эксперименты и бенчмарки: Проведение ML-экспериментов на едином оборудовании для воспроизводимых результатов
- Разработка и отладка: тестирование GPU-кода без локальной установки CUDA
Передача переменных окружения и секретов
Вы можете передать переменные окружения в вашу задачу с помощью
# Pass environment variables
>>> hf jobs run -e FOO=foo -e BAR=bar python:3.12 python -c 'import os; print(os.environ["FOO"], os.environ["BAR"])'# Pass an environment from a local .env file
>>> hf jobs run --env-file .env python:3.12 python -c 'import os; print(os.environ["FOO"], os.environ["BAR"])'# Pass secrets by name - the value is read from your environment, never from the command line
>>> hf jobs run -s MY_SECRET python:3.12 python -c 'import os; print(os.environ["MY_SECRET"])'# Pass secrets from a local .env.secrets file - they will be encrypted server side
>>> hf jobs run --secrets-file .env.secrets python:3.12 python -c 'import os; print(os.environ["MY_SECRET"])'# Or pipe them in, so the values touch neither the command line nor the disk
>>> printf 'MY_SECRET=psswrd\n' | hf jobs run --secrets-file - python:3.12 python -c 'import os; print(os.environ["MY_SECRET"])'Секреты шифруются на стороне сервера во всех трёх формах. -s MY_SECRET=psswrd тоже работает, но в этом случае значение попадает в историю командной строки и в список процессов (/proc/<pid>/cmdline в Linux), поэтому CLI выводит предупреждение в stderr при использовании этой формы; оставляйте её для значений, которые не являются действительно конфиденциальными. То же самое относится и к --token <value>: предпочитайте hf auth login или переменную окружения HF_TOKEN. Файл переменных окружения или секретов должен быть доступен только вам (chmod 600) — CLI предупредит, если это не так.
Используйте
--secrets HF_TOKEN, чтобы неявно передать локальный токен Hugging Face. При таком синтаксисе секрет извлекается из переменной окружения. ДляHF_TOKENпри отсутствии переменной окружения может быть прочитан файл токена, расположенный в домашней папке Hugging Face.
Встроенные переменные окружения
Внутри контейнера задания автоматически доступны следующие переменные окружения:
| Переменная | Описание |
|---|---|
JOB_ID | Уникальный идентификатор текущей задачи. Используйте его для программной ссылки на задачу. |
ACCELERATOR | Тип доступного ускорителя (например, t4-medium, a10g-small, a100x4). Пусто, если ускоритель отсутствует. |
CPU_CORES | Количество ядер CPU, доступных для задачи (например, 2, 4, 8). |
MEMORY | Объем памяти, доступный для задания (например, 16Gi, 32Gi). |
# Access job environment information
>>> hf jobs run python:3.12 python -c "import os; print(f'Job: {os.environ.get(\"JOB_ID\")}, CPU: {os.environ.get(\"CPU_CORES\")}, Mem: {os.environ.get(\"MEMORY\")}')"Тайм-аут задания
У заданий по умолчанию установлено время ожидания 30 минут, после чего они автоматически останавливаются. Для длительных задач, таких как обучение моделей, задайте собственное время ожидания с помощью параметра --timeout:
# Set timeout in seconds (default unit)
>>> hf jobs run --timeout 7200 python:3.12 python train.py
# Use time units: s (seconds), m (minutes), h (hours), d (days)
>>> hf jobs run --timeout 2h pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel python train.py
>>> hf jobs run --timeout 90m python:3.12 python process_data.py
>>> hf jobs run --timeout 1.5h python:3.12 python train.py # floats are supportedПараметр --timeout также работает со сценариями UV и запланированными заданиями:
# UV script with timeout
>>> hf jobs uv run --timeout 2h training_script.py
# Scheduled job with timeout
>>> hf jobs scheduled run @daily --timeout 4h python:3.12 python daily_task.pyЕсли время выполнения вашей задачи превышает установленный таймаут, она будет автоматически завершена. Всегда устанавливайте подходящий таймаут с запасом для длительных задач, чтобы избежать неожиданного завершения работы.
Повторная отправка и перезапуск задачи
--attempts задаёт максимальное количество попыток, включая первый запуск. Работает с Docker, UV и запланированными Jobs. Повторный запуск Job создаёт новый Job с тем же сохранённым spec:
>>> hf jobs run --attempts 3 --detach python:3.12 python train.py
>>> hf jobs rerun <job_id>Значение количества попыток, равное 3, позволяет выполнить до двух повторных попыток при сбое Job. hf jobs rerun также переиспользует исходное количество попыток. Как и hf jobs run, он транслирует логи нового Job до его завершения. Используйте --detach, чтобы сразу вернуться.
Аппаратное обеспечение
Доступные варианты --flavor:
- CPU:
cpu-basic,cpu-upgrade - GPU:
t4-small,t4-medium,l4x1,l4x4,a10g-small,a10g-large,a10g-largex2,a10g-largex4,a100-large - TPU:
v5e-1x1,v5e-2x2,v5e-2x4
(обновлено в 07/2025 из документации Hugging Face suggested_hardware)
Томы
Подключите том к диску Job с помощью -v или --volume.
Вы можете подключить любой репозиторий Hugging Face (модель/датасет/спейс) или Storage Bucket с помощью схемы URL hf://. Например:
- подключить репозиторий модели:
-v hf://openai/gpt-oss-120b:/model - подключить репозиторий датасета:
-v hf://datasets/HuggingFaceFW/fineweb:/data - подключить хранилище:
-v hf://buckets/username/my-bucket:/mnt - подключить пространство:
-v hf://spaces/username/my-space:/app - подключить подпапку внутри репозитория:
-v hf://datasets/org/ds/train:/data
Затем вы можете использовать смонтированный том как локальный каталог:
# Docker Job with a mounted volume as input
>>> hf jobs run -v hf://datasets/HuggingFaceFW/fineweb:/dataset \
... duckdb/duckdb duckdb -c "SELECT * FROM '/dataset/**/*.parquet' LIMIT 5"
# UV Job with a mounted volume to save checkpoints when training a model
>>> hf jobs uv run -v hf://buckets/username/my-bucket:/training-outputs \
... sft.py --output-dir /training-outputs/training-v3-final ...Модели, наборы данных и пространства всегда монтируются только для чтения. Бuckets хранения по умолчанию доступны для чтения и записи — это особенно полезно для часто изменяемых данных, так как файлы можно перезаписывать или удалять на месте.
Используйте :ro, чтобы включить режим только для чтения:
- подключить хранилище в режиме только для чтения:
-v hf://buckets/username/my-bucket:/mnt:ro
Подключение локальных данных
Исходная сторона -v также может быть локальным каталогом. Сначала он синхронизируется с вашим jobs-artifacts Storage Bucket, а затем полученная папка в бакете монтируется в Job:
>>> hf jobs uv run -v ./my-data:/data process.pyПовторное выполнение команды загружает только новые или изменённые файлы. Локальные каталоги по умолчанию монтируются в режиме только для чтения. Используйте :rw, чтобы разрешить Job запись в том, например, для получения результатов после завершения Job (подойдёт и пустой локальный каталог):
>>> hf jobs uv run -v ./pdfs:/input -v ./md-out:/output:rw ocr.py
...
Hint: Volume '/output' is mounted read-write. Once the job is over, pull back its data with:
hf buckets sync hf://buckets/username/jobs-artifacts/md-out-a1b2c3d4 ./md-outМетки
Добавьте метки к Job с помощью -l или --label. Метки — это пары ключ=значение, которые добавляют метаданные к Job. Чтобы назначить Job две метки, повторите флаг метки (-l или --label):
>>> hf jobs run -l my-label --label foo=bar ubuntu echo "This Job has multiple labels"Ключ my-label не указывает значение, поэтому его значение по умолчанию — пустая строка ("").
Используйте --name, чтобы добавить метку name при создании Job. Имена облегчают поиск и идентификацию Job в интерфейсе; они необязательны и не обязаны быть уникальными. Если вы не передаёте --name, имя формируется автоматически из Docker-образа или скрипта, а также из короткого хэша команды и разрешённых настроек среды выполнения (flavor, timeout, значения переменных окружения, …), поэтому одна и та же конфигурация всегда порождает одно и то же имя (например, python:3.12 foo --truc → python-3-12-1a2b3c4d). Изменение настройки меняет имя, даже если команда остаётся прежней. Вы также можете переименовать существующий Job:
>>> hf jobs run --name training-v2 python:3.12 python train.py
>>> hf jobs labels <job_id> --name training-v2Используйте --status, --label и --name в hf jobs ls для фильтрации Jobs. --status принимает один или несколько статусов, --label принимает пары key=value, а --name является сокращением для --label name=NAME. Job должен соответствовать каждому фильтру, чтобы быть включенным в список. Имя Job также отображается в отдельном столбце NAME:
# Show completed Jobs
>>> hf jobs ls -a --status completed
# Show running or scheduling Jobs
>>> hf jobs ls --status running,scheduling
# Show Jobs named `training-v2`
>>> hf jobs ls -a --name training-v2
# Show Jobs with the `model=Qwen3-06B` label
>>> hf jobs ls -a --label model=Qwen3-06B
# Combine filters: running Jobs labelled both `env=prod` and `team=ml`
>>> hf jobs ls --status running --label env=prod --label team=mlПо умолчанию hf jobs ps отображает не более 100 задач, чтобы не перегружать терминал. Используйте --limit, чтобы изменить это значение, или --limit 0, чтобы отобразить все задачи:
# Show up to 500 Jobs
>>> hf jobs ps -a --limit 500
# Show all Jobs (no limit)
>>> hf jobs ps -a --limit 0Открыть порты задания
Используйте --expose для порта с защитой по токену и --expose-public для порта, который должен разрешать доступ без аутентификации. Оба флага можно повторять и комбинировать, а также они работают с Docker, UV и запланированными Jobs.
# Start a Job with a public HTTP server
>>> hf jobs run --detach --expose-public 8000 python:3.12 python -m http.server 8000
# Replace the configuration on a running Job: port 8000 is private, 9000 is public
>>> hf jobs expose <job_id> 8000 --public 9000
# Close all exposed ports
>>> hf jobs expose <job_id> --clearhf jobs expose принимает защищённые токеном порты в качестве позиционных аргументов, а публичные порты — с флагом --public. Изменение применяется без перезапуска Job. Порты, не указанные в списке замены, закрываются.
Подключение к Job по SSH
Передайте --ssh в hf jobs run (или hf jobs uv run), чтобы сделать контейнер Job доступным по SSH, затем подключитесь с помощью hf jobs ssh:
# Start a job with SSH enabled
>>> hf jobs run --ssh --detach python:3.12 sleep infinity
# Open an SSH session into it
>>> hf jobs ssh <job_id>
# Print the SSH command instead of running it
>>> hf jobs ssh <job_id> --dry-run
# Use a specific identity file
>>> hf jobs ssh <job_id> -i ~/.ssh/id_ed25519Доступ разрешен только пользователям с правами на запись в пространство имен задачи (создателю задачи или членам организации-владельца), аутентифицированным по SSH-публичному ключу, зарегистрированному на https://huggingface.co/settings/keys.
Группы сетей
Передайте --network-group <name> в hf jobs run (или hf jobs uv run), чтобы Jobs в одном и том же namespace и resource group могли взаимодействовать друг с другом на всех портах. Внутри каждого участника $HF_NETWORK_GROUP_HOSTNAME разрешается в адрес каждого Job в группе, а ${HF_NETWORK_GROUP_PREFIX}<alias> — в адрес участников, заявивших alias с помощью --network-alias <alias>:
# Start a server, reachable by the other members of the group as "master"
>>> hf jobs run --detach --network-group train --network-alias master python:3.12 python -m http.server 8000
# Start a client in the same group
>>> hf jobs run --detach --network-group train python:3.12 sh -c 'curl --retry 10 --retry-connrefused "http://${HF_NETWORK_GROUP_PREFIX}master:8000/"'Участники разрешаются до того, как они будут готовы, поэтому подключайтесь с повторными попытками. Имена групп и псевдонимы — это строчные буквы, цифры и дефисы, максимум 46 и 34 символа соответственно.
UV-скрипты (экспериментально)
Запуск скриптов UV (Python-скриптов с встроенными зависимостями) на инфраструктуре HF. Скрипты UV — это Python-скрипты, в которых зависимости указаны непосредственно в файле с использованием специального синтаксиса комментариев.
# Run a UV script (creates temporary repo)
>>> hf jobs uv run my_script.py
# Run with persistent repo
>>> hf jobs uv run --repo my-uv-scripts my_script.py
# Run with GPU
>>> hf jobs uv run --flavor t4-small ml_training.py
# Pass arguments to script
>>> hf jobs uv run process.py input.csv output.parquet
# Add dependencies
>>> hf jobs uv run --with transformers --with torch train.py
# Run a script directly from a URL
>>> hf jobs uv run https://huggingface.co/datasets/username/scripts/resolve/main/example.py
# Run a command
>>> hf jobs uv run --with lighteval python -c 'import lighteval'Скрипты UV — это Python-скрипты, в которых зависимости указаны непосредственно в файле с помощью специального синтаксиса комментариев. Это делает их идеальными для автономных задач, не требующих сложной настройки проекта. Подробнее о скриптах UV см. в документации UV.
Используйте --, чтобы передать конфликтующие параметры вашему скрипту. Здесь --help доходит до train.py, а не выводит справку по Jobs:
>>> hf jobs uv run --flavor t4-small train.py -- --helpЭто также касается флагов форматирования: hf jobs run, hf jobs uv run и их scheduled-варианты принимают --format, --json и -q в любом месте, поэтому используйте --, если вашему скрипту нужны эти флаги.
Включите конфигурацию запуска в скрипт
Некоторые скрипты корректно работают только в определённой среде выполнения: конкретный образ, тип GPU, системный интерпретатор и т. д. Скрипт может содержать эту конфигурацию в необязательной таблице [tool.hf-jobs] в своём заголовке PEP 723:
# /// script
# requires-python = ">=3.11"
# dependencies = ["vllm", "datasets"]
#
# [tool.hf-jobs]
# name = "unlimited-ocr"
# image = "vllm/vllm-openai:unlimited-ocr"
# flavor = "l4x1"
# python = "/usr/bin/python3"
# timeout = "2h"
# env = { PYTHONPATH = "/usr/local/lib/python3.12/dist-packages", BATCH_SIZE = "64" }
# secrets = ["HF_TOKEN"]
# labels = { task = "ocr" }
# volumes = ["hf://datasets/org/pdfs:/input"]
# ///hf jobs uv run ocr.py in_ds out_ds запускает процесс с правильным рантаймом, а не молча выполняет его в CPU-образе с неверным интерпретатором. Таблица невидима для обычного uv run: таблицы [tool.*] являются частью PEP 723, и инструменты игнорируют те, которые им не принадлежат.
Поддерживаемые ключи, все необязательные: image, flavor, python, timeout, name, namespace, env, secrets, labels, volumes, network_group и network_aliases. Они соответствуют флагам с теми же именами (name сохраняется как метка name, volumes принимает те же спецификации hf://...:/MOUNT_PATH, что и -v, network_aliases — это список значений --network-alias). Неизвестный ключ приводит к ошибке, а не к молчаливому игнорированию намерения — опечатка вроде flavour — это именно тот сбой, предотвращение которого и является целью данной функции.
Все значения должны быть строками, включая значения env и labels: -e BATCH_SIZE=64 преобразуется в env = { BATCH_SIZE = "64" }, а не в env = { BATCH_SIZE = 64 } (TOML интерпретирует второе как целое число, и таблица отклоняется). Единственное исключение — timeout, который также принимает целое число секунд (timeout = 7200 эквивалентно timeout = "2h").
Значения из скрипта являются значениями по умолчанию: явный флаг всегда имеет приоритет, а env, secrets, labels и volumes объединяются поэлементно, поэтому -e и -v могут дополнять то, что объявлено в скрипте:
# Same script, on bigger hardware, with one extra env var
>>> hf jobs uv run --flavor a10g-large -e BATCH_SIZE=64 ocr.py in_ds out_dsnetwork_aliases — исключение: алиасы, которые Job заявляет, образуют множество, поэтому --network-alias заменяет список в скрипте, а не добавляется к нему. У Scheduled Jobs нет сетевой группы, поэтому hf jobs scheduled uv run отклоняет скрипт, в котором объявлены network_group или network_aliases.
secrets содержит только имена секретов: значения всегда берутся из окружения того, кто запускает скрипт, и никогда не извлекаются из самого скрипта (HF_TOKEN также разрешается из hf auth login). Если запрошенный секрет не задан локально, возникает ошибка, а не ситуация, при которой Job молча получает пустое значение. При использовании --dry-run вместо этого отображается <not set>, чтобы конфигурация скрипта, секреты которого ещё не настроены, оставалась видимой.
Каждый запуск выводит конфигурацию, которую отправляет, помечая значения, пришедшие из скрипта. Используйте --dry-run, чтобы вывести её без запуска:
>>> hf jobs uv run --dry-run --flavor a10g-large ocr.py in_ds out_ds
Warning: The script's [tool.hf-jobs] table requests HF_TOKEN: the value(s) from your local environment would be sent to the Job.
Job configuration:
script ocr.py
args in_ds out_ds
image vllm/vllm-openai:unlimited-ocr (from script)
flavor a10g-large
python /usr/bin/python3 (from script)
timeout 2h (from script)
env PYTHONPATH=/usr/local/lib/python3.12/dist-packages (from script)
BATCH_SIZE=64 (from script)
secrets HF_TOKEN=*** (from script)
volumes hf://datasets/org/pdfs:/input (from script)
labels task=ocr (from script)
name=unlimited-ocr (from script)
(dry run) Job not submitted.Это также работает для скриптов, доступных по URL: скрипт загружается один раз при отправке Job (для чтения его заголовка) и передаётся в Job как локальный скрипт, а не скачивается повторно самим контейнером. URL должен быть доступен с вашего компьютера. Как и локальные скрипты, скрипты по URL используют зарезервированную точку монтирования артефактов
/data; для входных томов используйте другой путь монтирования.
Для hf jobs scheduled uv run это фиксирует скрипт в том виде, в каком он был на момент создания. Обновление исходного URL больше не влияет на будущие запуски: чтобы использовать новую версию, необходимо пересоздать запланированную Job.
--dry-run также доступен в hf jobs run, hf jobs scheduled run и hf jobs scheduled uv run. Он пропускает отправку задания и загрузку локальных томов. Автоматически генерируемые имена для Docker и UV Jobs включают в себя разрешённую конфигурацию запуска, поэтому изменение параметров среды выполнения или значений переменных окружения приводит к изменению имени.
hf jobs scheduled
Планируйте и управляйте задачами, которые будут выполняться на инфраструктуре HF.
Расписание должно быть одним из @annually, @yearly, @monthly, @weekly, @daily, @hourly или выражением CRON-расписания (например, "0 9 * * 1" для 9 утра каждый понедельник).
# Schedule a job that runs every hour
>>> hf jobs scheduled run @hourly --name hourly-task python:3.12 python -c 'print("This runs every hour!")'
# Use the CRON syntax
>>> hf jobs scheduled run "*/5 * * * *" python:3.12 python -c 'print("This runs every 5 minutes!")'
# Schedule with GPU
>>> hf jobs scheduled run @hourly --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
... python -c 'import torch; print(f"This code ran with the following GPU: {torch.cuda.get_device_name()}")'
# Schedule a UV script
>>> hf jobs scheduled uv run @hourly --name hourly-script my_script.pyИспользуйте те же параметры, что и в hf jobs run, чтобы передать переменные окружения, секреты, таймаут и т. д.
Управление запланированными заданиями с помощью
# List your active scheduled jobs
>>> hf jobs scheduled ls
# Same filters as `hf jobs ls`: --status, --label and --name
>>> hf jobs scheduled ls --all
>>> hf jobs scheduled ls --status suspended
>>> hf jobs scheduled ls --name hourly-task --label env=prod
# Inspect the status of a job
>>> hf jobs scheduled inspect <scheduled_job_id>
# Suspend (pause) a scheduled job
>>> hf jobs scheduled suspend <scheduled_job_id>
# Resume a scheduled job
>>> hf jobs scheduled resume <scheduled_job_id>
# Change future run times (Mondays at 9:00)
>>> hf jobs scheduled reschedule <scheduled_job_id> "0 9 * * 1"
# Trigger a scheduled job to run right now (does not change the schedule)
>>> hf jobs scheduled trigger <scheduled_job_id>
# Delete a scheduled job
>>> hf jobs scheduled delete <scheduled_job_id>hf sandbox
hf sandbox запускает изолированные облачные машины на базе Jobs: создайте одну, выполняйте команды с выводом в реальном времени и копируйте файлы внутрь и наружу. Подойдёт любой Docker-образ с /bin/sh. Python API описан в руководстве по Sandboxes, а принцип работы — в концептуальном руководстве.
Песочницы являются экспериментальными, и их API и поведение могут измениться без предварительного уведомления. Общие песочницы предназначены для рабочих нагрузок в пределах одной границы доверия; для рабочих нагрузок, которые не доверяют друг другу, используйте выделенную песочницу.
# Create a sandbox (waits until it is ready, prints its id)
>>> hf sandbox create
✓ Sandbox ready id=687f911eaea852de79c4a50a image=python:3.12 elapsed=6.0s
# Attach labels to the underlying Job
>>> hf sandbox create --label controller-run=run-42 --label team=data-infra
# Run commands inside it (output is streamed, exit code is propagated)
>>> hf sandbox exec 687f911eaea852de79c4a50a -- python -c "print('hi')"
hi
# Copy files in and out (docker-style)
>>> hf sandbox cp data.csv 687f911eaea852de79c4a50a:/data/data.csv
>>> hf sandbox cp 687f911eaea852de79c4a50a:/app/results.json results.json
# Terminate a sandbox
>>> hf sandbox kill 687f911eaea852de79c4a50aИспользуйте --flavor, чтобы выбрать оборудование (например, a10g-small), --idle-timeout, чтобы ограничить время жизни песочницы, и -l / --label, чтобы добавить метки к её Job. Чтобы запустить множество дешёвых CPU-песочниц, создайте пул с помощью hf sandbox pool create и запускайте в него с помощью hf sandbox create --pool <id> (см. Руководство по песочницам).
Передача переменных окружения и секретов в песочницу
Существуют два отдельных канала с различными свойствами хранения:
| канал | флаги | выделенная песочница | песочница с пулингом (--pool) |
|---|---|---|---|
| environment | -e / --env, --env-file | хранятся в метаданных задания | передаются хосту при создании, а не хранятся в метаданных задания |
| secrets | -s / --secrets, --secrets-file | зашифровано на стороне сервера | недоступно — используйте --env |
# Plain environment variables
>>> hf sandbox create -e LOG_LEVEL=debug --env-file .env
# Secrets, read from your environment by name (nothing sensitive on the command line)
>>> hf sandbox create -s OPENAI_API_KEY -s HF_TOKEN
# Secrets from a file, or piped in on stdin
>>> hf sandbox create --secrets-file .env.secrets
>>> printf 'OPENAI_API_KEY=sk-...\n' | hf sandbox create --secrets-file --s KEY=value тоже работает, но значение попадает в историю командной строки и в список процессов, поэтому CLI выводит предупреждение в stderr, в том числе в тихом режиме. Пулы песочниц категорически отклоняют --secrets: у пула нет канала для зашифрованных секретов, и hf sandbox create --pool <id> -s KEY=value завершается ошибкой со ссылкой на --env.
hf webhooks
hf webhooks позволяет управлять вебхуками на Hugging Face Hub прямо из терминала. Вебхуки позволяют отслеживать события (push, обсуждения и т. д.) в репозиториях, у пользователей или организаций и запускать действия — либо отправляя запрос на удалённый URL, либо выполняя Job на инфраструктуре Hugging Face.
Список вебхуков
>>> hf webhooks ls
ID URL DISABLED DOMAINS WATCHED
wh-abc123 https://example.com/hook False repo model:bert-base-uncased
wh-def456 https://example.com/other-hook False repo org:HuggingFaceИспользуйте --format json для вывода в машиночитаемом формате или -q, чтобы вывести только идентификаторы:
>>> hf webhooks ls --format json
>>> hf webhooks ls -qПолучить информацию о вебхуке
>>> hf webhooks info wh-abc123Выводит полные сведения о вебхуке в формате JSON.
Создать вебхук
Создайте вебхук, который отправляет данные (payload) по URL:
>>> hf webhooks create --url https://example.com/hook --watch model:bert-base-uncased
>>> hf webhooks create --url https://example.com/hook --watch org:HuggingFace --watch model:gpt2 --domain repoИли создайте вебхук, который запускает Job:
>>> hf webhooks create --job-id 687f911eaea852de79c4a50a --watch user:julien-cСекреты исходного Job не копируются в webhook. Используйте --secrets или --secrets-file (синтаксис аналогичен hf jobs run), чтобы передать их в запускаемый Job. Например, --secrets HF_TOKEN передаёт ваш локальный токен Hugging Face:
>>> hf webhooks create --job-id 687f911eaea852de79c4a50a --watch bucket:my-org/my-bucket --secrets HF_TOKENОпция --watch использует формат type:name, где type — это одно из значений model, dataset, space, bucket, org или user. Её можно повторять, чтобы отслеживать несколько элементов. Используйте --domain, чтобы отфильтровать события по repo или discussion, и --secret, чтобы задать секрет подписи.
Обновление вебхука
>>> hf webhooks update wh-abc123 --url https://new-url.com/hook
>>> hf webhooks update wh-abc123 --watch model:gpt2 --domain repoИзменяются только предоставленные параметры. Обратите внимание, что при указании --watch весь наблюдаемый список заменяется.
Чтобы обновить секреты вебхука, срабатывающего по Job, передайте --job-id вместе с --secrets. Перечисленные секреты заменяют сохранённые значения, а все остальные секреты сохраняются:
>>> hf webhooks update wh-abc123 --job-id 687f911eaea852de79c4a50a --secrets HF_TOKENВключение / отключение вебхука
>>> hf webhooks enable wh-abc123
>>> hf webhooks disable wh-abc123Удалить вебхук
>>> hf webhooks delete wh-abc123
Are you sure you want to delete webhook 'wh-abc123'? [y/N]: y
Webhook deleted: wh-abc123Используйте --yes, чтобы пропустить запрос подтверждения:
>>> hf webhooks delete wh-abc123 --yesВсе команды принимают
--tokenдля переопределения аутентификации. Используйте--helpс любой командой, чтобы увидеть все параметры.
hf endpoints
Используйте hf endpoints, чтобы просматривать, развертывать, описывать и управлять Inference Endpoints прямо из терминала. Устаревший псевдоним hf inference-endpoints по-прежнему доступен для совместимости.
# Lists endpoints in your namespace
>>> hf endpoints ls
# List the hardware you can deploy on
>>> hf endpoints hardware
# Deploy an endpoint from Model Catalog
>>> hf endpoints catalog deploy --repo openai/gpt-oss-120b --name my-endpoint
# Deploy an endpoint from the Hugging Face Hub
>>> hf endpoints deploy my-endpoint --repo gpt2 --framework pytorch --accelerator cpu --instance-size x2 --instance-type intel-icl
# List catalog entries
>>> hf endpoints catalog ls
# Show status and metadata
>>> hf endpoints describe my-endpoint
# Pause the endpoint
>>> hf endpoints pause my-endpoint
# Delete without confirmation prompt
>>> hf endpoints delete my-endpoint --yesДобавьте
--namespace, чтобы указать организацию, и--token, чтобы переопределить аутентификацию.
Найдите оборудование для развертывания
hf endpoints deploy требует пять флагов оборудования (--vendor, --region, --accelerator, --instance-type и --instance-size). hf endpoints hardware выводит список допустимых комбинаций, включая цену за реплику в час в USD и квоту на ускорители вашего пространства имён:
>>> hf endpoints hardware --vendor aws --region eu-west-1
VENDOR REGION ACCELERATOR INSTANCE_TYPE INSTANCE_SIZE MEMORY_GB GPU_MEMORY_GB PRICE_PER_HOUR QUOTA STATUS
------ --------- ----------- ------------- ------------- --------- ------------- -------------- ----- ---------
aws eu-west-1 cpu intel-spr x1 2.0 0.033 0/60 available
aws eu-west-1 cpu intel-spr x2 4.0 0.067 0/60 available
aws eu-west-1 cpu intel-spr x4 8.0 0.134 0/60 available
aws eu-west-1 cpu intel-spr x8 16.0 0.268 0/60 available
aws eu-west-1 cpu intel-spr x16 32.0 0.536 0/60 available
aws eu-west-1 gpu nvidia-a10g x1 30.0 24 1.0 0/16 available
aws eu-west-1 gpu nvidia-t4 x1 15.0 16 0.5 1/30 available
Hint: Deploy on one of these, e.g.: hf endpoints deploy my-endpoint --repo <repo> --framework <framework> --vendor aws --region eu-west-1 --accelerator cpu --instance-type intel-spr --instance-size x1Флаги фильтрации совпадают с флагами развёртывания (--vendor, --region, --accelerator, --instance-type), поэтому то, по чему вы фильтруете, и передаётся в deploy. В списке отображается только то оборудование, на котором можно развернуть модель прямо сейчас: доступный статус и достаточный остаток квоты на ускорители в вашем пространстве имён для одной реплики. Добавьте --all, чтобы также увидеть устаревшие, временно недоступные или превышающие квоту варианты. --format json добавляет к каждой записи оставшиеся спецификации на реплику (vCPUs, архитектура, количество ускорителей).
Квота назначается на пространство имён и определяет, какие строки вообще будут отображены. Если вы разворачиваете модель в организации, передайте тот же
--namespace, который вы передадите вdeploy— иначе вы будете видеть свою личную квоту, которая может как скрывать оборудование, доступное для развёртывания в организации, так и показывать оборудование, на котором организация развернуть модель не может.
Развертывание пользовательского контейнера
Чтобы развернуть собственный Docker-образ вместо управляемого Hugging Face, передайте --framework custom вместе с --custom-image. Репозиторий модели монтируется в /repository внутри контейнера. Используйте --container-args (и при необходимости --container-command), чтобы передать строку запуска в кавычках, --env/--secrets для внедрения переменных окружения, а также --type для установки типа доступа (public, authenticated или private):
>>> hf endpoints deploy nex-n2-pro \
--repo nex-agi/Nex-N2-Pro \
--framework custom \
--accelerator gpu --vendor aws --region us-east-1 \
--instance-type nvidia-h200 --instance-size x8 \
--custom-image nexagi/sglang:v0.5.12 \
--health-route /health --port 30000 \
--container-args "--reasoning-parser qwen3 --tool-call-parser qwen3_coder --mamba-scheduler-strategy extra_buffer --tp 8" \
--env MODEL_ID=/repository \
--type authenticated--container-args и --container-command не ограничены только кастомными образами: они соответствуют model.args и model.command в API-запросе, что применимо и к управляемым образам. Для существующего эндпоинта оба флага заменяют текущее значение, а не добавляют к нему, поэтому передавайте полный список, который вам нужен, и используйте пустую строку для очистки. Эндпоинты, развернутые из каталога, уже содержат настроенные флаги движка, поэтому перед их перезаписью проверьте hf endpoints describe:
>>> hf endpoints update my-endpoint \
--container-args "--enable-auto-tool-choice --tool-call-parser lfm2"Развернуть образ управляемого движка
--custom-image в одиночку разворачивает произвольный контейнер. Добавьте --engine, чтобы запустить его как один из движков, управляемых API (vllm, sglang, tgi, tei, llamacpp, hf-serve, …), что открывает доступ к настройкам этого движка, включая --tensor-parallel-size и --data-parallel-size. По умолчанию vLLM и SGLang используют один ускоритель, хотя эндпоинт получает все ускорители своего инстанса, поэтому, если оставить оба параметра не заданными, модель будет загружена на один ускоритель, остальные останутся простаивать, а система всё равно будет сообщать о нормальном состоянии. Именно поэтому API теперь отклоняет такую конфигурацию:
>>> hf endpoints deploy gpt-oss-120b-vllm \
--repo openai/gpt-oss-120b \
--framework custom \
--accelerator gpu --vendor aws --region us-east-1 \
--instance-type nvidia-h200 --instance-size x8 \
--engine vllm --custom-image vllm/vllm-openai:v0.23.0 \
--tensor-parallel-size 8Это не то же самое, что --container-args "... --tp 8" выше: --tensor-parallel-size записывает значение в конфигурацию model.image движка, по которой API проверяет количество ускорителей в инстансе, тогда как --container-args лишь добавляет флаг в командную строку. Используйте --container-args для флагов движка, у которых нет соответствующего поля в образе, а также для обычных пользовательских контейнеров, не имеющих полей параллелизма.
Чтобы перенастроить работающий endpoint, передайте размеры по отдельности. model.image отправляется целиком и требует url, поэтому текущее изображение endpoint извлекается и обновляется на месте:
>>> hf endpoints update gpt-oss-120b-vllm --tensor-parallel-size 4 --data-parallel-size 2hf endpoints update также принимает --custom-image и --engine, это единственный способ изменить образ эндпоинта из CLI. Этот путь заменяет model.image, а не дополняет его, поэтому сначала выполните hf endpoints describe и передайте обратно то, что хотите сохранить.
hf endpoints catalog
Используйте hf endpoints catalog для работы с каталогом моделей Inference Endpoints. Разворачивайте модели напрямую из каталога с оптимизированными конфигурациями.
Каждая модель в каталоге сопровождается одной или несколькими рецептами: комбинацией аппаратного обеспечения и движка, протестированной для неё. Команда hf endpoints catalog ls выводит по одной строке на каждый рецепт, поэтому модель, имеющая рецепты для GPU и Neuron, отображается дважды:
# List available catalog models
>>> hf endpoints catalog ls
REPO_ID TASK LICENSE ACCELERATOR ENGINE GGUF_FILE RECIPE_ID
----------------------------------- ------------------ ---------- ----------- -------- ----------------------------- -------------------------
meta-llama/Llama-3.1-8B-Instruct text-generation Llama 3.1 gpu vllm sizzling-biryani-g4xsi1ac
meta-llama/Llama-3.1-8B-Instruct text-generation Llama 3.1 neuron vllmNeuron artisanal-quinoa-yz9ynamx
bartowski/QwQ-32B-Preview-GGUF text-generation Apache 2.0 gpu llamacpp QwQ-32B-Preview-Q8_0.gguf baked-orange-m863gx7d
# Narrow it down
>>> hf endpoints catalog ls --engine vllm --task text-generation --search llama --limit 10--accelerator, --engine, --license, --task, --search и --limit фильтруют данные на стороне сервера.
# Deploy the default recipe of a model
>>> hf endpoints catalog deploy --repo meta-llama/Llama-3.2-1B-Instruct
# Deploy an exact recipe listed above
>>> hf endpoints catalog deploy --recipe artisanal-quinoa-yz9ynamx
# Deploy with a custom name
>>> hf endpoints catalog deploy --repo meta-llama/Llama-3.2-1B-Instruct --name my-llama-endpointС помощью --repo выбор рецепта по умолчанию можно сузить с помощью --accelerator (cpu, gpu, neuron) и --gguf-file (для моделей, у которых есть отдельный рецепт для каждого кванта). Оба параметра отклоняются вместе с --recipe, который уже указывает конкретный рецепт.