llama-swap: как держать много локальных LLM и автоматически менять модели по запросу
На одном компьютере может лежать десять моделей, но в VRAM одновременно помещаются одна-две. llama-swap решает именно эту проблему: клиент всегда обращается к одному API, а proxy сам запускает нужный inference server, ждёт его готовности, направляет запрос и позже выгружает модель по TTL. Переключаться между coding LLM, обычным chat, embeddings, image/audio backend можно без ручного перезапуска сервисов.
llama-swap не считает токены сам — он управляет inference servers
Это важное отличие от Ollama, llama.cpp или vLLM.
llama-swap получает request, смотрит поле model,
находит соответствующую запись в YAML и запускает указанную команду.
Саму генерацию выполняет внешний server.
Клиенту не нужно знать, на каком случайном локальном порту поднята модель.
Server запускается по требованию и может автоматически завершаться после простоя.
Команда запуска задаётся вами, поэтому proxy не привязан к одной inference library.
Groups или matrix определяют, какие модели могут одновременно занимать GPU/RAM.
24 ГБ VRAM может хватать каждой модели по отдельности, но не всем сразу
Загружается, когда Codex/IDE запрашивает llm-code.
Автоматически заменяет coder, когда приходит обычный chat request.
Можно держать постоянно загруженной в отдельной persistent group.
Запускается отдельным backend только когда нужен image generation.
llama-swap экономит память за счёт lifecycle: ненужная сейчас модель выгружается, а нужная занимает её место.
Поле model становится командой маршрутизации
Например model: "coder".
Если нужный backend уже ready, request идёт сразу дальше.
По group/matrix rules.
Например запуск llama-server с конкретным GGUF.
llama-swap проксирует запрос после готовности upstream.
После периода простоя модель может быть остановлена автоматически.
В v256 idle-time window начинает отсчитываться после того, как модель стала ready или была перезапущена — это отдельное изменение release v256.
Установить сам proxy проще, чем inference stack
Windows
winget install llama-swap
llama-swap -versionWinGet package поддерживается community contributor, а официальные pre-built binaries проекта доступны для Windows напрямую в GitHub Releases.
macOS / Linux через Homebrew
brew tap mostlygeek/llama-swap
brew install llama-swap
llama-swap \
--config ./config.yaml \
--listen localhost:8080Docker
В 2026 основной рекомендуемый Docker-вариант — unified image. Он уже включает llama-server, ik-llama-server, stable-diffusion.cpp, whisper.cpp, audio.cpp и llama-swap. Есть CUDA 12/13 и Vulkan variants.
docker pull ghcr.io/mostlygeek/llama-swap:unified-cuda13
Если в cmd указан llama-server,
этот executable должен быть установлен отдельно и доступен по указанному пути.
Для первой модели достаточно четырёх строк YAML
models:
coder:
cmd: >
llama-server
--port ${PORT}
--model D:/models/coder.gguf
${PORT} назначается автоматически.
Если proxy не задан явно,
default для модели строится как http://localhost:${PORT}.
Две модели
models:
coder:
cmd: >
llama-server
--port ${PORT}
--model D:/models/coder.gguf
general:
cmd: >
llama-server
--port ${PORT}
--model D:/models/general.gguf
В basic routing по умолчанию работает логика «одна модель за раз»:
запрос general остановит несовместимый coder и загрузит нужный backend.
TTL определяет, сколько idle-модель остаётся загруженной
models:
coder:
cmd: >
llama-server
--port ${PORT}
--model D:/models/coder.gguf
ttl: 300ttl: 3005 минутПосле idle-window backend выгружается.
ttl: 0Никогда автоматически не выгружатьПодходит для постоянно нужной маленькой модели.
ttl: -1Global defaultИспользуется глобальное TTL-значение.
Если модель весит 20–40 ГБ, постоянная выгрузка и повторная загрузка увеличит TTFT. TTL лучше подбирать по реальному интервалу между запросами.
Groups и matrix позволяют описать, что реально помещается в память
Current config имеет два routing engines: group — более простой, и matrix — более гибкий DSL для допустимых комбинаций моделей.
routing:
mode: group
settings:
groups:
main-llm:
swap: true
exclusive: true
members:
- coder
- general
always-on:
persistent: true
swap: false
exclusive: false
members:
- embeddingsДве большие LLM делят одну и ту же VRAM.
Используется, если памяти достаточно.
Полезно для embedding/reranker моделей.
Solver старается освободить минимально необходимое количество running models.
Profiles позволяют переключать routing без изменения приложений
profiles:
coding:
description: "Coding-focused model routing"
pins:
llm-code: coder-big
llm-plan: qwen-plan
economy:
description: "Lower memory usage"
pins:
llm-code: coder-small
llm-plan: general-small
Клиент продолжает запрашивать llm-code,
а active profile решает, какая конкретная local/peer model стоит за этим ID.
С v252 profile можно автоматически выбирать через startup hook.
Codex/IDE можно один раз настроить на стабильное имя модели, а мощный/экономичный вариант переключать уже внутри llama-swap.
Current llama-swap проксирует большой набор OpenAI и Anthropic endpoints
/v1/chat/completionsChatОсновной OpenAI-compatible chat path.
/v1/responsesResponsesСовременный OpenAI Responses-compatible endpoint.
/v1/embeddingsEmbeddingsМожно выделить отдельную embedding model.
/v1/messagesAnthropic MessagesClaude-style compatible API surface.
/v1/images/*ImagesImage generation/edit backends.
/v1/audio/*AudioSpeech/transcription/voice endpoints.
curl http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "coder",
"messages": [
{
"role": "user",
"content": "Напиши функцию проверки конфигурации."
}
]
}'Playground показывает не только chat, но и состояние всего inference-host
Видно, что сейчас заняло ресурсы.
Удобно искать slow TTFT и длинные generations.
Есть Prometheus endpoint /metrics.
Можно смотреть proxy и upstream logs отдельно.
v256 улучшил mobile layout, timings и generation stats.
Задаёт вопросы собственной документации llama-swap.
Activity/logs способны раскрывать prompts, responses и operational details. Отдельная configurable UI authentication на момент статьи всё ещё обсуждается как feature request.
Help Agent использует документацию llama-swap, а те же tools доступны через MCP
Начиная с свежей 2026-линии у проекта есть встроенная knowledge base
и Help page, которая отвечает по реальному config.example.yaml и docs.
Эти documentation tools также публикуются как MCP endpoint:
/api/mcp.
Можно спросить, как настроить group, filter или backend command.
Полезно для Claude/Codex и других клиентов при настройке сервера.
Этот endpoint предназначен прежде всего для tools по документации/configuration. Сам inference остаётся на обычных API endpoints.
Peers превращают один llama-swap в entry point к другим серверам
peers:
gpu-pc:
proxy: http://192.168.1.23:8080
models:
- coder-large
- vision-model
Peer может быть другим llama-swap либо любым server,
который предоставляет поддерживаемые generative API endpoints.
Remote model можно адресовать как gpu-pc/coder-large.
Tailcat в v255+
В сентябре 2026 llama-swap получил интеграцию Tailcat:
можно создать защищённое peer-соединение без обычного port forwarding.
Конфигурация поддерживает connection token, node public-key allowlist,
список публикуемых model IDs и отдельный флаг admin,
который по умолчанию выключен.
Но access token и private key остаются credentials: их нельзя публиковать в статье, Git repository или screenshot.
API keys не включены по умолчанию, а UI заслуживает отдельной защиты
Current config прямо указывает:
apiKeys — optional array, default пустой;
при пустом списке authentication inference endpoints не проверяется.
apiKeys:
- "${env.LLAMA_SWAP_API_KEY}"--listen localhost:8080 уменьшает сетевую поверхность.
Не оставляйте default-allow на shared LAN без причины.
Отдельный password-login для UI не стоит считать встроенной зрелой RBAC-системой.
Это чувствительные telemetry data.
YAML configuration фактически управляет выполнением локальных команд.
Config поддерживает environment macros, чтобы не хранить secrets прямо в YAML.
На GitHub Security page проекта на дату проверки нет опубликованных advisories
и отдельного SECURITY.md.
Это не доказательство отсутствия уязвимостей — только состояние публичного GitHub security feed.
0.0.0.0:8080 внутри container.
Это нужно, чтобы Docker port publishing работал. Ограничивайте публикацию на host/firewall уровне либо используйте host networking с loopback bind, если endpoint должен быть доступен только локально.
llama-swap, Ollama и LiteLLM решают разные проблемы
Их можно комбинировать. Например: Open WebUI → LiteLLM → llama-swap → несколько локальных llama-server/vLLM backends. Но для одного пользователя это может быть избыточно: добавляйте каждый слой только если он решает конкретную задачу.
Hot swap экономит VRAM, но за это платите временем загрузки и сложностью
Большая модель после swap может загружаться секунды или дольше.
Следующий cold run снова платит TTFT.
Native binary не превращает GGUF в модель без llama-server/vLLM.
Сложные groups/matrix/profiles нужно документировать и version-control.
Не использовать как публичную многопользовательскую панель без внешней защиты.
Разные upstream servers поддерживают разные параметры и features.
Он начинает окупать сложность, когда один host обслуживает несколько тяжёлых моделей или разные inference backends, которые конкурируют за GPU/RAM.
Где llama-swap особенно полезен
Большой coder и general LLM автоматически делят VRAM.
Маленькая модель остаётся loaded, большие LLM меняются.
Один proxy управляет llama-server и Stable Diffusion/ComfyUI.
Клиенты используют стабильные model IDs, сервер сам управляет lifecycle.
Peers объединяют модели разных машин под одним entry point.
Переключать quality/VRAM policy без перенастройки клиентов.
llama-swap: release, config, installation, security и новые функции
Latest release — v256 от 17 сентября 2026 года.
Проект лицензируется по MIT.
llama-swap нужен не для запуска первой LLM, а когда локальный AI-server уже вырос из одной модели
Его ключевое преимущество — отделить client configuration от реальной model lifecycle. Open WebUI, coding-agent или приложение всегда просит стабильный ID, а server решает, какой процесс поднять, что выгрузить и какие модели разрешено держать вместе.
Особенно разумна схема на ПК с одной GPU: несколько больших GGUF/vLLM models лежат на SSD, embeddings остаются loaded, а heavy LLM автоматически занимают VRAM только на время работы.
Частые вопросы про llama-swap
Что такое llama-swap простыми словами?
Proxy и process manager, который автоматически запускает нужный local inference server по полю model и выгружает несовместимые/простаивающие модели.
Это замена Ollama?
Не совсем. Ollama сам является model runtime. llama-swap управляет внешними runtimes: llama.cpp, vLLM, image/audio servers и другими OpenAI/Anthropic-compatible backends.
Работает ли на Windows?
Да. Есть pre-built Windows binaries и community-maintained WinGet package.
Можно ли держать две модели одновременно?
Да. Groups и matrix позволяют явно описать compatible combinations. Если VRAM не хватает, другие модели можно автоматически swapping/unload.
Что делает TTL?
Останавливает простаивающий model backend после указанного времени. Значение 0 отключает automatic unloading.
Есть ли OpenAI-compatible API?
Да. Поддерживаются Chat Completions, Responses, embeddings и другие endpoints. Также есть Anthropic Messages-compatible endpoints.
Есть ли Web UI?
Да. Встроенный UI показывает models, chat/playground, activity, timing, logs и metrics.
Можно ли безопасно открыть UI в интернет?
Не рекомендуется напрямую. API keys защищают inference endpoints, но отдельная configurable UI-auth на дату статьи всё ещё фигурирует как открытый feature request. Используйте localhost, VPN или внешний reverse proxy/auth.
Какая версия актуальна?
На 21 сентября 2026 года latest release — llama-swap v256.
На одном ПК уже несколько локальных моделей и постоянно приходится вручную освобождать VRAM?
Можно разложить модели по groups, оставить embeddings постоянно загруженной, настроить TTL для тяжёлых LLM и дать клиентам один стабильный OpenAI-compatible endpoint.
