Интеграция с GitLab¶

Интеграция с GitLab позволяет сохранять и обучать проекты с использованием CI/CD и GitLab Runner. Требуемая версия GitLab Community Edition — 15.3.5 или выше.

Сохранение проектов WiseBot в GitLab¶

Рекомендуется создать новую учетную запись в GitLab для реализации синхронизации между GitLab и WiseBot. В целях безопасности новой учетной записи следует выдать только доступы на необходимые проекты (после их создания).

Создание проекта в GitLab¶

Создайте пустой проект в GitLab.
Клонируйте проект:

git clone <ссылка_на_проект>

Перейдите в папку проекта и создайте пустую ветку:

cd <имя_проекта>
git switch --orphan <новая_ветка>
git commit --allow-empty -m "Initial commit on orphan branch"
git push -u origin <новая_ветка>

Создание токена авторизации¶

Перейдите в настройки проекта GitLab -> “Токены доступа”.

Консоль администратора reCAPTCHA

Создайте токен с ролью Developer и правами read_repository и write_repository.

Токены доступа GitLab

Сохраните токен.

Настройка авторизации в WiseBot¶

В настройках проекта WiseBot выберите “Учетные данные Git”.

Учетные данные Git

Укажите репозиторий в формате:

https://<login>:<token>@<url>/<group>/<project>.git#<branch>

login - логин от учетной записи
token - токен, полученный в п. 2.1.2
url - адрес инстанса GitLab
group - имя группы проектов
project - имя проекта в GitLab
branch - название ветки, созданной в п. 2.1.1

Сохраните настройки.

Синхронизация WiseBot с GitLab¶

В разделе "Диалоги" WiseBot появится кнопка Git. С ее помощью можно фиксировать изменения и синхронизировать их с GitLab.

Кнопка Git в WiseBot

При нажатии на кнопку выберите “Фиксировать и применить”. В появившемся модальном окне опционально можно добавить сообщения для коммита в GitLab. При нажатии “Загрузить в удаленный репозиторий” произойдет синхронизация проекта WiseBot и проекта GitLab.

Обучение моделей с использованием GitLab CI/CD¶

CI/CD (Continuous Integration, Continuous Delivery — непрерывная интеграция и доставка) — технология автоматизации тестирования и доставки новых модулей проекта заинтересованным сторонам. Обучение моделей происходит в двух режимах: с использованием GPU и без него.

Подготовка системы¶

Требуется следующее окружение:

Linux Ubuntu 20 и выше;
Docker 20.10 и выше;
Docker Compose 2.21 и выше;
GitLab Runner 15.7.1 и выше;

Для обучения с использованием GPU:

NVIDIA драйверы 525.147.05 и выше;
NVIDIA Container Toolkit 1.13.0 и выше.

Инструкции по установке:

Установка Docker¶

Для установки Docker обратитесь к пункту 1.2.

Установка GitLab Runner¶

GitLab Runner — приложение с открытым исходным кодом, выполняющее задания конвейера GitLab CI/CD на основе файла .gitlab-ci.yml. Подробные инструкции по установке доступны в официальной документации.

Регистрация GitLab Runner¶

После установки GitLab Runner необходимо зарегистрировать его в проекте. Подробное руководство по регистрации находится в документации.

Создание `.gitlab-ci.yml`¶

Файл .gitlab-ci.yml определяет конфигурацию CI/CD конвейера. Подробнее о синтаксисе и использовании см. в официальной документации.

Ключевые элементы файла:¶

Задачи: например, тестирование и развертывание.
Включение других конфигураций.
Зависимости и кэши.
Последовательное и параллельное выполнение команд.
Локация развертывания.
Настройка ручного или автоматического запуска.

Создайте файл .gitlab-ci.yml в основной ветке (main) проекта GitLab. Пример заполнения файла представлен в Приложении 1.

Также необходимо создавать файл .gitlab-ci.yml в каждой ветке, содержащей обучающие данные. Его структура отличается от основной и представлена в Приложении 2. Для его работы необходимо создать триггер сборочной линии (Настройки → CI/CD → Триггеры сборочной линии) и заполнить недостающие параметры (token, branch, trigger-url).

Создание `Dockerfile`¶

Механизм обучения моделей с использованием GitLab CI/CD основан на создании Docker-образов. Необходимо описать два файла Dockerfile, которые должны быть созданы в основной ветке проекта GitLab.

