Как импортировать 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, но это отдельный путь, и раздел о --quantize ниже показывает, где он применяется.

Все инструкции ниже предполагают, что 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 на Hugging Face, прочитанная 10 октября 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, и на сегодняшний день он применяется только в одном случае: модель, импортированная из каталога с весами .safetensors. Текст справки в текущем исходном коде Ollama, проверенный 10 октября 2026 года, гласит: "Quantize safetensors model to this level (e.g. nvfp4)", а допустимые значения: int4, int8, nvfp4, mxfp4 и mxfp8. Имена квантования GGUF, такие как q8_0 или q4_K_M, отклоняются как неподдерживаемые типы. Документация по импорту Ollama прямо говорит о GGUF: "Ollama не выполняет квантование моделей GGUF во время импорта".

ollama create --quantize int8 my-model

Эта команда предполагает наличие Modelfile, в котором строка FROM указывает на каталог, содержащий файлы .safetensors.

Не передавайте этот флаг, если FROM указывает на .gguf, независимо от его точности. GGUF в формате FP16 или FP32 отклоняется так же, как и Q4_K_M, с ошибкой, начинающейся со слов "create-time quantization is only supported for safetensors imports". Файл .gguf, в имени которого есть Q4_K_M или Q5_K_S, уже был квантован, и утраченную точность вернуть невозможно. Утилита llama-quantize из состава llama.cpp может перекодировать такой файл в другой тип, включая Q8_0, если передать --allow-requantize, но в руководстве предупреждается, что это "может значительно снизить качество по сравнению с квантованием из 16-битных или 32-битных исходников", а файл Q4, переписанный в Q8, станет больше, не став при этом лучше. Чтобы уменьшить GGUF с полной точностью, сначала запустите на нем llama-quantize — это инструмент, на который ссылается документация Ollama, а затем импортируйте файл, который он создаст. Если ваш источник — репозиторий Hugging Face с файлами .safetensors, вы можете либо указать FROM на этот каталог и позволить ollama create импортировать его (с --quantize, если хотите уменьшить размер), либо конвертировать его с помощью convert_hf_to_gguf.py из репозитория llama.cpp и импортировать 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, изученной 10 октября 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 работает только при импорте safetensors во время ollama create. Команда отклоняет любые исходные файлы GGUF, включая FP16 или FP32, выдавая ошибку с требованием квантовать GGUF-модели перед импортом. Файл, в имени которого уже указано квантование (например, Q4_K_M), уже был преобразован. Повторное квантование не вернет потерянную точность: llama-quantize --allow-requantize может переписать его в формате Q8_0, но результат станет больше, не став при этом лучше. Чтобы получить файл меньшего размера из полноразмерного GGUF, запустите на нем llama-quantize из состава llama.cpp и импортируйте полученный результат.

Как загрузить приватный репозиторий 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} будет работать с вашими приватными репозиториями и репозиториями организаций, в которых вы состоите.