Как использовать llama.cpp для запуска моделей

После выполнения этой инструкции вы сможете запустить локальную GGUF-модель через llama.cpp двумя способами: в терминале через CLI и как локальный OpenAI-совместимый сервер. Ниже — минимальный воспроизводимый маршрут, основанный на официальных README и docs проекта.

Короткий ответ: на 2026-08-15 самый предсказуемый путь — собрать llama.cpp из исходников, проверить бинарник через --version, подготовить модель в формате GGUF, затем запустить её через llama-cli или через llama-server и проверить сервер по /health.

• ⏱️ Время: 20–40 минут для сценария со сборкой из исходников; дольше, если вы отдельно подбираете backend или GPU-настройки.
• 🎯 Сложность: средний.
• 💰 Стоимость: upstream не указывает прямую цену. Проект open-source, но расходы на железо, Docker, GPU, хостинг и трафик зависят от вашей инфраструктуры и провайдера.
• 🛠️ Что потребуется: Unix-подобная среда для команд ниже, git, CMake, компилятор, GGUF-модель или идентификатор Hugging Face-совместимого репозитория.
• 📌 Актуальная версия: llama.cpp, latest release b10435 на 2026-08-15; релиз опубликован 2026-08-14 22:27. Команды и ограничения сверены по README, build/docs и README инструментов CLI/server.

Практический вердикт: если вам нужен самый понятный сценарий без догадок по матрице пакетных сборок, используйте сборку из исходников. Редакционное ограничение: в документации виден переход от legacy-имён llama-cli/llama-server к унифицированным вызовам llama cli/llama serve. На вашей системе сначала подтвердите реальное имя бинарника через --help или --version, а уже потом повторяйте команды ниже.

Какой способ установки выбрать

Текущий quick start в README даёт четыре официальных пути: llama.app, Docker, pre-built binaries из releases и сборка из исходников. Отдельный install guide также перечисляет conda-forge, winget, Homebrew, MacPorts и Nix. Для этой инструкции я беру путь через исходники, потому что для него в источниках зафиксированы точные команды сборки.

Если вы уже установили llama.cpp через release, Docker или пакетный менеджер, пропустите шаги 1–2 и переходите к проверке бинарника. Ниже для краткости используются legacy-имена ./llama-cli и ./llama-server, потому что они явно присутствуют в отдельных официальных документах; подставьте реальный путь и имя бинарника, которые покажет ваша установка.

Пошаговая инструкция

1. Шаг 1. Склонируйте репозиторий llama.cpp.

   git clone https://github.com/ggml-org/llama.cpp
   cd llama.cpp

   Это официальный старт для сборки из исходников. После клонирования вы работаете с тем же репозиторием, на который ссылаются README, build guide и docs моделей.

   Ожидаемый результат: у вас есть локальная директория llama.cpp, и вы находитесь в ней.

2. Шаг 2. Соберите проект в режиме Release.

   cmake -B build
   cmake --build build --config Release

   Это базовые команды из официального build guide. Если вам нужен конкретный CPU/GPU backend, не добавляйте флаги наугад: в build guide для разных backend есть отдельные флаги и verification steps, и они различаются по ОС и ускорителю.

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

3. Шаг 3. Подтвердите имя бинарника и версию сборки.

   ./llama-cli --version

   CLI-документация подтверждает, что --version показывает версию и информацию о сборке. Если вместо legacy-имени ваша установка использует новое имя из README, проверьте эквивалентную команду для llama cli.

   Ожидаемый результат: вы видите строку с версией и данными сборки, а не ошибку вида command not found или сообщение о неверном имени бинарника.

4. Шаг 4. Подготовьте модель именно в формате GGUF.

   Официальные docs/models.md требуют хранить модели в формате GGUF. Если у вас модель в другом формате, используйте скрипты конвертации из этого же репозитория; точный сценарий конвертации зависит от исходной модели, поэтому здесь его нельзя честно зафиксировать одной универсальной командой.

   Если вы не хотите предварительно складывать файл на диск, документация также подтверждает поддержку загрузки по идентификатору Hugging Face-совместимого репозитория через -hf <user>/<model>[:quant]. Для альтернативного Hugging Face-совместимого источника поддерживается MODEL_ENDPOINT.

   Ожидаемый результат: у вас либо есть локальный файл .gguf, либо вы знаете точный идентификатор репозитория и нужный вариант квантизации.

5. Шаг 5. Запустите модель локально через CLI.

   Если модель уже лежит на диске, укажите путь через -m:

   ./llama-cli -m /path/to/model.gguf

   Если модель нужно подтянуть из Hugging Face-совместимого источника, используйте:

   ./llama-cli -hf <user>/<model>[:quant]

   Документация подтверждает оба режима. Важный нюанс: если вы используете -hf, итоговый выбор файла лучше сверить по выводу запуска. В источниках отдельно отмечено, что по умолчанию предпочитается Q4_K_M, но при его отсутствии CLI может выбрать другой файл.

   Ожидаемый результат: процесс начинает загрузку модели и не падает на ошибке формата или отсутствующего файла.

6. Шаг 6. Поднимите локальный OpenAI-совместимый сервер, если вам нужен API-доступ.

   Server-документация описывает llama-server/llama serve как OpenAI API-compatible слой с маршрутами chat completions, responses и embeddings. Официальный quick start на Unix использует команду вида:

   ./llama-server -m /path/to/model.gguf -c 2048

   По умолчанию сервер слушает 127.0.0.1:8080.

   Ожидаемый результат: процесс сервера стартует, загружает модель и резервирует локальный адрес 127.0.0.1:8080.