Первый Dockerfile: отвечает за создание базового образа, содержащего все необходимые компоненты для обучения моделей. Создавайте его один раз и обновляйте только при необходимости изменения компонентов обучения. Пример данного Dockerfile представлен в Приложении 3.
Второй Dockerfile: отвечает за обучение моделей. Основным образом будет базовый образ из первого Dockerfile. В процессе создания образа выполняется обучение модели. В результате получается образ NGINX, содержащий модель по адресу /default. Логи обучения доступны по адресу /logs.txt. Пример данного Dockerfile представлен в Приложении 4.

Если вы правильно настроили .gitlab-ci.yml и Dockerfile, в реестре контейнеров вашего проекта (Пакеты и реестры → Реестр контейнеров) появится контейнер с моделью под именем <название ветки>-<время создания>.

Добавление модели в WiseBot¶

После обучения и создания образа с моделью необходимо добавить его в docker-compose.yml.

wisebot-model:
  image: <название образа>
  container_name: wisebot-model
  restart: always
  labels:
    - 'com.centurylinklabs.watchtower.enable=true'

wisebot-model-watchtower:
  image: containrrr/watchtower
  container_name: wisebot-model-watchtower
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock
  command: --interval 30 --label-enable

wisebot-model: предоставляет модель.
wisebot-model-watchtower: автоматически обновляет образ wisebot-model при изменении в реестре образов GitLab.

Запустите эти образы командой:

docker-compose up -d wisebot-model wisebot-model-watchtower

Отредактируйте настройки WiseBot (Настройки → Конечные точки) и добавьте следующие строки, заменив необходимые параметры:

models:
  url: <http-адрес модели>
  wait_time_between_pulls: 60

Настройки моделей в WiseBot

Перезапустите один из образов командой:

docker-compose stop wisebot-rasa
docker-compose up -d wisebot-rasa

Обучение моделей с использованием GPU¶

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

Установка драйверов для GPU NVIDIA¶

Установка драйверов для GPU является важным этапом. Подробные инструкции доступны в официальной документации. Установка CUDA не обязательна.

Установка NVIDIA Container Toolkit¶

NVIDIA Container Toolkit позволяет управлять доступом к графическим ресурсам и GPU, обеспечивая оптимальную производительность при работе с графическими интерфейсами внутри контейнера. Это расширение для Docker позволяет запускать контейнеры с использованием GPU и предоставляет доступ к драйверам и библиотекам Nvidia. Благодаря этому разработчики и исследователи могут обучать нейронные сети, выполнять рендеринг 3D графики и решать другие задачи, требующие мощного аппаратного обеспечения, непосредственно внутри контейнеров.

Подробности об установке доступны в официальной документации.

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

sudo docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

Конфигурация GitLab Runner для использования GPU¶

Для использования GPU при сборке образа модели необходимо настроить GitLab Runner. В зависимости от способа установки и запуска конфигурация может различаться. Подробнее об этом можно прочитать в официальной документации.

Работа с вебхуками¶

Вебхуки¶

Вебхуки в проекте WiseBot позволяют взаимодействовать с вашим Rasa проектом через HTTP-запросы. Ниже приведено описание доступных вебхуков:

Загрузить файл
Принимает HTTP POST запросы для загрузки файлов в проект WiseBot. Поддерживаемые типы файлов: аудио, изображения, модели NLU и диалоги из других источников.
Перезапуск Rasa
Принимает HTTP POST запросы для перезапуска сервера Rasa. Полезно для применения изменений в настройках или конфигурации без полного перезапуска сервера.
Удалить файл
Принимает HTTP DELETE запросы для удаления файлов из проекта WiseBot. Укажите путь к файлу в теле запроса.
Развернуть проект
Принимает HTTP POST запросы для развертывания проекта WiseBot. Все внесенные изменения будут развернуты на сервере Rasa.
Сообщить о сбое
Принимает HTTP POST запросы для отправки отчетов об ошибках из проекта WiseBot. Помогает отслеживать и устранять проблемы в процессе разработки.
Посттренинг
Принимает HTTP POST запросы для запуска процесса обучения модели NLU и диалогов в проекте WiseBot. Обучение происходит на основе новых данных или изменений.

