Як запускати GGUF-моделі з Hugging Face в Ollama

В огляді Ollama 0.30 я показав базову механіку запуску GGUF у три кроки і пообіцяв окремий розбір з усіма нюансами. Ось він. Тут — повний практичний гайд: де брати GGUF-файл, як правильно написати Modelfile, які команди виконати, як перевірити підтримку tool calling і що робити, коли модель не запускається.

Гайд розрахований на тих, хто вже має встановлену Ollama. Якщо ще ні — почни з гайда зі встановлення Ollama на Mac, Windows і Linux.

Коротко: завантажуєш .gguf-файл з Hugging Face, створюєш текстовий Modelfile з одним рядком FROM ./файл.gguf, виконуєш ollama create my-model -f Modelfile — і модель готова. Усе інше в цій статті — нюанси, які відрізняють «запустилось» від «працює як треба».

Зміст

1. Що таке GGUF і чому моделі лежать саме в цьому форматі
2. Що знадобиться перед стартом
3. Крок 1: завантажуєш GGUF-файл з Hugging Face
4. Крок 2: створюєш Modelfile
5. Крок 3: ollama create і ollama run
6. Перевірка: чи підтримує модель tool calling
7. Підключення до coding-агента через ollama launch
8. Типові помилки і як їх діагностувати
9. З особистого досвіду
10. Висновки

Що таке GGUF і чому моделі лежать саме в цьому форматі

GGUF — це формат-контейнер для моделі: ваги, токенізатор і метадані упаковані в один файл, у вже квантизованому вигляді. Формат створив Георгій Герганов, автор llama.cpp — і саме тому Ollama, яка працює поверх llama.cpp, читає GGUF як рідний формат.

Практичний наслідок простий: більшість нових open-weight моделей спершу зʼявляється у форматі GGUF на Hugging Face, і лише потім (якщо взагалі) потрапляє в офіційний реєстр Ollama. Якщо хочеш запустити модель, якої немає в ollama pull, або конкретну квантизацію — GGUF-файл це твій шлях. Як саме Ollama співвідноситься з llama.cpp і де в цьому стеку місце GGUF, я розбирав в огляді 0.30 — тут не дублюю.

Важливо розуміти межу: Ollama не запускає .gguf-файл напряму як ollama run ./file.gguf. Файл спершу треба «зареєструвати» через Modelfile командою ollama create. Це займає менше двох хвилин і робиться один раз на модель.

Що знадобиться перед стартом

Три речі:

• Ollama 0.30 або новіша — у цій версії розширена сумісність GGUF. Перевір версію: ollama --version. Як оновитись — у огляді 0.30.
• Акаунт на Hugging Face — формально не обовʼязковий для публічних моделей, але зручний, якщо хочеш качати через CLI або працювати з gated-моделями (які вимагають згоди на ліцензію).
• Достатньо місця на диску і RAM — розмір залежить від квантизації (про це нижче).

Як читати назви квантизацій у файлах

На Hugging Face одна модель зазвичай має кілька GGUF-файлів з різними квантизаціями в назві: model.Q4_K_M.gguf, model.Q5_K_M.gguf, model.Q8_0.gguf тощо. Число після Q — кількість біт на параметр: менше число — менший файл і менше RAM, але нижча якість.

Коротке практичне правило для вибору: Q4_K_M — золотий баланс розміру і якості для більшості випадків. Q5_K_M або Q8_0 — якщо потрібна вища точність і є запас памʼяті. Q2/Q3 — крайній варіант для дуже обмеженого заліза з помітною втратою якості.

Детальний розбір рівнів квантизації, скільки RAM займає кожен і чому Q4_K_M майже завжди кращий за Q2 більшої моделі — у статті Ollama на 8 ГБ RAM: які моделі працюють у 2026. Тут лише запамʼятай: розмір файлу в назві ≈ скільки RAM знадобиться плюс 1–2 ГБ на KV-кеш.

Крок 1: завантажуєш GGUF-файл з Hugging Face

На сторінці моделі на Hugging Face відкрий вкладку Files and versions. Там ти побачиш список .gguf-файлів з різними квантизаціями. Обери потрібну (зазвичай Q4_K_M) і завантаж — або кнопкою завантаження поряд з файлом, або через CLI.

Через браузер: просто натисни на іконку завантаження біля потрібного файлу.

Через CLI (зручніше для великих файлів і відтворюваності):

# встановити Hugging Face CLI (один раз)
pip install -U "huggingface_hub[cli]"

# завантажити конкретний GGUF-файл у поточну теку
hf download <user>/<repo> model.Q4_K_M.gguf --local-dir .

Поклади файл у фіксовану теку, з якої будеш на нього посилатись. Порада з практики: якщо в назві файлу є пробіли чи спецсимволи — перейменуй його у щось просте на кшталт model.gguf, інакше шлях у Modelfile доведеться екранувати.

Пастка з шардами. Великі моделі на Hugging Face часто розбиті на кілька файлів — model-00001-of-00005.gguf, model-00002-of-00005.gguf і так далі. Це sharded (розбиті) GGUF. Ollama наразі не запускає sharded GGUF напряму — команда впаде з помилкою. Такі файли спершу треба злити в один через llama-gguf-split --merge з llama.cpp. Детальніше — у розділі про помилки нижче.

