KoboldCpp: инференс для тех, кому не нужен Docker

MAATRIX

Хочется просто запустить локальную модель и пообщаться с ней в браузере, а вместо этого выходит установка Docker, разбор docker-compose.yml, venv с точными версиями CUDA — и половина инструкций вообще не подходит для VPS без GPU. KoboldCpp решает именно эту боль: скачиваете один файл, запускаете его, открываете браузер — и всё работает без единого контейнера. Ниже — честный разбор, кому этот путь подходит, а кому лучше сразу смотреть в сторону production-инструментов.

Для кого этот инструмент

Целевой читатель — не DevOps-инженер, а человек, который хочет за один вечер попробовать локальную LLM: разработчик без опыта с контейнерами, автор, которому нужен приватный чат без утечки текстов в облако, энтузиаст, уставший от подписок на облачные API. Ему не нужен кластер и балансировщик нагрузки — нужен рабочий чат-бот на своём железе, желательно за один вечер, а не после недели чтения документации по Kubernetes.

Типичный первый опыт с локальным инференсом: находишь инструкцию по vLLM, там pip install vllm, конфликт версий CUDA с уже стоящим драйвером, час на пересборку окружения. Или Docker: поставить сам Docker, разобраться с --gpus all, пробросить том с весами модели, дождаться скачивания образа на несколько гигабайт — и это ещё до того, как модель начала думать. Для разового эксперимента порог входа неоправданно высокий.

KoboldCpp не заменяет Docker и не решает то, что Docker решает хорошо — воспроизводимость окружения, изоляцию, оркестрацию нескольких сервисов. Он закрывает более узкую и при этом более частую задачу: дать одному человеку на одной машине запустить одну модель максимально быстро. Сценарий "поставить и поговорить", а не "поставить одинаково на 50 серверов" — это именно сюда.

Что такое KoboldCpp

Проект вырос из сообщества KoboldAI, изначально заточенного под текстовые приключения и ролевые чаты, а сейчас работает как универсальный сервер инференса. Технически это надстройка над llama.cpp — тем же движком на C/C++ поверх библиотеки ggml, который грузит модели в формате GGUF и гоняет их на CPU, на GPU через CUDA/Vulkan/OpenCL или в смешанном режиме, раскидывая часть слоёв сети на видеокарту, а часть оставляя процессору.

Разница с "чистым" llama.cpp — в подаче. Сам llama.cpp — набор бинарников (llama-server, llama-cli, llama-quantize), из которых нужно самому собрать связный workflow: скомпилировать через CMake, разобраться с флагами, поднять сервер. Мы разбирали этот путь в статье про установку llama.cpp на VPS — он даёт максимум контроля, но требует и больше самостоятельной сборки. KoboldCpp берёт тот же движок и упаковывает в готовый продукт: один исполняемый файл, встроенный веб-интерфейс, встроенный HTTP API.

Похожую задачу решает и Ollama, но другим способом — через собственный формат хранения и менеджер загрузок моделей; разница подходов разобрана в материале про llama.cpp против Ollama. KoboldCpp ближе к "сырому" llama.cpp тем, что напрямую работает с файлами GGUF без промежуточного реестра, но при этом даёт готовый UI, которого у голого llama.cpp нет.

Установка без Docker

Практическая выгода для целевой аудитории — вот весь процесс на Linux-сервере:

# скачиваем бинарник с GitHub Releases проекта LostRuins/koboldcpp
wget https://github.com/LostRuins/koboldcpp/releases/latest/download/koboldcpp-linux-x64 -O koboldcpp

# делаем исполняемым
chmod +x koboldcpp

# запускаем с моделью в формате GGUF
./koboldcpp --model qwen2.5-7b-instruct-q4_k_m.gguf --port 5001 --host 0.0.0.0

Точное имя файла в Releases отличается от версии к версии (сборки публикуются под разные архитектуры и GPU-бэкенды) — актуальное имя проверяйте на странице релизов, а не полагайтесь на жёстко прописанную ссылку. Принцип не меняется: нет docker pull, нет ожидания скачивания образа, нет правки docker-compose.yml, нет настройки томов под веса модели — файл модели просто лежит рядом или указывается полным путём.

Стоит сказать честно: у KoboldCpp также существует установщик с графическим интерфейсом и вариант через Python-скрипт с зависимостями — так исторически развивался проект. Но именно скачиваемый одиночный бинарник для Linux/Windows/macOS — то, что отличает его от большинства других инструментов инференса и делает "без Docker и без Python" буквально верным для типичного сценария на сервере.

Веб-интерфейс из коробки

После запуска сервер поднимает встроенный веб-интерфейс Kobold Lite прямо на указанном порту — открываете http://ваш-ip:5001 и сразу попадаете в чат, без отдельного шага "теперь разверните ещё и фронтенд". Это отличается от голого llama.cpp, где веб-морда у llama-server минималистична, или от Ollama, у которой из коробки графического интерфейса вообще нет — только терминальный ollama run или сторонний UI поверх её API.

