Быстрый старт с LocalAI: запуск локальных LLM, совместимых с OpenAI

LocalAI — это самодостаточный сервер вывода с приоритетом на локальное использование, разработанный для работы как прямая замена OpenAI API для запуска ИИ-нагрузок на вашем собственном оборудовании (ноутбук, рабочая станция или сервер в центре обработки данных).

Проект нацелен на практическую совместимость «замените URL облачного API», при этом поддерживая множество бэкендов и модальностей (текст, изображения, аудио, эмбеддинги и многое другое).

Что такое LocalAI и почему инженеры его используют

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

Помимо базовой генерации текста, набор функций LocalAI охватывает распространенные «строительные блоки для продакшена», такие как эмбеддинги для RAG, генерация изображений на основе диффузии, преобразование речи в текст и текста в речь, с опциональным ускорением GPU и распределенными паттернами.

Если вы оцениваете самодостаточное развертывание LLM, LocalAI представляет интерес, так как он фокусируется на совместимости API (для более легкой интеграции), одновременно предоставляя встроенный веб-интерфейс и рабочий процесс галереи моделей для снижения сложности установки и настройки моделей.

Для более широкого сравнения вариантов самодостаточного и облачного хостинга LLM — включая Ollama, vLLM, Docker Model Runner и управляемые облачные провайдеры — см. руководство по хостингу LLM на 2026 год.

Если вы хотите получить подробное сравнение LocalAI с Ollama, vLLM, LM Studio и другими инструментами, сравнение основных локальных инструментов LLM в 2026 году охватывает поддержку API, совместимость с оборудованием и готовность к продакшену. Для более широкого обоснования сохранения моделей на вашей собственной инфраструктуре раздел самодостаточный хостинг LLM и суверенитет ИИ рассматривает мотивации, связанные с резидентностью данных и соответствием требованиям.

Варианты установки LocalAI, которые хорошо работают на практике

LocalAI можно установить несколькими способами, но для большинства команд самым быстрым и наименее рискованным стартом являются контейнеры (Docker или Podman). Если вам нужна справочная информация по командам при работе с приведенными ниже примерами, шпаргалка по Docker охватывает самые частые и полезные команды Docker.

Самый быстрый старт с Docker

Эта команда запускает сервер LocalAI и привязывает API и веб-интерфейс к порту 8080:

docker run -p 8080:8080 --name local-ai -ti localai/localai:latest

Документация контейнера LocalAI называет это самым быстрым способом развертывания рабочего сервера, при этом API доступен по адресу http://localhost:8080.

Выбор правильного образа контейнера LocalAI

LocalAI публикует несколько разновидностей контейнеров, чтобы вы могли подобрать их под ваше оборудование:

• Образ для CPU для широкой совместимости.
• Специализированные образы для GPU NVIDIA CUDA, AMD ROCm, Intel oneAPI и Vulkan.
• Образы All-in-One (AIO), которые поставляются с предконфигурированными моделями, сопоставленными с названиями моделей, похожими на OpenAI.

Официальный README на GitHub включает конкретные примеры docker run для CPU-only и нескольких вариантов GPU (варианты NVIDIA CUDA, AMD ROCm, Intel, Vulkan), а также варианты AIO.

Сохранение моделей между перезапусками

Если вы не монтируете хранилище, загруженные вами модели могут не сохраняться при изменениях жизненного цикла контейнера. Руководство по контейнерам рекомендует монтировать том моделей, например:

docker run -ti --name local-ai -p 8080:8080 \
  -v "$PWD/models:/models" \
  localai/localai:latest-aio-cpu

Это делает /models внутри контейнера постоянным на вашем хосте.

Минимальный QuickStart с Docker Compose

LocalAI также предоставляет референсный файл docker-compose.yaml в репозитории, демонстрирующий распространенный паттерн: привязка порта 8080, монтирование тома /models, установка MODELS_PATH=/models, и опциональная предзагрузка модели путем указания ее в списке команд (в примере репозитория показана модель phi-2). Шпаргалка по Docker Compose является полезным справочником при адаптации этого под вашу настройку.

«Хороший вариант по умолчанию» для Compose (CPU) выглядит так:

services:
  localai:
    image: localai/localai:latest
    container_name: local-ai
    ports:
      - "8080:8080"
    volumes:
      - ./models:/models
    environment:
      - MODELS_PATH=/models