Крок 2: створюєш Modelfile

Modelfile — це текстовий файл (без розширення), який описує, як зібрати модель. Для запуску GGUF мінімальний Modelfile складається з одного рядка — директиви FROM зі шляхом до файлу:

FROM ./model.Q4_K_M.gguf

Якщо твоя мета — просто запустити модель, цього рядка зазвичай достатньо. Збережи файл під назвою Modelfile у тій самій теці, де лежить .gguf.

Що ще можна покласти в Modelfile

Окрім FROM, Modelfile приймає кілька опціональних директив, які помітно покращують поведінку моделі під конкретну задачу. Найкорисніші:

FROM ./model.Q4_K_M.gguf

# Параметри інференсу
PARAMETER temperature 0.7
PARAMETER num_ctx 8192
PARAMETER stop "</s>"

# Системний промпт за замовчуванням
SYSTEM """Ти — технічний асистент. Відповідай стисло і по суті."""

# Шаблон промпту (потрібен деяким чат-моделям для коректних відповідей)
TEMPLATE "[INST] {{ .Prompt }} [/INST]"

Коротко що роблять директиви: PARAMETER temperature керує «креативністю» відповідей, PARAMETER num_ctx задає розмір контекстного вікна (більше — більше RAM на KV-кеш), PARAMETER stop визначає стоп-токени, SYSTEM задає системний промпт, а TEMPLATE — формат, у якому промпт подається моделі.

Про TEMPLATE окремо. Багато чат-моделей вимагають правильний шаблон промпту, інакше відповідають некоректно або «ламано». Якщо модель після запуску поводиться дивно — перша підозра саме на шаблон. Правильний TEMPLATE зазвичай вказаний на сторінці моделі на Hugging Face або в картці моделі. Як орієнтир можна підглянути шаблон офіційної моделі схожої архітектури: ollama show llama3.2 --modelfile.

Якщо для старту тобі вистачає одного FROM — починай з нього, а параметри додавай за потреби. Не ускладнюй Modelfile наперед.

Крок 3: ollama create і ollama run

З теки, де лежить Modelfile, виконай команду створення моделі:

ollama create my-model -f Modelfile

Ollama прочитає Modelfile, зареєструє GGUF як локальну модель під назвою my-model і додасть її у свій реєстр. Зазвичай це займає 10–60 секунд залежно від розміру файлу. Перевірити, що модель зʼявилась:

ollama list

Тепер модель можна запускати як будь-яку іншу:

ollama run my-model "Привіт! Що ти вмієш?"

Найчастіша помилка — порядок аргументів. Правильно: ollama create my-model -f Modelfile (спочатку назва, потім прапорець -f зі шляхом до Modelfile). Багато переказів плутають порядок і пишуть ollama create -f Modelfile my-model — така команда впаде з помилкою. Якщо Modelfile лежить у поточній теці й названий саме Modelfile, прапорець -f можна навіть не вказувати: ollama create my-model підхопить його автоматично.

Після create модель доступна і через CLI, і через локальний REST API на порту 11434 — одразу, без додаткових кроків. Як інтегрувати її у свій застосунок на Java, Python чи JavaScript — у статті Ollama REST API: інтеграція у свій застосунок.

Перевірка: чи підтримує модель tool calling

Якщо ти плануєш використовувати модель в агенті — недостатньо, щоб вона просто запустилась. Потрібно, щоб вона підтримувала tool calling нативно. Перевір це через ollama show, дивлячись на секцію Capabilities:

ollama show my-model

Capabilities
  completion
  tools           ← є — модель підтримує виклик інструментів

Якщо tools у секції Capabilities немає — модель не викличе інструменти нативно. Ollama спробує fallback через промпт, але це ненадійно: модель може повернути JSON у тексті замість структурованого tool_calls, або проігнорувати інструмент зовсім. Для агентного пайплайну така модель не підходить.

Важливий нюанс: підтримка tool calling залежить не від формату GGUF, а від того, на чому модель навчалась. Один і той самий .gguf-файл або має цю здатність «вшиту» у ваги, або ні — Modelfile тут нічого не додасть.

Як обрати модель, яка стабільно викликає інструменти (з порівнянням надійності, швидкості й multi-tool) — у статті Яку модель Ollama обрати для агента з tool calling. А як влаштований сам виклик на рівні API і чим він відрізняється від простого function calling — у статті Tool use vs function calling: механіка, JSON Schema і звʼязок з RAG.

Підключення до coding-агента через ollama launch

Коли GGUF запущений і підтримує tool calling, його можна підключити до coding-агента однією командою. Наприклад, для Claude Code:

ollama launch claude

Команда інтерактивно проведе через вибір моделі та запустить інтеграцію без ручного редагування конфігів. Офіційно підтримуються Claude Code, OpenCode, Codex і Droid. Детальніше про ollama launch, його синтаксис і типові неточності в переказах — у розділі огляду 0.30. Тут лише фіксую сам місток: запустив GGUF → перевірив tools → підключив до агента.

