Как импортировать GGUF модель в Ollama

Два способа импорта GGUF-модели в Ollama

Существует два способа импорта GGUF-модели в Ollama, и выбор зависит от того, где сейчас находится файл. Если модель размещена в репозитории Hugging Face, одна команда ollama run загрузит и запустит её без использования Modelfile. Если файл .gguf уже находится на диске вашего сервера, создайте Modelfile из двух строк и выполните ollama create.

Оба пути ведут к одному результату: именованной модели в вашей локальной библиотеке Ollama, которую могут обслуживать ollama run и Ollama API. Используйте первый способ, если файл опубликовал кто-то другой. Используйте второй, если вы выполнили квантование модели самостоятельно, если файл был передан через scp или rsync, либо если машина не имеет доступа к Hugging Face.

Файл GGUF — это единый бинарный файл, содержащий веса, токенизатор и метаданные модели. Это формат, который считывает llama.cpp, а так как Ollama построена на базе llama.cpp, почти для каждой открытой модели существует GGUF-конвертация, созданная сообществом. Ollama не загружает папку с весами .safetensors напрямую, поэтому этап конвертации необходим.

Всё, что описано ниже, предполагает, что Ollama уже установлена и её служба запущена. Если это не так, начните с установки Ollama на VPS и вернитесь сюда. Сначала выполните ollama list. Если команда вернет таблицу (даже пустую), а не ошибку соединения, значит сервер работает и остальная часть руководства будет выполнима.

Вариант первый: запуск GGUF из Hugging Face без Modelfile

Ollama может загружать GGUF напрямую из репозитория Hugging Face. Команда представляет собой путь к репозиторию с префиксом hf.co/:

ollama run hf.co/{username}/{repository}

hf.co и huggingface.co равнозначны в качестве доменного имени. Реальный пример из документации Hugging Face:

ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF

При первом запуске происходит загрузка файла, поэтому приглашение к чату появится только после завершения скачивания. После этого модель сохраняется в локальной библиотеке и запускается быстро. Откройте вторую оболочку и выполните ollama list, чтобы увидеть имя, под которым модель была сохранена. Это имя представляет собой всю строку hf.co/... вместе с тегом, что неудобно вводить каждый раз. Создайте короткий псевдоним:

ollama cp hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF my-llama
ollama run my-llama

Этот способ работает только с репозиториями, которые содержат файлы GGUF. Если в репозитории опубликованы только веса .safetensors, Ollama не сможет ничего загрузить, и вам потребуется этап конвертации, описанный ниже.

Какую квантование выбирает Ollama?

В документации Ollama на Hugging Face, прочитанной 25 августа 2026 года, прямо указано: «По умолчанию используется схема квантования Q4_K_M, если она присутствует в репозитории модели. Если нет, мы автоматически выбираем один из подходящих типов квантования, имеющихся в репозитории». Таким образом, если в репозитории опубликовано десять вариантов квантования, вы получите Q4_K_M, а если Q4_K_M отсутствует, Ollama выберет вариант за вас. Перечитайте эту страницу перед тем, как полагаться на неё, так как значения по умолчанию могут меняться.

Запросите конкретный тип квантования, добавив его в качестве тега:

ollama run hf.co/{username}/{repository}:{quantization}

ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:Q8_0
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:iq3_m
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:Llama-3.2-3B-Instruct-IQ3_M.gguf

Регистр имени квантования не имеет значения, поэтому :iq3_m и :IQ3_M означают одно и то же. Вы также можете передать точное имя файла в качестве тега; это самый надежный способ, если короткие имена в репозитории неоднозначны. Тег должен соответствовать имени файла, который существует в репозитории, поэтому откройте вкладку Files and versions и уточните реальные имена файлов перед вводом. Выбор квантования зависит от доступной памяти и требований к качеству; в различиях между Q4, Q8 и FP16 этот компромисс описан подробно.

Вариант второй: импорт файла .gguf с вашего диска

Если файл уже находится на сервере, вам потребуется Modelfile. Он может состоять из одной строки. Создайте каталог, поместите в него Modelfile и укажите путь к файлу в FROM:

mkdir -p ~/models/my-model
cd ~/models/my-model

FROM /home/you/models/my-model-Q4_K_M.gguf

Сохраните это как Modelfile, затем соберите модель:

ollama create my-model