Основная идея такая же, как в примере upstream: каталог моделей хоста ↔ контейнер /models.

Если вы также используете встроенные инструменты Docker docker model вместе с LocalAI, шпаргалка по Docker Model Runner охватывает команды pull, run, package и настройки конфигурации.

Установка LocalAI без контейнеров

LocalAI также поддерживает установку через платформенно-специфичные методы (например, DMG для macOS и бинарные файлы для Linux), а также более широкие варианты развертывания, такие как Kubernetes.

Если вы предпочитаете скриптовую установку на Linux, руководство DeepWiki описывает путь install.sh, который автоматически определяет оборудование и настраивает систему соответствующим образом.

Предсказуемая последовательность использования

Надежный рабочий процесс LocalAI выглядит так:

Запустить LocalAI → установить или импортировать модель → проверить загруженные модели → вызвать совместимые с OpenAI конечные точки.

Эта последовательность соответствует официальной документации «Попробуйте» и «Настройка моделей», которая описывает процесс вокруг запуска сервера, установки моделей через галерею или CLI, а затем тестирования конечных точек с помощью curl.

Запустите сервер и подтвердите его работоспособность

После запуска сервера распространенной проверкой является конечная точка готовности:

curl http://localhost:8080/readyz

Руководство по устранению неполадок использует /readyz в качестве первой диагностической проверки, чтобы подтвердить, что LocalAI отвечает.

Установите модель из галереи или импортируйте URI

LocalAI предоставляет два основных потока внедрения моделей:

• Установка из галереи моделей через веб-интерфейс, где вы открываете UI, переходите на вкладку Models, просматриваете модели и нажимаете Install.
• Установка и запуск через CLI, используя команды local-ai models list, local-ai models install и local-ai run.

Документация также поддерживает импорт моделей по URI (репозитории Hugging Face, прямые URI файлов моделей и другие реестры), а веб-интерфейс включает отдельный поток импорта модели с редактором YAML для продвинутой конфигурации.

Проверьте, что LocalAI считает возможным для обслуживания

Чтобы вывести развернутые модели через совместимое с OpenAI API:

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

Это явно рекомендуется как «следующий шаг» после установки контейнера и как диагностическая процедура при устранении неполадок.

Основные параметры командной строки, которые стоит изучить

CLI LocalAI построен вокруг команды local-ai run с комплексной поверхностью конфигурации. Нужно выделить два важных эксплуатационных поведения:

• Каждый флаг CLI можно установить через переменную окружения.
• Переменные окружения имеют приоритет над флагами CLI.

Ниже приведены параметры, которые большинство практиков начинают использовать рано, сгруппированные по назначению. Все значения по умолчанию и названия переменных окружения взяты из справочника CLI upstream. Если вы оцениваете Ollama вместе с LocalAI, шпаргалка по CLI Ollama охватывает его команды serve, run, ps и управления моделями для сравнения.

Основные флаги сервера и хранилища

В FAQ LocalAI также задокументированы места хранения моделей по умолчанию и явно рекомендуется использовать LOCALAI_MODELS_PATH или --models-path, если вы хотите разместить модели вне каталога по умолчанию (например, чтобы избежать заполнения домашнего каталога).

Флаги производительности и емкости

Для более широкой совместимости и ограничений ускорения таблица совместимости моделей документирует, какие бэкенды поддерживают какие режимы ускорения (CUDA, ROCm, SYCL, Vulkan, Metal, CPU), и также отмечает, что модели, не настроенные явно, могут быть загружены автоматически, в то время как конфигурация YAML позволяет зафиксировать поведение. Для развертываний с высокой пропускной способностью и несколькими GPU с PagedAttention руководство по быстрому старту vLLM рассматривает аналогичный сервер, совместимый с OpenAI, с ориентированной на продакшен конфигурацией.

Флаги API, безопасности и UI

Если вы экспонируете LocalAI удаленно, вы должны защитить конечные точки и можете ограничить доступ ключом API; ключ API фактически предоставляет полный доступ.

Обзор веб-интерфейса и его соответствие системе

По умолчанию LocalAI предоставляет встроенный веб-интерфейс вместе с API (если вы его не отключили). Документация гласит, что UI доступен на том же хосте и порту, что и сервер, обычно http://localhost:8080.

Что можно сделать во встроенном интерфейсе

Веб-интерфейс — это браузерная среда, которая охватывает:

