Установка 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
Установщик выполняет следующие шаги:
- Проверяет Docker, Docker Compose v2, файл
.envи версиюAPP_VERSIONиз комплекта. - Предлагает режим GPU (vLLM), CPU (llama.cpp) или Внешние LLM и Embedding, дополнительные сервисы Whisper и BGE Reranker и доступную LLM-Модель. Для Whisper и reranker нужен GPU. При выборе нескольких Моделей необходимо учитывать объем видеопамяти.
- Находит нужные архивы Docker-образов версии
APP_VERSION. При наличии сети скачивает недостающие, проверяет SHA-256 и теги в Docker manifest, загружает образы и распаковывает выбранные Модели. Без сети сообщает, чего не хватает. - Создает резервную копию
.env, предлагает настроитьHOST_IP,NGINX_DOMAIN_NAME,MAX_TOKENS_MESSAGE, пароль PostgreSQL, Модель и другие параметры. Необходимо заменить пароль по умолчанию на уникальный надежный пароль. Не следует хранить пароли в открытых заметках. Для.envустановщик ограничивает права доступа. - Предлагает настроить HTTPS для основного сервера и соединения с сервером эмбеддингов. Необходимо подготовить доверенные сертификаты и ключи. Для тестового стенда можно выбрать самоподписанные сертификаты. Подробности есть в инструкции по SSL.
- Показывает итоговые параметры и план запуска Docker Compose. Необходимо проверить выбранный режим, Модель, домен и профили, затем необходимо подтвердить запуск.
Установщик сохраняет выбранные профили в COMPOSE_PROFILES. Если установка прервана, необходимо устранить указанную причину и необходимо запустить install.sh снова. Не следует смешивать файлы разных версий ради обхода проверки.
Внешние LLM и Embedding#
Этот вариант подходит, когда оба сервиса уже работают на другом сервере. Основному серверу нужен сетевой доступ к их API. LLM должен предоставлять совместимый API, а сервер Embedding — API Sherpa Embedding. Для защищенного соединения подготовьте доверенные сертификаты. Если внешний Embedding требует токен, получите его у администратора сервиса до установки.
- Запустите
sudo ./sh_scripts/install.shиз каталога установки и выберите пункт [3] Внешние LLM и Embedding. - Укажите адрес LLM, например
http://llm.example.local:8000, адрес Embedding, напримерhttps://embed.example.local:443, и имя модели из API LLM. Укажите токен Embedding, если сервер требует авторизацию. Адреса вводятся без пути/v1. - На шаге проверки архивов предоставьте только перечисленные установщиком образы. Образы и архивы моделей локальных LLM и Embedding в этом режиме не нужны.
- Проверьте итоговую сводку и состав запускаемых сервисов. В
.envдолжен бытьCOMPOSE_PROFILES=external. Командаdocker compose --profile external config --servicesне должна показыватьaiserver-embed,aiserver-llm-serverиaiserver-llm-server-cpu. - После запуска проверьте
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, необходимо согласовать путь обновления с сопровождением.