Как скачать модель с Hugging Face на GPU-сервер: токен и hf CLI

Модель с Hugging Face качают на сервер командой hf download — по SSH, с запасом места на диске и, для закрытых моделей, с токеном. Файл GPT-OSS 120B в формате GGUF весит 63,4 ГБ: на канале 1 Гбит/с он скачивается за 8,5 мин, на 100 Мбит/с — за 85 мин (теоретический минимум). Ниже — шесть шагов для арендованного сервера, правила для закрытых моделей, что делать при обрыве и таблица времени загрузки для популярных файлов.

Что понадобится

• Аккаунт на Hugging Face и токен доступа. Он создаётся за минуту, как — ниже.
• Сервер с доступом по SSH. Если подключаетесь впервые, начните с гайда по SSH.
• Диск с запасом: размер файла плюс 50 ГБ. Правило и примеры — в разделе про диск.
• Время: от секунд до нескольких часов, в зависимости от файла и канала. Сервер оплачивается и во время загрузки.

Как скачать модель на сервер за шесть шагов

Пример скачивает один файл Qwen3 8B в квантизации Q4_K_M. Для своей модели замените репозиторий и маску файла.

1. 1

   Подключитесь и откройте tmux

   Войдите на сервер по SSH и запустите сеанс tmux: если связь оборвётся, загрузка продолжит работать. Вернуться в сеанс можно командой tmux attach -t hf.

   tmux new -s hf
   # tmux нет: apt-get update && apt-get install -y tmux

2. 2

   Поставьте hf

   Команда hf входит в пакет huggingface_hub, вместе с ним ставится hf_xet, который ускоряет загрузку. Официальный установщик создаёт отдельное окружение и требует Python 3.10 или новее. Если у вас уже есть окружение с Python, например в шаблоне vLLM, хватит pip.

   curl -LsSf https://hf.co/cli/install.sh | bash
   export PATH="$HOME/.local/bin:$PATH"
   hf --help
   
   # вместо установщика, если окружение с Python уже есть
   pip install -U huggingface_hub

3. 3

   Передайте токен

   Токен вводится без показа на экране и не попадает в историю команд. Он действует только в этом сеансе. Если токен принят, hf auth whoami покажет ваше имя на Hugging Face.

   read -rs -p "HF token: " HF_TOKEN && export HF_TOKEN
   hf auth whoami

4. 4

   Проверьте размер и место

   Флаг --dry-run перечисляет файлы и общий размер, ничего не скачивая. Сравните его с df: при нехватке места hf только предупреждает, и загрузка может оборваться на середине.

   df -h /workspace
   hf download unsloth/Qwen3-8B-GGUF --include "*Q4_K_M*" --dry-run
   # [dry-run] Will download 1 files (out of 1) totalling 5.0G

5. 5

   Скачайте файл

   Флаг --local-dir кладёт готовые файлы в вашу папку, а не в кэш Hugging Face. Папку держите на диске сервера, например в /workspace.

   hf download unsloth/Qwen3-8B-GGUF --include "*Q4_K_M*" --local-dir /workspace/models/qwen3-8b

6. 6

   Сверьте контрольные суммы

   Команда сравнит файлы с тем, что хранит Hugging Face. Предупреждения «missing locally» относятся к остальным файлам репозитория, которые вы не качали.

   hf cache verify unsloth/Qwen3-8B-GGUF --local-dir /workspace/models/qwen3-8b

Какой токен создать: read или fine-grained

Для скачивания хватит токена read или fine-grained с правом читать нужные репозитории. Write для этого не нужен.

• read читает всё, что доступно вашему аккаунту, в том числе закрытые модели, к которым вам открыли доступ. Самый простой вариант.
• fine-grained даёт доступ только к выбранным репозиториям. Берите его для сервера: если токен утечёт, откроется меньше.
• write разрешает ещё и запись в ваши репозитории. Для скачивания не нужен.

Токен создают в настройках Hugging Face: Settings, вкладка Access Tokens, кнопка New token (адрес huggingface.co/settings/tokens). Документация советует отдельный токен на каждое применение. Создайте токен для этого сервера и удалите его, когда сервер станет не нужен.

Токен можно один раз добавить в раздел «Переменные окружения» настроек gpu.nz как HF_TOKEN: переменная попадёт во все новые серверы, но не в уже запущенные. На новом сервере проверьте её командой test -n "$HF_TOKEN" && echo ok. Если вывода нет, задайте токен вручную, как в шаге 3.

Команда hf auth login тоже подходит, но записывает токен в файл $HF_HOME/token, а файл остаётся на диске сервера. Переменная HF_TOKEN удобнее: она перекрывает сохранённый токен и исчезает вместе с сеансом.