Каждый вебхук обеспечивает взаимодействие с проектом WiseBot через стандартные HTTP методы (POST и DELETE), обеспечивая гибкость в управлении файлами, развертывании проекта, отчетах об ошибках и обучении модели.

Работа с reCAPTCHA¶

Настройка Google reCAPTCHA¶

Для защиты вашего сайта от спама и злоупотреблений рекомендуется настроить Google reCAPTCHA. Следуйте следующим шагам:

Регистрация сайта в Google reCAPTCHA¶

Перейдите на официальный сайт reCAPTCHA.
Нажмите кнопку "Admin Console" в правом верхнем углу.

Консоль администратора reCAPTCHA

Войдите в аккаунт Google или создайте новый.
В форме регистрации нового сайта введите:
Имя проекта: Название вашего проекта.
Тип reCAPTCHA: Выберите reCAPTCHA v2.
Домен: Укажите домен вашего сайта.
Нажмите "Submit" для завершения регистрации.

Форма регистрации reCAPTCHA

После регистрации вы получите Site Key и Secret Server Key.

Внедрение reCAPTCHA на сайт¶

В админ-панели вашего сайта перейдите в раздел "Администрирование" > "Общие настройки" > "Безопасность".

Настройки безопасности

Вставьте полученные Site Key и Secret Server Key в соответствующие поля для настройки reCAPTCHA.

После выполнения этих шагов ваш сайт будет защищен от спама и злоупотреблений с помощью Google reCAPTCHA.

"Безопасность".

reCAPTCHA

5. Приложения¶

Приложение 1. Пример файла основного `.gitlab-ci.yml`¶

stages:
    - build
    - push
    - test

before_script:
    - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY

Build base:
    stage: build
    tags:
        - botya-runner
    only:
        variables:
            - $BUILD_BASE == "true"
    script:
        - docker pull $CI_REGISTRY_IMAGE:base || true
        - >
            docker build
            --pull
            --cache-from $CI_REGISTRY_IMAGE:base
            --tag $CI_REGISTRY_IMAGE:base
            -f Dockerfile-base
            .
        - docker push $CI_REGISTRY_IMAGE:base

Build latest:
    stage: build
    tags:
        - botya-runner
    only:
        variables:
            - $BUILD_RELEASE == "false" && $BUILD_BRANCH_NAME != "" && $BUILD_BRANCH_NAME != "main"
    before_script:
        - nvidia-smi
        - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY
        - export BUILD_VERSION=${BUILD_BRANCH_NAME}-$(date +%Y-%m-%d-%H%M)
    script:
        - echo "Building and pushing $BUILD_VERSION version for $BUILD_BRANCH_NAME branch"
        - docker build --no-cache --tag $CI_REGISTRY_IMAGE:$BUILD_VERSION --build-arg BRANCH_NAME=$BUILD_BRANCH_NAME .
        - docker push $CI_REGISTRY_IMAGE:$BUILD_VERSION
        - docker rmi $CI_REGISTRY_IMAGE:$BUILD_VERSION
        - echo BUILD_VERSION=$BUILD_VERSION >> build.env
    artifacts:
        reports:
            dotenv: build.env

Push latest:
    stage: push
    tags:
        - botya-runner
    only:
        variables:
            - $BUILD_RELEASE == "false" && $BUILD_BRANCH_NAME != "" && $BUILD_BRANCH_NAME != "main"
    variables:
        GIT_STRATEGY: none
    before_script:
        - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY
        - export LATEST_VERSION=${BUILD_BRANCH_NAME}-latest
    script:
        - echo "Pulling and pushing $LATEST_VERSION version for $BUILD_BRANCH_NAME branch"
        - docker pull $CI_REGISTRY_IMAGE:$BUILD_VERSION
        - docker tag $CI_REGISTRY_IMAGE:$BUILD_VERSION $CI_REGISTRY_IMAGE:$LATEST_VERSION
        - docker push $CI_REGISTRY_IMAGE:$LATEST_VERSION
        - docker rmi $CI_REGISTRY_IMAGE:$BUILD_VERSION $CI_REGISTRY_IMAGE:$LATEST_VERSION

