Ru

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

Установка Sherpa AIServer#

Рекомендуемый способ: автоматическая установка через скрипты#

Рекомендуется для большинства пользователей. Скрипты автоматически выполняют все шаги установки и обновления.

Установка#

После распаковки архива запустите скрипт установки:

tar -xvzf "$(ls docker_aiserver_client_files_*.tgz | sort -V | tail -n 1)"
cd sh_scripts && chmod +x *.sh && cd ..
sudo ./sh_scripts/install.sh

Скрипт проведёт вас через все шаги: выбор модели ИИ, загрузку Docker-образов, настройку окружения и запуск сервисов.

Ручная установка. Если вы хотите установить систему вручную или вам нужен полный контроль над каждым шагом — следуйте инструкции ниже.

Распаковка клиентских файлов#

На этом этапе вы распакуете архив с клиентскими файлами и подготовите систему к установке.

Распаковка архива с клиентскими файлами#

# Найдите и распакуйте архив (автоматически выбирается самая свежая версия)
tar -xvzf "$(ls docker_aiserver_client_files_*.tgz | sort -V | tail -n 1)"
💡 Комментарии к распаковке архива

tar -xvzf "$(ls docker_aiserver_client_files_*.tgz | sort -V | tail -n 1)" - распаковывает архив клиентских файлов

  • tar -xvzf - распаковывает архив с подробным выводом
  • ls docker_aiserver_client_files_*.tgz - находит все файлы архивов
  • sort -V - сортирует версии естественно (1.0 < 1.1 < 1.10)
  • tail -n 1 - выбирает самый свежий файл

Ожидаемый результат: Будет создана директория sh_scripts/ с исполняемыми скриптами и другие необходимые файлы.

Ожидаемый результат: Будет создана директория sh_scripts/ с исполняемыми скриптами и другие необходимые файлы.

Подготовка скриптов к выполнению#

# Перейдите в директорию со скриптами
# Сделайте все скрипты исполняемыми
# Вернитесь в корневую директорию проекта
cd sh_scripts/ && chmod +x *.sh && cd ..
💡 Комментарии к подготовке скриптов

cd sh_scripts/ - переходит в директорию со скриптами установки

*chmod +x .sh - устанавливает права исполнения для всех shell-скриптов

  • chmod +x - добавляет право исполнения
  • *.sh - все файлы с расширением .sh

cd .. - возвращает в корневую директорию проекта

Что делают эти команды:

  • chmod +x *.sh - устанавливает права исполнения для всех shell-скриптов
  • Это необходимо для запуска скриптов в следующих этапах установки

Структура распакованного архива:#

После распаковки вы должны увидеть следующие файлы и директории:

  • sh_scripts/ - директория с установочными скриптами
    • download_all_latest_docker_images.sh - скрипт для скачивания Docker-образов
    • load_all_docker_images.sh - скрипт для загрузки образов в Docker
    • extract_models.sh - скрипт для распаковки моделей ИИ
    • extract_vllm.sh - скрипт для распаковки LLM-моделей
  • docker-compose.yml - конфигурация Docker Compose для клиентской установки
  • .env - файл с переменными окружения для настройки системы

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

# Проверьте содержимое директории
ls -la