ollama create по умолчанию считывает файл с именем Modelfile в текущем каталоге. Используйте -f, если ваш файл называется иначе или находится в другом месте, как в ollama create my-model -f /home/you/models/my-model/Modelfile. Запустите ollama create --help, чтобы увидеть этот флаг и его значение по умолчанию для вашей сборки. Путь в FROM может быть абсолютным или относительным относительно Modelfile, поэтому FROM ./my-model-Q4_K_M.gguf сработает, если оба файла находятся в одном каталоге. Абсолютный путь полностью исключает двусмысленность.

Проверьте результат, прежде чем доверять ему:

ollama list
ollama show my-model
ollama run my-model "Reply with one short sentence."

ollama list теперь должен включать my-model. ollama show my-model выводит архитектуру, количество параметров, длину контекста и квантование, которые Ollama считала из метаданных самого файла. Читайте эти значения, а не доверяйте имени файла, так как имя файла — это строка, которую кто-то ввел вручную. Если модель отвечает на ваш тестовый запрос на обычном языке и затем останавливается, импорт прошел успешно. Если нет, перейдите к разделу о шаблонах ниже, так как причина почти всегда кроется в этом.

Важный момент относительно дискового пространства: ollama create копирует GGUF в собственное хранилище моделей Ollama, а не ссылается на файл там, где он лежит. Веса будут занимать место на диске дважды, пока вы не удалите оригинал. Удалите исходный файл, как только ollama run my-model заработает, или храните его там, где вы не платите за дублирование данных. В разделе о том, где Ollama хранит модели на диске описана структура каталогов и способы её перемещения.

Когда применяется --quantize, а когда нет

ollama create имеет флаг --quantize, и он существует только для одного случая: исходная модель в формате FP16 или FP32, что означает веса с полной точностью. Документация по импорту Ollama перечисляет q8_0, а также варианты k-means q4_K_S и q4_K_M в качестве целевых форматов.

ollama create --quantize q4_K_M my-model

Не используйте этот флаг для файла, который уже квантован. Файл .gguf, в имени которого есть Q4_K_M или Q5_K_S, уже прошел этот этап, и флагу нечего делать. Квантование — это одностороннее преобразование с понижением точности, поэтому пути от Q4 обратно к Q8 не существует. Если ваш источник — репозиторий Hugging Face с файлами .safetensors, сначала конвертируйте его с помощью convert_hf_to_gguf.py из репозитория llama.cpp — это инструмент, на который ссылается документация Ollama, — а затем импортируйте GGUF, который создаст этот скрипт. В разделе о связи Ollama и llama.cpp объясняется, почему скрипт конвертации относится к другому проекту.

Почему импортированная модель GGUF выдает «мусор» или не останавливается?

Это проблема, которую пропускают большинство руководств по импорту, и именно с ней вы столкнетесь. Симптомы выглядят как неисправность модели. Управляющие токены отображаются в ответе как обычный текст, например, строки вида <|im_start|>assistant или <|end|>. Модель отвечает, затем сама пишет новый вопрос от имени пользователя и отвечает на него. Генерация продолжается до тех пор, пока вы не нажмете Ctrl+C.

С моделью всё в порядке. Ошибка в шаблоне чата (chat template). Шаблон чата — это обертка, которая преобразует ваше сообщение в точную последовательность токенов, на которой обучалась модель, включая специальные маркеры, обозначающие конец системного промпта и начало реплики пользователя. Ollama выбирает шаблон за вас: в документации сказано, что шаблон «будет выбран автоматически из списка часто используемых» на основе встроенных метаданных tokenizer.chat_template, хранящихся внутри файла GGUF. Если эти метаданные отсутствуют или не соответствуют ни одному шаблону из списка, вы получаете универсальную обертку. В результате модель видит промпт, структура которого не совпадает с данными из обучения, и не находит маркер завершения реплики, на котором она должна остановиться.

Выведите шаблон, который фактически выбрала Ollama:

ollama show --template my-model
ollama show --modelfile my-model

Пустой или явно универсальный шаблон подтверждает проблему. Пропишите шаблон самостоятельно в Modelfile:

FROM /home/you/models/my-model-Q4_K_M.gguf

TEMPLATE """{{ if .System }}<|system|>
{{ .System }}<|end|>
{{ end }}{{ if .Prompt }}<|user|>
{{ .Prompt }}<|end|>
{{ end }}<|assistant|>
{{ .Response }}<|end|>"""

PARAMETER stop "<|end|>"