Push release:
    stage: push
    tags:
        - botya-runner
    only:
        variables:
            - $BUILD_RELEASE == "true" && $BUILD_BRANCH_NAME != "" && $BUILD_BRANCH_NAME != "main"
    variables:
        GIT_STRATEGY: none
    before_script:
        - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY
        - export LATEST_VERSION=${BUILD_BRANCH_NAME}-latest
        - export RELEASE_VERSION=${BUILD_BRANCH_NAME}-release
    script:
        - echo "Creating release $LATEST_VERSION version for $BUILD_BRANCH_NAME branch"
        - docker pull $CI_REGISTRY_IMAGE:$LATEST_VERSION
        - docker tag $CI_REGISTRY_IMAGE:$LATEST_VERSION $CI_REGISTRY_IMAGE:$RELEASE_VERSION
        - docker push $CI_REGISTRY_IMAGE:$LATEST_VERSION
        - docker rmi $CI_REGISTRY_IMAGE:$RELEASE_VERSION $CI_REGISTRY_IMAGE:$LATEST_VERSION

Приложение 2. Пример файла `.gitlab-ci.yml` для веток с обучающими данными¶

trigger_build_model:
    stage: build
    tags:
        - botya-runner
    variables:
        GIT_STRATEGY: none
    only:
        variables:
            - $CI_COMMIT_MESSAGE !~ /release/i && $CI_COMMIT_MESSAGE !~ /ci skip/i
    script:
        - |
            curl -X POST --fail --form token=<token> --form ref=main \
            --form 'variables[BUILD_RELEASE]=false' --form 'variables[BUILD_BRANCH_NAME]=<branch>' \
            <trigger-url>

trigger_release:
    stage: build
    tags:
        - botya-runner
    variables:
        GIT_STRATEGY: none
    only:
        variables:
            - $CI_COMMIT_MESSAGE =~ /release/i && $CI_COMMIT_MESSAGE !~ /ci skip/i
    script:
        - |
            curl -X POST --fail --form token=<token> --form ref=main \
            --form "variables[BUILD_RELEASE]=true" --form "variables[BUILD_BRANCH_NAME]=<branch>" \
            <trigger-url>

Приложение 3. `Dockerfile` базового контейнера (под именем `Dockerfile-base`)¶

FROM registry.digtlab.ru/kassistant/wisebot-datasets:cuda-10.1-cudnn7-runtime-ubuntu18.04
ENV WISEBOT_PATH=/app/wisebot

RUN mkdir -p $WISEBOT_PATH
RUN apt update && \
apt install -y software-properties-common git mc curl && \
add-apt-repository -y ppa:deadsnakes/ppa && \
apt update && \
apt install -y python3.8 python3.8-dev && \
update-alternatives --install /usr/bin/python python /usr/bin/python3.8 10 && \
apt install -y python3-pip && \
python -m pip install --upgrade pip

RUN pip install git+https://github.com/botfront/rasa-for-botfront pypred sgqlc protobuf==3.20.*
RUN git clone --depth 1 https://github.com/botfront/rasa-for-botfront /app/rasa-for-botfront
RUN cp -R /app/rasa-for-botfront/rasa_addons /usr/local/lib/python3.8/dist-packages
RUN rm -r /app/rasa-for-botfront
RUN rasa telemetry disable

WORKDIR $WISEBOT_PATH
CMD ["/bin/bash"]

Приложение 4. `Dockerfile` контейнера, используемого для обучения (под именем `Dockerfile`)¶

# Train stage
FROM registry.digtlab.ru/kassistant/wisebot-datasets:base as train
ENV PYTHONPATH=/custom_components

RUN mkdir $PYTHONPATH
RUN git clone --depth 1 <rasa-custom-components-url> -b main $WISEBOT_PATH/rasa-custom-components
RUN cp -r $WISEBOT_PATH/rasa-custom-components/custom_components/. $PYTHONPATH/
RUN rm -r $WISEBOT_PATH/rasa-custom-components
RUN pip install python-Levenshtein

ARG BRANCH_NAME=marsu
RUN git clone --depth 1 <datasets-url>-b $BRANCH_NAME $WISEBOT_PATH
RUN rasa train --debug --fixed-model-name default 2>&1 | tee logs.txt

# Deploy stage
FROM flashspys/nginx-static
COPY --from=train /app/wisebot/models/default.tar.gz /static/default
COPY --from=train /app/wisebot/logs.txt /static/logs.txt
EXPOSE 80
STOPSIGNAL SIGTERM
CMD ["nginx", "-g", "daemon off;"]