Как проверить, что всё работает

Проверка зависит от режима запуска.

• CLI: убедитесь, что команда ./llama-cli --version отрабатывает и что запуск с -m или -hf доходит до загрузки модели без ошибок про формат, отсутствие файла или неправильное имя бинарника.
• Server: после старта откройте http://127.0.0.1:8080/health в браузере или запросите endpoint любым HTTP-клиентом.

curl http://127.0.0.1:8080/health

Ожидаемый результат: при полностью загруженной модели server отвечает кодом 200 и телом {"status": "ok"}.

Если вы поднимали server ради интеграции с приложениями, после успешного /health можно подключать OpenAI-совместимых клиентов. Для общего контекста инструмента посмотрите карточку llama.cpp — inference-движок для локального запуска LLM.

Частые ошибки и исправления

• Ошибка: llama-cli или llama-server не находится.

  Исправление: в проекте идёт переход к именам llama cli и llama serve. Сначала подтвердите реальное имя бинарника через --help или --version, затем подставьте его во все команды.

• Ошибка: модель не открывается или llama.cpp сообщает о неверном формате.

  Исправление: проверьте, что это именно GGUF. Для других форматов используйте скрипты конвертации из репозитория llama.cpp; универсальной команды для всех исходных моделей нет.

• Ошибка: сборка прошла, но нужный backend или ускорение недоступны.

  Исправление: пересоберите проект по официальному build guide с backend-специфичными флагами и verification steps. Не используйте случайные флаги из сторонних гайдов: в upstream они зависят от ОС и ускорителя.

• Ошибка: /health не возвращает {"status": "ok"}.

  Исправление: убедитесь, что server действительно запущен с моделью, дождитесь завершения загрузки модели и проверьте адрес 127.0.0.1:8080, который указан как адрес по умолчанию.

• Ошибка: при запуске через -hf подтянулся не тот quant, который вы ожидали.

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

Безопасность и ограничения

• Только GGUF: официальный формат для запуска в llama.cpp — GGUF. Всё остальное сначала нужно конвертировать.
• Локальность зависит от вашего сценария: если вы запускаете локальный .gguf, модель и инференс остаются в вашей среде. Если вы используете -hf или Hugging Face-совместимый источник через MODEL_ENDPOINT, вы обращаетесь к внешнему endpoint для получения модели.
• Server по умолчанию локальный: quick start server слушает 127.0.0.1:8080, то есть локальный интерфейс. Это удобно для безопасной локальной проверки и для разработки без внешней публикации.
• Доступность сборок меняется: релизные assets, Docker tags и package-manager сборки зависят от времени, платформы и архитектуры. Перед автоматизацией проверяйте текущие релизы и install guide.
• Docker имеет свои caveats: docs перечисляют образы full, light, server и GPU-варианты, но GPU-образы помечены как не полностью протестированные в CI.
• Стоимость не фиксирована upstream: проект open-source, но вычислительные затраты на CPU/GPU, хранение моделей и инфраструктуру придётся оценивать отдельно.

Что делать дальше

• Откройте карточку инструмента: llama.cpp — inference-движок для локального запуска LLM.
• Сравните альтернативы в подборке лучших инструментов для локального запуска моделей.
• Если хотите применить локальную модель в IDE, посмотрите инструкцию как использовать Cursor для автодополнения кода.
• Если ваша цель — практическая разработка, пригодится руководство как использовать ИИ для код-ревью.

Источники

• llama.cpp – conda-forge | Anaconda.org

• llama.cpp/README.md at master · ggml-org/llama.cpp · GitHub
• llama.cpp/docs/models.md at master · ggml-org/llama.cpp · GitHub
• llama.cpp/docs/build.md at master · ggml-org/llama.cpp · GitHub
• llama.cpp/docs/install.md at master · ggml-org/llama.cpp · GitHub
• llama.cpp/tools/cli/README.md at master · ggml-org/llama.cpp · GitHub
• llama.cpp/tools/server/README.md at master · ggml-org/llama.cpp · GitHub
• llama.cpp/docs/docker.md at master · ggml-org/llama.cpp · GitHub
• Releases · ggml-org/llama.cpp · GitHub

Вопросы и ответы

Можно ли запускать модели не в GGUF?

Напрямую инструкция upstream требует формат GGUF. Для других форматов используйте скрипты конвертации из репозитория llama.cpp; конкретные команды зависят от исходной модели.

Что выбрать: CLI или server?

CLI подходит для локального ручного запуска модели из терминала. Server нужен, если вы хотите OpenAI-совместимый интерфейс с маршрутами chat completions, responses и embeddings.

Обязательно ли собирать llama.cpp из исходников?

Нет. README перечисляет ещё llama.app, Docker и pre-built binaries из releases. Install guide дополнительно перечисляет conda-forge, winget, Homebrew, MacPorts и Nix. Но именно для сборки из исходников в источниках зафиксированы самые конкретные команды.

Работает ли это на Windows?

Да, install guide перечисляет как минимум winget и conda-forge среди вариантов установки. Но команды в этой инструкции ориентированы на Unix-подобную среду, поэтому для Windows нужно перепроверить конкретный способ установки и имя бинарника в официальной документации.

Почему запуск через -hf мог выбрать не тот quant?

В источниках отдельно отмечено, что по умолчанию предпочитается Q4_K_M, но при его отсутствии CLI может выбрать другой файл. Если вам нужен конкретный вариант, указывайте :quant явно и сверяйте выбор по выводу запуска.