Пересоберите модель с помощью ollama create my-model и отправьте тот же тестовый промпт снова. Параметр stop — ваша страховка: он указывает Ollama прекратить генерацию при появлении этой строки. Это устраняет симптом бесконечной генерации, пока вы подбираете правильную обертку. Если ответ всё равно продолжается, так как указанный маркер не появляется, ограничение num_predict принудительно прервет генерацию на заданном количестве токенов, независимо от того, что выдает шаблон.

Шаблон должен быть написан на языке Go templates, а не Jinja. Документация Hugging Face прямо указывает на это, и это важно, так как поле tokenizer.chat_template в репозитории оригинальной модели содержит код Jinja. Если просто скопировать его без изменений, он не будет работать. Синтаксис Ollama использует три переменные: {{ .System }} для системного промпта, {{ .Prompt }} для сообщения пользователя и {{ .Response }} для ответа модели. Найдите реальные маркеры реплик модели в её карточке (model card) или в файле tokenizer_config.json, а затем вручную перепишите их в синтаксис Go.

Один простой способ позволяет сэкономить большую часть этой работы. Многие модели используют общий формат промпта, поэтому, если в вашей библиотеке есть другая модель с таким же форматом, выполните ollama show --template для неё и скопируйте полученный результат.

Файлы шаблонов, системных промптов и параметров в репозитории Hugging Face

Маршрут Hugging Face предоставляет те же элементы управления, что и файлы в репозитории, вместо инструкций в Modelfile. Если вы являетесь владельцем репозитория или публикуете собственный квантованный файл, добавьте их туда, и каждый ollama run hf.co/... будет их использовать.

• Файл с именем template содержит шаблон Go. Правило прежнее: используется Go, а не Jinja.
• Файл с именем system содержит системный промпт.
• Файл с именем params содержит параметры выборки и должен быть в формате JSON.

Минимальный файл params:

{
  "stop": ["<|end|>"],
  "temperature": 0.7
}

Если вы не являетесь владельцем репозитория, вы не можете добавить эти файлы. Загрузите модель один раз, выполните ollama show --modelfile hf.co/..., чтобы вывести полученные данные, и сохраните этот вывод как Modelfile. Его строка FROM указывает на blob-объект, который Ollama уже загрузила, поэтому вы редактируете строки TEMPLATE и PARAMETER и выполняете ollama create для создания исправленной локальной копии без повторной загрузки данных. Это стандартный способ исправления некорректно настроенной чужой квантованной модели.

Импорт приватного репозитория GGUF

Для доступа к приватному репозиторию необходимо добавить SSH-ключ Ollama в вашу учетную запись Hugging Face. Документированный метод для этого сценария использует SSH-ключ, а не API-токен, поэтому имеющийся у вас токен не обеспечит доступ.

Выведите содержимое публичного ключа. На сервере Linux, где Ollama была установлена с помощью официального скрипта, служба работает от имени пользователя ollama, поэтому ключ находится в домашнем каталоге этого пользователя:

sudo cat /usr/share/ollama/.ollama/id_ed25519.pub

Если вы запускаете ollama serve самостоятельно от своего имени, путь будет выглядеть как ~/.ollama/id_ed25519.pub. Скопируйте всю строку, откройте настройки вашей учетной записи Hugging Face по адресу https://huggingface.co/settings/keys и добавьте её как новый SSH-ключ. После этого стандартная команда будет работать с вашими приватными репозиториями:

ollama run hf.co/{username}/{repository}

Если после добавления ключа загрузка по-прежнему завершается ошибкой, вероятно, вы вывели содержимое не того файла. Загрузку выполняет сервер, используя свой собственный ключ. Сервер, запущенный через systemd, не считывает файл ~/.ollama вашего пользователя, поэтому ключ в вашем домашнем каталоге не является тем, который видит Hugging Face.

Поместится ли модель на ваш VPS?

Решающим фактором является размер файла на диске плюс объем памяти, необходимый для контекстного окна. Веса загружаются в память в объеме, близком к их размеру в файле, а выделение памяти под контекст добавляется сверху и растет пропорционально количеству разрешенных токенов. Запустите ollama list, чтобы узнать размер, который Ollama зафиксировала для модели, сравните его с free -h на сервере и оставьте запас для операционной системы и других запущенных процессов. Если вы хотите увидеть расчеты на примере реальной модели, запуск Nemotron 3.5 Lightning на VPS содержит точный тег для загрузки, необходимые требования к RAM и информацию о производительности на сервере без GPU.

