LocalAI в Docker: локальный API для языковой модели

Когда нужен LocalAI, а когда хватит Ollama?

LocalAI удобен, когда приложению нужен локальный HTTP-адрес с интерфейсом, близким к OpenAI Chat Completions, а модель и backend выбираются отдельно. Проект документирует путь «контейнер → каталог моделей → установленная модель → /v1/chat/completions» s1s3s7. Совместимость маршрута не означает совместимости любого поведения клиента, включая инструменты или форматы ответов: тестируйте именно свой сценарий. Если нужен более простой первый запуск и собственный API Ollama, начните с гайда Ollama; для прямой работы с GGUF и сервером — с llama.cpp.

Граф решения: локальный чат для приложения → конкретная модель → проверка памяти своего компьютера → LocalAI на CPU или подходящем GPU backend → HTTP-запрос → наблюдаемый ответ. CPU-образ не делает GPU-ускорение автоматически; разработчик описывает отдельные GPU-образы для NVIDIA, AMD, Intel и Vulkan, а также параметры backend модели s2s5. Размер загружаемого файла не равен минимуму RAM/VRAM, скорость этого стека мы не измеряли.

Как поднять LocalAI в Docker без открытия API наружу?

Нужны установленный Docker и место под выбранную модель и backend; конкретная потребность в памяти зависит от модели, формата, контекста и конфигурации s2s5. Официальная инструкция использует localai/localai:latest и пробрасывает 8080:8080; для личной проверки ниже порт намеренно привязан к 127.0.0.1 хоста, чтобы не публиковать API на всех интерфейсах. latest меняется: перед постоянной эксплуатацией закрепите проверенный тег/дижест, а не переносите этот тестовый пример на сервер без ревизии s1s2.

docker volume create localai-models
docker volume create localai-backends
docker volume create localai-configuration
docker volume create localai-data
docker run --name local-ai -p 127.0.0.1:8080:8080 \
-v localai-models:/models -v localai-backends:/backends \
-v localai-configuration:/configuration -v localai-data:/data \
-ti localai/localai:latest

Официальная документация требует сохранять все четыре пути: /models (модели), /backends (дополнительные backend), /configuration (настройки), /data (данные приложения). Содержимое вне томов может исчезнуть при пересоздании контейнера s2. Команда выполняется в переднем плане. В другом терминале проверьте:

curl -i http://127.0.0.1:8080/readyz
curl http://127.0.0.1:8080/v1/models

Документация предлагает /readyz для проверки готовности, /v1/models — для списка моделей s6s7. Если первый запрос успешен, но список пуст, сервер работает, модели ещё нет. В браузере на этом же компьютере откройте http://127.0.0.1:8080, перейдите в Models → Explore, выберите модель для своего железа и дождитесь завершения установки; LocalAI показывает прогресс и ошибки в Activity s1s3. В Quickstart в качестве примера назван qwen3-4b, но это пример из документации, не наша проверка доступности карточки, фактического размера, лицензии или скорости на вашем устройстве s1. Сверьте лицензию и формат именно выбранного артефакта, прежде чем загружать рабочие данные. При смене образа или backend сначала сохраняйте тома, затем проверяйте список моделей повторно s2s3.

Как проверить, что модель отвечает через API?

После установки снова вызовите /v1/models и возьмите точное значение id установленной модели, а не угадывайте имя. Документация LocalAI показывает список моделей и JSON-запрос с полями model и messages к Chat Completions s3s7. Для модели с ID qwen3-4b, если именно она появилась в списке, контрольный запрос выглядит так:

curl -sS http://127.0.0.1:8080/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{"model":"qwen3-4b","messages":[{"role":"user","content":"Ответь одним словом: готово"}]}'

Если ID другой, замените только model точным значением из списка. Успешный тест — валидный JSON-ответ без ошибки, с текстом в choices[0].message.content; буквальное слово «готово» не гарантируется. Сравните ID и трассу ошибок с фактическим backend: один удачный ответ ещё не доказывает пригодность модели для русского языка, стабильность под нагрузкой или офлайн-режим s1s6s7. Для проверки сетевых границ после ответа переходите к протоколу офлайн-контура — это основной следующий шаг.

Что делать, если API пуст, не отвечает или модель не грузится?

• Connection refused или нет готовности. Посмотрите docker logs local-ai, убедитесь, что контейнер работает и порт не занят; /readyz и /v1/models проверяют разные этапы готовности s6.
• Список моделей пуст или 404 для model ID. Дождитесь установки в Models → Explore, затем сравните точный ID из /v1/models с JSON-запросом. Ошибка имени и проблема загрузки backend — не одна и та же ошибка s3s6.
• Backend не грузится, хватает не всей памяти. Проверьте логи, совместимость модели с backend и фактическую доступную память; уменьшение контекста или выбор меньшей модели — диагностика, не универсальный «минимум VRAM» s5s6. Для GPU выберите образ под оборудование и драйвер, проверьте проброс устройства в контейнер и конкретную конфигурацию модели s2s5.
• HTTP 401. Проверьте, включены ли API-ключи либо пользовательская авторизация, и добавляйте заголовок с действительным ключом только на своём экземпляре; никогда не вставляйте настоящий ключ в публичную команду или логи s4s6.

Можно ли открыть этот API коллегам?

Не переносите тестовую команду в корпоративную сеть без отдельной схемы доступа. По документации, без включённых режимов аутентификации LocalAI не ограничивает HTTP-запросы; простой LOCALAI_API_KEY — общий административный ключ, а не изоляция пользователей s4. Для разных сотрудников и ролей документация описывает LOCALAI_AUTH=true и отдельные учётные записи; нужны также границы сети, TLS и проверка прав в своей конфигурации s1s4. Даже при доступном локальном API загрузка модели или backend может обращаться к внешним реестрам; сетевую изоляцию необходимо проверять отдельно, а не выводить из адреса localhost s2s3.

Для удаления тестового контейнера остановите его сочетанием Ctrl+C в первом терминале, затем удалите контейнер командой docker rm local-ai. Именованные тома при этом остаются; не удаляйте их без проверки, нужны ли сохранённые модели, настройки или данные s2. После успешного контрольного ответа выполните проверку офлайн-контура.