Как открыть закрытую модель (gated)

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

Автор выбирает автоматическое или ручное одобрение. При ручном придётся подождать, а доступ автор может отозвать в любой момент. Для fine-grained токена отдельно добавьте право читать этот репозиторий.

• Llama 3.3 70B Instruct: ручное одобрение запроса.
• FLUX.1 dev: автоматическое одобрение после принятия лицензии.
• Gemma 4 31B, Qwen3 8B, GPT-OSS 120B и DeepSeek V4 Flash: открыты без запроса. У предыдущей Gemma 3 27B доступ закрыт.

Статусы взяты из API Hugging Face на 20.10.2026: у автора они могут измениться.

Как скачать один файл, а не весь репозиторий

Репозиторий с GGUF хранит файл на каждую квантизацию, и без маски hf скачает всё. Семь основных квантизаций Qwen3 8B вместе весят 50,1 ГБ: в 10 раз больше одного файла Q4_K_M (5,0 ГБ). Нужный файл выбирают по имени или маской.

# один файл по имени
hf download unsloth/Qwen3-8B-GGUF Qwen3-8B-Q4_K_M.gguf --local-dir /workspace/models/qwen3-8b

# все файлы одной квантизации: большие модели режут на части
hf download unsloth/Qwen3-8B-GGUF --include "*Q4_K_M*" --local-dir /workspace/models/qwen3-8b

# репозиторий без лишних копий весов
hf download openai/gpt-oss-120b --exclude "original/*" --exclude "metal/*" --local-dir /workspace/models/gpt-oss-120b

Лишние копии весов — частая причина лишних сотен гигабайт. В репозитории openai/gpt-oss-120b на 20.10.2026 рядом с основными файлами safetensors лежат папки original и metal, и последняя команда их пропускает. Всегда сверяйтесь с --dry-run.

То же из Python: функция snapshot_download из пакета huggingface_hub принимает маски в allow_patterns и папку в local_dir. Токен она берёт из HF_TOKEN.

from huggingface_hub import snapshot_download

snapshot_download(
    "unsloth/Qwen3-8B-GGUF",
    allow_patterns=["*Q4_K_M*"],
    local_dir="/workspace/models/qwen3-8b",
)

Сколько ждать: время загрузки при 100 Мбит/с, 1 и 10 Гбит/с

Время равно размеру файла × 8 ÷ скорость канала. Это теоретический минимум: реальная скорость зависит от канала сервера, нагрузки на Hugging Face и диска, поэтому ждите дольше. Сервер оплачивается и во время загрузки, подробнее — в гайде как не переплатить за аренду GPU.

Размеры взяты из репозиториев, по которым считает калькулятор: GGUF, оригинальные веса BF16, родные форматы релиза (MXFP4 у GPT-OSS, FP4/FP8 у DeepSeek). У GPT-OSS 120B это файл GGUF, а в оригинальном репозитории openai веса safetensors весят немного больше. Точную цифру для своего репозитория даёт --dry-run.

Если загрузка с вашего канала медленная, сначала сверьтесь с таблицей. Потом попробуйте переменные из таблицы ниже: HF_XET_HIGH_PERFORMANCE=1 занимает весь канал и все ядра процессора, а больший HF_HUB_DOWNLOAD_TIMEOUT спасает от обрывов по таймауту. Ещё один способ — взять квантизацию полегче.

Переменная HF_HUB_ENABLE_HF_TRANSFER и пакет hf_transfer устарели. По документации Hugging Face, весь Hub теперь работает на хранилище Xet, а hf_transfer использовать нельзя: вместо него служит HF_XET_HIGH_PERFORMANCE.

Что делать, если загрузка оборвалась

Чаще всего рвётся не загрузка, а ваш SSH-сеанс. Поэтому в первом шаге команда запускается в tmux: она продолжит работу и после обрыва. Если оборвалась сама загрузка, действуйте так.

• Повторите ту же команду. Полностью скачанные файлы hf пропускает, и повторный запуск проходит почти мгновенно.
• Недокачанный файл начнётся заново. В документации Hugging Face про докачку ничего не сказано. В нашей проверке hf 2.2.0 после жёсткого обрыва скачивал файл с нуля, а старый кусок оставался в папке .cache/huggingface/download внутри --local-dir как файл .incomplete. Удалите такие файлы, они занимают место. Для общего кэша (когда нет --local-dir) это делает hf cache prune.
• Один огромный файл докачайте через wget -c. Он продолжает с места обрыва; мы проверили это на открытом файле. Для закрытой модели добавьте --header="Authorization: Bearer $HF_TOKEN".
• Загрузка зависла без прогресса. Остановите её (Ctrl+C) и запустите заново. Если зависает снова, отключите Xet: export HF_HUB_DISABLE_XET=1. В готовых шаблонах приложений Xet отключён: однажды загрузка там зависла.