# Убедитесь, что скрипты исполняемые
ls -la sh_scripts/*.sh
💡 Комментарии к проверке распаковки

ls -la - показывает подробное содержимое директории

  • -l - длинный формат
  • -a - показывает скрытые файлы

ls -la sh_scripts/*.sh - проверяет скрипты в директории sh_scripts

Выполнение скриптов для разархивации#

Загрузка Docker-образов#

# Запустите скрипт загрузки Docker-образов
sudo ./sh_scripts/load_all_docker_images.sh
💡 Комментарии к загрузке Docker-образов

sudo ./sh_scripts/load_all_docker_images.sh - запускает скрипт загрузки Docker-образов

Что делает скрипт:

  1. Загружает все Docker-образы из скачанных .tar.gz файлов
  2. Импортирует образы в локальный Docker registry
  3. Проверяет успешность загрузки

Распаковка моделей ИИ#

# Запустите скрипт распаковки основных моделей
sudo ./sh_scripts/extract_models.sh
💡 Комментарии к распаковке основных моделей

sudo ./sh_scripts/extract_models.sh - запускает скрипт распаковки моделей

Что делает скрипт:

  1. Распаковывает модель Whisper для распознавания речи
  2. Распаковывает модель BGE Reranker для улучшения поиска
  3. Распаковывает модели для генерации эмбеддингов
  4. Создает необходимые директории
  5. Проверяет успешность распаковки
# Запустите скрипт распаковки LLM моделей
sudo ./sh_scripts/extract_vllm.sh
💡 Комментарии к распаковке LLM модели

sudo ./sh_scripts/extract_vllm.sh - запускает скрипт распаковки LLM модели

Что делает скрипт:

  1. Распаковывает модели
  2. Помещает файлы непосредственно в директорию моделей
  3. Проверяет содержимое после распаковки

Структура директорий после распаковки(примерная):#

./whisper/
└── models/
    ├── base.pt
    └── ...

./bge_reranker/
└── models/
    └── bge-reranker-large/
        ├── config.json
        ├── model.bin
        └── ...

./embed-server/app/
└── model-store/
    └── sentence-transformers/
        └── paraphrase-multilingual-MiniLM-L12-v2/
            ├── config.json
            ├── pytorch_model.bin
            └── ...

./llm-server/models/
├── meta-llama/
│   └── Meta-Llama-3-8B-Instruct/
│       ├── config.json
│       ├── model-00001-of-00004.safetensors
│       ├── model-00002-of-00004.safetensors
│       └── ...
└── tokenizer.json

Настройка конфигурации системы#

Sherpa AIServer требует настройки переменных окружения в файле .env перед запуском.

Открытие файла конфигурации#

# Откройте файл .env в текстовом редакторе
nano ./.env

Или используйте любой текстовый редактор:

# Vim
vim ./.env

# VS Code (если установлен)
code ./.env
💡 Комментарии к открытию файла конфигурации

nano ./.env - открывает файл .env в редакторе nano

  • nano - простой текстовый редактор
  • ./.env - путь к файлу конфигурации

vim ./.env - открывает файл в редакторе Vim code ./.env - открывает файл в VS Code (если установлен)

Рекомендация: Используйте редактор, с которым вы знакомы

Основные параметры конфигурации#

Настройки основного сервера (aiserver):

# IP-адрес сервера (измените на ваш статический IP)
HOST_IP=127.0.0.1

# Доменное имя (измените на ваш домен)
NGINX_DOMAIN_NAME=aiserver.sherparpa.ru

# Максимальная длина сообщений (в токенах)
MAX_TOKENS_MESSAGE=32000

Настройки базы данных PostgreSQL:

# Пароль PostgreSQL (УСТАНОВИТЕ СВОЙ БЕЗОПАСНЫЙ ПАРОЛЬ)
POSTGRES_PASSWORD=password

Настройки LLM сервера:

Выбор модели ИИ: Выберите одну из доступных моделей, раскомментировав нужную строку и закомментировав остальные:

# === ВЫБОР МОДЕЛИ ИИ ===
# Раскомментируйте ТОЛЬКО ОДНУ из моделей ниже:

# Llama 3.1 модель (рекомендуется для общего использования)
LLM_COMPLETION_MODEL_NAME=/model-store/meta-llama/Meta-Llama-3-8B-Instruct
LLM_CHAT_TEMPLATE=/model-templates/tool_chat_template_llama3.1_json.jinja
LLM_TOOL_CALL_PARSER=llama3_json

# Qwen модель (альтернативная модель)
# LLM_COMPLETION_MODEL_NAME=/model-store/Qwen3-30B-A3B-AWQ
# LLM_COMPLETION_MODEL_NAME=/model-store/Qwen3.6-35B-A3B-AWQ
# LLM_CHAT_TEMPLATE=/model-templates/tool_chat_template_qwen3coder.jinja
# LLM_TOOL_CALL_PARSER=hermes

# OCR модель (специализированная для распознавания текста)
# LLM_COMPLETION_MODEL_NAME=/model-store/olmOCR-2-7B-1025-FP8

# === КОНЕЦ ВЫБОРА МОДЕЛИ ===

Безопасность и пароли#

Критически важно: Измените все пароли по умолчанию на надежные:

# Генерация надежных паролей
openssl rand -base64 32

# Или используйте pwgen, если установлен
pwgen -s 32 1

Рекомендации по паролям:

  • Минимум 32 символа
  • Используйте буквы, цифры и специальные символы
  • Не используйте словарные слова
  • Храните пароли в безопасном месте

Проверка конфигурации#

После редактирования файла .env проверьте корректность настроек:

# Проверьте синтаксис файла
cat .env | grep -v '^#' | grep '=' | wc -l

# Проверьте наличие обязательных переменных
grep -E "(POSTGRES_PASSWORD|HOST_IP|NGINX_DOMAIN_NAME)" .env
💡 Комментарии к проверке конфигурации

cat .env | grep -v '^#' | grep '=' | wc -l - подсчитывает количество переменных окружения

  • cat .env - выводит содержимое файла
  • grep -v '^#' - исключает комментарии (строки начинающиеся с #)
  • grep '=' - оставляет только строки с переменными
  • wc -l - подсчитывает количество строк

grep -E "(POSTGRES_PASSWORD|HOST_IP|NGINX_DOMAIN_NAME)" .env - проверяет наличие обязательных переменных

  • -E - расширенные регулярные выражения
  • Перечисляет обязательные переменные через |

Создание резервной копии#

# Создайте резервную копию настроек
cp .env .env.backup
💡 Комментарии к созданию резервной копии

cp .env .env.backup - создает резервную копию файла конфигурации

  • cp - copy (копирование)
  • .env - исходный файл
  • .env.backup - файл резервной копии

Важно: Без правильной настройки .env файла система не запустится корректно.

Копирование SSL-сертификатов#

Для обеспечения безопасного HTTPS-соединения необходимо скопировать SSL-сертификаты в директорию ./nginx/config/certs/:

# Создайте директорию для nginx из default (если не существует)
cp -a ./nginx/config/default/. ./nginx/config/

# Скопируйте ваши SSL-сертификаты
# Замените на пути к вашим реальным сертификатам
cp /path/to/your/certificate.crt ./nginx/config/certs/aiserver.crt
cp /path/to/your/private.key ./nginx/config/certs/aiserver.key

# Или если у вас wildcard сертификат:
cp /path/to/your/wildcard.crt ./nginx/config/certs/aiserver.crt
cp /path/to/your/wildcard.key ./nginx/config/certs/aiserver.key
💡 Комментарии к копированию SSL-сертификатов

mkdir -p ./nginx/config/certs/ - создает директорию для сертификатов

  • -p - создает родительские директории если они не существуют

cp /path/to/your/certificate.crt ./nginx/config/certs/aiserver.crt - копирует сертификат cp /path/to/your/private.key ./nginx/config/certs/aiserver.key - копирует приватный ключ

Требования к сертификатам:

  • Сертификат должен быть в формате .crt или .pem
  • Приватный ключ должен быть в формате .key
  • Имена файлов должны быть aiserver.crt и aiserver.key

Важно: Убедитесь что сертификаты имеют правильные права доступа:

# Установите правильные права на сертификаты
chmod 644 ./nginx/config/certs/*.crt
chmod 600 ./nginx/config/certs/*.key
chown 101:101 ./nginx/config/certs/*.key
chown 101:101 ./nginx/config/certs/*.crt

ВНИМАНИЕ: получить сертификаты необходимо у администратора сети либо в вашем корпоративном центре сертификации, в случае отсутствия данных пунктов вы можете воспользоваться статьей получения сертификатов

Запуск системы#

После завершения всех подготовительных этапов можно запустить Sherpa AIServer. Система будет работать в фоновом режиме как набор Docker-контейнеров.

Важно: Клиент получает файл docker-compose.yml, который содержит конфигурацию всех сервисов. Убедитесь, что вы используете именно этот файл для запуска системы.

Запуск базовых сервисов#

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

docker compose up -d
💡 Базовые сервисы (всегда запускаются)
Сервис Порт Описание
aiserver — Основной бэкенд
aiserver-nginx 80, 443 Веб-сервер / reverse proxy
aiserver-pg 5432 PostgreSQL
aiserver-embed 3004 Сервер эмбеддингов
aiserver-code-interpreter 3001 Интерпретатор кода
aiserver-websocket — WebSocket-сервер

Профили запуска (LLM и дополнительные сервисы)#

Сервисы LLM и дополнительные компоненты запускаются только при явном указании профиля. Можно комбинировать несколько профилей через --profile.

LLM-серверы (выберите один в зависимости от оборудования):

Профиль Сервис Порт Описание
gpu aiserver-llm-server 3003 Основной LLM-сервер на GPU (рекомендуется)
gpu2 aiserver-llm-server2 3006 Второй LLM-сервер на второй видеокарте (Qwen3)
cpu aiserver-llm-server-cpu 3007 LLM-сервер на CPU (без GPU)

Дополнительные сервисы:

Профиль Сервис Порт Описание
whisper aiserver-whisper 3005 Распознавание речи (требует GPU)
reranker aiserver-bge-reranker 8001 Переранжирование результатов поиска (требует GPU)
full whisper + reranker 3005, 8001 Оба дополнительных сервиса сразу

Примеры запуска

# GPU — основной LLM-сервер (наиболее распространённый вариант)
docker compose --profile gpu up -d

# GPU + распознавание речи Whisper
docker compose --profile gpu --profile whisper up -d

# GPU + переранжирование BGE Reranker
docker compose --profile gpu --profile reranker up -d

# GPU + все дополнительные сервисы
docker compose --profile gpu --profile full up -d

# Два LLM-сервера на разных GPU
docker compose --profile gpu --profile gpu2 up -d

# CPU-режим (без GPU)
docker compose --profile cpu up -d

# CPU + все дополнительные сервисы
docker compose --profile cpu --profile full up -d

Важно: Учитывайте объём доступной видеопамяти (VRAM). При запуске нескольких GPU-профилей убедитесь, что на сервере достаточно видеопамяти. При нехватке памяти система может работать нестабильно или не запуститься.

Проверка статуса контейнеров#

# Проверьте статус всех запущенных контейнеров
docker compose ps

# Или используйте docker ps для детальной информации
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
💡 Комментарии к проверке статуса

docker compose ps - показывает статус всех контейнеров Docker Compose

  • Выводит имена, статус и порты контейнеров

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}" - показывает детальную информацию о контейнерах

  • --format - задает пользовательский формат вывода
  • table - табличный формат
  • {{.Names}} - имена контейнеров
  • {{.Status}} - статус контейнеров
  • {{.Ports}} - открытые порты

Ожидаемый вывод (зависит от выбранного profile):

Базовые сервисы (без профилей):

NAME                        STATUS          PORTS
aiserver                    Up 2 minutes
aiserver-nginx              Up 2 minutes    0.0.0.0:80->8080/tcp, 0.0.0.0:443->1443/tcp
aiserver-pg                 Up 2 minutes    0.0.0.0:5432->5432/tcp
aiserver-embed              Up 2 minutes    0.0.0.0:3004->443/tcp
aiserver-code-interpreter   Up 2 minutes    0.0.0.0:3001->3001/tcp
aiserver-websocket          Up 2 minutes

С профилем gpu (основной LLM на GPU):

aiserver-llm-server         Up 2 minutes    0.0.0.0:3003->8000/tcp

С профилем gpu2 (второй LLM на второй видеокарте):

aiserver-llm-server2        Up 2 minutes    0.0.0.0:3006->8000/tcp

С профилем cpu (LLM на CPU):

aiserver-llm-server-cpu     Up 2 minutes    0.0.0.0:3007->8000/tcp

С профилем whisper (добавляется):

aiserver-whisper            Up 2 minutes    0.0.0.0:3005->8000/tcp

С профилем reranker (добавляется):

aiserver-bge-reranker       Up 2 minutes    0.0.0.0:8001->8000/tcp

Все запущенные контейнеры должны иметь статус "Up" и показывать открытые порты.

Проверка логов контейнеров#

# Посмотрите логи основного сервера
docker compose logs aiserver

# Посмотрите логи всех сервисов
docker compose logs

# Мониторинг логов в реальном времени
docker compose logs -f aiserver
💡 Комментарии к проверке логов

docker compose logs aiserver - показывает логи конкретного сервиса

  • aiserver - имя сервиса

docker compose logs - показывает логи всех сервисов

docker compose logs -f aiserver - следит за логами в реальном времени

  • -f - follow (следить за новыми сообщениями)

Проверка на ошибки:

  • Ищите сообщения об ошибках подключения к базам данных
  • Проверьте загрузку моделей ИИ
  • Убедитесь в корректности SSL сертификатов

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

Проверка основного веб-интерфейса:

# Проверьте HTTP доступность (замените на ваш домен)
curl -I http://aiserver.sherparpa.ru

# Проверьте HTTPS доступность (замените на ваш домен)
curl -I https://aiserver.sherparpa.ru

# Ожидаемый ответ: HTTP/2 200 или перенаправление на /login
💡 Комментарии к проверке веб-интерфейса

curl -I http://aiserver.sherparpa.ru - проверяет HTTP доступность

  • -I - показывает только заголовки ответа
  • http://aiserver.sherparpa.ru - URL для проверки

curl -I https://aiserver.sherparpa.ru - проверяет HTTPS доступность

Ожидаемый ответ: HTTP/2 200 или перенаправление на /login

Проверка сервисов ИИ:

# Проверьте LLM сервер
curl -X POST "http://localhost:3003/v1/completions" \
  -H "Content-Type: application/json" \
  -d '{"model": "meta-llama/Meta-Llama-3-8B-Instruct", "prompt": "Hello", "max_tokens": 10}'

<details>
<summary>💡 Комментарии к проверке LLM сервера</summary>

**curl -X POST "http://localhost:3003/v1/completions"** - проверяет LLM сервер
- `-X POST` - HTTP метод POST
- `"http://localhost:3003/v1/completions"` - URL API endpoint
- `-H "Content-Type: application/json"` - заголовок Content-Type
- `-d '{"model": "...", "prompt": "Hello", "max_tokens": 10}'` - данные запроса в JSON формате
</details>

### Проверка подключения к базам данных

```bash

# Проверьте подключение к PostgreSQL
docker compose exec aiserver-pg psql -U postgres -d postgres -c "SELECT version();"

Тестирование основных функций#

Веб-интерфейс:

  1. Откройте браузер и перейдите на https://aiserver.sherparpa.ru
  2. Должна открыться страница входа в систему
  3. Проверьте возможность регистрации/входа

Управление системой#

Остановка системы:

# Остановите все сервисы (с учетом запущенных profiles)
docker compose down

Перезапуск сервисов:

# Перезапустите конкретный сервис
docker compose restart aiserver

# Перезапустите все запущенные сервисы
docker compose restart

# Перезапустите сервисы с определенным profile
docker compose --profile whisper restart aiserver-whisper

Просмотр ресурсов:

# Проверьте использование ресурсов
docker stats

# Проверьте использование GPU
nvidia-smi
💡 Комментарии к управлению системой

Остановка системы:

  • docker compose down - останавливает все сервисы и удаляет контейнеры
  • docker compose down -v - останавливает сервисы и удаляет volumes (данные будут потеряны!)

Перезапуск сервисов:

  • docker compose restart aiserver - перезапускает конкретный сервис
  • docker compose restart - перезапускает все сервисы
  • docker compose --profile whisper restart aiserver-whisper - перезапускает сервис с определенным profile

Просмотр ресурсов:

  • docker stats - показывает использование CPU, памяти, сети для контейнеров
  • nvidia-smi - показывает использование GPU NVIDIA

Возможные проблемы при запуске:#

  • Контейнеры не запускаются: Проверьте логи с docker compose logs
  • Проблемы с SSL: Убедитесь в корректности сертификатов
  • Ошибки подключения к БД: Проверьте переменные окружения в .env
  • GPU проблемы: Проверьте настройки CUDA_VISIBLE_DEVICES

После успешного запуска и тестирования системы установка Sherpa AIServer завершена.