Установка компонентов целевых машин

1. Установка Docker

Настоящее краткое руководство основано на официальных инструкций:

• Install Docker Engine from binaries .
• NVIDIA Container Toolkit Installation Guide 

При наличии интернета доступа к необходимым ресурсам, установите docker согласно официально инструкции.

В отсутствие интернета установите Docker из комплекта поставки: пакеты docker.io и docker-compose-v2 согласно статье Установка пакета из комплекта поставки.

Комплект поставки AI Server размещён в Nexus: https://nexus.primo-rpa.ru/repository/raw/, авторизация для скачивания не нужна. Пути ниже указаны относительно этого адреса.

Запуск службы Docker

Пакет docker.io устанавливает службу Docker. Включите её автозапуск и запустите:

sudo systemctl enable --now docker

Создание группы docker

Проверьте наличие группы docker на сервере:

cat /etc/group | grep docker

Если группы нет, добавьте:

sudo groupadd docker

Раздача прав

Добавьте текущего пользователя в группу docker. Например, для пользователя ubuntu:

sudo usermod -aG docker ubuntu && \
  newgrp docker

Взаимодействие Docker с GPU

Архитектура

Взаимосвязь между GPU и приложениями происходит по следующей цепочке:

Таким образом, для работы с GPU из Docker необходимо:

• Совместимая GPU NVIDIA
• CUDA-драйвер на машине-хосте
• NVIDIA Container Toolkit (nvidia-docker2)

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

Используйте команду для определения рекомендованной версии драйвера (только для Ubuntu):

 ubuntu-drivers devices

Рекомендованная версия будет отмечена флагом recommended, например:

vendor   : NVIDIA Corporation
model    : AD102 [GeForce RTX 4090]
driver   : nvidia-driver-580-server - distro non-free
driver   : nvidia-driver-535 - distro non-free
                                                        ↓↓↓
driver   : nvidia-driver-580-open - distro non-free recommended
                                                        ↑↑↑
driver   : nvidia-driver-535-server-open - distro non-free
driver   : nvidia-driver-580-server-open - distro non-free
driver   : nvidia-driver-535-open - distro non-free
driver   : nvidia-driver-570-server - distro non-free
driver   : nvidia-driver-570-server-open - distro non-free
driver   : nvidia-driver-570-open - distro non-free
driver   : nvidia-driver-535-server - distro non-free
driver   : nvidia-driver-580 - distro non-free
driver   : nvidia-driver-570 - distro non-free
driver   : xserver-xorg-video-nouveau - distro free builtin

Установка драйвера

1. Через apt

• Удалите текущие драйверы.

sudo apt-get remove --purge '^nvidia-.'

sudo apt-get remove --purge '^libnvidia-.'

sudo apt-get remove --purge '^cuda-.*'

Если драйверы были установлены, перезагрузите сервер

sudo reboot

• Установите выбранный драйвер

sudo apt install nvidia-driver-580-open nvidia-dkms-580-open nvidia-utils-580

sudo reboot

2. С использованием run-файла

• Выберите run-файл в комплекте поставки: в Nexus лежат версии 570.124.04, 580.95.05 и 580.126.09. Если подходящего файла нет, скачайте его из https://www.nvidia.com/en-us/drivers/unix/  (архивные: https://download.nvidia.com/XFree86/Linux-x86_64/ )

• Скачайте и установите драйвер:

  wget "https://nexus.primo-rpa.ru/repository/raw/data/libraries/nvidia/NVIDIA-Linux-x86_64-580.95.05.run" && \
  sudo chmod +x ./NVIDIA-Linux-x86_64-580.95.05.run && \
  sudo ./NVIDIA-Linux-x86_64-580.95.05.run

3. Из комплекта поставки

Установите пакеты драйвера из комплекта поставки согласно статье Установка пакета из комплекта поставки.

Драйвер собирается под ядро машины, поэтому сначала проверьте, что в бандле есть архив linux-headers-* под ядро из uname -r.

Ставьте пакеты строго по порядку:

1. linux-headers-<версия> — заголовки под ваше ядро, например linux-headers-6.12-generic на Astra Linux 1.8 или linux-headers-generic на Ubuntu;
2. build-essential;
3. dkms;
4. nvidia-driver-580-open.

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

sudo reboot

Установка nvidia-docker2 / Nvidia Container Toolkit

При наличии доступа к интернету установите NVIDIA Container Toolkit согласно официальной инструкции выше.

В отсутствие интернета установите пакет nvidia-container-toolkit из комплекта поставки согласно статье Установка пакета из комплекта поставки.

Проверка

Проверьте наличие драйвера в системе:

nvidia-smi

При наличии доступа к репозиториям docker проверьте доступность драйвера GPU внутри контейнера:

 docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi

• Если драйвер доступен, в терминале будет информация по доступным устройствам Nvidia.
• В противном случае настройте драйвер принудительно и повторите проверку доступности:

sudo nvidia-ctk runtime configure --runtime=docker && \
    sudo systemctl restart docker

2. Настройка учетной записи

Для работы агента создайте группу primo-ai и учетную запись agent.

sudo groupadd primo-ai

sudo useradd -g primo-ai -m -s /bin/bash agent

sudo usermod -aG docker agent

3. Создание подсети для запуска контейнеров

Подсеть используется NLP-сервером, IDP-сервером, FT-сервером и LLM-ядром.

docker network create \
  --driver bridge \
  --subnet=172.19.0.0/24 \
  --gateway=172.19.0.1 \
  agent_agent_ai

4. Установка и настройка агента

Разверните файлы агента на целевой машине.

sudo mkdir -p /app/Primo.AI /app/Primo.AI/Agent /app/Primo.AI/AgentData

Для распаковки нужен пакет unzip. Если он отсутствует, установите его из комплекта поставки согласно статье Установка пакета из комплекта поставки.

wget "https://nexus.primo-rpa.ru/repository/raw/1.26.10/ai-server/linux/Agent-linux.zip"

sudo unzip Agent-linux.zip -d /app/Primo.AI/Agent

sudo chmod -R 771 /app/Primo.AI/Agent /app/Primo.AI/AgentData

sudo chown -R agent:primo-ai /app/Primo.AI/Agent /app/Primo.AI/AgentData

Настройка ACL для Ollama

Установите пакет acl, если он отсутствует, из комплекта поставки согласно статье Установка пакета из комплекта поставки.

Настройте права доступа и наследование для UID 1001:

sudo setfacl -R -m u:1001:rwx /app/Primo.AI/AgentData
sudo find /app/Primo.AI/AgentData -type d -exec setfacl -d -m u:1001:rwx {} +

Установите агент как службу и настройте автозапуск:

sudo cp /app/Primo.AI/Agent/Primo.AI.Agent.service /etc/systemd/system/

sudo systemctl daemon-reload

sudo systemctl enable /etc/systemd/system/Primo.AI.Agent.service

Настройте сервис, скорректировав конфигурационный файл /app/Primo.AI/Agent/appsettings.ProdLinux.json. Обычно требуется отредактировать следующий блок:

 "Api": {
	"AgentId": "{91E221E8-8E13-4100-8BCB-84EA318C32DA}", // Уникальный идентификатор агента
  ...
	"AuthBaseUrl": "https://primo-rpa-ai-server:44392",
	"ApiBaseUrl": "https://primo-rpa-ai-server:44392",
	"InferenceBaseUrl": "https://primo-rpa-ai-server:44392",
	"LogsBaseUrl": "https://primo-rpa-ai-server:44392",
  ...
  "AgentBaseUrl": "http://172.19.0.1:5092", // URL агента, доступный из IDP-сервера
  },

• AgentId — уникальный идентификатор агента в виде значения с типом данных GUID.

Установите корректный идентификатор агента, заменив на него заглушку XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXX:

sudo sed -i 's|"AgentId": "{91E221E8-8E13-4100-8BCB-84EA318C32DA}"|"AgentId": "{XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXX}"|g' /app/Primo.AI/Agent/appsettings.ProdLinux.json

• Если использована нестандартная подсеть Docker, укажите адрес хоста: AgentBaseUrl, заменив http://XXX.XXX.XX.1:5092 на эндпоинт агента, доступный из Docker-контейнера:

sudo sed -i 's|http://172.19.0.1:5092|http://XXX.XXX.XX.1:5092|g' /app/Primo.AI/Agent/appsettings.ProdLinux.json

• Обязательно установите адрес Primo.AI.Api и его компонентов – XxxxxxxBaseUrl, заменив https://XXXXXXXXXXXXXXXXX:44392 на доступный из Целевой машины эндпоинт AI Server:

sudo sed -i 's|https://primo-rpa-ai-server:44392|https://XXXXXXXXXXXXXXXXX:44392|g' /app/Primo.AI/Agent/appsettings.ProdLinux.json

Запустите службы:

sudo systemctl start Primo.AI.Agent

Проверьте статус службы:

sudo systemctl status Primo.AI.Agent

Просмотрите журнал службы:

sudo journalctl -u Primo.AI.Agent

Настройка правила брандмауэра ufw

Если пакета ufw нет, его можно установить из комплекта поставки согласно статье Установка пакета из комплекта поставки или открыть те же порты средствами другого брандмауэра.

Для разрешения доступа к API агента выполните команды:

sudo ufw allow 5002/tcp

Или для создания белого списка:

sudo ufw allow from x.x.x.x to any port 5002 proto tcp

