Установка Sherpa AI Server#

Перед началом#

Нужен сервер с Docker и Docker Compose v2, достаточным местом для архивов, Моделей и контейнеров, а также доступом к дистрибутиву либо заранее перенесенным комплектом файлов. Для локальной LLM необходимо выбрать сервер с GPU или установку только на CPU. Необходимо подготовить доменное имя, IP-адрес и SSL-сертификаты. Для LLM на другом компьютере см. подключение отдельного LLM-сервера.

Необходимо скачать архив client-files нужной опубликованной версии и файл его контрольной суммы. Необходимо сравнить SHA-256 скачанного архива со значением в соответствующем файле .SHA256SUM. При несовпадении сумм архив использовать нельзя. Все архивы Docker-образов должны быть той же версии. Установщик проверяет версию, контрольные суммы и теги образов до запуска контейнеров. Нельзя выбирать архивы независимо по latest и не запускайте load_all_docker_images.sh: этот старый вспомогательный скрипт выбирает последний файл для каждого образа отдельно.

Если сервер не имеет доступа к серверу загрузок, перенесите в один каталог client-files, нужные архивы образов и соответствующие файлы .SHA256SUM. Комплект должен содержать файлы для выбранных сервисов и Моделей. Перед установкой необходимо проверить свободное место для архивов, распакованных Моделей и Docker-образов.

Установка через скрипт#

Пример использует версию 2.5.1. Необходимо указать имя уже проверенного архива своей версии и выполняйте команды в каталоге установки:

CLIENT_ARCHIVE=docker_aiserver_client_files_2.5.1.tgz
tar -xzf "$CLIENT_ARCHIVE"
chmod +x sh_scripts/*.sh
sudo ./sh_scripts/install.sh

Установщик выполняет следующие шаги:

  1. Проверяет Docker, Docker Compose v2, файл .env и версию APP_VERSION из комплекта.
  2. Предлагает режим GPU (vLLM), CPU (llama.cpp) или Внешние LLM и Embedding, дополнительные сервисы Whisper и BGE Reranker и доступную LLM-Модель. Для Whisper и reranker нужен GPU. При выборе нескольких Моделей необходимо учитывать объем видеопамяти.
  3. Находит нужные архивы Docker-образов версии APP_VERSION. При наличии сети скачивает недостающие, проверяет SHA-256 и теги в Docker manifest, загружает образы и распаковывает выбранные Модели. Без сети сообщает, чего не хватает.
  4. Создает резервную копию .env, предлагает настроить HOST_IP, NGINX_DOMAIN_NAME, MAX_TOKENS_MESSAGE, пароль PostgreSQL, Модель и другие параметры. Необходимо заменить пароль по умолчанию на уникальный надежный пароль. Не следует хранить пароли в открытых заметках. Для .env установщик ограничивает права доступа.
  5. Предлагает настроить HTTPS для основного сервера и соединения с сервером эмбеддингов. Необходимо подготовить доверенные сертификаты и ключи. Для тестового стенда можно выбрать самоподписанные сертификаты. Подробности есть в инструкции по SSL.
  6. Показывает итоговые параметры и план запуска Docker Compose. Необходимо проверить выбранный режим, Модель, домен и профили, затем необходимо подтвердить запуск.

Установщик сохраняет выбранные профили в COMPOSE_PROFILES. Если установка прервана, необходимо устранить указанную причину и необходимо запустить install.sh снова. Не следует смешивать файлы разных версий ради обхода проверки.

Внешние LLM и Embedding#

Этот вариант подходит, когда оба сервиса уже работают на другом сервере. Основному серверу нужен сетевой доступ к их API. LLM должен предоставлять совместимый API, а сервер Embedding — API Sherpa Embedding. Для защищенного соединения подготовьте доверенные сертификаты. Если внешний Embedding требует токен, получите его у администратора сервиса до установки.

  1. Запустите sudo ./sh_scripts/install.sh из каталога установки и выберите пункт [3] Внешние LLM и Embedding.
  2. Укажите адрес LLM, например http://llm.example.local:8000, адрес Embedding, например https://embed.example.local:443, и имя модели из API LLM. Укажите токен Embedding, если сервер требует авторизацию. Адреса вводятся без пути /v1.
  3. На шаге проверки архивов предоставьте только перечисленные установщиком образы. Образы и архивы моделей локальных LLM и Embedding в этом режиме не нужны.
  4. Проверьте итоговую сводку и состав запускаемых сервисов. В .env должен быть COMPOSE_PROFILES=external. Команда docker compose --profile external config --services не должна показывать aiserver-embed, aiserver-llm-server и aiserver-llm-server-cpu.
  5. После запуска проверьте docker compose ps, откройте Чат и отправьте тестовый запрос. Проверьте поиск по документу, если он используется. Ответ и поиск подтверждают доступность внешних сервисов с основного сервера.

Установщик сохраняет URL, адреса, порты, схему LLM и имя модели в .env. При смене адреса LLM исправьте его URL, хост, порт и схему в .env. Затем в разделе «Модели» откройте соответствующий экземпляр и обновите поля «Хост», «Порт» и «Схема»: Чат использует сохраненные параметры экземпляра. При смене адреса или токена Embedding также исправьте .env. После правки .env выполните docker compose up -d --force-recreate aiserver: обычный restart не перечитывает переменные окружения. Если ответа нет, проверьте сетевой доступ к адресам из сети основного сервера и логи aiserver. Обновлятор сохраняет внешний режим и не требует локальных образов и моделей этих сервисов.

Сервисы и профили#

Базовые сервисы запускаются без отдельного профиля:

Сервис Назначение
aiserver Основной backend
aiserver-nginx Веб-сервер и HTTPS
aiserver-pg PostgreSQL
aiserver-code-interpreter Интерпретатор кода
aiserver-websocket WebSocket
aiserver-mcp-orchestrator MCP-интеграция с Orchestrator

Дополнительные профили задают LLM и обработку:

Профиль Сервис Назначение
embed aiserver-embed Локальный Embedding
gpu aiserver-llm-server LLM на GPU
gpu2 aiserver-llm-server2 Вторая LLM на отдельной GPU
cpu aiserver-llm-server-cpu LLM на CPU
external Локальные LLM и Embedding не запускаются Подключение к внешним сервисам через .env
whisper aiserver-whisper Распознавание речи на GPU
reranker aiserver-bge-reranker Переранжирование на GPU
full Whisper и reranker Оба дополнительных сервиса

При ручном управлении профилями указывайте ровно выбранные сервисы. Например, для GPU с Whisper:

docker compose --profile embed --profile gpu --profile whisper up -d

Для CPU без GPU:

docker compose --profile embed --profile cpu up -d

Проверка после установки#

Для диагностики установки администратору нужен доступ к Docker Compose на сервере. Из каталога с .env и docker-compose.yml необходимо выполнить:

sudo ./sh_scripts/diagnostics.sh

Скрипт проверяет основные контейнеры, локальную LLM, включенные профилями Whisper и BGE Reranker, доступность PostgreSQL, свободное место и ответ API. При успешной проверке появляется сообщение Диагностика завершена без замечаний, код выхода — 0. При ошибке скрипт называет проблемный компонент и возвращает код 1. Для подробностей необходимо выполнить указанную в сообщении команду docker compose logs.

Чтобы мастер установки предложил диагностику после успешного запуска, необходимо запустить его с SHERPA_DIAGNOSTICS_OFFER=true. Пример: sudo env SHERPA_DIAGNOSTICS_OFFER=true ./sh_scripts/install.sh. Без этой переменной приглашение не появляется. Диагностика не изменяет данные установки.

Необходимо проверить состояние контейнеров и логи. Запущенные сервисы должны иметь статус Up:

docker compose ps
docker compose logs --tail=100 aiserver

Можно открыть https://<ваш-домен> в браузере и необходимо проверить вход в систему. Для проверки ответа веб-сервера:

curl -I https://aiserver.example.com

Ожидается успешный HTTP-ответ или перенаправление на страницу входа. Необходимо проверить, что сертификат браузером принимается без предупреждения. Если используется локальная LLM, можно отправить тестовый запрос в Чат и необходимо проверить, что Модель отвечает. При проблемах можно посмотреть логи нужного сервиса:

docker compose logs --tail=100 aiserver-llm-server
docker compose logs --tail=100 aiserver-embed

Для режима CPU вместо aiserver-llm-server можно использовать aiserver-llm-server-cpu. Если не запускается контейнер, необходимо проверить место на диске и логи. Для ошибок входа или базы данных необходимо проверить .env. Для HTTPS — сертификаты и имя домена. Для GPU — драйвер, доступность видеокарты и объем VRAM.

Обслуживание#

Команды выполняйте из каталога с docker-compose.yml и .env:

docker compose ps
docker compose logs -f aiserver
docker compose restart aiserver
docker stats

Для GPU дополнительно можно использовать nvidia-smi. Команда docker compose down останавливает и удаляет контейнеры. не добавляйте -v, если хотите сохранить данные в Docker volumes. Для обновления можно использовать инструкцию по обновлению. Перед переходом с 2.5.0 на 2.5.1 обязательно необходимо выполнить подготовку индексов. Если текущая версия ниже 2.5.0, необходимо согласовать путь обновления с сопровождением.