# Как скачать модель с Hugging Face и запустить локально: фильтры, GGUF и квантизация > AI Release · @ai_release1 · https://ai-release.org/guides/kak-skachat-model-s-hugging-face-i-zapustit-lokalno-fil.html ## TL;DR - **Время выполнения:** 40–60 минут (без учёта времени скачивания файла модели) - **Уровень сложности:** Intermediate - **Понадобится:** Python 3.10+ и pip; git + git-lfs; пакет `huggingface_hub` (команда `hf`); llama.cpp (собранный из исходников или готовый бинарник под вашу ОС); аккаунт Hugging Face и токен с правами Read — для моделей с ограниченным доступом; свободное место на диске не меньше удвоенного размера выбранного `.gguf`-файла. ## Требования и подготовка ![Иллюстрация к разделу «Требования и подготовка»](https://ai-release.org/guides/img/kak-skachat-model-s-hugging-face-i-zapustit-lokalno-fil-ru-1.jpg?v=1793868166) - ОС: Linux x86_64, macOS (Apple Silicon) или Windows 10/11. - Python 3.10+ и pip. Точную минимальную версию Python для скриптов конвертации сверьте с документацией llama.cpp. - `git` и `git-lfs`. Без LFS вместо файла модели вы получите текстовый указатель. - Свободное место: минимум 2× размер выбранного файла модели (размер виден в колонке Size на вкладке Files страницы модели). - Права на запись в каталог, куда будете скачивать (`./models`). - Токен Hugging Face: сайт → Settings → Access Tokens → New token → тип Read. Установка и проверка инструментов: ```bash 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`. - [ ] `python3 --version` печатает версию - [ ] `git lfs install` печатает `Git LFS initialized.` - [ ] `hf --help` открывает справку без ошибок Общий порядок действий для новичка разобран в гайде [Как запустить ИИ-модель локально на своём компьютере: гайд для начинающих](https://ai-release.org/guides/kak-zapustit-ii-model-lokalno-na-svoem-kompyutere-gayd.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide). ## Шаг 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//-GGUF` → вкладка Files → файл вида `-Q4_K_M.gguf`. Имя файла кодирует квантизацию — степень сжатия весов. | Суффикс в имени файла | Что означает | Когда выбирать | |---|---|---| | `Q8_0` | самое лёгкое сжатие из перечисленных, самый крупный файл | памяти достаточно, качество критично | | `Q5_K_M` | среднее сжатие | компромисс между размером и качеством | | `Q4_K_M` | сильнее сжатие, заметно меньше файл | типовой выбор для бытовой видеокарты | | `Q3_K_M` / `Q2_K` | сильное сжатие | памяти мало, качество вторично | Точные размеры файлов смотрите в колонке Size — они зависят от числа параметров модели, поэтому универсальной цифры нет. Тот же поиск из Python, если не хочется кликать по интерфейсу: ```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("/-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»](https://ai-release.org/guides/img/kak-skachat-model-s-hugging-face-i-zapustit-lokalno-fil-ru-2.jpg?v=1793868169) **Что сделать:** скачать ровно один нужный файл, проверить его целостность, собрать llama.cpp и запустить модель. Скачивание одного файла по маске: ```bash hf download /-GGUF \ --include "*Q4_K_M.gguf" \ --local-dir ./models ``` **Зачем:** `--include` фильтрует файлы по glob-маске. В репозитории обычно лежат десятки квантизаций, и без фильтра вы скачаете несколько десятков гигабайт вместо одного файла. Для моделей с ограниченным доступом сначала авторизуйтесь: ```bash hf auth login hf auth whoami ``` **Пример:** `hf auth login` спросит токен (вставка не отображается на экране), `hf auth whoami` печатает имя вашего аккаунта. Перед этим на странице модели нужно принять условия доступа — иначе скачивание вернёт 401. Проверка файла — сигнатура формата: ```bash ls -lh ./models/*.gguf head -c 4 ./models/-Q4_K_M.gguf; echo ``` **Ожидаемый результат:** `ls` показывает размер в гигабайтах, `head` печатает `GGUF`. Если вместо этого вы видите `version https://git-lfs.github.com/spec/v1`, файл не скачался — это LFS-указатель. Сборка llama.cpp: ```bash 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 проекта — сверьтесь с документацией. Запуск в режиме одного запроса: ```bash ./build/bin/llama-cli -m ../models/-Q4_K_M.gguf \ -p "Напиши одну строку о себе" -n 64 ``` Запуск как локальный HTTP-сервер с OpenAI-совместимым API: ```bash ./build/bin/llama-server -m ../models/-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 токенов в секунду](https://ai-release.org/guides/kak-zapustit-model-na-125b-parametrov-na-rtx-4090-kvant.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide). **Как проверить:** в логе сервера появляется строка о прослушивании порта — вида `server is listening on http://127.0.0.1:8080`. Процесс не завершился, терминал занят. ## Шаг 3. Проверяем, что модель отвечает ![Иллюстрация к разделу «Шаг 3. Проверяем, что модель отвечает»](https://ai-release.org/guides/img/kak-skachat-model-s-hugging-face-i-zapustit-lokalno-fil-ru-3.jpg?v=1793868175) **Что сделать:** отправить запрос к локальному API и убедиться, что приходит осмысленный ответ. ```bash 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 означает, что модель загрузилась, токенизатор работает и порт доступен. **Пример ожидаемого вывода (сокращённо):** ```json {"choices":[{"message":{"role":"assistant","content":"ok"}}]} ``` Точный набор полей зависит от сборки — важны `choices` и непустой `content`. Проверка из Python: ```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` тоже игнорируется — сервер обслуживает ту модель, с которой запущен. **Как проверить, что всё получилось:** - [ ] `ls -lh ./models/*.gguf` показывает реальный размер, а не несколько байт - [ ] первые 4 байта файла — `GGUF` - [ ] в логе llama-server есть строка о прослушивании `127.0.0.1:8080` - [ ] `curl` вернул JSON с непустым `content` - [ ] `curl -s http://127.0.0.1:8080/health` возвращает статус OK (если эндпоинт отсутствует в вашей сборке — сверьтесь с документацией) ## Возможные проблемы и решения **Проблема. Скачивание падает с отказом доступа** - Ошибка: `401 Client Error: 401 Unauthorized for url: https://huggingface.co//-GGUF/resolve/main/...` - Причина: репозиторий приватный или имеет статус gated (доступ по заявке), либо токен не передан и не имеет прав Read. - Решение: откройте страницу модели и примите условия доступа, затем выполните `hf auth login`, вставьте токен и проверьте `hf auth whoami`. После этого повторите `hf download ...` в новой сессии терминала. **Проблема. Вместо весов скачался текстовый файл на пару сотен байт** - Ошибка: `head -c 4` печатает `vers`, а файл начинается со строки `version https://git-lfs.github.com/spec/v1`; при клонировании возможен `smudge filter lfs failed` - Причина: git-lfs не установлен или не инициализирован, либо файл скачан по «raw»-ссылке вместо LFS. - Решение: выполните `git lfs install`, затем в каталоге репозитория `git lfs pull`. Надёжнее — качать через `hf download /-GGUF --include "*<квантизация>.gguf" --local-dir ./models`. **Проблема. Модель не влезает в видеопамять** - Ошибка: `CUDA error: out of memory` или `ggml_backend_cuda_buffer_type_alloc_buffer: allocating ... failed` - Причина: значение `-ngl` выгружает на GPU больше слоёв, чем помещается в память, либо слишком велик контекст. - Решение: уменьшайте `-ngl` шагами (например, `-ngl 20`, затем `-ngl 10`, затем `-ngl 0` — только CPU) и уменьшите контекст: `./build/bin/llama-server -m ../models/.gguf --host 127.0.0.1 --port 8080 -ngl 10 -c 2048`. Если и `-ngl 0` не работает — возьмите более сильную квантизацию (`Q4_K_M` вместо `Q8_0`). ## Резюме и следующие шаги Вы прошли путь от фильтра `GGUF` на Hugging Face до рабочего локального эндпоинта `http://127.0.0.1:8080/v1`. Дальше имеет смысл подобрать квантизацию и `-ngl` под свою видеокарту, а для запуска на телефоне — перейти к гайду [Как запустить ИИ-модель локально на Android: приложения и настройка](https://ai-release.org/guides/kak-zapustit-ii-model-lokalno-na-android-prilozheniya-i.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide). ## 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`, пока не упрётесь в лимит памяти.