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 зіставляє імʼя моделі з файлом конфігурації в каталозі моделей. Якщо модель завантажили вручну без 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 зазвичай зручніший.