wget -c -O /workspace/models/qwen3-8b/Qwen3-8B-Q4_K_M.gguf \
  "https://huggingface.co/unsloth/Qwen3-8B-GGUF/resolve/main/Qwen3-8B-Q4_K_M.gguf"

Сколько диска арендовать

Диск равен размеру файла плюс запас. В наших шаблонах чата рекомендуемый диск — размер модели плюс 50 ГБ, минимальный — плюс 30 ГБ. Запас занимают система, пакеты и недокачанные файлы .incomplete после обрыва. Колонка «Диск» в таблице выше посчитана по рекомендуемому правилу.

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

Куда положить файлы: Ollama, vLLM, llama.cpp, ComfyUI

Не каждому инструменту нужен hf: Ollama и llama.cpp умеют скачивать модель сами, а vLLM берёт её из кэша Hugging Face. Вручную качайте, когда нужен файл в своей папке: для проверки размера, для ComfyUI или чтобы не скачивать заново.

Пример для ComfyUI: FLUX.1 dev требует принять лицензию, а файлы раскладываются по трём папкам. Если ComfyUI лежит не в /workspace/ComfyUI, найдите папку командой ls /workspace.

cd /workspace/ComfyUI/models
hf download black-forest-labs/FLUX.1-dev flux1-dev.safetensors --local-dir diffusion_models
hf download black-forest-labs/FLUX.1-dev ae.safetensors --local-dir vae
hf download comfyanonymous/flux_text_encoders clip_l.safetensors t5xxl_fp16.safetensors --local-dir text_encoders

Поместится ли скачанная модель в видеокарту

Размер файла — только нижняя граница: сверху добавляются кэш контекста и служебные буферы. GPT-OSS 120B в MXFP4 с контекстом 8K работает на карте 80 ГБ. Проверьте свою модель и контекст в калькуляторе; сводная таблица по 35 моделям — в статье «Сколько видеопамяти нужно открытым LLM».

Что может пойти не так

• huggingface-cli: command not found. В свежей версии пакета (2.2.0) есть только команда hf. В старых инструкциях и на карточках моделей замените huggingface-cli download на hf download: флаги те же. Вход теперь выполняется командой hf auth login.
• Ошибка доступа к закрытой модели. Проверьте три вещи: условия приняты в браузере, токен выпущен тем же аккаунтом, у fine-grained токена есть право читать репозиторий.
• Токен не меняется после hf auth login. Переменная HF_TOKEN перекрывает сохранённый токен, а hf auth logout не выходит из аккаунта, пока она задана. Снимите её командой unset HF_TOKEN.
• Не хватило места. hf при нехватке места лишь предупреждает и может остановиться посреди файла. Проверяйте df -h до загрузки, а размер диска выбирайте при запуске: потом он не меняется.
• Одна модель скачана дважды. vLLM и библиотеки на основе huggingface_hub кладут файлы в кэш, а hf download с --local-dir — в вашу папку. Выберите одно место.

Как мы считали

Размеры файлов взяты из данных калькулятора: это реальные размеры файлов в репозиториях Hugging Face (GGUF из репозиториев unsloth и других, оригинальные веса, у GPT-OSS 120B — файл GGUF из ggml-org). Калькулятор хранит гибибайты (1 ГБ = 1024³ байт), как память видеокарт, а Hugging Face показывает десятичные гигабайты (10⁹ байт), поэтому здесь цифры умножены на 1,0737. Время равно размеру в байтах × 8 ÷ скорость канала в битах в секунду; накладные расходы, CDN и диск не учтены. Данные на 2026-10-19; ключевые цифры по моделям — в калькуляторе.

Команды и переменные сверены 20.10.2026 с документацией: huggingface.co/docs/huggingface_hub (руководства по CLI, загрузке, кэшу и переменным окружения), huggingface.co/docs/hub (токены, закрытые модели, Ollama), docs.ollama.com, docs.vllm.ai, README llama.cpp и docs.comfy.org. Кроме того, мы установили hf 2.2.0 (hf_xet 1.7.0) и проверили на Linux справку команд, --dry-run, hf cache verify, повторный запуск и обрыв загрузки. Поведение hf при нехватке места и после обрыва мы подтвердили по исходному коду загрузки. Команду wget -c мы проверили на открытом файле, закрытый файл с токеном — нет.