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

Источник: https://modelium.tech/zhurnal/localai/

LocalAI поднимает локальный HTTP-сервер с совместимыми с OpenAI маршрутами, включая `/v1/chat/completions`. Для первого запуска в Docker используйте CPU-образ, сохраните данные в отдельных томах, установите модель через интерфейс и отправьте контрольный запрос. Готовность `/readyz` не доказывает, что модель установлена или отвечает; Docker и сама модель в этой редакционной проверке не запускались.

**Источники сверены 26 сентября 2026 года по commit **`**dbdd2a4101cb2f299a7647394dad4516210ec3ae**`**.** Ни Docker, ни LocalAI, ни модель на машине Modelium не запускались. Описанные ответы — ожидаемые критерии читательского теста, а не результаты нашей лаборатории. Google Suggest подтвердил формулировку «localai docker»; частотность и позиции не измерялись.

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

**LocalAI** удобен, когда приложению нужен локальный HTTP-адрес с интерфейсом, близким к OpenAI Chat Completions, а модель и backend выбираются отдельно. Проект документирует путь «контейнер → каталог моделей → установленная модель → `/v1/chat/completions`» [s1](#src-s1)[s3](#src-s3)[s7](#src-s7). Совместимость маршрута не означает совместимости любого поведения клиента, включая инструменты или форматы ответов: тестируйте именно свой сценарий. Если нужен более простой первый запуск и собственный API Ollama, начните с [гайда Ollama](/zapusk/ollama/); для прямой работы с GGUF и сервером — с [llama.cpp](/zhurnal/llama-cpp/).

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

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

Нужны установленный Docker и место под выбранную модель и backend; конкретная потребность в памяти зависит от модели, формата, контекста и конфигурации [s2](#src-s2)[s5](#src-s5). Официальная инструкция использует `localai/localai:latest` и пробрасывает `8080:8080`; для личной проверки ниже порт **намеренно привязан к **`**127.0.0.1**`** хоста**, чтобы не публиковать API на всех интерфейсах. `latest` меняется: перед постоянной эксплуатацией закрепите проверенный тег/дижест, а не переносите этот тестовый пример на сервер без ревизии [s1](#src-s1)[s2](#src-s2).

docker volume create localai-modelsdocker volume create localai-backendsdocker volume create localai-configurationdocker volume create localai-datadocker 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](#src-s2). Команда выполняется в переднем плане. В другом терминале проверьте:

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

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

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

После установки снова вызовите `/v1/models` и возьмите точное значение `id` установленной модели, а не угадывайте имя. Документация LocalAI показывает список моделей и JSON-запрос с полями `model` и `messages` к Chat Completions [s3](#src-s3)[s7](#src-s7). Для **модели с 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: один удачный ответ ещё не доказывает пригодность модели для русского языка, стабильность под нагрузкой или офлайн-режим [s1](#src-s1)[s6](#src-s6)[s7](#src-s7). Для проверки сетевых границ после ответа переходите к [протоколу офлайн-контура](/zhurnal/proverka-offline-kontura-ii/) — это основной следующий шаг.

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

- `**Connection refused**`** или нет готовности.** Посмотрите `docker logs local-ai`, убедитесь, что контейнер работает и порт не занят; `/readyz` и `/v1/models` проверяют разные этапы готовности [s6](#src-s6).

- **Список моделей пуст или 404 для model ID.** Дождитесь установки в **Models → Explore**, затем сравните точный ID из `/v1/models` с JSON-запросом. Ошибка имени и проблема загрузки backend — не одна и та же ошибка [s3](#src-s3)[s6](#src-s6).

- **Backend не грузится, хватает не всей памяти.** Проверьте логи, совместимость модели с backend и фактическую доступную память; уменьшение контекста или выбор меньшей модели — диагностика, не универсальный «минимум VRAM» [s5](#src-s5)[s6](#src-s6). Для GPU выберите образ под оборудование и драйвер, проверьте проброс устройства в контейнер и конкретную конфигурацию модели [s2](#src-s2)[s5](#src-s5).

- **HTTP 401.** Проверьте, включены ли API-ключи либо пользовательская авторизация, и добавляйте заголовок с действительным ключом только на своём экземпляре; никогда не вставляйте настоящий ключ в публичную команду или логи [s4](#src-s4)[s6](#src-s6).

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

Не переносите тестовую команду в корпоративную сеть без отдельной схемы доступа. По документации, без включённых режимов аутентификации LocalAI не ограничивает HTTP-запросы; простой `LOCALAI_API_KEY` — **общий административный ключ**, а не изоляция пользователей [s4](#src-s4). Для разных сотрудников и ролей документация описывает `LOCALAI_AUTH=true` и отдельные учётные записи; нужны также границы сети, TLS и проверка прав в своей конфигурации [s1](#src-s1)[s4](#src-s4). Даже при доступном локальном API загрузка модели или backend может обращаться к внешним реестрам; сетевую изоляцию необходимо проверять отдельно, а не выводить из адреса `localhost` [s2](#src-s2)[s3](#src-s3).

Для удаления тестового контейнера остановите его сочетанием Ctrl+C в первом терминале, затем удалите контейнер командой `docker rm local-ai`. Именованные тома при этом остаются; не удаляйте их без проверки, нужны ли сохранённые модели, настройки или данные [s2](#src-s2). После успешного контрольного ответа выполните [проверку офлайн-контура](/zhurnal/proverka-offline-kontura-ii/).

## Источники

1. [LocalAI — Quickstart](https://github.com/mudler/LocalAI/blob/dbdd2a4101cb2f299a7647394dad4516210ec3ae/docs/content/getting-started/quickstart.md) — получено 2026-09-26
2. [LocalAI — Containers](https://github.com/mudler/LocalAI/blob/dbdd2a4101cb2f299a7647394dad4516210ec3ae/docs/content/getting-started/containers.md) — получено 2026-09-26
3. [LocalAI — Setting Up Models](https://github.com/mudler/LocalAI/blob/dbdd2a4101cb2f299a7647394dad4516210ec3ae/docs/content/getting-started/models.md) — получено 2026-09-26
4. [LocalAI — Authentication & Authorization](https://github.com/mudler/LocalAI/blob/dbdd2a4101cb2f299a7647394dad4516210ec3ae/docs/content/features/authentication.md) — получено 2026-09-26
5. [LocalAI — GPU Acceleration](https://github.com/mudler/LocalAI/blob/dbdd2a4101cb2f299a7647394dad4516210ec3ae/docs/content/features/GPU-acceleration.md) — получено 2026-09-26
6. [LocalAI — Troubleshooting](https://github.com/mudler/LocalAI/blob/dbdd2a4101cb2f299a7647394dad4516210ec3ae/docs/content/getting-started/troubleshooting.md) — получено 2026-09-26
7. [LocalAI — Text Generation](https://github.com/mudler/LocalAI/blob/dbdd2a4101cb2f299a7647394dad4516210ec3ae/docs/content/features/text-generation.md) — получено 2026-09-26