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

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

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

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

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

💡 Комментарии к распаковке архива

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

• tar -xvzf - распаковывает архив с подробным выводом

• ls client_files_*.tgz - находит все файлы архивов

• sort -V - сортирует версии естественно (1.0 < 1.1 < 1.10)

• tail -n 1 - выбирает самый свежий файл

Ожидаемый результат: Будет создана директория 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 AI Server требует настройки переменных окружения в файле .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=examples/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_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-сертификаты в директорию ./oais/backend/config/certs/:

# Создайте директорию для сертификатов (если не существует)
mkdir -p ./oais/backend/config/certs/

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

# Или если у вас wildcard сертификат:
cp /path/to/your/wildcard.crt ./oais/backend/config/certs/aiserver.crt
cp /path/to/your/wildcard.key ./oais/backend/config/certs/aiserver.key

💡 Комментарии к копированию SSL-сертификатов

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

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

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

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

• Сертификат должен быть в формате .crt или .pem

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

• Имена файлов должны быть aiserver.crt и aiserver.key

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

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

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

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

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

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

Запуск всех сервисов

# Запустите базовые сервисы в фоновом режиме
docker compose up -d

💡 Комментарии к запуску сервисов

docker compose up -d - запускает все сервисы в фоновом режиме

• docker compose - использует Docker Compose для управления контейнерами

• up - создает и запускает все сервисы из docker-compose.yml

• -d - запускает контейнеры в detached режиме (фоновом)

Ожидаемое время запуска: 2-5 минут, в зависимости от производительности системы.

Запуск сервисов с дополнительными функциями

В файле docker-compose.yml некоторые сервисы имеют profiles и запускаются только при явном указании:

# Запуск с сервисом распознавания речи Whisper
docker compose --profile whisper up -d

# Запуск с сервисом переранжирования BGE Reranker
docker compose --profile reranker up -d

# Запуск всех сервисов (Whisper + BGE Reranker + базовые)
docker compose --profile full up -d

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

Доступные profiles:

• whisper - включает сервис распознавания речи (порт 3005)

• reranker - включает сервис переранжирования результатов поиска (порт 8001)

• full - включает все дополнительные сервисы (Whisper + BGE Reranker)

Важно: Без указания profiles сервисы Whisper и BGE Reranker не запустятся. Выберите нужный profile в зависимости от ваших требований к функциональности.

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

# Проверьте статус всех запущенных контейнеров
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):

Базовые сервисы (без profiles):

NAME                    STATUS              PORTS
aiserver                Up 2 minutes        0.0.0.0:443->443/tcp, 0.0.0.0:80->80/tcp, 0.0.0.0:4500->4500/tcp
aiserver-db             Up 2 minutes        0.0.0.0:3306->3306/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-llm-server     Up 2 minutes        0.0.0.0:3003->8000/tcp
aiserver-code_interpreter Up 2 minutes        0.0.0.0:3001->3001/tcp

С profile whisper (добавляется):

aiserver-whisper        Up About a minute   0.0.0.0:3005->8000/tcp

С profile reranker (добавляется):

aiserver-bge_reranker   Up About a minute   0.0.0.0:8001->8000/tcp

С profile full (добавляются оба):

aiserver-whisper        Up About a minute   0.0.0.0:3005->8000/tcp
aiserver-bge_reranker   Up About a minute   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

# Остановите с удалением volumes (осторожно!)
docker compose down -v

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

# Перезапустите конкретный сервис
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 AI Server завершена.