LocalAI на VDS: OpenAI-совместимый сервер моделей

Что такое LocalAI?

LocalAI — open-source REST API, полностью совместимый с OpenAI API, но работающий с локальными моделями. Поддерживает GGUF, GPTQ модели, генерацию изображений (Stable Diffusion), синтез речи (TTS) и распознавание речи (Whisper).

Преимущества перед Ollama

• Полная совместимость с OpenAI API (замена без изменения кода)
• Поддержка генерации изображений
• TTS и STT встроены
• Больше форматов моделей

Установка через Docker

>docker run -d \
  --name localai \
  -p 8080:8080 \
  -v localai_models:/build/models \
  --restart always \
  localai/localai:latest-aio-cpu

Загрузка модели

# Через API
curl http://localhost:8080/models/apply -H "Content-Type: application/json" \
  -d '{"id": "huggingface://TheBloke/Mistral-7B-Instruct-v0.2-GGUF/mistral-7b-instruct-v0.2.Q4_K_M.gguf"}'

Использование как OpenAI замена

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed"
)

response = client.chat.completions.create(
    model="mistral-7b-instruct",
    messages=[{"role": "user", "content": "Привет!"}]
)
print(response.choices[0].message.content)

Частые ошибки при настройке

Модель долго не загружается и контейнер падает по памяти

Killed
exit code 137

Код 137 — сигнал OOM Killer: процессу не хватило оперативной памяти. LocalAI держит в RAM саму модель и рабочие буферы контекста, поэтому для GGUF-моделей нужен запас RAM ощутимо больше веса файла модели на диске. Если сервер уходит в OOM, возьмите модель с более агрессивной квантизацией (например, Q4 вместо Q8) или VDS с большим объёмом памяти.

API отвечает 404 на знакомое имя модели

{"error":{"message":"could not load model - all backends returned error","code":404}}

LocalAI matches имя модели с файлом конфигурации в каталоге моделей. Если модель была загружена вручную без YAML-описания или имя в запросе не совпадает с именем файла, бэкенд не находит соответствие. Проверьте список моделей через GET /v1/models и используйте точное имя оттуда.

Режимы Whisper и генерации изображений не запускаются на слабом CPU

Error: failed to load model: context deadline exceeded

AIO-образ включает несколько тяжёлых режимов сразу, и их первичная инициализация требует заметно больше ресурсов, чем обычный текстовый чат. На слабом VDS без GPU загрузка может просто не укладываться в таймаут по умолчанию — проверьте логи на нехватку CPU и памяти, а не считайте это зависанием сервиса. Для стабильной работы таких режимов обычно нужен либо более мощный CPU с большим числом ядер, либо GPU с поддержкой CUDA.

LocalAI, Ollama и vLLM: что выбрать

Все три инструмента дают локальный инференс, но целятся в разные сценарии — от одной команды в терминале до продакшн-кластера с GPU.

Когда LocalAI не подходит

Универсальность LocalAI имеет цену: больше движущихся частей, чем у узкоспециализированного инструмента под одну задачу.

• Нужен максимум скорости инференса на GPU под нагрузкой многих пользователей одновременно — для этого лучше подходит vLLM с батчингом запросов
• Важна простота: одна команда, одна модель, минимум настроек — тут проще стартовать с Ollama
• Сервер совсем без GPU и с ограниченной RAM — тяжёлые режимы (Stable Diffusion, Whisper) в таких условиях будут крайне медленными или не запустятся вовсе
• Нужна модель редкого формата, которого нет в реестре LocalAI — тогда проще собственный инференс-сервер под конкретный формат
• Команда ценит минимум конфигурации превыше набора функций — AIO-образ ощутимо тяжелее по ресурсам, чем однозадачный сервер

Проверка результата

Перед тем как переключать продакшн-код на LocalAI, проверьте и совместимость API, и реальную производительность.

1. Запросите список загруженных моделей и убедитесь, что нужная присутствует
2. Отправьте тестовый запрос на chat completions и проверьте, что ответ приходит без ошибок
3. Замерьте время ответа на типичный промпт — если оно неприемлемо велико, проверьте, не работает ли инференс без ожидаемого ускорения на GPU
4. Проверьте логи контейнера на предупреждения о нехватке памяти
5. Если нужен режим изображений или речи, отдельно протестируйте именно его — базовый текстовый чат может работать, пока тяжёлый режим падает

curl http://localhost:8080/v1/models

По теме: базовый локальный сервер моделей — Ollama на VDS, расчёт нужной видеопамяти — сколько VRAM нужно модели, квантизация моделей — llama.cpp и GGUF.

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

Сколько оперативной памяти реально нужно для модели на несколько миллиардов параметров в GGUF?

Правило простое: запас RAM должен заметно превышать размер файла модели на диске, потому что LocalAI держит в памяти саму модель и рабочие буферы контекста запроса. Если сервер уходит в OOM по нехватке памяти, выбирайте более агрессивную квантизацию вроде Q4 вместо Q8 или арендуйте VDS с большим объёмом памяти.

Почему LocalAI не видит модель, которую загрузили на сервер вручную через SFTP?

Сопоставление имени модели с файлом происходит через YAML-описание в каталоге моделей, а не по самому факту наличия файла. Без такого описания или при несовпадении имени в запросе с именем файла бэкенд возвращает ошибку. Проверьте точное имя через GET /v1/models и используйте его в запросах без изменений.

Нужен ли GPU для LocalAI, или достаточно обычного VDS без видеокарты?

Для базового текстового чата CPU-версии AIO-образа обычно хватает, особенно с небольшой квантизованной моделью. А вот режимы генерации изображений и распознавания речи заметно тяжелее по ресурсам: на слабом процессоре без CUDA их первичная инициализация легко упирается в таймаут. Для стабильной работы таких режимов GPU практически обязателен.

Чем LocalAI лучше или хуже Ollama для небольшого проекта с одной моделью?

Ollama проще запустить и настроить, если нужен только текстовый чат без лишних функций. LocalAI добавляет совместимость без изменения кода с клиентами OpenAI API, а также генерацию изображений и распознавание речи, но требует больше ресурсов и настройки. Для одной простой задачи без таких функций Ollama обычно удобнее.