В Kobold Lite есть несколько режимов: обычный чат, "инструктаж" под модели, дообученные следовать указаниям, и оригинальный режим текстового приключения, из которого вырос проект. Температура, top-p, top-k, штраф за повторы, длина контекста — регулируются ползунками прямо в интерфейсе, без правки конфигов.

Помимо веб-интерфейса, KoboldCpp поднимает HTTP API, частично совместимый с форматом OpenAI (/v1/chat/completions) и свой нативный API (/api/v1/generate) — можно подключать сторонние клиенты так же, как к любому OpenAI-совместимому эндпоинту. По умолчанию сервер слушает только 127.0.0.1; для доступа с других машин нужен флаг --host 0.0.0.0 и обязательно открытие порта в файрволе только для доверенных адресов — интерфейс без авторизации, показанный всему интернету, это прямой риск.

Квантование под скромное железо

KoboldCpp работает с тем же форматом GGUF, что и llama.cpp — модель можно взять сжатой (квантованной) под конкретный объём памяти сервера, а не только в исходной точности fp16, которая требует в разы больше RAM или VRAM. Квантование — компромисс между размером/скоростью и точностью: чем агрессивнее сжатие, тем меньше памяти нужно, но тем больше модель теряет в качестве ответов.

Практический ориентир (без точных цифр по конкретной модели — они зависят от архитектуры, размер файла всегда стоит проверять перед скачиванием):

Выбор конкретного кванта под конкретные семейства моделей подробнее разобран в материале про квантование Q4/Q5/Q8: что выбрать. Для KoboldCpp правило то же: скачиваете GGUF нужного кванта и указываете путь флагом --model.

Управлять нагрузкой помогают флаги: --threads N — число потоков CPU под генерацию, --contextsize N — размер контекстного окна (больше окно — больше памяти уходит на KV-кэш), --gpulayers N — сколько слоёв сети выгрузить на видеокарту, если она есть, при этом бэкенд GPU (CUDA, Vulkan, CLBlast) выбирается отдельным флагом при запуске — актуальный список стоит смотреть через ./koboldcpp --help, он менялся от версии к версии. Видеокарты нет вообще — KoboldCpp прекрасно работает в чистом CPU-режиме.

Где KoboldCpp не подходит

Важно не создавать иллюзию, что простой инструмент закрывает все сценарии. KoboldCpp спроектирован вокруг одного пользователя (или небольшой группы) и одной модели на одном процессе. У него нет из коробки того, что есть у специализированных production-серверов инференса:

• Батчинг запросов. Production-движки вроде vLLM или SGLang умеют непрерывный батчинг (continuous batching) — эффективно обслуживать десятки одновременных запросов на одной видеокарте. KoboldCpp рассчитан на то, что запросы идут не очень часто и не строго параллельно.
• Горизонтальное масштабирование. Нет встроенного механизма развернуть несколько реплик за общим балансировщиком с единой очередью — придётся собирать самому, если вообще понадобится.
• Tensor parallelism на несколько GPU для одной модели — задача, под которую заточены production-инструменты, а не KoboldCpp.
• Метрики уровня прод-сервиса. Дашбордов по латентности и throughput из коробки нет — придётся смотреть логи руками.

Установку и грабли vLLM мы разбирали отдельно — см. настройку vLLM на VPS: путь там сложнее (Python-окружение, версии CUDA), но и цель другая — обслуживать нагрузку, а не удобство одного человека.

Граница простая: задача "поговорить с моделью на своём сервере без утечки данных наружу и без танцев с Docker" — KoboldCpp закрывает отлично. Задача "продукт с живыми пользователями, которым нужен быстрый ответ под нагрузкой" — простота перестаёт быть преимуществом, а отсутствие батчинга и масштабирования становится реальным узким местом. Это два разных инструмента под разные задачи, подменять один другим не стоит в обе стороны.

Автозапуск и безопасность

Для разового эксперимента хватит команды из раздела про установку. Для постоянной работы разумно оформить сервис systemd, а не полагаться на висящий в фоне терминал:

# /etc/systemd/system/koboldcpp.service
[Unit]
Description=KoboldCpp inference server
After=network.target

[Service]
Type=simple
User=koboldcpp
WorkingDirectory=/opt/koboldcpp
ExecStart=/opt/koboldcpp/koboldcpp --model /opt/koboldcpp/models/qwen2.5-7b-instruct-q4_k_m.gguf --port 5001 --host 0.0.0.0 --contextsize 8192
Restart=on-failure

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now koboldcpp

Отдельного пользователя (koboldcpp выше) стоит завести, чтобы процесс не работал от root. Порт не стоит открывать всему интернету — если доступ нужен только с вашего IP, ограничьте это правилом файрвола:

sudo ufw allow from 203.0.113.10 to any port 5001 proto tcp

Если доступ нужен более широкому кругу людей, разумнее поставить перед KoboldCpp обратный прокси (Nginx) с базовой авторизацией — сам KoboldCpp не задумывался как публичный многопользовательский сервис с разграничением прав, и полагаться на встроенную защиту не стоит.

Частые вопросы