• Управление моделями и опыт просмотра галереи
• Взаимодействие в чате
• Интерфейсы генерации изображений и преобразования текста в речь
• Распределенную и P2P конфигурацию

Структура маршрутов дает четкую ментальную модель области поверхности UI:

• / для панели управления
• /browse для браузера галереи моделей
• /chat/ для чата
• /text2image/ для генерации изображений
• /tts/ для преобразования текста в речь
• /talk/ для голосового взаимодействия
• /p2p для настроек и мониторинга P2P

Галерея моделей и рабочий процесс «Импорт модели»

Для инженеров самой важной функцией UI является внедрение моделей. Официальное руководство «Настройка моделей» описывает:

• Установка моделей через вкладку Models с однонажимной установкой.
• Импорт моделей через UI импорта модели, который поддерживает простой режим (URI + предпочтения) и продвинутый режим с редактором YAML и инструментами валидации.

Это важно, потому что LocalAI в конечном итоге запускает модели на основе конфигурации YAML: вы можете управлять отдельными файлами YAML в каталоге моделей, использовать один файл с несколькими определениями моделей через --models-config-file или ссылаться на удаленные URL YAML при запуске.

Примеры, которые можно вставить в терминал

Совместимые с OpenAI конечные точки LocalAI разработаны для приема знакомых форматов запросов и возврата JSON-ответов (при этом аудио-конечные точки возвращают аудио-нагрузки).

Пример завершения чата с помощью curl

Страница «Попробуйте» LocalAI показывает вызов конечной точки завершения чата напрямую:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [
      { "role": "user", "content": "Write a one paragraph explanation of what LocalAI is." }
    ],
    "temperature": 0.2
  }'

Образы AIO поставляются с предконфигурированными моделями, сопоставленными с названиями, похожими на OpenAI, такими как gpt-4, и документация контейнера объясняет, что они обеспечены открытыми исходными моделями.

Если вы не используете образ AIO, замените "model" на название модели, которую вы установили (проверьте через /v1/models).

Пример эмбеддингов для конвейеров RAG

LocalAI поддерживает эмбеддинги и документирует, что конечная точка эмбеддингов совместима с несколькими бэкендами, включая llama.cpp, bert.cpp и sentence-transformers.

Минимальный запрос «встроение этого текста» к совместимой с OpenAI конечной точке выглядит так:

curl http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-ada-002",
    "input": "LocalAI embeddings are handy for semantic search and RAG."
  }'

Документация LocalAI по эмбеддингам также показывает, как включаются эмбеддинги через конфигурацию YAML путем установки embeddings: true.

Пример использования клиента, совместимого с OpenAI

LocalAI разработан так, что вы можете использовать стандартные библиотеки клиентов OpenAI, указав их на базовый URL LocalAI (и опционально установив ключ API, если вы включили аутентификацию). Эта цель «прямой замены» описана как в upstream README, так и в документации по совместимости с OpenAI.

Типичная конфигурация:

• Базовый URL: http://localhost:8080/v1
• Ключ API: либо не требуется (по умолчанию), либо требуется, если вы настроили --api-keys

Основы безопасности и устранения неполадок

Защитите сервер LocalAI перед его экспонированием

LocalAI по умолчанию может работать полностью открытым на localhost. Если вы привязываете его к общедоступному интерфейсу или экспонируете через ingress, добавьте хотя бы один из этих контролей:

• Включите аутентификацию ключа API, используя --api-keys / API_KEY.
• Разместите перед ним обратный прокси и сетевые контроллеры (файрвол, белый список, VPN).
• Отключите веб-интерфейс, если вам нужен только API (--disable-webui).
• Оставляйте CORS отключенным, если браузерный клиент действительно в этом нуждается.

Когда ключи API включены, совместимые с OpenAI конечные точки принимают учетные данные в распространенных местах, таких как заголовок Authorization Bearer или заголовок x-api-key.

Быстрая диагностика, когда что-то не работает

Руководство LocalAI по устранению неполадок предлагает небольшой набор проверок, которые решают большинство инцидентов «работает ли оно»:

# readiness
curl http://localhost:8080/readyz

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

# version
local-ai --version

Оно также документирует включение отладочного ведения журнала через DEBUG=true или --log-level=debug, а для развертываний Docker — проверку журналов контейнера с помощью docker logs local-ai.