Где x.x.x.x - IP-адрес машины, на которой установлена серверная часть AI Server.

Также создайте правило для доступности агента по http:5092 только из других компонентов целевой машины внутри подсети agent_agent_ai (IDP-, NLP- и FT-сервер):

sudo ufw allow from 172.19.0.0/24 to 172.19.0.1 port 5092 proto tcp

Настройка SELinux

Проверьте, включен ли SELinux в системе командой sestatus. Если включен, измените контекст исполняемого файла агента:

sudo chcon -t bin_t /app/Primo.AI/Agent/Primo.AI.Agent

5. Компоненты Умного OCR

Вариант загрузки образов 1: скачайте необходимые архивы из официальной поставки AI Server:

Если 7z не установлен, установите пакет 7zip из репозитория ОС или из комплекта поставки согласно статье Установка пакета из комплекта поставки.

name="ai-server-idp-cpu" # или ai-server-idp-gpu - см. таблицу выше
wget "https://nexus.primo-rpa.ru/repository/raw/1.26.10/ai-server/docker/images/$name.tar.7z"
7z x $name.tar.7z
docker load -i $name.tar

Вариант загрузки образов 2: используя репозиторий Docker:

Работает при наличии подключения к nexus.primo-rpa.ru:8000.

name="ai-server-idp-cpu" # или ai-server-idp-gpu - см. таблицу выше
docker pull nexus.primo-rpa.ru:8000/primo-rpa/$name:1.26.10.0

Имя образа в файле конфигурации.

• Только для GPU. Скорректируйте имя образа:

sudo sed -i 's|"ImageName": "nexus.primo-rpa.ru:8000/primo-rpa/ai-server-idp-cpu:1.26.10.0"|"ImageName": "nexus.primo-rpa.ru:8000/primo-rpa/ai-server-idp-gpu:1.26.10.0"|g' /app/Primo.AI/Agent/appsettings.ProdLinux.json

SDC-сервер (семантический классификатор)

SDC-сервер выполняет проекты Классификация (семантическая): определяет тип документа по смысловому содержанию текста. Образ один для машин с GPU и без.

Вариант загрузки образа 1: скачайте архив из официальной поставки AI Server (нужен 7z, см. выше):

name="ai-server-sdc"
wget "https://nexus.primo-rpa.ru/repository/raw/1.26.10/ai-server/docker/images/$name.tar.7z"
7z x $name.tar.7z
docker load -i $name.tar

Вариант загрузки образа 2: из репозитория Docker, при наличии подключения к nexus.primo-rpa.ru:8000:

docker pull nexus.primo-rpa.ru:8000/primo-rpa/ai-server-sdc:1.26.10.0

Секция DocClassifyProcess с образом SDC-сервера уже есть в конфигурации агента из комплекта поставки, править её не нужно.

SDC-сервер работает в контейнере от пользователя с UID 1002 и хранит модели в каталоге /app/Primo.AI/AgentData/SdcModels. Создайте каталог и назначьте права (нужен пакет acl):

sudo mkdir -p "/app/Primo.AI/AgentData/SdcModels"
sudo chown agent:primo-ai "/app/Primo.AI/AgentData/SdcModels"
sudo find "/app/Primo.AI/AgentData/SdcModels" -type d -exec setfacl -d -m u:1002:rwx {} +
sudo setfacl -R -m u:1002:rwx "/app/Primo.AI/AgentData/SdcModels"

Модели SDC-сервер при первом запуске загружает с машины сервера: эмбеддинг-модель qwen3vl-embed-2B и модель семантического классификатора должны быть размещены в Центре управления (см. установку Центра управления).

6. Компоненты Задач NLP

Выбор LLM-движка (Ollama, vLLM)

LLM-модели отличаются высокой требовательностью к производительности. Время генерации токенов на графическом ускорителе на порядок ниже, чем на CPU.

Primo RPA AI Server поддерживает 2 разновидности LLM-ядра — vLLM и Ollama. Для высокопроизводительных вычислений на графической карте подходит vLLM, тогда как Ollama лучше работает на CPU (отличается меньшим временем генерации первого токена). Свежие видеокарты с высокой compute capability несколько месяцев поддерживаются только движком Ollama.

Выбор ядра также влияет на выбор модели. Модель base-llm-06-7b-safetensors-fp16 поддерживается только движком vLLM, тогда как модель base-llm-06-7b-gguf-q8 только Ollama.

Для работы с LLM-ядром необходимо выбрать хотя бы 1 вариант из представленных.

О FT-сервере

FT-сервер – компонент целевой машины, который отвечает за файнтюнинг моделей.

В настоящий момент поддерживается файнтюнинг только для задач классификации текста.

Вариант загрузки образов 1: скачайте необходимые архивы из официальной поставки AI Server:

1. Если на машине нет GPU:

Если 7z не установлен, установите пакет 7zip из репозитория ОС или из комплекта поставки согласно статье Установка пакета из комплекта поставки.

names="ai-server-nlp ai-server-ollama"
for name in $names; do
    wget "https://nexus.primo-rpa.ru/repository/raw/1.26.10/ai-server/docker/images/$name.tar.7z"
    7z x $name.tar.7z
    docker load -i $name.tar
done

2. Если на машине есть GPU:

Если 7z не установлен, установите пакет 7zip из репозитория ОС или из комплекта поставки согласно статье Установка пакета из комплекта поставки.

names="ai-server-nlp ai-server-ft ai-server-ollama"
externals="vllm/vllm-openai:v0.30.0"
for name in $names; do
    wget "https://nexus.primo-rpa.ru/repository/raw/1.26.10/ai-server/docker/images/$name.tar.7z"
    7z x $name.tar.7z
    docker load -i $name.tar
done
for external in $externals; do
    filename=$(echo "${external##*/}" | sed 's/:/_/g')
    wget "https://nexus.primo-rpa.ru/repository/raw/data/libraries/docker/images/$filename.tar.7z"
    7z x $filename.tar.7z
    docker load -i $filename.tar
done

Вариант загрузки образов 2: используя репозиторий Docker:

Работает при наличии подключения к nexus.primo-rpa.ru:8000.

1. Если на машине нет GPU:

names="ai-server-nlp ai-server-ollama"
for name in $names; do
    docker pull nexus.primo-rpa.ru:8000/primo-rpa/$name:1.26.10.0
done

2. Если на машине есть GPU:

names="ai-server-nlp ai-server-ft ai-server-ollama"
externals="vllm/vllm-openai:v0.30.0"
for name in $names; do
    docker pull nexus.primo-rpa.ru:8000/primo-rpa/$name:1.26.10.0
done
for external in $externals; do
    docker pull nexus.primo-rpa.ru:8000/$external
done

Имя образа в файле конфигурации.

• Только для GPU. В секции LlmEngineProcess.EnginesDockerRun.Vllm файла /app/Primo.AI/Agent/appsettings.ProdLinux.json укажите образ vLLM:

"ImageName": "nexus.primo-rpa.ru:8000/vllm/vllm-openai:v0.30.0"

7. Компоненты Агентских систем.

Вариант загрузки образов 1: скачайте необходимые архивы из официальной поставки AI Server:

Если 7z не установлен, установите пакет 7zip из репозитория ОС или из комплекта поставки согласно статье Установка пакета из комплекта поставки.

#основные образы
names="ai-server-rag-gpu ai-server-langflow-backend"
for name in $names; do
    wget "https://nexus.primo-rpa.ru/repository/raw/1.26.10/ai-server/docker/images/$name.tar.7z"
    7z x $name.tar.7z
    docker load -i $name.tar
done
 
#PostgreSQL + pgVector
wget "https://nexus.primo-rpa.ru/repository/raw/data/libraries/docker/images/pgvector_pg18.tar.7z"
7z x pgvector_pg18.tar.7z
docker load -i pgvector_pg18.tar

Вариант загрузки образов 2: используя репозиторий Docker:

Работает при наличии подключения к nexus.primo-rpa.ru:8000.

names="ai-server-rag-gpu ai-server-langflow-backend"
for name in $names; do
    docker pull nexus.primo-rpa.ru:8000/primo-rpa/$name:1.26.10.0
done
 
#PostgreSQL + pgVector
docker pull nexus.primo-rpa.ru:8000/pgvector/pgvector:pg18

Данные Исполнителя агентских систем

При необходимости чтения файлов (например, для наполнения БД RAG-системы), их можно разместить в /app/Primo.AI/AgentData/LangflowData/95XX/..., где 95XX – порт контейнера с Исполнителем агентских систем. Эта папка будет подключена как том в контейнеры Исполнителя агентских систем. В проекте необходимо будет указать путь к этой папке, как /app/data/.... Изменить это поведение можно в файле конфигурации агента, ключ Lfx > Volumes:

sudo nano /app/Primo.AI/Agent/appsettings.ProdLinux.json

8. Настройка производительности

При необходимости скорректируйте параметры производительности в конфигурационном файле агента (/app/Primo.AI/Agent/appsettings.ProdLinux.json).

Ограничение параллельной обработки

Уменьшите значения при нехватке оперативной памяти или вычислительных ресурсов. Это позволит избежать перегрузки целевой машины.

Таймауты запуска процессов

Каждый компонент целевой машины (IDP-сервер, NLP-сервер, LLM-движок) при первом запросе загружается в память. Если загрузка не укладывается в таймаут, процесс считается зависшим и прерывается. Увеличьте таймауты при работе на медленном оборудовании.