Контекст — это то, о чем часто забывают. Модель, которая загружается с параметрами окна по умолчанию, может завершиться с ошибкой при увеличении num_ctx, так как объем выделяемой памяти масштабируется в зависимости от заданного размера окна. В статье Настройка num_ctx и затраты памяти приведены правила расчета. Если итоговый объем слишком велик, обычно помогает выбор квантованной версии той же модели меньшего размера; этот компромисс рассмотрен в сравнении Q4 и Q8.

Сбой происходит явно. На VPS без GPU механизм OOM killer ядра завершает процесс, а journalctl -u ollama -n 50 вместе с dmesg показывают факт принудительного завершения. На сервере с GPU команда ollama ps выводит столбец PROCESSOR, который показывает, была ли загружена модель в память GPU, в системную память или распределена между ними. Модель, которая была вытеснена в системную память, продолжает отвечать, но медленно. Измерение количества токенов в секунду позволяет перевести понятие «медленно» в конкретные числа, которые можно сравнивать между разными квантованиями.

Проверка импортированных данных

Выполните эти четыре команды после любого импорта строго в указанном порядке:

ollama list
ollama show my-model
ollama show --modelfile my-model
ollama run my-model "Reply with one short sentence."

ollama list подтверждает наличие модели и показывает размер, зафиксированный в Ollama. ollama show подтверждает, что Ollama успешно считала необходимые метаданные из файла GGUF. ollama show --modelfile показывает, какой шаблон и параметры будут использоваться на самом деле; эта проверка позволяет выявить некорректный вывод до того, как с ним столкнутся пользователи. Тестовый запрос проверяет всю цепочку целиком, так как модель с поврежденным шаблоном выдает ошибку даже на самом коротком запросе. Как только вы получите корректный ответ, используйте имя модели для взаимодействия с API Ollama, включая настройку агента для написания кода на вашем сервере. Удалите неудачный импорт с помощью ollama rm my-model и повторите сборку. Эта команда удаляет копию Ollama, оставляя исходный файл .gguf без изменений.

FAQ

Можно ли импортировать GGUF в Ollama без создания Modelfile?

Да, если файл находится в репозитории Hugging Face. ollama run hf.co/{username}/{repository} загружает и запускает его напрямую, а ollama run hf.co/{username}/{repository}:{quantization} позволяет выбрать конкретный квантованный вариант. Modelfile требуется только для .gguf, который уже находится на вашем диске; в этом случае он может состоять из одной строки FROM /path/to/file.gguf, за которой следует ollama create my-model.

Какую квантованную версию скачивает Ollama, если я не указываю её явно?

Согласно документации Hugging Face, актуальной на 25 августа 2026 года, используется Q4_K_M, если этот вариант присутствует в репозитории. В противном случае Ollama выбирает один из подходящих типов квантования, имеющихся в репозитории. Чтобы управлять выбором, добавьте тег, например :Q8_0. Проверьте, что именно было загружено, с помощью ollama show <model>: эта команда выводит тип квантования из метаданных файла, а не из его имени.

Почему импортированная модель повторяется или не прекращает генерацию?

Шаблон чата не соответствует модели. Ollama выбирает шаблон автоматически на основе метаданных tokenizer.chat_template внутри GGUF. Если эти метаданные отсутствуют или не распознаются, используется стандартная обёртка, из-за чего модель не видит маркер завершения хода, на котором она обучалась. Выведите текущий шаблон с помощью ollama show --template <model>, затем добавьте блок TEMPLATE и строку PARAMETER stop в Modelfile и снова выполните ollama create. Используйте синтаксис шаблонов Go. Шаблон Jinja из оригинального репозитория работать не будет.

Нужно ли использовать --quantize для скачанного GGUF?

Нет. --quantize выполняет конвертацию из исходного формата FP16 или FP32 во время ollama create, а файл, в имени которого уже указан тип квантования (например, Q4_K_M), уже был конвертирован. Точность нельзя восстановить повторным квантованием, и обратного пути к исходному качеству нет. Используйте этот флаг только в том случае, если вы самостоятельно конвертировали safetensors в GGUF с полной точностью и теперь хотите получить уменьшенную версию.

Как загрузить приватный репозиторий GGUF?

Добавьте публичный SSH-ключ Ollama в свою учётную запись Hugging Face. Выведите его с помощью sudo cat /usr/share/ollama/.ollama/id_ed25519.pub при стандартной установке в Linux или из ~/.ollama/id_ed25519.pub, если вы запускаете сервер от имени своего пользователя, а затем добавьте его на странице настроек SSH-ключей в личном кабинете. После этого ollama run hf.co/{username}/{repository} будет работать с вашими приватными репозиториями и репозиториями организаций, в которых вы состоите.