Руководство по установке

В этом руководстве описаны все шаги, необходимые для успешной установки, настройки и запуска программного комплекса «Отаскрайб» (Otascribe) в Docker.

Требуемые компетенции

Для установки программного комплекса «Отаскрайб» требуются специалисты со следующими компетенциями:

• Docker: владение Docker на базовом уровне, включая просмотр логов (docker logs), запуск и остановка контейнеров (docker up/stop), очистка кеша (docker system prune -f), проверка статуса (docker ps), управление стеками (docker compose).
  • Понимание принципов работы с docker-compose.yml и умение запускать и проверять состояние многоконтейнерных приложений (docker compose up, docker compose ps, docker compose logs).
• Администрирование Linux: уверенная работа в командной строке, включая управление файлами и директориями (mkdir, tar, rm, ls -a), загрузку файлов (wget) и управление правами (например, добавление пользователя в группу docker).
• Настройка GPU-окружения: опыт установки и проверки драйверов NVIDIA, CUDA Toolkit, cuDNN и NVIDIA Container Toolkit.
• Редактирование конфигураций: Умение работать с конфигурационными файлами в форматах .env и .yml для настройки параметров сервисов.

Раздел 1. Системные требования

Перед началом установки убедитесь, что ваша система соответствует следующим требованиям.

1.1. Операционная система

Требуется операционная система на базе Linux.

Рекомендуемые дистрибутивы:

• Debian 10/11
• Ubuntu 22.04/24.04
• РЕД ОС 7.3

1.2. Аппаратное обеспечение

Рекомендуемые архитектуры: NVIDIA Turing, Ampere или новее (например, NVIDIA A100 или L40S).

1.3. Программные зависимости

Для работы «Отаскрайб» необходимо установить и настроить следующие компоненты:

1. Драйверы NVIDIA и CUDA

• Драйверы NVIDIA для графического ускорителя (не ниже 5xx).
• CUDA Toolkit (версии 12.8 или 13, в зависимости от требований графического ускорителя).
• Библиотека cuDNN (версия должна быть совместима с установленной версией CUDA).

2. Docker и NVIDIA Container Toolkit

• Docker
• Плагин Docker Compose (для управления многоконтейнерными приложениями)
• NVIDIA Container Toolkit, чтобы разрешить Docker-контейнерам использовать CUDA

3. Программные компоненты

• Docker-образ Postgres 16 c pgroonga.
• Docker-образ Redis 7.4.2.

1.4. Проверка готовности системы

Перед переходом к следующему шагу необходимо убедиться, что:

Драйверы NVIDIA и CUDA установлены корректно.

Выполните команду nvidia-smi. Должен появиться вывод, отображающий видеокарту, версию драйвера и версию CUDA.

nvidia-smi

• 1️⃣🟥 — версия драйвера графического ускорителя
• 2️⃣🟩 — версия CUDA
• 3️⃣🟦 — Наименование графического ускорителя
• 4️⃣🟨 — Потребление VRAM графического ускорителя

Библиотека cuDNN работает.

Следуйте официальной документации NVIDIA для тестирования установки cuDNN.

Docker и NVIDIA Container Toolkit настроены.

Убедитесь, что у вашего пользователя есть права для работы с Docker (обычно это достигается добавлением пользователя в группу docker).

Управление Docker от имени пользователя без root.

Раздел 2. Установка дистрибутива

После подготовки сервера можно приступать к загрузке и развертыванию файлов «Отаскрайб».

Шаг 1. Подготовка рабочей директории

Создайте рабочую директорию для хранения файлов конфигурации и архивов Docker-образов и перейдите в неё:

mkdir -p /path/to/otascribe
cd /path/to/otascribe

md C:\otascribe
cd C:\otascribe

Шаг 2. Загрузка файлов

Загрузите необходимые файлы в созданную рабочую директорию. Используйте соответствующую команду для вашей ОС:

wget https://vfrc.rtatex.ru/{CUSTOMER_SLUG}/{.env,backend.tar.gz,config.yml,docker-compose.yml,frontend.tar.gz,otawhisp-worker.tar.gz,summarization-service.tar.gz,license-service.tar.gz,LICENSE_CUSTOMER_SLUG_DATE.lic}

$baseUrl = "https://vfrc.rtatex.ru/{CUSTOMER_SLUG}/"
$files = @(
    ".env",
    "backend.tar.gz",
    "config.yml",
    "docker-compose.yml",
    "frontend.tar.gz",
    "otawhisp-worker.tar.gz",
    "summarization-service.tar.gz",
    "license-service.tar.gz",
    "LICENSE_CUSTOMER_SLUG_DATE.lic"
)

foreach ($file in $files) {
    Invoke-WebRequest -Uri "$baseUrl$file" -OutFile $file
}

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

Шаг 3. Локальная загрузка Docker-образов

Далее необходимо загрузить образы, полученные на Шаге 2, в локальный реестр Docker.

docker load --input backend.tar.gz
docker load --input frontend.tar.gz
docker load --input otawhisp-worker.tar.gz
docker load --input summarization-service.tar.gz
docker load --input license-service.tar.gz

После успешной загрузки (проверить можно командой docker images), образы *.tar.gz можно удалить для экономии места на диске:

