← Все гайды AI Release
EN Подписаться на @ai_release1

Как скачать модель с Hugging Face и запустить локально: фильтры, GGUF и квантизация

Обновлено: 05.11.2026 · AI Release · @ai_release1
Как скачать модель с Hugging Face и запустить локально: фильтры, GGUF и квантизация

TL;DR

Требования и подготовка

Иллюстрация к разделу «Требования и подготовка»
Иллюстрация к разделу «Требования и подготовка»

Установка и проверка инструментов:

python3 --version
git --version
git lfs install
pip install -U "huggingface_hub[cli]"
hf --help

Пример: успешный вывод git lfs install — строка Git LFS initialized.; hf --help печатает список подкоманд (download, auth, upload).

Зачем: hf — официальный CLI для Hugging Face Hub, он умеет качать отдельные файлы из репозитория, не вытягивая весь репозиторий целиком. git-lfs нужен, потому что веса моделей хранятся через Git Large File Storage, а не как обычные файлы в git.

Если команда hf не найдена — в вашей версии пакета она может называться huggingface-cli; сверьтесь с документацией huggingface_hub.

Общий порядок действий для новичка разобран в гайде Как запустить ИИ-модель локально на своём компьютере: гайд для начинающих.

Шаг 1. Фильтруем модели на Hugging Face и выбираем нужный файл

Что сделать: открыть https://huggingface.co/models и сузить выдачу фильтрами в левой колонке: Task → Text Generation, Library → GGUF, Size → диапазон параметров. Сортировку переключить на Most downloads. Затем зайти на страницу выбранной модели → вкладка Files → найти файлы *.gguf.

Зачем: GGUF — формат файла «одна модель в одном файле», его читают llama.cpp, llama-server и большинство локальных раннеров. Фильтр по библиотеке GGUF сразу отсекает репозитории с «сырыми» весами (safetensors), которые нельзя запустить одной командой без конвертации.

Пример: https://huggingface.co/<owner>/<model>-GGUF → вкладка Files → файл вида <model>-Q4_K_M.gguf. Имя файла кодирует квантизацию — степень сжатия весов.

Суффикс в имени файлаЧто означаетКогда выбирать
`Q8_0`самое лёгкое сжатие из перечисленных, самый крупный файлпамяти достаточно, качество критично
`Q5_K_M`среднее сжатиекомпромисс между размером и качеством
`Q4_K_M`сильнее сжатие, заметно меньше файлтиповой выбор для бытовой видеокарты
`Q3_K_M` / `Q2_K`сильное сжатиепамяти мало, качество вторично

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

Тот же поиск из Python, если не хочется кликать по интерфейсу:

from huggingface_hub import HfApi

api = HfApi()
for m in api.list_models(filter="gguf", sort="downloads", direction=-1, limit=10):
    print(m.id, m.downloads)

for f in api.list_repo_files("<owner>/<model>-GGUF"):
    if f.endswith(".gguf"):
        print(f)

Пример вывода: идентификаторы вида owner/name-GGUF и имена файлов name-Q4_K_M.gguf, name-Q8_0.gguf.

Как проверить: в списке файлов есть хотя бы один .gguf с суффиксом квантизации. Если файл разбит на шарды (-00001-of-00003.gguf), качать нужно все части — по ним llama.cpp собирает модель.

Если тег gguf в list_models не сработал в вашей версии библиотеки — сверьтесь с документацией HfApi.

Шаг 2. Скачиваем файл и запускаем модель через llama.cpp

Иллюстрация к разделу «Шаг 2. Скачиваем файл и запускаем модель через llama.cpp»
Иллюстрация к разделу «Шаг 2. Скачиваем файл и запускаем модель через llama.cpp»

Что сделать: скачать ровно один нужный файл, проверить его целостность, собрать llama.cpp и запустить модель.

Скачивание одного файла по маске:

hf download <owner>/<model>-GGUF \
  --include "*Q4_K_M.gguf" \
  --local-dir ./models

Зачем: --include фильтрует файлы по glob-маске. В репозитории обычно лежат десятки квантизаций, и без фильтра вы скачаете несколько десятков гигабайт вместо одного файла.

Для моделей с ограниченным доступом сначала авторизуйтесь:

hf auth login
hf auth whoami

Пример: hf auth login спросит токен (вставка не отображается на экране), hf auth whoami печатает имя вашего аккаунта. Перед этим на странице модели нужно принять условия доступа — иначе скачивание вернёт 401.

Проверка файла — сигнатура формата:

ls -lh ./models/*.gguf
head -c 4 ./models/<model>-Q4_K_M.gguf; echo

Ожидаемый результат: ls показывает размер в гигабайтах, head печатает GGUF. Если вместо этого вы видите version https://git-lfs.github.com/spec/v1, файл не скачался — это LFS-указатель.

Сборка llama.cpp:

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build
cmake --build build --config Release -j

Зачем: llama.cpp — движок инференса (то есть выполнения модели), который читает GGUF и умеет работать на CPU и GPU. Если cmake недоступен, возьмите готовый бинарник со страницы Releases проекта — сверьтесь с документацией.

Запуск в режиме одного запроса:

./build/bin/llama-cli -m ../models/<model>-Q4_K_M.gguf \
  -p "Напиши одну строку о себе" -n 64

Запуск как локальный HTTP-сервер с OpenAI-совместимым API:

./build/bin/llama-server -m ../models/<model>-Q4_K_M.gguf \
  --host 127.0.0.1 --port 8080 -ngl 0

Зачем: -ngl — число слоёв, выгружаемых на GPU (offload). -ngl 0 означает «только CPU»: так модель точно запустится, но медленнее. Если модель не влезает в память одной карты, порядок действий с offload разобран в гайде Как запустить модель на 125B параметров на RTX 4090: квантизация, offload и 100 токенов в секунду.

Как проверить: в логе сервера появляется строка о прослушивании порта — вида server is listening on http://127.0.0.1:8080. Процесс не завершился, терминал занят.

Шаг 3. Проверяем, что модель отвечает

Иллюстрация к разделу «Шаг 3. Проверяем, что модель отвечает»
Иллюстрация к разделу «Шаг 3. Проверяем, что модель отвечает»

Что сделать: отправить запрос к локальному API и убедиться, что приходит осмысленный ответ.

curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Скажи ok"}],"max_tokens":16}'

Зачем: это тот же формат, что у OpenAI API, поэтому ваш локальный сервер подключается в существующий код заменой base_url. Ответ в JSON означает, что модель загрузилась, токенизатор работает и порт доступен.

Пример ожидаемого вывода (сокращённо):

{"choices":[{"message":{"role":"assistant","content":"ok"}}]}

Точный набор полей зависит от сборки — важны choices и непустой content.

Проверка из Python:

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:8080/v1", api_key="none")
r = client.chat.completions.create(
    model="local",
    messages=[{"role": "user", "content": "Привет"}],
)
print(r.choices[0].message.content)

Зачем: поле api_key локальный сервер не проверяет, поэтому подойдёт плейсхолдер none; поле model тоже игнорируется — сервер обслуживает ту модель, с которой запущен.

Как проверить, что всё получилось:

Возможные проблемы и решения

Проблема. Скачивание падает с отказом доступа

Проблема. Вместо весов скачался текстовый файл на пару сотен байт

Проблема. Модель не влезает в видеопамять

Резюме и следующие шаги

Вы прошли путь от фильтра GGUF на Hugging Face до рабочего локального эндпоинта http://127.0.0.1:8080/v1. Дальше имеет смысл подобрать квантизацию и -ngl под свою видеокарту, а для запуска на телефоне — перейти к гайду Как запустить ИИ-модель локально на Android: приложения и настройка.

FAQ

Чем GGUF отличается от safetensors и почему нужен именно он?

Safetensors — формат хранения «сырых» весов, его обычно требуют фреймворки обучения и тяжёлые инференс-стеки. GGUF — упакованный файл «модель + метаданные» для llama.cpp и совместимых раннеров, поэтому для локального запуска одной командой берут именно .gguf.

Сколько места на диске нужно?

Ориентируйтесь на размер файла в колонке Size на вкладке Files: он зависит от числа параметров модели и выбранной квантизации. Практическое правило — свободного места должно быть минимум в два раза больше размера файла, чтобы хватило на скачивание и распаковку.

Можно ли запустить без видеокарты?

Да, -ngl 0 переводит все слои на CPU, и модель будет работать — медленнее, чем на GPU. Скорость зависит от процессора, объёма RAM и размера модели; конкретных цифр без замера на вашей машине назвать нельзя.

Какую квантизацию выбрать для 8 ГБ видеопамяти?

Универсальной рекомендации нет: сравните размеры файлов Q4_K_M, Q5_K_M и Q8_0 на странице модели и возьмите самый крупный, который оставляет запас памяти под контекст. Начните с -ngl 0, затем увеличивайте -ngl, пока не упрётесь в лимит памяти.

🤖 Кратко для ИИ

📚 Связанные гайды

Как запустить ИИ-модель локально на своём компьютере: гайд для начинающих

Пошаговое руководство по установке и запуску локальных нейросетей на домашнем ПК без облачных сервисов.

Как запустить ИИ-модель локально на Android: приложения и настройка

Инструкция по запуску LLM на смартфоне с Android: выбор приложений, установка моделей и ограничения по памяти.

Как запустить модель на 125B параметров на RTX 4090: квантизация, offload и 100 токенов в секунду

Практический гайд по запуску больших моделей вроде Qwen 3.8 Flash Next на домашней видеокарте: выбор квантизации, распре