Типові помилки і як їх діагностувати

Більшість проблем із запуском GGUF зводяться до кількох сценаріїв. Нижче — діагностика для кожного.

Помилка 1. Sharded GGUF — модель розбита на кілька файлів

Як виглядає: у репозиторії замість одного файлу — model-00001-of-00005.gguf, model-00002-of-00005.gguf і т.д. Спроба запустити падає з помилкою про непідтримку sharded GGUF.

Причина: Ollama наразі не вміє завантажувати розбиті GGUF напряму.

Рішення: злий шарди в один файл через інструмент llama-gguf-split з llama.cpp:

llama-gguf-split --merge model-00001-of-00005.gguf model-merged.gguf

Потім вказуй у Modelfile вже злитий файл: FROM ./model-merged.gguf. Альтернатива — пошукати в тому ж репозиторії несплітнуту версію меншої квантизації (часто вони лежать поряд).

Помилка 2. Out of memory — модель не вміщується в RAM

Як виглядає: create проходить, але run або падає, або модель завантажується десятки секунд і видає 1–2 токени на секунду з постійними паузами.

Причина: обрана квантизація завелика для твого заліза. Успішний create не гарантує, що модель комфортно працюватиме.

Рішення: візьми меншу квантизацію (Q4_K_M замість Q8_0) або меншу модель. Перевір реальне завантаження після run:

ollama ps
# Дивись на колонку PROCESSOR:
# 100% GPU  — добре
# частково CPU — модель свопить, треба менша квантизація

Орієнтир по памʼяті й вибору під слабке залізо — у статті Ollama на 8 ГБ RAM.

Помилка 3. Невірний шлях у FROM

Як виглядає: ollama create падає з повідомленням, що файл не знайдено.

Причина: шлях у FROM не збігається з реальним розташуванням .gguf, або в назві файлу є пробіли/спецсимволи.

Рішення: запускай create з тієї самої теки, де лежить файл, і використовуй відносний шлях FROM ./model.gguf. Якщо в назві файлу є пробіли — перейменуй у щось просте.

Помилка 4. Модель відповідає «ламано» або ігнорує формат

Як виглядає: модель запустилась, але відповіді обірвані, з дивними токенами або не тримають формат чату.

Причина: неправильний або відсутній TEMPLATE у Modelfile. Чат-моделі чутливі до шаблону промпту.

Рішення: знайди правильний шаблон у картці моделі на Hugging Face і додай директиву TEMPLATE. Як орієнтир — подивись Modelfile офіційної моделі схожої архітектури: ollama show llama3.2 --modelfile.

Помилка 5. Модель працює, але tool_calls порожній

Як виглядає: в агенті модель відповідає текстом замість того, щоб викликати інструмент; tool_calls у відповіді порожній.

Причина: модель не підтримує tool calling нативно (а не проблема GGUF чи Modelfile).

Рішення: перевір ollama show my-model — чи є tools у Capabilities. Якщо немає — заміни модель на ту, що підтримує. Детальніше — у статті про вибір моделі для агента.

Швидка таблиця діагностики

З особистого досвіду

На моєму MacBook Pro M1 16 ГБ я регулярно тестую нові моделі з Hugging Face перш ніж брати щось у роботу для AskYourDocs. Сценарій майже завжди однаковий: знаходжу свіжу модель або цікаву квантизацію, якої ще немає в офіційному реєстрі Ollama, завантажую Q4_K_M-файл, пишу Modelfile з одного FROM і перевіряю через ollama show, чи є tools — бо без них модель для мого агентного пайплайну марна.

Дві речі, на яких я обпікався і які тепер перевіряю першими. Перша — шарди: великі моделі часто розбиті, і поки не звик, витрачав час на «чому не запускається», аж поки не зрозумів, що Ollama їх просто не бере без злиття. Друга — шаблон: одного разу модель запустилась, але відповідала уривками, і я думав що зламаний файл — а проблема була у відсутньому TEMPLATE. Тому порада з досвіду: якщо модель поводиться дивно, не поспішай перезавантажувати файл — спершу перевір шаблон і ollama ps.

Висновки

• Базовий шлях — завантажити .gguf, написати Modelfile з одним FROM, виконати ollama create my-model -f Modelfile.
• Порядок аргументів у create має значення: спочатку назва, потім -f Modelfile.
• Sharded GGUF Ollama не бере напряму — злий через llama-gguf-split --merge.
• Квантизацію обирай під своє залізо: Q4_K_M — безпечний старт для більшості.
• Для агента завжди перевіряй tools у ollama show — запуск не гарантує підтримку tool calling.
• Дивна поведінка моделі — перша підозра на TEMPLATE, а не на зламаний файл.

Що нового в самій версії 0.30 і чому інтеграція з llama.cpp відкрила весь GGUF-екосистему — в огляді Ollama 0.30. А якщо наступний крок — вибрати модель саме під агента з tool calling, переходь до порівняння моделей за надійністю.

Джерела

• Ollama — Importing a Model (офіційна документація)
• llama.cpp — GitHub (формат GGUF, gguf-split)
• Hugging Face — реєстр моделей