rm ./*.tar.gz

Remove-Item *.tar.gz

Раздел 3. Конфигурация

Перед запуском можно (опционально) настроить файлы конфигурации. Все файлы (.env, config.yml, docker-compose.yml) должны находиться в одной рабочей директории (/path/to/otascribe).

Шаг 4. Настройка файла .env

Файл .env содержит переменные окружения для базы данных, публичного адреса Backend-а, Redis и сервиса резюмирования.

Пример файла .env:

POSTGRES_DATABASE=db
POSTGRES_USER=user
POSTGRES_PASSWORD=1234
POSTGRES_ADMIN_EMAIL=admin@oscb.lan
POSTGRES_ADMIN_PASSWORD=5678

REDIS_PASSWORD=1234
REDIS_USER=admin
REDIS_USER_PASSWORD=1234
REDIS_CONNECTION_URL=redis://admin:1234@redis/0

OTASCRIBE_ENV_API_BASE_URL=http://localhost:7575

LLM_API_URL=COMPLETE_LLM_API_URL
LLM_API_KEY=COMPLETE_LLM_API_KEY
LLM_MODEL_NAME=rtex2510-4b-instruct
LLM_MAX_NEW_TOKENS=8192

Шаг 5. Настройка файла config.yml

Файл config.yml содержит основные параметры для работы сервисов «Отаскрайб».

Рекомендации по настройке:

• Database / Redis: Убедитесь, что пароли и URL-адреса подключения здесь (config.yml) полностью совпадают с теми, что указаны в .env.
• JWT: Для производственной среды сгенерируйте безопасный jwt_secret_key (например, командой openssl rand -hex 32).
• Email: Если планируется отправка почты, раскомментируйте и настройте параметры вашего SMTP-сервера.
• OIDC: Раскомментируйте и настройте, если используете единую точку входа (SSO).
• App: Убедитесь, что uploads_path указывает на корректный путь, куда будут загружаться файлы.

Шаг 6. Опциональная конфигурация сетевых настроек

Необходимо настроить .env следующим образом:

OTASCRIBE_ENV_API_BASE_URL=http://<public_ip>:<backend_port>

По данному адресу клиентская часть (интерфейс frontend) будет обращаться к серверу приложения (backend). Если backend недоступен по адресу http://localhost:7575, необходимо задать в переменной окружения OTASCRIBE_ENV_API_BASE_URL публичный адрес backend (внутренний или внешний).

docker compose down frontend
docker compose up -d frontend

Шаг 7. (Опционально) Настройка LLM-провайдера

Для работы функции умного резюмирования и генерации отчетов необходимо подключить внешний или локальный LLM-провайдер, совместимый со стандартом API OpenAI.

Рекомендация по выбору размера модели:

Раздел 4. Запуск и тестирование

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

Шаг 8. Запуск контейнеров

1. Убедитесь, что вы находитесь в рабочей директории (/path/to/otascribe), где лежат файлы docker-compose.yml, config.yml и .env.
2. Запустите все сервисы в фоновом режиме:

docker compose up -d

Шаг 9. Проверка работы системы

1. Проверьте статус запущенных контейнеров:

docker compose ps

Все сервисы (backend, frontend, db, redis и т.д.) должны находиться в состоянии Up.

Пример вывода:

Name                     Command               State   Ports
----------------------------------------------------------------
otascribe_backend_1       ...                     Up      ...
otascribe_frontend_1      ...                     Up      ...
otascribe_db_1            ...                     Up      5432/tcp
otascribe_redis_1         ...                     Up      6379/tcp
...

2. Проверьте общие логи на наличие ошибок (особенно в первые минуты запуска):

docker compose logs -f

Шаг 10. Доступ к веб-интерфейсу

1. Откройте браузер и перейдите по IP-адресу вашего сервера, используя порт 7576:

http://<SERVER_IP>:7576

2. Должна появиться страница входа в систему.

Раздел 5. Диагностика и поддержка

Диагностика проблем

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

Частые проблемы

Неизвестная ошибка транскрибации

Проверить логи воркера:

docker compose logs -n 1000 otawhisp-worker

Если видим строки:

otawhisp-worker-1  | 2025-12-04 10:12:56 ERROR <>:95 No CUDA GPUs are available
otawhisp-worker-1  | 2025-12-04 10:12:57 ERROR <>:153 No CUDA GPUs are available
otawhisp-worker-1  | 2025-12-04 10:15:18 ERROR <>:153 CUDA failed with error no CUDA-capable device is detected

Необходимо проверить:

1. CUDA, Nvidia Container toolkit, NVCC установлены?

   nvidia-smi
   nvcc -V

2. Контейнер видит карточку?

   docker compose exec -it otawhisp-worker nvidia-smi

Если видим ошибку: <Callout type="error">Failed to initialize NVML: Unknown Error</Callout>

Исправление (только для Linux):

sudo nano /etc/nvidia-container-runtime/config.toml
# Ставим:
no-cgroups = false
# Перезапускаем:
sudo systemctl restart docker

Перепроверяем:

docker compose exec -it otawhisp-worker nvidia-smi

Техническая поддержка

Если вы столкнулись с проблемами, обратитесь в техническую поддержку в чате или по почте support@otascribe.ru.