NAV
Input Output

Contract: анализатор документов

Contract by Embedika — решение для анализа и проверки документов на риски. Помогает быстро и эффективно выделять нежелательные условия в тексте документа и предлагает рекомендации по их устранению.

Архитектурные решения

Записи об архитектурных решениях, реализованных в Contract.

Продуктивизация

Context

Цель: поставлять продукт любому заказчику без дополнительных затрат времени на разработку.

Considered Options

  1. Вынести алгоритмы обработки рисков под каждого заказчика в отдельный jar-файл и подключать в зависимости от проекта.
    • В итоги пришли к универсальному алгоритму под все риски, из-за чего необходимость вынесения алгоритмов отдельно отпала.
  2. Вынести общий код сервиса в библиотеку, создавать на её основе реализацию сервиса под каждого заказчика.
    • Сложно поддерживать большое количество сервисов.
    • Нельзя просто развернуть один из сервисов у нового заказчика, т. к. он содержит кастом.
  3. Один универсальный сервис, который содержит в себе реализации под всех заказчиков, выбирать нужную настройками окружения.
    • Размер сервиса будет неограниченно возрастать и занимать лишнее место, т. к. использоваться будет только одна реализация.
    • Сложно поддерживать код, т. к. реализации начинают пересекаться внутри сервиса, отделить их будет большой проблемой.
  4. Один универсальный сервис, но весь кастом под заказчика выносится из исходного кода сервиса наружу.
    • Используется универсальный формат конфигов, которые понятны и могут поддерживаться не только программистами.
    • Конфиги + модели под конкретного заказчика нужно собирать в отдельный образ для облегчения развертывания.

Decision

Выполняем один универсальный сервис: risk-checker. Выносим кастомизацию под нужды заказчика в Json-файлы конфигурации.

Реализован перенос данных из Json во внешние сервисы и собственную БД путем выполнения Liquibase-миграции. Чтение Json выполняется из файлового хранилища S3.

Перед запуском сервиса должна выполняться джоба config-pusher (копирует файлы из образа в S3). Для контроля актуальности данных используется файл version с номером релиза - и в коде сервиса, и в S3 номера релиза должны совпадать (миграция упадет при несовпадении).

Positive Consequences

Negative Consequences

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

Context

Для работы анализатора нужно загрузить первоначальные данные в систему (требования чек-листа, риски, сущности, модели, каталоги, группы пользователей, политики, подписки, техконстанты). Набор первоначальных данных определяется требованиями заказчика и берется из Json-файлов ( см. Продуктивизация).

Considered Options

  1. Загрузка данных командой.
    • На каждую разновидность объекта нужна отдельная команда на импорт и интерфейс для её выполнения.
    • Не обеспечивается автоматическое развертывание, необходимое для некоторых объектов (группы и политики).
    • Нужна инструкция для админа с порядком импорта.
    • Некоторые миграции зависят друг от друга и не могут выполняться раздельно, а делать одновременный импорт из разных файлов сложно.
  2. Миграция Verdi (ExternalMigration) - механизм, встроенный в шаблон сервиса Verdi.
    • Выполняется при каждом перезапуске сервиса, хотя достаточно один раз при развертывании релиза (лишняя нагрузка, замедление запуска, вопросы от техподдержки).
    • Для каждой миграции нужно придумывать свой механизм вычисления needExecution из-за разной архитектуры API сервисов.
    • Не понятно, выполнилась миграция или нет, т. к. нет чейнджлога.
    • Сервис запускается и работает, даже если упала миграция.
  3. Миграция Liquibase:
    • Сервис не будет запущен, если упала миграция, что гарантирует обновление всех данных.
    • В таблице databasechangelog отображаются выполенные миграции.
    • Удалением из databasechangelog можно инициировать перезапуск миграции при необходимости.

Decision

Миграции импорта кастомизации под заказчика используют Liquibase. Для удобства они имеют схожую структуру и наследуются от трейта SystemImport. Перезапуск миграции из кода инициируется изменением номера задачи в названии Changeset / имени автора.

Positive Consequences

Negative Consequences

Статусная модель задач Marker

Context

Цель: изменения статусной модели задач, которые периодически происходят, должны выполняться безболезненно для разработки. В идеале, переходы по статусам должны настраиваться пользователем (по аналогии с таск-трекерами).

Considered Options

  1. В исходной реализации статусы и их переходы были захардкожены на фронте и на бэке. Гибко настраивать статусную модель при таком подходе невозможно - на каждое изменение нужно привлекать разработчиков.
  2. Обобщенный механизм обработки статусов в Маркере. Описание статусной модели скомпоновать в Json, реализовать обработку и хранение статусов с БД Маркера. По сути, данный функционал уже реализован в сервисе sed-route.
  3. Использовать для хранения статусов сервис маршрутов (sed-route). Описание статусной модели скомпоновать в Json, и переносить эти данные в sed-route с помощью миграции.

Decision

Используем для хранения статусной модели сервис маршрутов (sed-route). Он представляет собой справочник для маршрутов, на основе которого удобно реализовать бизнес-логику перемещения по статусам, благодаря заложенной в сервис возможности фильтрации, в т. ч. и по произвольным полям в data.

Positive Consequences

Negative Consequences

marker-service: сервис разметчика

Сервис для подготовки обучающей выборки. Сервис позволяет пользователям размечать данные документов и проверять корректность разметки других пользователей. На основе результатов разметки есть возможность сгенерировать модели машинного обучения с помощью ML-сервиса autoMl.

Сервис разбит на несколько модулей, в виде sbt проектов:

Локальный запуск сервиса разметчика

При запуске сервиса ожидается, что уже развернута необходимая инфраструктура:

Запуск сервиса разметчика из консоли с помощью SBT

MARKER_DB_HOST=localhost MARKER_DB_PORT=5432 MARKER_DB_NAME=marker MARKER_DB_USER=postgres MARKER_DB_PASSWORD=12345 sbt boot/run

Переменные окружения сервиса разметчика

Все доступные переменные окружения для настройки сервиса разметчика.

Переменная Тип Обязательная Значение по умолчанию Описание
MARKER_HTTP_HOST string нет "0.0.0.0" Хост, на котором слушает HTTP-сервер
MARKER_HTTP_PORT int нет 8192 Порт, на котором слушает HTTP-сервер
MARKER_KAFKA_SERVERS string да "localhost:9092" Адрес Kafka
MARKER_KAFKA_TOPIC string нет "marker_commands" Название кафка-топика для получения команд. Сервис получает кафка-команды по нему, но и также сам публикует это название в CommandDiscovery.
MARKER_KAFKA_CONSUMER_GROUP string нет "marker_consumer_group" Имя consumer-группы для чтения из кафка-топика команд. Не должна меняться и не должна быть пустой, иначе сервис перечитает свои команды при перезапуске.
MARKER_KAFKA_COMMANDEVENT_TOPIC string да "commandevents" Название кафка-топика для отправки сообщений со статусами выполняемых команд. ОБЯЗАТЕЛЬНО должно соответствовать названию этого топика в сервисе статуса команд.
MARKER_KAFKA_ENTITY_OBJECT_EVENT_TOPIC string нет "entityObjectEvent" Название кафка-топика, с событиями об объектах в модели данных
MARKER_KAFKA_PARTITIONS int нет 10 Количество партиций в топике команд.
MARKER_ENTITY_OBJECT_EVENT_KAFKA_PARTITIONS int нет 10 Количество партиций в топике с событиями об объектах в модели данных
MARKER_KAFKA_CONSUMER_RESTART_MIN_BACKOFF duration string нет 1 second Минимальная задержка перед перезапуском.
MARKER_KAFKA_CONSUMER_RESTART_MAX_BACKOFF duration string нет 30 seconds Максимально возможная задержка перед перезапуском.
MARKER_KAFKA_CONSUMER_RESTART_RANDOM_FACTOR double нет 0.2 Величина дополнительной случайной задержки: 0.0 - без случайно задержки, 1.0 - до 100% задрежки.
MARKER_KAFKA_CONSUMER_RESTART_MAX_RESTARTS int нет 5 Максимальное количество перезапусков в заданный период времени.
MARKER_KAFKA_CONSUMER_RESTART_MAX_RESTARTS_WITHIN duration string нет 5 minutes Период времени для ограничения перезапусков.
MARKER_KAFKA_AUTH_USER string да "" Название учетной записи Kafka. Если название не указано, то настройки авторизации не будут применены.
MARKER_KAFKA_AUTH_PASSWORD string да "" Пароль учетной записи Kafka.
MARKER_KAFKA_AUTH_PRINCIPAL string нет "" Principal учетной записи Kafka в Kerberos(в случае соединения с kafka через Kerberos).
MARKER_KAFKA_AUTH_KEYTAB_PATH string нет "" Путь до keytab-файла(в случае соединения с kafka через Kerberos).
MARKER_KAFKA_AUTH_TRUSTSTORE_LOCATION string нет "" Путь до хранилища сертификатов (Java key store). Если путь не указан, то сертификат применятся не будет.
MARKER_KAFKA_AUTH_TRUSTSTORE_PASSWORD string нет "" Пароль к харнилищу сертификатов.
MARKER_KAFKA_AUTH_MODE string нет "static" Режим аутентификации: static - одна учетная запись на все запросы, mapping - учетная запись зависит от запроса
MARKER_KAFKA_AUTH_CONFIG string нет "" Настройки для аутентификации
MARKER_KAFKA_AUTH_CACHE_SIZE int нет Максимальный размер кеша для Kafka producer (количество активных соединений).
MARKER_KAFKA_AUTH_CACHE_TTL duration string нет Время жизни Kafka producer в кеше.
MARKER_CONSUL_ADDR url string да "http://localhost:8500" Адрес Сonsul.
MARKER_CONSUL_AUTH_USER string да "" Название учетной записи Сonsul. Если название не указано, то настройки авторизации не будут применены.
MARKER_CONSUL_AUTH_PASSWORD string да "" Пароль учетной записи Сonsul.
MARKER_TRACE_DURATION boolean нет false Признак необходимости трассировки выполнения команд
MARKER_DISCOVERABLE_ID string нет "another_marker_instance" ID сервиса в ServiceDiscovery
MARKER_DISCOVERABLE_NAME string нет "marker" Имя сервиса в ServiceDiscovery
MARKER_DISCOVERABLE_HOST string да "localhost" Хост, публикуемый в ServiceDiscovery. По нему на данный сервис будут обращаться другие через HTTP. Указанный адрес должен быть виден другим сервисам. Пример: имя kubernetes/docker_swarm service
MARKER_DISCOVERABLE_PORT int нет Порт, публикуемый в ServiceDiscovery. По нему на данный сервис будут обращаться другие через HTTP. По умолчанию указывается порт, который слушает HTTP-сервер.
MARKER_DISCOVERABLE_LIVETIME duration string нет 2 minutes Период после последней отправки health check, в течение которого ServiceDiscovery считает данный сервис живым.
MARKER_DISCOVERABLE_HEALTHPASS string нет 1 minute Периодичность отправки health check в ServiceDiscovery
MARKER_AKKA_HTTP_CLIENT_MAXCON int нет 512 Максимальное число одновременных исходящих HTTP-соединений
MARKER_AKKA_HTTP_CLIENT_MAXREQ int нет 1024 Максимальное число одновременных исходящих HTTP-запросов
MARKER_AKKA_HTTP_HOST_CONN_POOL_IDLE_TIMEOUT duration string нет 10 minutes Максимальное время жизни пула соединений (с каким-либо сервисом) при отсутствии исходящих соединений
MARKER_AKKA_HTTP_HOST_CONN_POOL_CLIENT_IDLE_TIMEOUT duration string нет 10 minutes Позволяет отдельно настроить максимальное время на исходящий http-запрос, использующий пул соединений (т.е. для синхронной отправки синхронной команды)
MARKER_AKKA_HTTP_CLIENT_IDLE_TIMEOUT duration string нет 10 minutes Максимальное время на исходящий http-запрос (в какой-либо сервис)
MARKER_AKKA_HTTP_SERVER_MAXCON int нет 1024 Максимальное число одновременных входящих HTTP-соединений
MARKER_AKKA_HTTP_SERVER_IDLE_TIMEOUT duration string нет 11 minutes Максимальное время жизни входящего http-соединения
MARKER_AKKA_HTTP_SERVER_REQUEST_TIMEOUT duration string нет 10 minutes Максимальное время обработки входящего http-запроса. Должно быть не больше предыдущего значения, иначе входящее соединение оборвется по таймауту времени жизни запроса
MARKER_INTERNALCMD_ALLOW bool нет true Можно ли сервису отправлять внутрисистемные команды
MARKER_HEALTH_TIMEOUT duration string нет 5 seconds Максимальное время ожидания ответа health check
MARKER_SENDERLIB_COMMANDS_CACHE_UPDATEPERIOD duration string нет 10 minutes Время кэширования данных по командам из CommandDiscovery
MARKER_SENDERLIB_SERVICES_CACHE_UPDATEPERIOD duration string нет 30 seconds Время кэширования данных по сервисам из ServiceDiscovery
MARKER_DB_HOST string да Хост БД
MARKER_DB_PORT int да Порт БД
MARKER_DB_NAME string да Имя базы в БД
MARKER_DB_URL jdbc url string нет JDBC-url для соединения с БД. По умолчанию собирается из других обязательных переменных. Можно указать только его, если не хочется отдельно указывать хост/порт/имя базы.
MARKER_DB_USER string да Пользователь БД
MARKER_DB_PASSWORD string да Пароль пользователя БД
MARKER_FS_URI url string нет http://localhost:9000 Адрес для подключения к Minio
MARKER_FS_ACCESS_KEY_ID string нет "minioadmin" Ключ доступа к хранилищу файлов Minio (aka пользователь)
MARKER_FS_SECRET_ACCESS_KEY string нет "minioadmin" Секретный код доступа к хранилищу файлов Minio (aka пароль)
MARKER_FS_UPLOAD_PARALLELISM int нет 4 Максимально возможный параллелизм при загрузке файлов в хранилище
MARKER_FS_AUTH_MODE string нет static Режим аутентификации: static - одна учетная запись на все запросы, mapping - учетная запись зависит от запроса
MARKER_FS_AUTH_CONFIG string нет "" Настройки для аутентификации: если AuthMode = mapping, то необходим JSON с маппингом учетных записей
MARKER_FS_CACHE_SIZE int нет 1 Максимальный размер кеша клиентов для хранилища файлов (количество активных соединений).
MARKER_FS_CACHE_TTL duration string нет Время жизни клиента в кеше
MARKER_TEMP_BUCKET string нет "temp" Название бакета в Minio, в котором сохраняются временные файлы
MARKER_LABELING_BUCKET string нет "labeling" Название бакета в Minio, в котором сохраняются файлы экспорта разметки
MARKER_PROJECT_INSTRUCTION_BUCKET string нет "instruction" Название бакета в Minio, в котором хранятся файлы инструкций
MARKER_FS_MODELS_BUCKET string нет "models" Название бакета в Minio, в котором сохраняются файлы моделей
MARKER_FS_METRICS_BUCKET string нет "metrics" Название бакета в Minio, в котором сохраняются файлы метрик
MARKER_ADDITIONAL_FIELDS_PDF_VIEW string нет "extractedText" Ключ, под которым сервис индексации сохраняет результаты извлечения json из pdf
MARKER_FEATURES_MODE string нет "default" Режим работы: default - без обучения, learning - с обучением моделей
MARKER_SERVICE_NAME string нет "marker" Читаемое имя сервиса
MARKER_SERVICE_DESCRIPTION string нет "Сервис разметчика" Читаемое описание сервиса
MARKER_CUSTOM_CHANGE_MIGRATIONS_TIMEOUT duration string нет 3 minutes Максимальное время выполнения одной миграции customChange
MARKER_AUTOML_TRAIN_MODEL_URI url string нет http://localhost:1030/train RnD: http эндпоинт сервиса обучения моделей
MARKER_AUTOML_SOFT_RESTART_URI url string нет http://localhost:1031/soft_restart RnD: http эндпоинт для остановки обучения
MARKER_KAFKA_CONNECTION_CHECK_TEST_MESSAGES_INTERVAL duration string нет 4 minutes Применяется только для producer-ов со способом аутентификации kerberos. Интервал отправки тестовых сообщений кафки в топик connectionCheck.testMessagesTopicName. Тестовые сообщения (null, service producer test) отправляются регулярно с этим интервалом.
MARKER_KAFKA_CONNECTION_CHECK_INTERVAL duration string нет 60 seconds Применяется только для producer-ов со способом аутентификации kerberos. Интервал проверки того, сколько тестовых сообщений было отправлено за данный период. Если количество сообщений за этот период равно количеству сообщений за прошлый период, то начинается отсчет периода без сообщений.
MARKER_KAFKA_CONNECTION_CHECK_FAILED_AFTER_INTERVAL duration string нет 5 minutes Применяется только для producer-ов со способом аутентификации kerberos. Максимальная продолжительность периода без успешно отправленных тестовых сообщений. По ее достижении сервис будет объявлен больным.

Команды сервиса разметчика

В сервисе предусмотрены следующие команды:

Название команды EntityType Actions
—Проект—
Создать проект Project Marker_EditProject
Обновить проект Project Marker_EditProject
Обновить статус проекта Project Marker_EditProject
Удалить проект Project Marker_EditProject
Добавить файлы в проект Project Marker_EditProject
Получить проект Project Marker_ViewProjects
Получить статистику проекта Project Marker_ViewProjects
Получить список проектов Project Marker_ViewProjects
Список настроек сущностей с полем Project Marker_ViewProjects
Список всех уникальных настроек выделения сущностей Project Marker_ViewProjects
Список всех уникальных настроек классификации Project Marker_ViewProjects
Получить статистику по спанам проекта Project Marker_ViewProjects
Получение статистики проекта без учета пользователя Project Marker_ViewProjects
Получить список проектов со статистикой Project Marker_ViewProjects
—Именованная сущность—
Получить статистику по сущностям NerSetting Marker_ViewProjects
—Документ—
Получить конкретный документ в проекте Document Marker_ViewProjects
Список документов проекта Document Marker_ViewProjects
Обновить разметку документа Task Marker_EditProject
—Задача—
Получение данных задачи по ID Task Marker_ViewProjects
Создать задачи Task Marker_EditProject
Удалить задачи Task Marker_EditProject
Обновить задачи Task Marker_EditProject
Обновить статусы у задач Task Marker_EditProject
Список задач Task Marker_ViewProjects
Список задач проекта для текущего пользователя Task Marker_ViewProjects
Список задач проекта Task Marker_ViewProjects
Список задач с разметкой Task Marker_ViewProjects
Позиция задачи в списке Task Marker_ViewProjects
—Пользователь—
Добавить пользователей в проект User Marker_EditProject
Удалить пользователей из проекта User Marker_EditProject
Получить список пользователей, назначенных на разметку документов User Marker_ViewProjects
Получить проекты по пользователям User Marker_ViewProjects
Получить список пользователей в проекте User Marker_ViewProjects
—Разметка—
Экспортировать разметку Labeling Marker_ViewMarker
Список разметок в статусе 'Завершено' Labeling Marker_ViewMarker
Импорт разметки в формате RnD Labeling Marker_ViewMarker
Удаление разметки в формате RnD Labeling Marker_ViewMarker
—Обучение—
Запустить обучение Learning Marker_ViewLearning
Остановить обучение Learning Marker_ViewLearning
Список обучений Learning Marker_ViewLearning

Сервис публикует события для следующих уведомлений:

Код уведомления EntityType Описание
EntityCreated NerSetting Создана настройка выделения сущностей
ProjectCreated Project Создан проект разметки
EntityAddedToProject NerSetting Сущность добавлена в проект
LearningStarted NerSetting Запущено обучение по сущности
LearningFinished NerSetting Завершено обучение по сущности
ProjectInWork Project Проект передан в работу
ProjectCompleted Project Проект завершен

—Проект—

CreateProject

На входе свойства и перечень настроек создаваемого проекта / На выходе ID созданного проекта

{
  "title": "Проект Пандора",
  "startDate": 1648114231,
  "endDate": 1648114231,
  "instruction": "Берешь и размечаешь, чего думать-то",
  "instructionUrl": "temp/e3e3e3e3-e3e3-e3e3-e3e3-e3e3e3e3e3e3",
  "labelingType": "labelingType_classification",
  "nerSettings": [
    {
      "title": "Город",
      "selectionColor": "#783f13",
      "showInDocList": true,
      "nerHint": "размечай обдумывая",
      "minLabelingCount": 10,
      "attributes": [
        {
          "title": "Тип",
          "classificationAction": "classificationAction_fromList",
          "optionsList": [
            "райцентр",
            "поселок",
            "деревня"
          ],
          "showInDocList": true
        }
      ],
      "subNers": [
        {
          "title": "Город",
          "selectionColor": "#783f13",
          "attributes": [
            {
              "title": "Тип",
              "classificationAction": "classificationAction_fromList",
              "optionsList": [
                "райцентр",
                "поселок",
                "деревня"
              ],
              "showInDocList": true
            },
            {
              "title": "Описание города",
              "classificationAction": "classificationAction_fromList",
              "maxLength": 250,
              "classificationHint": "описывайте тезисно, без фанатизма",
              "showInDocList": true
            }
          ]
        }
      ]
    },
    {
      "title": "Телефон",
      "selectionColor": "#8b10ad"
    }
  ],
  "classificationSettings": [
    {
      "title": "Город",
      "classificationAction": "classificationAction_fromList",
      "optionsList": [
        "Москва",
        "Казань",
        "Омск"
      ],
      "classificationHint": "Выбирайте правильно!",
      "minLabelingCount": 10,
      "showInDocList": true
    }
  ],
  "docsPerTask": 10,
  "markupSuggesters": [
    "userRole_expert",
    "userRole_marker"
  ]
}

"db77be48-6ffb-4d8f-983a-c20411043e10"

Создание нового проекта. Подсущности подсущностей не обрабатываются текущей реализацией сервиса.

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

Команда Путь
marker_createProject Kafka Topic "marker_commands"

UpdateProject

На входе свойства обновляемого объекта, включая ID и версию / На выходе признак успешности

{
  "id": "662d697d-c037-474e-8f18-5736f992f7ff",
  "version": 2,
  "title": "Проект Пандора",
  "startDate": 1648114231,
  "endDate": 1648114231,
  "instruction": "Берешь и размечаешь, чего думать-то",
  "instructionUrl": "temp/e3e3e3e3-e3e3-e3e3-e3e3-e3e3e3e3e3e3",
  "labelingType": "labelingType_ner",
  "nerSettings": [
    {
      "title": "Город",
      "selectionColor": "#8b10ad",
      "showInDocList": true,
      "nerHint": "размечай обдумывая",
      "minLabelingCount": 10,
      "attributes": [
        {
          "title": "Тип",
          "classificationAction": "classificationAction_fromList",
          "optionsList": [
            "столица",
            "райцентр",
            "поселок",
            "деревня"
          ],
          "showInDocList": true,
          "minLabelingCount": 10
        }
      ],
      "subNers": [
        {
          "title": "Город",
          "selectionColor": "#783f13",
          "showInDocList": true,
          "nerHint": "размечай обдумывая",
          "minLabelingCount": 10,
          "attributes": [
            {
              "title": "Тип",
              "classificationAction": "classificationAction_fromList",
              "optionsList": [
                "райцентр",
                "поселок",
                "деревня"
              ],
              "showInDocList": true
            },
            {
              "title": "Описание города",
              "classificationAction": "classificationAction_fromList",
              "maxLength": 250,
              "classificationHint": "описывайте тезисно, без фанатизма",
              "showInDocList": true
            }
          ]
        }
      ]
    }
  ],
  "docsPerTask": 10,
  "markupSuggesters": [
    "userRole_expert",
    "userRole_observer"
  ]
}

true

Обновление проекта. Подсущности подсущностей не обрабатываются текущей реализацией сервиса.

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

Команда Путь
marker_updateProject Kafka Topic "marker_commands"

UpdateProjectStatus

На входе новый статус проекта, а также его ID и версия / На выходе признак успешности

{
  "id": "db77be48-6ffb-4d8f-983a-c20411043e10",
  "projectStatus": "projectStatus_draft",
  "version": 2
}

true

Обновление статуса проекта

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

Команда Путь
marker_updateProjectStatus Kafka Topic "marker_commands"

DeleteProject

На входе ID проекта / На выходе результат удаления

"db77be48-6ffb-4d8f-983a-c20411043e10"

true

Удаление проекта по ID

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

Команда Путь
marker_deleteProject Kafka Topic "marker_commands"

AddFilesToProject

На входе ID проекта и список ID файлов / На выходе ссылки для скачивания добавленных файлов

{
  "projectId": "db77be48-6ffb-4d8f-983a-c20411043e10",
  "fileIds": [
    "f11614f5-0c78-4408-84a9-a1e68aac6dca",
    "24aff3d7-200b-4b1b-b70e-8e9e19a519a0"
  ]
}

[
  "temp/5192b9e8-8b67-4cba-b6b0-6317d4d5863c",
  "temp/1cf4fd4b-f33a-4c0f-be0e-5f9ea65bcbf9"
]

Добавление указанных файлов в проект

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

Команда Путь
marker_addFilesToProject Kafka Topic "marker_commands"

GetProject

На входе ID проекта / На выходе свойства проекта и список настроек разметки

"db77be48-6ffb-4d8f-983a-c20411043e10"

{
  "id": "0a25b8ad-0734-4b6b-a1b7-5005db0cb813",
  "title": "Проект Пандора",
  "created": 1653305248400,
  "startDate": 1648114231,
  "endDate": 1648114231,
  "instruction": "Берешь и размечаешь, чего думать-то",
  "labelingType": "labelingType_classification",
  "projectStatus": "projectStatus_draft",
  "documentEntityType": "DocForbWpsVi-iTNSTHn7ZRzJYlQ",
  "nerSettings": [
    {
      "id": "nerField1",
      "projectIds": [
        "0a25b8ad-0734-4b6b-a1b7-5005db0cb813"
      ],
      "title": "Город",
      "selectionColor": "#783f13",
      "showInDocList": true,
      "nerHint": "размечай обдумывая",
      "minLabelingCount": 10,
      "attributes": [
        {
          "id": "nerField1_Attribute1",
          "projectIds": [
            "0a25b8ad-0734-4b6b-a1b7-5005db0cb813"
          ],
          "title": "Тип",
          "classificationAction": "classificationAction_fromList",
          "optionsList": [
            "райцентр",
            "поселок",
            "деревня"
          ],
          "showInDocList": true
        }
      ],
      "subNers": [
        {
          "id": "nerField1SubNer3",
          "projectIds": [
            "0a25b8ad-0734-4b6b-a1b7-5005db0cb813"
          ],
          "title": "Город",
          "selectionColor": "#783f13",
          "showInDocList": true,
          "nerHint": "размечай обдумывая",
          "minLabelingCount": 10,
          "attributes": [
            {
              "id": "nerField1SubNer3Attribute1",
              "projectIds": [
                "0a25b8ad-0734-4b6b-a1b7-5005db0cb813"
              ],
              "title": "Тип",
              "classificationAction": "classificationAction_fromList",
              "optionsList": [
                "райцентр",
                "поселок",
                "деревня"
              ],
              "showInDocList": true
            },
            {
              "id": "nerField1SubNer3Attribute2",
              "projectIds": [
                "0a25b8ad-0734-4b6b-a1b7-5005db0cb813"
              ],
              "title": "Описание города",
              "classificationAction": "classificationAction_fromList",
              "maxLength": 250,
              "classificationHint": "описывайте тезисно, без фанатизма",
              "showInDocList": true
            }
          ],
          "subNers": []
        }
      ]
    },
    {
      "id": "nerField2",
      "projectIds": [
        "0a25b8ad-0734-4b6b-a1b7-5005db0cb813"
      ],
      "title": "Телефон",
      "selectionColor": "#8b10ad",
      "attributes": []
    }
  ],
  "classificationSettings": [
    {
      "id": "classificationField1",
      "projectIds": [
        "0a25b8ad-0734-4b6b-a1b7-5005db0cb813"
      ],
      "title": "Город",
      "classificationAction": "classificationAction_fromList",
      "optionsList": [
        "Москва",
        "Казань",
        "Омск"
      ],
      "classificationHint": "Выбирайте правильно!",
      "minLabelingCount": 10,
      "showInDocList": true
    }
  ],
  "version": 1,
  "docsPerTask": 10,
  "markupSuggesters": [
    "userRole_expert",
    "userRole_observer"
  ]
}

Получение проекта по ID

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

Команда Путь
marker_getProject HTTP POST "/v1/projects/get"

GetProjectStatistics

На входе ID проекта / На выходе свойства и статистика проекта

"db77be48-6ffb-4d8f-983a-c20411043e10"

{
  "id": "db77be48-6ffb-4d8f-983a-c20411043e10",
  "title": "TestProject",
  "startDate": 1649146493990,
  "endDate": 1649146493990,
  "projectStatus": "6fae306e-9120-4b84-a79e-530a0be5617c",
  "instructionContent": {
     "fileId": "3e47c8bb-5cc9-4bf0-b1c8-18028c217915"
  },
  "labelingType": "9d08b328-9882-4ea2-bbc9-c44d341e028c",
  "statistics": {
    "taskStatuses": [
      {
        "status": "18388b51-3c31-4530-a76b-24404f32ae3c",
        "count": 0
      },
      {
        "status": "66d92292-10da-48e2-81c7-6189725ed813",
        "count": 1
      },
      {
        "status": "a0305766-bb9d-499a-92a4-a34cc6333355",
        "count": 2
      },
      {
        "status": "25e5128f-7e8b-44d6-b515-d1c0c3e0bf3d",
        "count": 3
      }
    ]
  }
}

Получение статистики проекта по его ID

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

Команда Путь
marker_getProjectStatistics HTTP POST "/v1/projects/getStatistics"

ListProjects

На входе параметры поиска / На выходе свойства проектов

{
  "query": "",
  "context": {},
  "paging": {
    "page": 1,
    "count": 5
  }
}

{
  "items": [
    {
      "id": "9bc7e8c6-f71c-4a53-abc6-222a8a431e84",
      "title": "Test Classification",
      "created": 1649847357350,
      "startDate": 1649146493990,
      "endDate": 1649146493990,
      "labelingType": "labelingType_classification",
      "projectStatus": "projectStatus_draft",
      "version": 1,
      "documentsTotal": 5,
      "participantsTotal": 10
    }
  ],
  "total": 1
}

Получение списка проектов

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

Команда Путь
marker_listProjects HTTP POST "/v1/projects/list"

Доступные поля для фильтрации:

Поле Виды фильтров
id InSetQuery, LikeQuery
title InSetQuery, LikeQuery
status, projectStatus InSetQuery, LikeQuery
labelingType InSetQuery, LikeQuery

Доступные поля для сортировки:

Поле Примечание
title По умолчанию, по возрастанию
created
modified
startDate

ListSettingsByField

На входе поле настроек разметки / На выходе настройки с данным полем

"nerField1"

[
  {
    "id": "nerField1",
    "title": "Животное",
    "projectId": "b0d79c75-82be-4b4d-893e-55f995455e3e"
  },
  {
    "id": "nerField1",
    "title": "Тех. задание",
    "projectId": "b0d79c75-82be-4b4d-893e-55f995455e3e"
  }
]

Возвращает список настроек (NerSetting и ClassificationSetting) в обобщенном виде с запрошенным полем (кодом).

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

Команда Путь
marker_listSettingsByField HTTP POST "/v1/projects/listSettingsByField"

ListAllNerSettings

На входе параметры поиска / На выходе список всех уникальных настроек выделения сущностей

{
  "query": "",
  "context": {},
  "sorting": {
    "fieldName": "title",
    "order": "asc"
  },
  "paging": {
    "page": 1,
    "count": 1
  }
}

{
  "items": [
    {
      "id": "testNerField",
      "projectIds": [
        "9ebbd15c-2be8-4055-a8ed-5d457b36e12c"
      ],
      "title": "Тестовая сущность",
      "selectionColor": "#000000",
      "showInDocList": true,
      "attributes": [],
      "subNers": [
        {
          "id": "testSubNerField",
          "projectIds": [
            "9ebbd15c-2be8-4055-a8ed-5d457b36e12c"
          ],
          "title": "Тестовая подсущность",
          "selectionColor": "#101010",
          "showInDocList": false,
          "attributes": [],
          "subNers": []
        }
      ]
    }
  ],
  "total": 10
}

Возвращает список уникальных сущностей со всеми аттрибутами и подсущностями по всем проектам, не копированных ниоткуда. Уникальность определяется по признаку копирования.

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

Команда Путь
marker_listAllNerSettings HTTP POST "/v1/projects/nerSettings/listAll"

Доступные поля для фильтрации:

Поле Виды фильтров
id InSetQuery, LikeQuery
title InSetQuery, LikeQuery

Доступные поля для сортировки: нет

ListAllClassificationSettings

На входе параметры поиска / На выходе список всех уникальных настроек классификации

{
  "query": "",
  "context": {},
  "sorting": {
    "fieldName": "title",
    "order": "asc"
  },
  "paging": {
    "page": 1,
    "count": 1
  }
}

{
  "items": [
    {
      "id": "testClass",
      "projectIds": [
        "0201a55f-50e3-45de-acdb-86e294e3ec8d"
      ],
      "title": "Тестовая классификация",
      "classificationAction": "classificationAction_fromList4",
      "optionsList": [
        "раз",
        "два",
        "три"
      ],
      "showInDocList": true
    }
  ],
  "total": 10
}

Возвращает список уникальных настроек классификации по всем проектам, не копированных ниоткуда. Уникальность определяется по признаку копирования.

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

Команда Путь
marker_listAllClassificationSettings HTTP POST "/v1/projects/classificationSettings/listAll"

Доступные поля для фильтрации:

Поле Виды фильтров
id InSetQuery, LikeQuery
title InSetQuery, LikeQuery

Доступные поля для сортировки: нет

GetProjectFields

На входе параметры поиска (поддерживается только пагинация) / На выходе статистика по спанам проекта

{
   "query": "",
   "context": {},
   "paging": {
      "page": 1,
      "count": 10
   }
}

{
   "items": [
      {
         "id": "db77be48-6ffb-4d8f-983a-c20411043e10",
         "title":  "Проект 1",
         "startDate": 1649146493990,
         "endDate": 1649146493990,
         "projectStatus": "db77be48-6ffb-4d8f-983a-c20411043e10",
         "labelingType": "db77be48-6ffb-4d8f-983a-c20411043e10",
         "taskCount": 10,
         "nerSettings": [
            {
               "field": "nerField1",
               "title": "Город",
               "selectionColor": "#783f13",
               "showInDocList": true,
               "nerHint": "размечай обдумывая",
               "minLabelingCount": 10,
               "attributes": [],
               "subNers": [
                  {
                     "field": "nerField1SubNer3",
                     "title": "Город",
                     "selectionColor": "#783f13",
                     "showInDocList": true,
                     "nerHint": "размечай обдумывая",
                     "minLabelingCount": 10,
                     "subNers": []
                  }
               ]
            }
         ],
        "spanCounts": [
           {
              "field": "nerField1",
              "count": 3
           }
        ]
      }
   ],
   "total": 1
}

Получение статистики по спанам проекта

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

Команда Путь
marker_getProjectFields HTTP POST "/v1/projects/getFields"

Доступные поля для фильтрации: аналогично marker_listProjects.

Доступные поля для сортировки: аналогично marker_listProjects.

GetFullProjectStatistics

На входе ID проекта / На выходе статистика проекта

"db77be48-6ffb-4d8f-983a-c20411043e10"

{
   "distributedUsersCount": 20,
   "newUsersCount": 20,
   "distributedTasksCount": 10,
   "newTasksCount": 10
}

Получение статистики проекта по его ID без учета пользователя

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

Команда Путь
marker_getFullProjectStatistics HTTP POST "/v1/projects/getFullStatistics"

ListProjectStatistics

На входе параметры поиска / На выходе свойства и статистика проектов из выборки

{
  "query": "",
  "context": {},
  "paging": {"page": 1, "count": 5}
}

{
  "items": [
    {
      "id": "9bc7e8c6-f71c-4a53-abc6-222a8a431e84",
      "title": "Test Classification",
      "startDate": 1649146493990,
      "endDate": 1649146493990,
      "labelingType": "9d08b328-9882-4ea2-bbc9-c44d341e028c",
      "projectStatus": "6fae306e-9120-4b84-a79e-530a0be5617c",
      "statistics": {
        "taskStatuses": [
          {
            "status": "18388b51-3c31-4530-a76b-24404f32ae3c",
            "count": 0
          },
          {
            "status": "66d92292-10da-48e2-81c7-6189725ed813",
            "count": 1
          },
          {
            "status": "a0305766-bb9d-499a-92a4-a34cc6333355",
            "count": 2
          },
          {
            "status": "25e5128f-7e8b-44d6-b515-d1c0c3e0bf3d",
            "count": 3
          }
        ]
      }
    }
  ],
  "total": 1
}

Получение статистики проектов

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

Команда Путь
marker_listProjectStatistics HTTP POST "/v1/projects/listStatistics"

Доступные поля для фильтрации: аналогично marker_listProjects.

Доступные поля для сортировки: аналогично marker_listProjects.

—Именованная сущность—

ListEntityStats

На входе ID проекта / На выходе статистика по сущностям

"09e65817-e136-4f7c-913b-cb04f4edbef1"

[
   {
      "entityCode": "nerField1",
      "documentCount": 28
   },
   {
      "entityCode": "nerField10",
      "documentCount": 5
   }
]

Возвращает статистику по сущностям указанного проекта.

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

Команда Путь
marker_listEntityStats HTTP POST "/v1/projects/listEntityStats"

—Документ—

GetDocument

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

{
  "projectId": "c187a081-87aa-4962-bcfb-3d02de66aee4",
  "documentId": "24330347-d7e6-4ad0-b153-a299e04612d2"
}

{
  "id": "24330347-d7e6-4ad0-b153-a299e04612d2",
  "projectId": "c187a081-87aa-4962-bcfb-3d02de66aee4",
  "title": "TestDoc.pdf",
  "created": 1649146493990,
  "modified": 1649146493990,
  "entityType": "DocForNDJ3jhDJSbaeyd9YfHDnwQ",
  "data": {
    "name": "TestDoc.pdf",
    "file": [
      {
        "fileId": "545828dd-7b6a-40e3-b9b3-317eb52b4c71",
        "name": "TestDoc.pdf",
        "extension": "pdf",
        "size": 1025,
        "url": "datamodel/545828dd-7b6a-40e3-b9b3-317eb52b4c71",
        "additional": {},
        "created": 0,
        "modified": 0,
        "md5": "D41D8CD98F00B204E9800998ECF8427E"
      }
    ]
  }
}

Получение документа определенного проекта по их ID.

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

Команда Путь
marker_getDocument HTTP POST "/v1/documents/get"

ListProjectDocuments

На входе ID проекта и параметры поиска / На выходе страница документов

{
  "projectId": "c187a081-87aa-4962-bcfb-3d02de66aee4",
  "search": {
    "query": "",
    "context": {},
    "sorting": null,
    "paging": null
  }
}

{
  "items": [
    {
      "id": "24330347-d7e6-4ad0-b153-a299e04612d2",
      "projectId": "c187a081-87aa-4962-bcfb-3d02de66aee4",
      "title": "TestDoc.pdf",
      "created": 1649146493990,
      "modified": 1649146493990,
      "entityType": "DocForNDJ3jhDJSbaeyd9YfHDnwQ",
      "data": {
        "name": "TestDoc.pdf",
        "file": [
          {
            "fileId": "545828dd-7b6a-40e3-b9b3-317eb52b4c71",
            "name": "TestDoc.pdf",
            "extension": "pdf",
            "size": 1025,
            "url": "datamodel/545828dd-7b6a-40e3-b9b3-317eb52b4c71",
            "additional": {},
            "created": 0,
            "modified": 0,
            "md5": "D41D8CD98F00B204E9800998ECF8427E"
          }
        ]
      }
    }
  ],
  "total": 5
}

Получение документов проекта.

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

Команда Путь
marker_listProjectDocuments HTTP POST "/v1/documents/listByProject"

LabelDocument

На входе ID задачи на разметку документа, версия разметки и новая разметка / На выходе новая версия разметки

{
  "projectId": "1879aa41-10d9-4ae5-89a6-aeeff005b345",
  "taskId": "3c6a450e-bbce-442c-905e-8108ed8c5a05",
  "ner": {
    "nerField1": [
      {
        "fragment": "Fragment of text",
        "start": 250,
        "end": 266,
        "created": 1234124321432,
        "byExpert": true,
        "uncertain": false,
        "segments": [
          {
            "start": 250,
            "end": 257
          },
          {
            "start": 262,
            "end": 266
          }
        ],
        "nerField1Attribute1": "Attribute value",
        "nerField1Attribute3": [
          "Attribute value"
        ],
        "nerField1SubNer1": [
          {
            "fragment": "Fragment of text",
            "start": 255,
            "end": 260,
            "created": 12341243223432
          }
        ],
        "nerField1SubNer2": []
      }
    ],
    "nerField2": []
  },
  "version": 5
}

6

Обновление разметки документа. Ранее также переводила документ в статус "В работе". Теперь это не делает.

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

Команда Путь
marker_labelDocument Kafka Topic "marker_commands"

—Задача—

GetTask

На входе ID проекта и задачи / На выходе свойства задачи со соответствующей разметкой для NER

{
  "projectId": "c187a081-87aa-4962-bcfb-3d02de66aee4",
  "taskId": "24330347-d7e6-4ad0-b153-a299e04612d2"
}

{
  "id": "24330347-d7e6-4ad0-b153-a299e04612d2",
  "projectId": "c187a081-87aa-4962-bcfb-3d02de66aee4",
  "title": "TestDoc.pdf",
  "created": 1649146493990,
  "status": "00000002-0001-0000-0000-000000000001",
  "documentId": "24330347-d7e6-4ad0-b153-a299e04612d2",
  "skipReason": "Document not valid",
  "skipDate": 1649146493990,
  "ner": {
    "data": {
      "nerField1": [
        {
          "start": 54,
          "length": 10
        },
        {
          "start": 1976,
          "length": 10
        }
      ]
    },
    "version": 4
  },
  "checkingTask": "2408012d-4f06-442d-b7ac-c3221fdbdcd5"
}

Получает данные задачи по его ID и ID проекта. Получает данные любой задачи, без привязки к пользователю.

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

Команда Путь
marker_getTask HTTP POST "/v1/tasks/getById"

CreateTasks

На входе параметры создания задач / На выходе количество созданных задач

{
  "title": null,
  "markerId": "10000000-0000-0000-0000-000000000001",
  "expertId": "20000000-0000-0000-0000-000000000001",
  "projectId": "ee07097c-af39-46f0-9d1b-02583a8ffabe",
  "documentIds": [
    "d4fac3a8-d30c-43ea-a201-963bb51f6584",
    "d01eaa30-5b4b-47ec-8f97-42a5425ede8f"
  ]
}

4

Команда для массового создания задач. Если указан title - он присваивается всем созданным задачам в качестве названия. Если нет - каждой задаче присваивается название в соответствии с названием файла документа.

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

Команда Путь
marker_createTasks Kafka Topic "marker_commands"

DeleteTasks

На входе список ID задач / На выходе количество удаленных задач

[
  "00044c27-c46c-403e-82e7-8983353c5b70",
  "00044c27-c46c-403e-82e7-8983353c5b71"
]

2

Команда для массового удаления задач.

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

Команда Путь
marker_deleteTasks Kafka Topic "marker_commands"

UpdateTasks

На входе параметры обновления задач / На выходе количество обновленных задач

[
  {
    "id": "00044c27-c46c-403e-82e7-8983353c5b70",
    "title": "Slide 1.pptx",
    "status": "00000002-0001-0000-0000-000000000001",
    "markerId": "10000000-0000-0000-0000-000000000001",
    "expertId": "20000000-0000-0000-0000-000000000001",
    "version": 1
  }
]

1

Команда для массового обновления задач.

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

Команда Путь
marker_updateTasks Kafka Topic "marker_commands"

UpdateTasksStatus

На входе параметры обновления статусов задач / На выходе количество обновленных задач

[
  {
    "id": "00044c27-c46c-403e-82e7-8983353c5b70",
    "status": "00000002-0001-0000-0000-000000000001",
    "version": 1
  }
]

1

Команда для изменения статуса задач.

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

Команда Путь
marker_updateTasksStatus Kafka Topic "marker_commands"

ListTasks

На входе параметры пагинации / На выходе страница задач

{
  "page": 1,
  "count": 1
}

{
  "items": [
    {
      "id": "00044c27-c46c-403e-82e7-8983353c5b70",
      "title": "Slide 1.pptx",
      "projectId": "cae17fa7-84fc-485a-995d-8127078c5fda",
      "documentId": "23519541-dd7d-4dff-8b61-216aa1580948",
      "skipReason": null,
      "skipDate": null,
      "created": 1695188446555,
      "modified": 1695188446555,
      "createdBy": "00000000-0000-0000-0000-000000000000",
      "modifiedBy": "00000000-0000-0000-0000-000000000000",
      "status": "00000002-0001-0000-0000-000000000001",
      "markerId": null,
      "expertId": null,
      "version": 1
    }
  ],
  "total": 16
}

Получить список всех задач.

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

Команда Путь
marker_listTasks HTTP POST "/v1/tasks/list"

ListTaskWithFragment

На входе ID проекта, название поля, Search объект / На выходе страница задач с фрагментами

{
  "projectId": "f41d1d65-6530-40b8-b601-43be45d3f195",
  "field": "nerField1",
  "search": {
    "query": "",
    "context": {},
    "sorting": null,
    "paging": {
      "page": 1,
      "count": 1
    }
  }
}

{
  "total": 300,
  "items": [
    {
      "id": "6a0559e5-0ce6-4a7a-8046-732e3cb010d7",
      "projectId": "4486145d-e3d6-4d9a-9e7d-c27f54c2cf17",
      "taskId": "1cb3e56e-580a-4651-927b-e33068060c6f",
      "status": "8a7dabaa-da2c-4b8a-85ff-b7a70e0c71ab",
      "fragments": [
        {
          "created": 1668083991767,
          "fragment": "Политика определяет основные подходы к организации страхования рисков\r\nОАО «Газпром нефть» и ее ДЗО (далее - группы компаний ГПН)",
          "attributes": [
            {
              "key": "Ненужный атрибут для тестов",
              "value": "ппшашнломащ78"
            }
          ],
          "subNer": [
            {
              "title": "Месяц",
              "fragments": [
                {
                  "created": 1668083991767,
                  "fragment": "ром нефть» и ее ДЗО",
                  "attributes": [],
                  "subNer": []
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

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

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

Команда Путь
marker_listTaskWithFragment HTTP POST "/v1/tasks/listWithFragment"

Доступные поля для фильтрации:

Поле Виды фильтров Комментарии
taskId InSetQuery, LikeQuery По id
title InSetQuery, LikeQuery
markerId InSetQuery, LikeQuery
expertId InSetQuery, LikeQuery
documentid InSetQuery, LikeQuery
status InSetQuery, LikeQuery
data.status InSetQuery, LikeQuery

Сортировка выполняется всегда по полю modified модели Labeling.

ListProjectTasksForUser

На входе параметры поиска / На выходе страница задач

{
  "query": "",
  "context": {},
  "sorting": null,
  "paging": null
}

{
  "items": [
    {
      "id": "24330347-d7e6-4ad0-b153-a299e04612d2",
      "projectId": "c187a081-87aa-4962-bcfb-3d02de66aee4",
      "title": "TestDoc.pdf",
      "created": 1649146493990,
      "createdBy": "d7e6d7e6-d7e6-d7e6-d7e6-d7e6d7e6d7e6",
      "modified": 1649146493990,
      "modifiedBy": "d7e6d7e6-d7e6-d7e6-d7e6-d7e6d7e6d7e6",
      "status": "00000002-0001-0000-0000-000000000001",
      "documentId": "24330347-d7e6-4ad0-b153-a299e04612d2",
      "skipReason": "Document not valid",
      "skipDate": 1649146493990,
      "ner": {
        "data": {
          "nerField1": [
            {
              "start": 54,
              "length": 10
            },
            {
              "start": 1976,
              "length": 10
            }
          ]
        },
        "version": 4
      }
    }
  ],
  "total": 5
}

Получение задач проекта (для текущего пользователя).

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

Команда Путь
marker_listProjectTasksForUser HTTP POST "/v1/tasks/listTasksForUser"

Доступные поля для фильтрации:

Поле Виды фильтров Комментарии
id InSetQuery, LikeQuery
title InSetQuery, LikeQuery
markerId InSetQuery, LikeQuery
expertId InSetQuery, LikeQuery
documentId InSetQuery, LikeQuery
status InSetQuery, LikeQuery
data.status InSetQuery, LikeQuery
projectId InSetQuery

Доступные поля для сортировки:

Поле Примечание
created По умолчанию
id

ListProjectTasks

На входе параметры поиска / На выходе страница сокращённых задач

{
  "query": "",
  "context": {},
  "sorting": null,
  "paging": null
}

{
  "items": [
    {
      "taskId": "15b52661-4ca3-4ce7-bf20-05cd14c68dee",
      "projectId": "f999d516-0107-4d86-85aa-c2c4a45a981d",
      "title": "Таких пользователей нет в проекте",
      "status": "00000002-0001-0000-0000-000000000001",
      "markerUserInfo": {
        "id": "4fcbcc75-35a8-48ad-8c90-2e72764f016c",
        "email": "admin02@embedika.ru",
        "info": {
          "firstName": "Имя",
          "lastName": "Фамилия",
          "middleName": "Отчество"
        }
      },
      "expertUserInfo": {
        "id": "eaf08f3f-d074-4c7d-82e1-2b65d88621e4",
        "email": "admin01@embedika.ru",
        "info": {
          "firstName": "Тест",
          "lastName": "",
          "middleName": "Тестович"
        }
      },
      "authorUserInfo": {
        "id": "eaf08f3f-d074-4c7d-82e1-2b65d88621e4",
        "email": "admin01@embedika.ru",
        "info": {
          "firstName": "Тест",
          "lastName": "",
          "middleName": "Тестович"
        }
      },
      "documentId": "f999d516-0107-4d86-85aa-c2c4a45a981d"
    }
  ],
  "total": 27
}

Получение списка сокращённой информации по задачам проекта.

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

Команда Путь
marker_listProjectTasks HTTP POST "/v1/tasks/listByProject"

GetTaskPositionInProject

На входе ID проекта, ID задачи и параметры поиска / На выходе позиция задачи и общее количество всех найденных

{
  "projectId": "c187a081-87aa-4962-bcfb-3d02de66aee4",
  "taskId": "24330347-d7e6-4ad0-b153-a299e04612d2",
  "search": {
    "query": "",
    "context": {}
  }
}

{
  "position": 1,
  "total": 5
}

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

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

Команда Путь
marker_getTaskPositionInProject HTTP POST "/v1/tasks/getPositionInProject"

—Пользователь—

AddUsersToProject

На входе ID проекта, роль и список ID пользователей / На выходе признак успешного выполнения

{
  "projectId": "b2993663-8dd4-435d-b14d-a1cf18a4ddae",
  "role": "userRole_marker",
  "userIds": [
    "4eb15e5a-f388-4e85-9b35-cc025e784249"
  ]
}

true

Добавляет пользователeй в проект, устанавливая им роль.

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

Команда Путь
marker_addUsersToProject Kafka Topic "marker_commands"

DeleteUsersFromProject

На входе ID проекта и список ID пользователй / На выходе признак успешного выполнения

{
  "projectId": "b2993663-8dd4-435d-b14d-a1cf18a4ddae",
  "userIds": [
    "4eb15e5a-f388-4e85-9b35-cc025e784249"
  ]
}

true

Удаляет пользователя из проекта.

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

Команда Путь
marker_deleteUsersFromProject Kafka Topic "marker_commands"

ListDocumentAssessors

На входе список ID документов / На выходе список пользователей

{
  "documents": [
    "3c6a450e-bbce-442c-905e-8108ed8c5a05",
    "294146d9-ed05-4251-b34f-2192d4e83f05"
  ]
}

{
  "documentUsers": [
    {
      "documentId": "3c6a450e-bbce-442c-905e-8108ed8c5a05",
      "assessors": [
        {
          "status": "00000002-0001-0000-0000-000000000001",
          "users": [
            {
              "id": "4324bf49-e556-4058-ba5a-ccdc02199f79",
              "modified": 1651234477
            },
            {
              "id": "17f41b3b-100b-492e-a17d-4c6ea60d21ed",
              "modified": 1651234477
            }
          ]
        },
        {
          "status": "00000002-0001-0000-0000-000000000001",
          "users": [
            {
              "id": "9e89421b-bfb6-40f8-bcc6-833aeb2bd676",
              "modified": 1651234477
            }
          ]
        }
      ]
    },
    {
      "documentId": "294146d9-ed05-4251-b34f-2192d4e83f05",
      "assessors": [
        {
          "status": "00000002-0001-0000-0000-000000000001",
          "users": [
          ]
        },
        {
          "status": "00000002-0001-0000-0000-000000000001",
          "users": [
            {
              "id": "4fcd63d6-db92-4d5b-93c6-bb78e4a59656",
              "modified": 1651234477
            },
            {
              "id": "9e89421b-bfb6-40f8-bcc6-833aeb2bd676",
              "modified": 1651234477
            }
          ]
        }
      ]
    }
  ]
}

Получить список пользователей, назначенных на разметку документов.

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

Команда Путь
marker_listDocumentAssessors HTTP POST "/v1/users/listDocumentAssessors"

ListProjectsForUsers

На входе список ID пользователей, для которых нужна информация / На выходе информация о проектах пользователей

[
  "022b1185-c0cd-4c7b-87b5-0dc35c430a76",
  "b42d0857-1128-44af-b876-bec33f028326",
  "a62cc9e4-2ca1-40f4-98e9-d0c189b9c731",
  "f57143ef-c129-4500-8e2e-97db93bd0c1b"
]

[
  {
    "userId": "022b1185-c0cd-4c7b-87b5-0dc35c430a76",
    "projects": [
      {
        "projectId": "8af0fcbe-4b95-4b06-afb3-b77b4a3e1200",
        "role": "userRole_marker",
        "addedToProject": 1651234477
      }
    ]
  }
]

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

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

Команда Путь
marker_listProjectsForUsers HTTP POST "/v1/users/listProjects"

ListProjectUsers

На входе ID проекта, роль пользователя и входе параметры поиска (только пагинация) / На выходе страница пользователей проекта

{
  "projectId": "db77be48-6ffb-4d8f-983a-c20411043e10",
  "role": "userRole_marker",
  "search": {
    "query": "",
    "context": {},
    "sorting": null,
    "paging": {
      "page": 1,
      "count": 5
    }
  }
}

{
  "items": [
    {
      "userId": "f0ed4aa8-2090-4e48-82e5-62a2ef5623cf",
      "role": "userRole_marker",
      "taskStatuses": [
        {
          "status": "18388b51-3c31-4530-a76b-24404f32ae3c",
          "count": 0
        },
        {
          "status": "66d92292-10da-48e2-81c7-6189725ed813",
          "count": 1
        },
        {
          "status": "a0305766-bb9d-499a-92a4-a34cc6333355",
          "count": 2
        },
        {
          "status": "25e5128f-7e8b-44d6-b515-d1c0c3e0bf3d",
          "count": 3
        }
      ]
    }
  ],
  "total": 300
}

Возвращает список пользователей в проекте. На данный момент Search объект поддерживает только Paging

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

Команда Путь
marker_listProjectUsers HTTP POST "/v1/users/listForProject"

—Разметка—

ExportLabeling

На входе объект с ID проекта, списком ID необходимый сущностей и форматом выгрузки / На выходе url файла с результатом экспорта (пример строки выходного файла)

{
  "projectId": "5f10f6e2-7127-4989-9dda-b69c685880ec",
  "nerSettingIds": [
    "nerField2",
    "a101"
  ],
  "format": "jsonl"
}

"labeling/1cf14222-3d28-4584-a02c-60113f6d7031"

{
  "nerField2": [
    {
      "fragment": "направляет Подрядчику на электронный адрес",
      "start": 982,
      "end": 2544,
      "created": 1699592041197,
      "byExpert": null,
      "uncertain": null,
      "userId": "7e498091-f9d2-4573-bc7a-857000d22073",
      "segments": []
    }
  ],
  "documentId": "ec8a361d-cd51-4edb-8de4-94df8ad59f32",
  "documentUrl": null,
  "extractedTextUrl": null
}

Генерирует выгрузку разметки по проекту. На выходе выдает файл в формате JSON Lines(где каждая строка имеет формат ExportLabelingItem) или Csv(формат documentId,entityCode,fragment)

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

Команда Путь
marker_exportLabeling Kafka Topic "marker_commands"

ListCompletedLabelings

На входе пагинация / На выходе список разметок

{
  "page": 1,
  "count": 10
}

{
  "items": [
    {
      "id": "f41d1d65-6530-40b8-b601-43be45d3f195",
      "projectId": "f41d1d65-6530-40b8-b601-43be45d3f195",
      "userId": "f41d1d65-6530-40b8-b601-43be45d3f195",
      "created": 1668083991767,
      "modified": 1668083991767,
      "data": {
        "nerField1": []
      },
      "version": 1
    }
  ],
  "total": 10
}

Возвращает список разметок в статусе 'Завершено'.

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

Команда Путь
marker_listCompletedLabelings HTTP POST "/v1/labelings/listCompleted"

ImportRndLabeling

На входе ID файла во временном хранилище (пример файла) и параметры импорта / На выходе количество измененных версий разметки

{
  "fileId": "d0cd48f3-8c9e-4c47-a640-83d2d1e4871c",
  "include": {
    "fields": [
      "UnilateralChange"
    ],
    "docIds": [
      "24793790-787e-4865-94b0-8eeb5b37db37"
    ]
  },
  "exclude": {}
}

{"docId": "356be847-b5c5-459a-9315-5cb2596a7e31", "start": 32128, "end": 32575, "entityType": "UnilateralChange", "text": "коротки хитрый текст"}
{"docId": "b326453e-128c-4ae3-a50b-3f8510b7b6a5", "start": 32129, "end": 32577, "entityType": "UnilateralChange", "text": "хитрый странный очень текст побольше"}
{"docId": "b326453e-128c-4ae3-a50b-3f8510b7b6a5", "start": 32578, "end": 32983, "entityType": "UnilateralChange", "text": "еще один очень хитрый текст"}

9

Загружает в систему разметку в формате RnD.

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

Команда Путь
marker_importRndLabeling Kafka Topic "marker_commands"

RemoveRndLabeling

На входе параметры для удаления / На выходе количество измененных версий разметки

{
  "include": {
    "nerSettingIds": [
      "ArbitrationClause"
    ]
  },
  "exclude": {
    "docIds": [
      "24793790-787e-4865-94b0-8eeb5b37db37"
    ]
  }
}

3620

Удаляет из системы разметку, загруженную в формате RnD.

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

Команда Путь
marker_removeRndLabeling Kafka Topic "marker_commands"

—Обучение—

StartLearning

На входе ID проекта и список ID сущностей для обучения / На выходе количество запущенных обучений

{
  "projectId": "238837d3-54fe-4685-ae73-48728b93ea0a",
  "nerSettingIds": [
    "Limited",
    "Unlimited"
  ]
}

2

Запускает обучение в сервисе обучения ML-моделей (/train)

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

Команда Путь
marker_startLearning Kafka Topic "marker_commands"

StopLearning

На входе ID проекта / На выходе ничего

"238837d3-54fe-4685-ae73-48728b93ea0a"

{}

Запускает soft restart в сервисе обучения ML-моделей (/soft_restart)

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

Команда Путь
marker_stopLearning Kafka Topic "marker_commands"

ListLearnings

На входе параметры поиска / На выходе страница обучений

{
  "query": "",
  "context": {},
  "sorting": null,
  "paging": {
    "page": 1,
    "count": 1
  }
}

{
  "items": [
    {
      "nerSetting": {
        "id": "Limited",
        "title": "Ограниченная ответственность",
        "projectIds": [
          "5b950949-05b1-439a-a864-94a19e46c453"
        ]
      },
      "learningItems": [
        {
          "project": {
            "id": "5b950949-05b1-439a-a864-94a19e46c453",
            "title": "Проект",
            "created": 1711734922172,
            "startDate": 1648114231,
            "endDate": 1648114231,
            "labelingType": "labelingType_ner",
            "projectStatus": "projectStatus_draft",
            "version": 1,
            "tasksTotal": 0,
            "documentsTotal": 0,
            "participantsTotal": 0
          },
          "learning": {
            "nerSettingId": "Limited",
            "projectId": "5b950949-05b1-439a-a864-94a19e46c453",
            "status": "Draft",
            "error": null,
            "labelingId": null,
            "modelId": null,
            "metricsId": null,
            "created": 1711734923053,
            "createdBy": "eaf08f3f-d074-4c7d-82e1-2b65d88621e4",
            "modified": 1711734923053,
            "modifiedBy": "eaf08f3f-d074-4c7d-82e1-2b65d88621e4",
            "version": 1
          }
        }
      ]
    }
  ],
  "total": 15
}

Перечень обучений, сгруппированный по сущностям. Для сущностей, не добавленных ни в один проект, придет: "learningItems": [].

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

Команда Путь
marker_listLearnings HTTP POST "/v1/learning/list"

Доступные поля для фильтрации:

Поле Виды фильтров
nerSetting.id InSetQuery, LikeQuery
nerSetting.title InSetQuery, LikeQuery
project.id InSetQuery, LikeQuery
project.title InSetQuery, LikeQuery

Доступные поля для сортировки (обучения у каждой сущности расположены всегда в порядке убывания modified - последннее запущенное обучение сверху):

Поле Примечание
nerSetting.created По умолчанию - по убыванию
nerSetting.title

Объекты сервиса разметчика

—Проект—

CreateProjectReq

Поле Тип Обязательное Описание
title string да Наименование проекта
startDate timestamp нет Дата и время начала проекта
endDate timestamp нет Дата и время окончания проекта
instruction string нет Инструкция
instructionFile string нет Url файла с инструкцией полученное из upload
labelingType string да ID вида разметки (из справочника)
nerSettings object[] нет Настройки выделения сущностей
classificationSettings object[] нет Настройки классификации
markupSuggesters string[] да Список ID ролей, которые могу предлагать разметку

UpdateProjectReq

Поле Тип Обязательное Описание
id uuid string да ID обновляемого проекта
version number да Версия обновляемого проекта для оптимистичных блокировок
title string да Наименование проекта
startDate timestamp нет Дата и время начала проекта
endDate timestamp нет Дата и время окончания проекта
instruction string нет Инструкция
instructionUrl string нет Url файла с инструкцией полученное из upload
labelingType string да ID вида разметки (из справочника)
nerSettings object[] нет Настройки выделения сущностей
classificationSettings object[] нет Настройки классификации
markupSuggesters string[] да Список ID ролей, которые могу предлагать разметку

UpdateProjectStatusReq

Поле Тип Обязательное Описание
id uuid string да ID обновляемого проекта
version number да Версия обновляемого проекта для оптимистичных блокировок
projectStatus string да ID статуса проекта (из справочника)

AddFilesToProject (dto)

Поле Тип Обязательное Описание
projectId uuid string да ID проекта
fileIds uuid string[] да Список ID файлов

UpsertNerSetting

Поле Тип Обязательное Описание
id uuid string нет ID настройки, если она существует
title string да Наименование настройки
selectionColor string да Цвет выделения
attributes object[] нет Атрибуты сущности
subNers object[] нет Подсущности
showInDocList boolean да Показывать в списке документов
nerHint string нет Подсказка
minLabelingCount string нет Минимальное количество разметки для обучения

UpsertClassificationSetting

Поле Тип Обязательное Описание
id uuid string нет ID настройки, если она существует
title string да Наименование настройки
classificationAction string да ID действия при классификации
optionsList string[] нет Перечень вариантов
maxLength number нет Ограничение длины
classificationHint string нет Подсказка для настройки
showInDocList boolean да Показывать в списке документов
minLabelingCount string нет Минимальное количество разметки для обучения

Project

Поле Тип Обязательное Описание
id uuid string да ID проекта
created timestamp да Дата создания проекта
title string да Наименование проекта
startDate timestamp нет Дата и время начала проекта
endDate timestamp нет Дата и время окончания проекта
instruction string нет Инструкция
instructionFile object нет Файл инструкции
labelingType string да ID вида разметки (из справочника)
projectStatus string да ID статуса проекта (из справочника)
documentEntityType string да Тип сущности в модели данных, с которым сохраняются документы для этого проекта
nerSettings object[] нет Настройки выделения сущностей
classificationSettings object[] нет Настройки классификации
version number да Версия проекта для оптимистичных блокировок
markupSuggesters string[] да Список ID ролей, которые могу предлагать разметку

ProjectFields

Поле Тип Обязательное Описание
id uuid string да ID проекта
title string да Название проекта
startDate timestamp нет Дата и время начала проекта
endDate timestamp нет Дата и время окончания проекта
projectStatus uuid string да ID статуса проекта (из справочника)
labelingType uuid string да ID вида разметки (из справочника)
taskCount number да Количество документов в проекте
nerSettings object[] да Настройки выделения сущностей
spanCounts object[] да Информация по количеству спанов

NerSetting

Поле Тип Обязательное Описание
id string да ID (код) настройки
projectIds uuid string[] да ID проекта, в котором определена эта настройка
title string да Наименование настройки
selectionColor string да Цвет выделения
attributes object[] нет Атрибуты сущности
subNers object[] нет Подсущности
showInDocList boolean да Показывать в списке документов
nerHint string нет Подсказка
minLabelingCount string нет Минимальное количество разметки для обучения

ClassificationSetting

Поле Тип Обязательное Описание
id string да ID (код) настройки
projectIds uuid string[] да ID проекта, в котором определена эта настройка
title string да Наименование настройки
classificationAction string да ID действия при классификации
optionsList string[] нет Перечень вариантов
maxLength number нет Ограничение длины
classificationHint string нет Подсказка для настройки
showInDocList boolean да Показывать в списке документов
minLabelingCount string нет Минимальное количество разметки для обучения

ProjectListItem

Поле Тип Обязательное Описание
id uuid string да ID проекта
created timestamp да Дата создания проекта
title string да Наименование проекта
startDate timestamp нет Дата и время начала проекта
endDate timestamp нет Дата и время окончания проекта
instructionFile uuid string нет Файл инструкции
labelingType uuid string да ID вида разметки (из справочника)
projectStatus uuid string да ID статуса проекта (из справочника)
version number да Версия проекта для оптимистичных блокировок
tasksTotal number да Количество задач в проекте
documentsTotal number да Количество документов в проекте
participantsTotal number да Количество участников в проекте

ProjectStatistics

Поле Тип Обязательное Описание
id uuid string да ID проекта
created timestamp да Дата создания проекта
title string да Наименование проекта
startDate timestamp нет Дата и время начала проекта
endDate timestamp нет Дата и время окончания проекта
instruction string нет Инструкция
instructionFile uuid string нет Файл инструкции
labelingType uuid string да ID вида разметки (из справочника)
projectStatus uuid string да ID статуса проекта (из справочника)
version number да Версия проекта для оптимистичных блокировок
statistics object да Статистика проекта

ProjectStatisticsData

Поле Тип Обязательное Описание
taskStatuses object да Статистика статусов заданий запросившего статистику пользователя

ProjectTaskStatusStatItem

Поле Тип Обязательное Описание
status uuid string да ID Статуса задачи (из сервиса маршрутов)
count number да Количество заданий в данном статусе

Setting

Настройка (nerSetting или classificationSetting) в обобщенном виде

Поле Тип Обязательное Описание
id string да ID настройки
title string да название
projectIds uuid string да ID проекта

FullProjectStatistics

Поле Тип Обязательное Описание
distributedUsersCount number да Кол-во распределенных пользователей
newUsersCount number да Кол-во нераспределенных пользователей
distributedTasksCount number да Кол-во распределенных документов
newTasksCount number да Кол-во нераспределенных документов

—Именованная сущность—

EntityStatsItem

Поле Тип Обязательное Описание
entityCode string да Код сущности
documentCount number да Количество документов с этой сущностью

—Документ—

GetDocumentReq

Поле Тип Обязательное Описание
projectId uuid string да ID проекта
documentId uuid string да ID документа в проекте

Document

Поле Тип Обязательное Описание
id uuid string да ID документа
projectId uuid string да ID проекта
title string да Наименование документа
created timestamp да Дата и время создания объекта документа (не путать с датой создания файла)
entityType string да Тип сущности соответствующей этому документу в модели данных
data object да Метаданные документа. В этом поле будут возвращены все поля документа, хранящиеся в модели данных. По умолчанию как пример всем документам разметчика создается модель DocumentData.

DocumentData

Поле Тип Обязательное Описание
file file object да Файл документа
name string да Наименование документа
path string нет Путь до файла в источнике
created timestamp да Дата и время создания файла (в источнике)
modified timestamp нет Дата и время изменения файла (в источнике)
owner object нет Владелец документа (в источнике файла)

ListProjectDocumentsReq

Поле Тип Обязательное Описание
projectId uuid string да ID проекта
search Search да Фильтры, сортировка, пагинация

LabelDocumentReq

Поле Тип Обязательное Описание
projectId uuid string да ID проекта задачи
taskId uuid string да ID задачи на разметку
ner [string, NerLabelingItem[]] нет Новое выделение сущностей
classification object нет Новая классификация
version number да Версия разметки

—Задача—

ProjectTaskIdentity

Поле Тип Обязательное Описание
projectId uuid string да ID проекта, к которому относится задание
taskId uuid string да ID задачи на разметку
reason string да Причина пропуска

SkipTaskReq

Поле Тип Обязательное Описание
projectId uuid string да ID проекта, к которому относится задание
taskId uuid string да ID задачи на разметку

Task

Поле Тип Обязательное Описание
id uuid string да ID задачи
projectId uuid string да ID проекта
documentId uuid string да ID документа задачи
userId uuid string да ID пользователя, которому назначено задание
title string да Наименование задачи
created timestamp да Дата и время создания задачи
createdBy uuid string да ID пользователя создавшего запись
modified timestamp да Дата и время изменения задачи
modifiedBy uuid string да ID пользователя последним изменившего запись
status string да ID статуса задачи (из сервиса маршрутов)
skipReason string нет Причина пропуска задачи
skipDate timestamp нет Дата и время пропуска
ner object нет Выделенные сущности
classification object нет Классификация
checkingTask uuid string нет ссылка на задание, проверяющее текущее (задание эксперта для разметчика)
checkedTask uuid string нет ссылка на исходное задание, которое проверяется текущим (задание разметчика для эксперта)
version number да Версия задачи для оптимистичной блокировки

TaskLabeling

Поле Тип Обязательное Описание
version number да Версия разметки
data LabelingData да Данные (в зависимости от вида разметки, см. примеры в Confluence)

TaskShort

Поле Тип Обязательное Описание
id uuid string да ID задачи
title string да Название задачи
projectId uuid string да ID проекта
documentId uuid string да ID документа задачи
skipReason string нет Причина пропуска задачи
skipDate timestamp нет Дата пропуска задачи
created timestamp да Дата и время создания
modified timestamp да Дата и время изменения
createdBy uuid string да ID пользователя создавшего запись
modifiedBy uuid string да ID пользователя последним изменившего запись
status string да ID статуса задачи (из сервиса маршрутов)
markerId uuid string нет ID пользователя - разметчика
expertId uuid string нет ID пользователя - эксперта
version int да Версия для оптимистичной блокировки

TaskShortInfo

Поле Тип Обязательное Описание
taskId uuid string да ID задачи
projectId uuid string да ID проекта
title string да Название задачи
status string да ID статуса задачи (из сервиса маршрутов)
markerUserInfo User нет Информация об разметчике
expertUserInfo User нет Информация об эксперте
authorUserInfo User нет Информация об авторе
documentId uuid string да ID документа задачи

ListTaskWithFragment (dto)

Поле Тип Обязательное Описание
projectId uuid string да ID проекта
field string да Поле, документы с которым нужно получить
search Search да Search объект

TaskWithFragment

Поле Тип Обязательное Описание
id uuid string да ID документа
projectId uuid string да ID проекта
taskId uuid string да ID задачи
status LabelingStatus string да Статус разметки
title string Да Название документа
fragments Fragment[] Да Фрагменты

Fragment

Поле Тип Обязательное Описание
created TimeStamp да Дата создания разметки
fragment string да Фрагмент
attributes Atribute[] да Аттрибуты
subNer SubNer[] да Дочерние разметки

Attribute

Поле Тип Обязательное Описание
key string да Ключ аттрибута
value string нет Значение аттрибута

SubNer

Поле Тип Обязательное Описание
title string да Название разметки
fragments Fragment[] Да Фрагменты

CreateTasksDto

Поле Тип Обязательное Описание
title string нет Название всех задач
markerId uuid string да ID пользователя - разметчика
expertId uuid string да ID пользователя - эксперта
projectId uuid string да ID проекта
documentIds string[] да Список ID документов

UpdateTaskDTO

Поле Тип Обязательное Описание
id uuid string да ID задачи
title string нет Название задачи, если пусто, то используется название документа
status string да ID статуса задачи (из сервиса маршрутов)
markerId uuid string нет ID пользователя - разметчика
expertId uuid string нет ID пользователя - эксперта
skipReason string нет Причина пропуска задачи
version number да Версия задачи для оптимистичных блокировок

UpdateTaskStatusDTO

Поле Тип Обязательное Описание
id uuid string да ID задачи
status string да ID статуса задачи (из сервиса маршрутов)
skipReason string нет Причина пропуска задачи
version number да Версия задачи для оптимистичных блокировок

GetTaskPositionInProjectReq

Поле Тип Обязательное Описание
projectId uuid string да ID проекта
taskId uuid string да ID задачи в проекте
search Search да Фильтры, сортировка, пагинация

—Пользователь—

User

Поле Тип Обязательное Описание
id uuid string да ID пользоваетля
email string да Email пользователя
info UserInfo нет Информация о пользователе

UserInfo

Поле Тип Обязательное Описание
firstName string нет Имя пользователя
lastName string нет Фамилия пользователя
middleName string нет Отчествао пользователя

AddUsersToProject (dto)

Поле Тип Обязательное Описание
projectId uuid string да ID проекта
userIds uuid string[] да ID пользователей
role string нет Код роли в справочнике

DeleteUsersFromProject (dto)

Поле Тип Обязательное Описание
projectId uuid string да ID проекта
userId uuid string[] да ID пользователей

ListDocumentAssessorsReq

Поле Тип Обязательное Описание
documents uuid string[] да ID документов проекта

ListDocumentAssessorsResult

Поле Тип Обязательное Описание
documentUsers object[] да Разметчики документов

SingleDocumentAssessors

Поле Тип Обязательное Описание
documentId uuid string да ID документа
assessors object[] да Разметчики документа, разбитые по статусу разметки

TaskStatusAssessors

Поле Тип Обязательное Описание
status string да ID статуса из сервиса маршрутов
assessors object[] да Данные пользователей-разметчиков

TaskAssessor

Поле Тип Обязательное Описание
id uuid string да ID пользователя
modified timestamp да Последнее время изменения статуса задачи на разметку
skipReason string нет Причина пропуска задачи
skipDate timestamp нет Дата и время пропуска задачи

UserWithProjects

Поле Тип Обязательное Описание
userId uuid string да ID пользователя
projects UserProjectInfo[] да Список с ифнформациями о проектах пользователя

UserProjectInfo

Поле Тип Обязательное Описание
projectId uuid string да ID проекта
role string да ID роли в справочнике
addedToProject timestamp Да Дата, когда пользователя добавили в проект

ListProjectUsers (dto)

Поле Тип Обязательное Описание
projectId uuid string да ID проекта
role string нет ID роли, пользователей с которой нужно вернуть. Если не указан, вернет всех пользователей
search Search да Объект поиска аналогичный другим сервисам

ProjectUser

Поле Тип Обязательное Описание
userId uuid string да ID пользователя
role string да Код роли в справочнике
taskStatuses object[] да Статистика статусов заданий запросившего статистику пользователя

—Разметка—

LabelingData:

NerLabelingItem

Поле Тип Обязательное Описание
fragment string да Текст фрагмента
start number да Координаты начала фрагмента
end number да Координаты оконачания фрагмента
created TimeStamp да Время создания спана
byExpert boolean нет Спан создан экспертом
uncertain boolean нет Уверен ли пользователь в спане
segments List[{start: number, end: number}] нет Сегменты спана
userId uuid string нет ID пользователя, кто создал спан
___ List[NerLabelingItem] нет Подсущности спана
___Attribute String \ List[String] нет

ExportLabeling (dto)

Поле Тип Обязательное Описание
projectId uuid string да ID проекта
nerSettingIds string[] нет Список сущностей для выгрузки (отсутствие сущностей == all)
format string (Jsonl/Csv) нет Формат выгрузки разметки (Jsonl или Csv) По дефолту Jsonl

ExportLabelingItem

Поле Тип Обязательное Описание
documentId uuid string да ID документа
documentUrl url string нет Ссылка на файл документа
extractedTextUrl url string нет Ссылка на извлеченный текст документа
classificationFieldN (где N - номер поля) object для проектов типа Classification Поля со значениями проставленных классов
nerFieldN (где N - номер поля) object для проектов типа Ner (выделение сущностей) Поля с выделенными сущностями

Labeling

Поле Тип Обязательное Описание
id uuid string да ID разметки
projectId uuid string да ID проекта
userId uuid string да ID пользователя
created TimeStamp да Дата создания разметки
modified TimeStamp да Дата изменения разметки
data object да Данные разметки
version number да Версия разметки

ImportLabeling

Поле Тип Обязательное Описание
fileId string нет ID файла JSON Lines из временного хранилища (для импорта)
include ImportItems нет Объекты, которые будут включены в импорт/удаление
exclude ImportItems нет Объекты, которые будут исключены из импорта/удаления

ImportItems

Поле Тип Обязательное Описание
nerSettingIds string[] нет Список кодов полей
docIds uuid string[] нет Список ID документов

—Обучение—

StartLearningDTO

Поле Тип Обязательное Описание
projectId uuid string да ID проекта
nerSettingIds string[] да ID настройки выделения сущности

LearningListDTO

Поле Тип Обязательное Описание
nerSetting Setting да Настройка выделения сущности в сокращенном виде
learningItems LearningItemDTO[] да Элемент проекта и обучения

LearningItemDTO

Поле Тип Обязательное Описание
project ProjectListItem да Атрибуты проекта со счетчиками задач, документов, участников
learning Learning да ID настройки выделения сущности

Learning

Поле Тип Обязательное Описание
nerSettingId string да ID настройки выделения сущности
projectId uuid string да ID проекта
status LearningStatus да Статус обучения
error string нет Сообщение об ошибке при обучении
labelingId string нет ID файла экспорта разметки
modelId string нет ID файла модели
metricsId string нет ID файла метрик
created TimeStamp да Дата и время создания
createdBy uuid string да ID пользователя создавшего запись
modified TimeStamp да Дата и время изменения
modifiedBy uuid string да ID пользователя последним изменившего запись
version number да Версия для оптимистичной блокировки

LearningStatus

Значение Описание
Draft Черновик обучения
Running Обучение запущено
Error Обучение завершено с ошибкой
Stopped Обучение остановлено пользователем
Finished Обучение завершено успешно

—Маршруты—

RouteMigrationDTO

При ручном создании ID имеют вид подобный такому: "00000001-0000-0000-0000-000000000001". Число в первой группе указывает, что это id маршрута, в последней - номер маршрута.

Не следует завязывать какую-либо логику на данный принцип формирования ID.

Поле Тип Обязательное Описание
id uuid string да ID маршрута
versionId uuid string да ID версии маршрута
title string да Название маршрута
description string да Описание маршрута
data {} да Данные маршрута (пока пустые)

RouteStageMigrationDTO

При ручном создании ID имеют вид подобный такому: "00000002-0001-0000-0000-000000000001". Число в первой группе указывает, что это id этапа маршрута, во второй - номер маршрута, к которому относится этап, в последней - номер этапа.

Не следует завязывать какую-либо логику на данный принцип формирования ID.

Поле Тип Обязательное Описание
id uuid string да ID этапа маршрута
routeVersionId uuid string да ID версии маршрута
title string да Название этапа
description string да Описание этапа
data RouteStageData да Данные этапа
stageTypeId uuid string да ID типа этапа

RouteStageData

Поле Тип Обязательное Описание
color hex string нет Цвет этапа в UI

RouteStageLinkMigrationDTO

При ручном создании ID имеют вид подобный такому: "00000003-0001-0002-0000-000000000001". Число в первой группе указывает, что это id связи этапов, во второй - номер маршрута, к которому относится связь, в третьей - номер этапа откуда, в четвертой - номер этапа куда, в последней - номер связи.

Не следует завязывать какую-либо логику на данный принцип формирования ID.

Поле Тип Обязательное Описание
id uuid string да ID связи этапов
title string да Название связи
stageFrom uuid string да ID этапа откуда
stageTo uuid string да ID этапа куда
conditions RouteStageLinkConditions да Условия перехода

RouteStageLinkConditions

Поле Тип Обязательное Описание
roles string[] да роли, которые могут выполнять переход

risk-checker: сервис анализа документов на риски

Сервис обеспечивает работу с чек-листами проверки, рисками, сущностями и моделями машинного обучения. Позволяет запускать пайплайн обработки экстракции текста документа ML-сервисами.

Сервис разбит на несколько модулей, в виде sbt проектов:

Требования к запуску сервиса анализа

При запуске сервиса ожидается, что уже развернута необходимая инфраструктура:

Пайплайн выделения сущностей

Настройка списка сервисов пайплайна переменной окружения RISK_CHECKER_ML_SERVICES:

При пропуске сервиса работает логика байпаса: на выход передаются входные данные в неизменном виде, либо подставляются пустые данные (в зависимости от логики обработки).

Конфигурация внутренних сервисов

Настройка конфигурации сервисов переменной окружения RISK_CHECKER_LICENSE_MODE:

Ключ Функция default extended
features Роуты включенных моделей model-mapping model-mapping, model-mapping-customers
Маппинг дополнительных рисков - ServiceDateUndefined, ServiceDateSourcesLinksFound, WarrantyPeriodParametersMissing, WithoutCompanyAgreementTerminationFound
services Создание сущностей для разметки - Создание и обновление через реестр Сущностей в marker-service
notifications Уведомления о событиях в системе - Создание подписки на персональные уведомления для пользователя по его группе

Продуктовые миграции сервиса анализа

Ключи настройки в json-файлах миграций:

Название Описание Файл Удаление (cleanup)
Import catalogs Каталоги и их элементы catalogs.json Каталогов (с содержимым), отсутствующих в миграции
Import policy rules Экшены правил, разрешенные группам actions.json Версий политик, отсутствующих в миграции
Import subscriptions Групповые подписки на уведомления subscriptions.json Подписок отдельных пользователей
Import tech constants Техконстанты для событий журнала techсonstants.json Техконстант сервисов risk-checker, отсутствующих в миграции
Import user groups Группы пользователей groups.json Групп пользователей, отсутствующих в миграции
Import requirements, Требования чек-листа requirements.json Не обрабатывается
~ risks, Риски на основе выделения сущностей risks.json Не обрабатывается
~ entities, Сущности, выделяемые ML-сервисами entities.json Не обрабатывается
~ models, Модели ML-сервиса models.json Не обрабатывается
~ templates Шаблоны отчета с настройками templates.json Не обрабатывается

Переменные окружения сервиса анализа

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

Переменная Тип Обязательная Значение по умолчанию Описание
RISK_CHECKER_SERVICE_SCALING_POSTFIX string нет "" Глобальный постфикс для развёртывания нескольких независимых друг от друга экземпляров сервиса. Применяется к командам и экшенам, а также к группам и политикам, создаваемым миграциями Contract.
RISK_CHECKER_HTTP_HOST string нет "0.0.0.0" Хост, на котором слушает HTTP-сервер
RISK_CHECKER_HTTP_PORT int нет 8192 Порт, на котором слушает HTTP-сервер
RISK_CHECKER_HTTP_CLIENT_CONNECT_TIMEOUT duration string нет 10 seconds Максимальное время ожидания ответов на http запросы
RISK_CHECKER_KAFKA_SERVERS string да "localhost:9092" Адрес Kafka
RISK_CHECKER_KAFKA_TOPIC string нет "risk_checker_commands" Название кафка-топика для получения команд. Сервис получает кафка-команды по нему, но и также сам публикует это название в CommandDiscovery.
RISK_CHECKER_KAFKA_DATAMODEL_EVENTS_TOPIC string нет "risk_checker_datamodel_events" Название кафка-топика для получения событий из datamodel по сущностям
RISK_CHECKER_KAFKA_DATAMODEL_RELATION_EVENTS_TOPIC string нет "risk_checker_datamodel_relation_events" Название кафка-топика для получения событий из datamodel по отношениям
RISK_CHECKER_KAFKA_MARKER_EVENTS_TOPIC string нет "risk_checker_marker_events" Название кафка-топика для получения событий из marker-service
RISK_CHECKER_KAFKA_CONSUMER_GROUP string нет "risk_checker_consumer_group" Имя consumer-группы для чтения из кафка-топика команд. Не должна меняться и не должна быть пустой, иначе сервис перечитает свои команды при перезапуске.
RISK_CHECKER_KAFKA_PARTITIONS int нет 10 Число читаемых партиций из кафка-топика команд.
RISK_CHECKER_KAFKA_CONSUMER_RESTART_MIN_BACKOFF duration string нет 1 second Изначальная задержка до рестарта консьюмера после падения (увеличивается в 2 раза после каждого рестарта)
RISK_CHECKER_KAFKA_CONSUMER_RESTART_MAX_BACKOFF duration string нет 30 seconds Максимальное задержка до рестарта консьюмера после падения
RISK_CHECKER_KAFKA_CONSUMER_RESTART_RANDOM_FACTOR double нет 0.2 Рандомный фактор для вычисления задержки перед следующим рестратом консьюмера (При значении 0.2 задержка может быть до 20% больше, чем при 0)
RISK_CHECKER_KAFKA_CONSUMER_RESTART_MAX_RESTARTS int нет 5 Максимальное число рестартов консьюмера после падения (в пределах RISK_CHECKER_KAFKA_CONSUMER_RESTART_MAX_RESTARTS_WITHIN)
RISK_CHECKER_KAFKA_CONSUMER_RESTART_MAX_RESTARTS_WITHIN duration string нет 5 minutes Временной отрезок, в который RISK_CHECKER_KAFKA_CONSUMER_RESTART_MAX_RESTARTS ограничивает число рестартов
RISK_CHECKER_KAFKA_COMMANDEVENT_TOPIC string да "commandevents" Название кафка-топика для отправки сообщений со статусами выполняемых команд. ОБЯЗАТЕЛЬНО должно соответствовать названию этого топика в сервисе статуса команд.
RISK_CHECKER_KAFKA_AUTH_USER string да "" Название учетной записи Kafka. Если название не указано, то настройки авторизации не будут применены.
RISK_CHECKER_KAFKA_AUTH_PASSWORD string да "" Пароль учетной записи Kafka.
RISK_CHECKER_KAFKA_AUTH_PRINCIPAL string нет "" Principal учетной записи Kafka в Kerberos(в случае соединения с kafka через Kerberos).
RISK_CHECKER_KAFKA_AUTH_KEYTAB_PATH string нет "" Путь до keytab-файла(в случае соединения с kafka через Kerberos).
RISK_CHECKER_KAFKA_AUTH_TRUSTSTORE_LOCATION string нет "" Путь до хранилища сертификатов (Java key store). Если путь не указан, то сертификат применятся не будет.
RISK_CHECKER_KAFKA_AUTH_TRUSTSTORE_PASSWORD string нет "" Пароль к хранилищу сертификатов.
RISK_CHECKER_KAFKA_AUTH_MODE string нет "" Режим аутентификации: static - одна учетная запись на все запросы, mapping - учетная запись зависит от запроса
RISK_CHECKER_KAFKA_AUTH_CONFIG string нет "" Настройки для аутентификации: если AuthMode = mapping, то необходим JSON с List[KafkaAuthConfig]
RISK_CHECKER_KAFKA_AUTH_CACHE_SIZE int нет Максимальный размер кеша для Kafka producer (количество активных соединений).
RISK_CHECKER_KAFKA_AUTH_CACHE_TTL duration string нет Время жизни Kafka producer в кеше.
RISK_CHECKER_CONSUL_ADDR url string да "http://localhost:8500" Адрес Сonsul.
RISK_CHECKER_CONSUL_AUTH_USER string да "" Название учетной записи Сonsul. Если название не указано, то настройки авторизации не будут применены.
RISK_CHECKER_CONSUL_AUTH_PASSWORD string да "" Пароль учетной записи Сonsul.
RISK_CHECKER_TRACE_DURATION boolean нет false Признак необходимости трассировки выполнения команд
RISK_CHECKER_DISCOVERABLE_ID string нет "another_RISK_CHECKER_service_instance" ID сервиса в ServiceDiscovery
RISK_CHECKER_DISCOVERABLE_NAME string нет "riskchecker" Имя сервиса в ServiceDiscovery
RISK_CHECKER_DISCOVERABLE_HOST string да "localhost" Хост, публикуемый в ServiceDiscovery. По нему на данный сервис будут обращаться другие через HTTP. Указанный адрес должен быть виден другим сервисам. Пример: имя kubernetes/docker_swarm service
RISK_CHECKER_DISCOVERABLE_PORT int нет Порт, публикуемый в ServiceDiscovery. По нему на данный сервис будут обращаться другие через HTTP. По умолчанию указывается порт, который слушает HTTP-сервер.
RISK_CHECKER_DISCOVERABLE_LIVETIME duration string нет 2 minutes Период после последней отправки health check, в течение которого ServiceDiscovery считает данный сервис живым.
RISK_CHECKER_DISCOVERABLE_HEALTHPASS string нет 1 minute Периодичность отправки health check в ServiceDiscovery
RISK_CHECKER_SERVICE_NAME string нет "risk-checker" Название сервиса для отображения
RISK_CHECKER_SERVICE_DESCRIPTION string нет "Service RISK_CHECKER" Описание сервиса для отображения
RISK_CHECKER_AKKA_HTTP_CLIENT_MAXCON int нет 512 Максимальное число одновременных исходящих HTTP-соединений
RISK_CHECKER_AKKA_HTTP_CLIENT_MAXREQ int нет 1024 Максимальное число одновременных исходящих HTTP-запросов
RISK_CHECKER_AKKA_HTTP_SERVER_MAXCON int нет 1024 Максимальное число одновременных входящих HTTP-соединений
RISK_CHECKER_INTERNALCMD_ALLOW bool нет false Можно ли сервису отправлять внутрисистемные команды
RISK_CHECKER_SENDERLIB_COMMANDS_CACHE_UPDATEPERIOD duration string нет 10 minutes Время кэширования данных по командам из CommandDiscovery
RISK_CHECKER_SENDERLIB_SERVICES_CACHE_UPDATEPERIOD duration string нет 30 seconds Время кэширования данных по сервисам из ServiceDiscovery
RISK_CHECKER_DB_HOST string да Хост БД
RISK_CHECKER_DB_PORT int да Порт БД
RISK_CHECKER_DB_NAME string да Имя базы в БД
RISK_CHECKER_DB_URL jdbc url string нет JDBC-url для соединения с БД. По умолчанию собирается из других обязательных переменных. Можно указать только его, если не хочется отдельно указывать хост/порт/имя базы.
RISK_CHECKER_DB_USER string да Пользователь БД
RISK_CHECKER_DB_PASSWORD string да Пароль пользователя БД
RISK_CHECKER_EXTERNAL_MIGRATIONS_RETRY_DELAY duration string нет 15 seconds Задержка между повторными попытками запуска внешних миграций
RISK_CHECKER_EXTERNAL_MIGRATIONS_RETRY_ATTEMPTS int нет 5 Максимальное количество попыток запуска внешних миграций
RISK_CHECKER_EXTERNAL_MIGRATIONS_SKIP_MIGRATIONS bool нет false Игнорировать ли внешние миграции
RISK_CHECKER_CUSTOM_CHANGE_MIGRATIONS_TIMEOUT duration string нет 3 minutes Максимальное время выполнения одной Liquibase-миграции customChange
RISK_CHECKER_LOG_LEVEL string нет INFO Общий уровень логирования в сервисе
RISK_CHECKER_LOG_LEVEL_AKKA string нет INFO Уровень логирования для akka
RISK_CHECKER_LOG_LEVEL_LIQUIBASE string нет INFO Уровень логирования для liquibase (миграции)
RISK_CHECKER_LOG_LEVEL_APPLICATION string нет INFO Уровень логирования для application
RISK_CHECKER_LOG_LEVEL_SLICK_STATEMENT string нет OFF Уровень логирования SQL-запросов slick в БД
RISK_CHECKER_LOG_LEVEL_SLICK_PARAMETER string нет OFF Уровень логирования параметров запросов slick в БД
RISK_CHECKER_LOG_LEVEL_SLICK_BENCHMARK string нет OFF Уровень логирование времени выполнения запросов slick
RISK_CHECKER_LOG_LEVEL_SLICK_RESULT string нет OFF Уровень логирование первых строк результатов запросов slick
RISK_CHECKER_LOG_LEVEL_KAFKA_PRODUCER string нет WARN Уровень логирования конфига kafka-producer
RISK_CHECKER_LOG_LEVEL_KAFKA_CONSUMER string нет WARN Уровень логирования конфига kafka-consumer
RISK_CHECKER_LOG_LEVEL_AKKAHTTPSENDER string нет INFO Уровень логирования для отправки команд через HTTP. На уровне INFO логируется трассировка, если она включена
RISK_CHECKER_LOG_LEVEL_KAFKASENDER string нет INFO Уровень логирования для отправки команд через Kafka. На уровне INFO логируется трассировка, если она включена
RISK_CHECKER_LOG_LEVEL_COMMANDSTATUSCLI string нет INFO Уровень логирования для проверки состояний команд в сервисе статусов
RISK_CHECKER_LOG_LEVEL_HTTP_CLIENT string нет INFO Уровень логирования HTTP-клиента
RISK_CHECKER_COMPLEX_RISK_PARALLELISM int нет 1 Параллелизм выполнения сложных рисков
RISK_CHECKER_LICENSE_MODE string нет features->default;services->default Описание конфигурации лицензии через ";" в формате: nameOfParameter->valueOfParameter. Конфигурация внутренних сервисов
RISK_CHECKER_REPORT_DATE_PATTERN string нет dd.MM.yyyy Формат записи даты в отчёте по рискам
RISK_CHECKER_REPORT_CLIENT_ZONE_ID string нет Europe/Moscow Таймзона, которая используется при генерации отчета.
RISK_CHECKER_LAMP_HOST url string нет lamp-dev.dev.embedika.ru LAMP: адрес
RISK_CHECKER_LAMP_PORT int нет 443 LAMP: порт
RISK_CHECKER_LAMP_TLS boolean нет false LAMP: использовать защищенное соединение или нет
RISK_CHECKER_LAMP_TIMEOUT duration string нет 1 minute LAMP: таймаут отправки сообщения и получения результатов
RISK_CHECKER_LAMP_EXTRACTION_ROUTE string нет extraction_route LAMP: название маршрута для экстракции
RISK_CHECKER_ML_SERVICES string нет Segmentor,Classifier,Resolver Список ML-сервисов для анализа, разделитель - запятая. Пайплайн выделения сущностей
RISK_CHECKER_ML_SEGMENTOR_URI url string нет http://localhost:2010/segment http-роут сервиса сегментации (Segmentor)
RISK_CHECKER_ML_VECTORIZER_URI url string нет http://localhost:2011/vectorize http-роут сервиса векторизации (Vectorizer)
RISK_CHECKER_ML_CLASSIFIER_URI url string нет http://localhost:2020/predict http-роут сервиса детекции сущностей с помощью классификации (Classifier)
RISK_CHECKER_ML_CLASSIFIER_REPLACE_URI url string нет http://localhost:2021/replace_model http-роут актуализации версий сервиса классификации
RISK_CHECKER_ML_ML_DETECTION_URI url string нет http://localhost:2022/predict http-роут сервиса детекции сущностей с помощью ML-моделей Эмбедики (Ml)
RISK_CHECKER_ML_ML_DETECTION_REPLACE_URI url string нет http://localhost:2023/replace_model http-роут актуализации версий сервиса ML-моделей Эмбедики
RISK_CHECKER_ML_ML_DETECTION_CUSTOMERS_URI url string нет http://localhost:2024/predict http-роут сервиса детекции сущностей с помощью ML-моделей Пользователя (MlCustom)
RISK_CHECKER_ML_ML_DETECTION_CUSTOMERS_REPLACE_URI url string нет http://localhost:2025/replace_model http-роут актуализации версий сервиса ML-моделей Пользователя
RISK_CHECKER_ML_PREAMBLE_DETECTION_URI url string нет http://localhost:2030/predict http-роут сервиса детекции сущностей с помощью преамбул (Preamble)
RISK_CHECKER_ML_REGEXP_DETECTION_URI url string нет http://localhost:2031/predict http-роут сервиса детекции сущностей с помощью регулярных выражений (Regexp)
RISK_CHECKER_ML_NER_DETECTION_URI url string нет http://localhost:2032/predict http-роут сервиса детекции маленьких сущностей (Ner)
RISK_CHECKER_ML_DTWL_DETECTION_URI url string нет http://localhost:2033/predict http-роут сервиса детекции сущностей с помощью алгоритма DTW и расстояния Левенштейна - бывший сервис судов (Dtwl)
RISK_CHECKER_ML_PREDICTION_RESOLVER_URI url string нет http://localhost:2040/resolve http-роут сервиса объединения результатов детекции сущностей (Resolver)
RISK_CHECKER_ML_PREDICTION_FORMATION_URI url string нет http://localhost:2041/form http-роут сервиса формирования предсказаний (Formation)
RISK_CHECKER_ML_SUBENTITIES_DETECTION_URI url string нет http://localhost:2042/predict http-роут сервиса детекции подсущностей (Subentities)
RISK_CHECKER_FS_URI url string да http://localhost:9000 Адрес файлового хранилища S3
RISK_CHECKER_FS_ACCESS_KEY_ID string да minioadmin Идентификатор доступа к S3
RISK_CHECKER_FS_SECRET_ACCESS_KEY string да minioadmin Секретный ключ доступа к S3
RISK_CHECKER_FS_UPLOAD_PARALLELISM int нет 4 Параллелизм загрузки файлов
RISK_CHECKER_FS_CACHE_SIZE int нет 1 Максимальный размер кеша клиентов для хранилища файлов (количество активных соединений)
RISK_CHECKER_FS_CACHE_TTL duration string нет Время жизни клиента в кеше
RISK_CHECKER_FS_CONFIGS_BUCKET string нет configs Название бакета для файлов конфигурации: entities.json, risks.json, requirements.json, template.docx, company_names.txt (ext.)
RISK_CHECKER_FS_MODELS_BUCKET string нет null Название бакета для внешних моделей (результат работы сервиса autoMl)
RISK_CHECKER_FS_TEMP_BUCKET string нет "temp" Название бакета, в котором находятся временные файлы
RISK_CHECKER_FS_ANALYZED_DOCUMENTS_BUCKET string нет null Название бакета для хранения обработанных документов. Если не определено, то сервис не копирует документы в дополнительный бакет.
RISK_CHECKER_FS_BUCKETS_REMOVE_ANALYZED string нет false Удалять документы из S3 после анализа. Защита от несанкционированного доступа в публичном бакете (все, кроме temp) - пока не будет сделана задача SUP-341.
RISK_CHECKER_KAFKA_CONNECTION_CHECK_TEST_MESSAGES_INTERVAL duration string нет 4 minutes Применяется только для producer-ов со способом аутентификации kerberos. Интервал отправки тестовых сообщений кафки в топик connectionCheck.testMessagesTopicName. Тестовые сообщения (null, service producer test) отправляются регулярно с этим интервалом.
RISK_CHECKER_KAFKA_CONNECTION_CHECK_INTERVAL duration string нет 60 seconds Применяется только для producer-ов со способом аутентификации kerberos. Интервал проверки того, сколько тестовых сообщений было отправлено за данный период. Если количество сообщений за этот период равно количеству сообщений за прошлый период, то начинается отсчет периода без сообщений.
RISK_CHECKER_KAFKA_CONNECTION_CHECK_FAILED_AFTER_INTERVAL duration string нет 5 minutes Применяется только для producer-ов со способом аутентификации kerberos. Максимальная продолжительность периода без успешно отправленных тестовых сообщений. По ее достижении сервис будет объявлен больным.
RISK_CHECKER_RATE_LIMITING_CONCURRENCY int нет 10 Ограничение на количество одновременно запущенных проверок документов
RISK_CHECKER_RATE_LIMITING_TIMEOUT duration string нет 1 minute Таймаут на запросы проверки документа.

Команды сервиса анализа

В описании команд используется путь/route для отправки команды в сам сервис, а не в ApiGateway. В качестве Input-а для команд, сервис всегда ожидает CommandRequest (как и любой другой сервис, принимающий команды), так что в описании команды указано лишь описание поля payload для CommandRequest.

В сервисе предусмотрены следующие команды:

Название команды EntityType Actions
—Риск—
Список рисков с указанными ID Risk Contract_ViewRisks
Список рисков Risk Contract_ViewRisks
Добавление/обновление рисков Risk Contract_EditRisk
Изменение простого риска Risk Contract_EditRisk
Изменение комплексного риска Risk Contract_EditRisk
Архивация риска Risk Contract_ArchiveRisk
Активация риска Risk Contract_EditRisk
Создание простого риска Risk Contract_CreateRisk
—Именованная сущность—
Список сущностей с указанными ID NamedEntity Contract_ViewEntities
Список сущностей NamedEntity Contract_ViewEntities
Добавление/обновление сущностей NamedEntity Contract_EditEntity
Создание сущности NamedEntity Contract_CreateEntity
Изменение сущности NamedEntity Contract_EditEntity
Архивация сущности NamedEntity Contract_EditEntity
—Модель—
Список моделей Model Contract_ViewModels
Активация моделей Model Contract_ActivateModels
—Анализ—
Анализ документа Contract_ViewAnalyzer
Выгрузка по анализу документа Contract_ViewAnalyzer
Сортировка результатов анализа Contract_ViewAnalyzer
—Шаблон—
Список шаблонов экспорта Contract_ViewAnalyzer

Сервис публикует события для следующих уведомлений:

Код уведомления EntityType Описание
RiskCreated Risk Создан риск

—Риск—

ListRisksByIds

На входе список ID рисков / На выходе список рисков

[
  "FineFee",
  "ServiceDateSourcesLinksFound"
]

 [
  {
    "riskType": "Simple",
    "name": "Штрафная неустойка",
    "id": "FineFee",
    "degree": "riskDegree_low",
    "documentTypes": [],
    "documentSubjects": [],
    "mutualSettlementsTypes": [],
    "entities": [
      {
        "id": "FineFee",
        "name": "Штрафная неустойка",
        "static": false,
        "parentId": null,
        "found": true
      }
    ],
    "recommendation": "...",
    "requirement": {
      "id": 11,
      "text": "Вместо слова «штрафная» и т.п. неустойка однозначно формулировать условия о взыскании убытков в полной сумме сверх неустойки",
      "name": "1. Чек-лист общий для всех ДД с резидентами",
      "section": "1. Содержание договора",
      "version": 1
    },
    "archived": false,
    "created": "1699440881202",
    "createdBy": "00000000-0000-0000-0000-000000000001",
    "modified": "1699440881202",
    "modifiedBy": "00000000-0000-0000-0000-000000000001",
    "version": 3
  },
  {
    "riskType": "Complex",
    "name": "Сроки определены путем ссылки",
    "id": "ServiceDateSourcesLinksFound",
    "degree": "riskDegree_low",
    "documentTypes": [],
    "documentSubjects": [],
    "mutualSettlementsTypes": [],
    "entities": [
      {
        "id": "ServiceDateSourcesLinksSubNer",
        "name": "Ссылки на другие источники",
        "static": true,
        "parentId": "ServiceDate",
        "found": true
      },
      {
        "id": "ServiceDate",
        "name": "Срок оказания услуг/выполнения работ/поставки",
        "static": false,
        "parentId": null,
        "found": true
      }
    ],
    "recommendation": "...",
    "requirement": {
      "id": 51,
      "text": "\t\nПроверять наличие в договоре условия о начальном и конечном сроках выполнения работ / оказания услуг. Допускается следующие способы обозначения сроков:\n\nпутем указания конкретных календарных дат (с «___» _______ 20__ года по «___» ________ 20__ года);\n\nпутем указания периодов времени, отсчитываемых от «даты заключения договора» или совершения заказчиком определенных действий (например, перечисление аванса или передачи исходных данных. См. постановление Президиума ВАС РФ от 18.05.2010 № 1404/10).",
      "name": "2. Чек-лист Подряд_Услуги",
      "section": "",
      "version": 1
    },
    "archived": false,
    "created": "1699440881202",
    "createdBy": "00000000-0000-0000-0000-000000000001",
    "modified": "1699440881202",
    "modifiedBy": "00000000-0000-0000-0000-000000000001",
    "version": 3
  }
]

Возвращает список рисков с указанными в запросе ID. Могут встречаться риски разных типов. Риски приведены к обобщенному виду.

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

Команда Путь
riskchecker_http_ListRisksByIds HTTP POST "/riskchecker_http_ListRisksByIds"

ListRisks

На входе параметры поиска / На выходе страница рисков

{
  "query": "",
  "context": {},
  "sorting": {},
  "paging": {
    "page": 1,
    "count": 2
  }
}

{
  "items": [
    {
      "riskType": "Simple",
      "name": "Штрафная неустойка",
      "id": "FineFee",
      "degree": "riskDegree_low",
      "documentTypes": [],
      "documentSubjects": [],
      "mutualSettlementsTypes": [],
      "entities": [
        {
          "id": "FineFee",
          "name": "Штрафная неустойка",
          "static": false,
          "parentId": null,
          "found": true
        }
      ],
      "recommendation": "...",
      "requirement": {
        "id": 11,
        "text": "Вместо слова «штрафная» и т.п. неустойка однозначно формулировать условия о взыскании убытков в полной сумме сверх неустойки",
        "name": "1. Чек-лист общий для всех ДД с резидентами",
        "section": "1. Содержание договора",
        "version": 1
      },
      "active": true,
      "archived": false,
      "created": "1699440881202",
      "createdBy": "00000000-0000-0000-0000-000000000001",
      "modified": "1699440881202",
      "modifiedBy": "00000000-0000-0000-0000-000000000001",
      "version": 3
    },
    {
      "riskType": "Complex",
      "name": "Сроки определены путем ссылки",
      "id": "ServiceDateSourcesLinksFound",
      "degree": "riskDegree_low",
      "documentTypes": [],
      "documentSubjects": [],
      "mutualSettlementsTypes": [],
      "entities": [
        {
          "id": "ServiceDateSourcesLinksSubNer",
          "name": "Ссылки на другие источники",
          "static": true,
          "parentId": "ServiceDate",
          "found": true
        },
        {
          "id": "ServiceDate",
          "name": "Срок оказания услуг/выполнения работ/поставки",
          "static": false,
          "parentId": null,
          "found": true
        }
      ],
      "recommendation": "...",
      "requirement": {
        "id": 51,
        "text": "\t\nПроверять наличие в договоре условия о начальном и конечном сроках выполнения работ / оказания услуг. Допускается следующие способы обозначения сроков:\n\nпутем указания конкретных календарных дат (с «___» _______ 20__ года по «___» ________ 20__ года);\n\nпутем указания периодов времени, отсчитываемых от «даты заключения договора» или совершения заказчиком определенных действий (например, перечисление аванса или передачи исходных данных. См. постановление Президиума ВАС РФ от 18.05.2010 № 1404/10).",
        "name": "2. Чек-лист Подряд_Услуги",
        "section": "",
        "version": 1
      },
      "active": true,
      "archived": false,
      "created": "1699440881202",
      "createdBy": "00000000-0000-0000-0000-000000000001",
      "modified": "1699440881202",
      "modifiedBy": "00000000-0000-0000-0000-000000000001",
      "version": 3
    }
  ],
  "total": 47
}

Возвращает список рисков соответствующих параметрам поиска.

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

Команда Путь
riskchecker_http_ListRisks HTTP POST "/riskchecker_http_ListRisks"

Доступные поля для фильтрации:

Поле Виды фильтров
id InSetQuery
name InSetQuery, LikeQuery
documentType InSetQuery
documentSubject InSetQuery
mutualSettlementsType InSetQuery
active InSetQuery
archived InSetQuery
riskType InSetQuery
degree InSetQuery
entityId / entity.id InSetQuery
entity.name InSetQuery, LikeQuery
entity.found InSetQuery
entity.show InSetQuery

Доступные поля для сортировки:

Поле Примечание
name
created По умолчанию, по убыванию

ApplyRiskMigrations

На входе список рисков для системной миграции или null / На выходе список ID созданных/обновленных рисков

[
  {
    "riskType": "SimpleRisk",
    "name": "test1",
    "id": "test1",
    "degree": "riskDegree_low",
    "active": false,
    "documentTypes": [
      "documentType_agreement"
    ],
    "documentSubjects": [
      "documentSubject_contract"
    ],
    "mutualSettlementsTypes": [
      "mutSettlementsType_expandable"
    ],
    "requirementId": 1,
    "entityId": "Unlimited",
    "found": false,
    "recommendation": "none"
  },
  {
    "riskType": "ComplexRisk",
    "name": "test2",
    "id": "test2",
    "degree": "riskDegree_low",
    "active": false,
    "documentTypes": [
      "documentType_agreement"
    ],
    "documentSubjects": [
      "documentSubject_contract"
    ],
    "mutualSettlementsTypes": [
      "mutSettlementsType_expandable"
    ],
    "recommendation": "Any more",
    "entities": [
      "nerField1"
    ]
  }
]

[
  "e326cb31-7098-4137-842e-edb0abd3bbc6",
  "900f42af-0686-4647-aaa4-dd1e6e9f6023"
]

Сохраняет/обновляет риски в базе по Json со стандартными рисками (если передан null) или переданному в аргументах Json. Автор риска помечается ID Системы. Не затрагивает пользовательские данные.

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

Команда Путь
riskchecker_kafka_ApplyRiskMigrations Kafka Topic "risk_checker_commands"

UpdateSimpleRisk

На входе новые данные риска / На выходе ничего

{
  "id": "FineFee",
  "name": "Гига штрафная неустойка",
  "degree": "riskDegree_high",
  "riskInputData": {
    "documentTypes": [
      "documentType_agreement"
    ],
    "documentSubjects": [
      "document",
      ""
    ],
    "mutualSettlementsTypes": []
  },
  "entityId": "FineFee",
  "found": false,
  "recommendation": "...",
  "requirement": {
    "id": 1000001,
    "text": "Очень новый текст требования",
    "name": "1. Очень новое название требования",
    "section": "1. Очень новый раздел требования",
    "version": 1
  },
  "version": 4
}

{}

Команда обновляет простой риск.

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

Команда Путь
riskchecker_kafka_UpdateSimpleRisk Kafka Topic "risk_checker_commands"

UpdateComplexRisk

На входе новые данные риска / На выходе ничего

{
  "id": "WarrantyPeriodParametersMissing",
  "name": "Расторжение без согласия предприятия",
  "degree": "riskDegree_low",
  "riskInputData": {
    "documentTypes": [
      "documentType_agreement"
    ],
    "documentSubjects": [
      "document",
      ""
    ],
    "mutualSettlementsTypes": []
  },
  "entities": [
    {
      "id": "WarrantyPeriod",
      "found": true,
      "show": true
    },
    {
      "id": "WarrantyPeriodParametersSubNer",
      "found": true,
      "show": false
    }
  ],
  "recommendation": "recommendation",
  "requirement": {
    "id": 42,
    "text": "Какое-то требование",
    "name": "Оч строгое требование",
    "section": "Секция лыжных гонок",
    "version": 1
  },
  "version": 1
}

{}

Команда обновляет комплексный риск.

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

Команда Путь
riskchecker_kafka_UpdateComplexRisk Kafka Topic "risk_checker_commands"

SetRiskArchived

На входе id риска и новое значение параметра / На выходе ничего

{
  "riskId": "ContractSubjectMissing",
  "archived": true,
  "version": 7
}

{}

Архивирует или извлекает из архива комплексный или простой риск.

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

Команда Путь
riskchecker_kafka_SetRiskArchived Kafka Topic "risk_checker_commands"

SetRiskStatus

На входе id риска и новое значение active / На выходе ничего

{
  "riskId": "ContractSubjectMissing",
  "active": true,
  "version": 1
}

{}

Активирует или деактивирует риск.

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

Команда Путь
riskchecker_kafka_SetRiskStatus Kafka Topic "risk_checker_commands"

CreateSimpleRisk

На входе id риска и новое значение параметра / На выходе ничего

{
  "id": "HardRisk",
  "name": "Жёсткий риск",
  "degree": "riskDegree_high",
  "entityId": "Unlimited",
  "found": true,
  "show": true,
  "riskInputData": {
    "documentTypes": [
      "documentType_agreement"
    ],
    "documentSubjects": [
      "document",
      "documentSubject_contract"
    ],
    "mutualSettlementsTypes": [
      "mutSettlementsType_expandable"
    ]
  },
  "recommendation": "Жёстко не упускать такого",
  "requirementDto": {
    "text": "Требование очень жёсткое",
    "name": "Название жёсткого требования",
    "section": "1. Очень важная"
  }
}

{}

Добавляет новый простой риск в базу.

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

Команда Путь
riskchecker_kafka_CreateSimpleRisk Kafka Topic "risk_checker_commands"

—Именованная сущность—

ListEntitiesByIds

На входе список ID сущностей / На выходе список сущностей

[
  "Limited",
  "FinancialDocumentDates"
]

[
  {
    "id": "Limited",
    "name": "Ограниченная ответственность",
    "static": false,
    "projects": [],
    "parentId": null,
    "archived": false,
    "created": 1700461709415,
    "createdBy": "00000000-0000-0000-0000-000000000001",
    "modified": 1701838574644,
    "modifiedBy": "00000000-0000-0000-0000-000000000001",
    "version": 2
  },
  {
    "id": "FinancialDocumentDates",
    "name": "Сроки предоставления финансовых документов",
    "static": false,
    "projects": [
      {
        "id": "1032ce5a-afaf-45a6-a1f0-b0ac036de15f",
        "name": "Проект из контракта"
      },
      {
        "id": "1b4dabb3-34ef-4b6d-8205-fa48d730bae0",
        "name": "Еще один проект 25.12"
      }
    ],
    "parentId": null,
    "archived": false,
    "created": 1700461709415,
    "createdBy": "00000000-0000-0000-0000-000000000001",
    "modified": 1701838574644,
    "modifiedBy": "00000000-0000-0000-0000-000000000001",
    "version": 2
  }
]

Возвращает список сущностей с указанными в запросе ID.

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

Команда Путь
riskchecker_http_ListEntitiesByIds HTTP POST "/riskchecker_http_ListEntitiesByIds"

ListEntities

На входе параметры поиска / На выходе страница сущностей

{
  "query": "static",
  "context": {
    "static": {
      "values": [
        "true"
      ],
      "kind": "any"
    }
  },
  "sorting": {
    "fieldName": "name",
    "order": "desc"
  },
  "paging": {
    "page": 1,
    "count": 1
  }
}

{
  "items": [
    {
      "id": "WrongLinks",
      "name": "Противоречие в ссылках",
      "static": true,
      "projects": [],
      "risks": [
        {
          "id": "WrongLinksFound",
          "riskType": "Simple",
          "name": "Найдено противоречие",
          "degree": "riskDegree_high",
          "recommendation": "...",
          "requirementId": 1,
          "active": true,
          "archived": true,
          "created": 1706524099191,
          "createdBy": "00000000-0000-0000-0000-000000000001",
          "modified": 1707125527278,
          "modifiedBy": "00000000-0000-0000-0000-000000000001",
          "version": 3
        }
      ],
      "parentId": null,
      "archived": false,
      "created": 1706524098909,
      "createdBy": "00000000-0000-0000-0000-000000000001",
      "modified": 1706524098909,
      "modifiedBy": "00000000-0000-0000-0000-000000000001",
      "version": 1
    }
  ],
  "total": 14
}

Возвращает страницу сущностей, соответствующих параметрам поиска.

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

Команда Путь
riskchecker_http_ListEntities HTTP POST "/riskchecker_http_ListEntities"

Доступные поля для фильтрации:

Поле Виды фильтров
id InSetQuery
name InSetQuery, LikeQuery
static InSetQuery
parentId InSetQuery
archived InSetQuery
created RangeQuery
modified RangeQuery

Доступные поля для сортировки:

Поле Примечание
name
created По умолчанию, по возрастанию
modified

UploadEntities

На входе ID файла JSON из временного хранилища (список сущностей для импорта NamedEntityUpsertDto) / На выходе количество исходных сущностей, импортированных, не импортированных и список не импортированных сущностей

"a80d49f2-a0f7-444b-a6ae-5d74f71379af"

[
  {
    "id": "Unlimited",
    "name": "Неограниченная ответственность",
    "static": false
  },
  {
    "id": "RetroactiveClause",
    "name": "Ретроактивная оговорка",
    "static": false
  }
]

{
  "input": 29,
  "succeed": 28,
  "failed": 1,
  "failedEntities": [
    {
      "id": "LoanAbsence",
      "name": "Отсутствие коммерческого кредита",
      "static": false
    }
  ]
}

Сохраняет/обновляет сущности в базе из файла JSON.

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

Команда Путь
riskchecker_kafka_UploadEntities Kafka Topic "risk_checker_commands"

CreateEntity

На входе ID и имя сущности / На выходе ничего

{
  "entityId": "LimitedOne",
  "name": "Ограниченная ответственность один"
}

{}

Создаёт новую сущность

Поддерживается асинхронный и синхронный вызов.
Результат выполнения команды журналируется. Синхронизируется с NerSetting в Marker

Команда Путь
riskchecker_kafka_CreateEntity Kafka Topic "risk_checker_commands"

UpdateEntity

На входе ID и новое имя сущности / На выходе ничего

{
  "entityId": "Limited",
  "name": "Ограниченная ответственность",
  "version": 2
}

{}

Изменяет имя сущности

Поддерживается асинхронный и синхронный вызов.
Результат выполнения команды журналируется. Синхронизируется с NerSetting в Marker

Команда Путь
riskchecker_kafka_UpdateEntity Kafka Topic "risk_checker_commands"

SetEntityArchived

На входе id сущности и новое значение параметра / На выходе ничего

{
  "entityId": "ContractSubjectMissing",
  "archived": true,
  "version": 2
}

{}

Архивирует или извлекает из архива сущность.

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

Команда Путь
riskchecker_kafka_SetEntityArchived Kafka Topic "risk_checker_commands"

—Модель—

ListModels

На входе параметры поиска / На выходе страница моделей

{
  "query": "",
  "context": {
  },
  "sorting": {
    "fieldName": "model.number",
    "order": "asc"
  },
  "paging": {
    "page": 1,
    "count": 2
  }
}

{
  "items": [
    {
      "entityId": "ArbitrationClause",
      "nameEntity": "Арбитражная оговорка",
      "models": [
        {
          "modelId": "classifier_ArbitrationClause.catboost",
          "number": 0,
          "name": "Арбитражная оговорка",
          "displayName": "V0 Арбитражная оговорка",
          "recall": 80,
          "precision": 72,
          "fScore": 76,
          "active": false,
          "activated": null,
          "created": 1710502104448,
          "version": 1
        },
        {
          "modelId": "classifier_ArbitrationClause_1.catboost",
          "number": 1,
          "name": "Арбитражная оговорка 1",
          "displayName": "V1 Арбитражная оговорка 1",
          "recall": 90,
          "precision": 90,
          "fScore": 90,
          "active": false,
          "activated": null,
          "created": 1710502104449,
          "version": 1
        }
      ]
    },
    {
      "entityId": "ActionsCoordination",
      "nameEntity": "Согласование действий",
      "models": [
        {
          "modelId": "classifier_ActionsCoordination.catboost",
          "number": 0,
          "name": "Согласование действий",
          "displayName": "V0 Согласование действий",
          "recall": 48,
          "precision": 72,
          "fScore": 58,
          "active": true,
          "activated": null,
          "created": 1710502104448,
          "version": 1
        }
      ]
    }
  ],
  "total": 2
}

Команда позволяет получить список всех/выбранных моделей.

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

Команда Путь
riskchecker_http_ListModels HTTP POST "/riskchecker_http_ListModels"

Доступные поля для фильтрации:

Поле Виды фильтров Описание
nameEntity LikeQuery Фильтрация по названию сущности
entityId InSetQuery Фильтрация по Ids сущностей

Доступные поля для сортировки:

Поле Примечание Описание
nameEntity По умолчанию, по возрастанию Название сущности
model.number Номер модели

ActivateModels

На входе список ID моделей / На выходе ничего

[
  "classifier_ArbitrationClause.catboost"
]

{}

Команда активации моделей разных сущностей

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

Команда Путь
riskchecker_kafka_ActivateModels Kafka Topic "risk_checker_commands"

—Анализ—

GetAnalysis

На входе данные анализируемого документа / На выходе результат анализа

{
  "url": "somebucket/3a0d88fb-42cf-4171-8feb-ed98c01b2da7",
  "originalUrl": "someotherbucket/3a0d88fb-42cf-4171-8feb-ed98c01b2da7",
  "documentType": "documentType_agreement",
  "documentSubject": "documentSubject_contract",
  "mutualSettlementsType": "mutSettlementsType_expandable",
  "templateId": "templateRisks.docx",
  "headerFooter": {
    "defaultHeader": 30.0,
    "defaultFooter": 180.0,
    "pages": [
      {
        "number": 1,
        "header": 50.0,
        "footer": 150.0
      }
    ]
  }
}

[
  {
    "id": "code1",
    "degree": "riskDegree_low",
    "recommendation": "Recommendation 1",
    "riskType": "Simple",
    "name": "RiskStub1",
    "entities": [
      {
        "id": "code11",
        "name": "code11",
        "span": {
          "start": 15,
          "end": 35
        },
        "found": true
      }
    ]
  },
  {
    "id": "code2",
    "degree": "riskDegree_low",
    "recommendation": "Recommendation 2",
    "riskType": "Complex",
    "name": "RiskStub1",
    "entities": [
      {
        "id": "code21",
        "name": "code21",
        "span": {
          "start": 25,
          "end": 35,
          "segments": [
            {
              "start": 25,
              "end": 28
            },
            {
              "start": 32,
              "end": 35
            }
          ]
        }
      },
      {
        "id": "code22",
        "name": "code22",
        "span": null
      }
    ]
  },
  {
    "id": "code4",
    "degree": "riskDegree_low",
    "recommendation": "Recommendation 4",
    "riskType": "Complex",
    "name": "RiskStub4",
    "entities": []
  }
]

Команда запускает процесс анализа документа и возвращает результат. Этот процесс может занимать длительное время, рекомендуется вызывать асинхронно.

Команда может сохранить обрабатываемый документ, если это включено в конфигурации сервиса.

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

Команда Путь
riskchecker_kafka_GetAnalysis Kafka Topic "risk_checker_commands"

ExportAnalysis

На входе результат анализа (с некоторыми изменениями) / На выходе url pdf-файла с выгрузкой

{
  "fileName": "analysis.pdf",
  "templateId": "templateRisks.docx",
  "risks": [
    {
      "id": "stub-2",
      "name": "Право на одностороннее изменение",
      "degree": "riskDegree_low",
      "recommendation": "Убрать право на одностороннее изменение",
      "riskType": "Complex",
      "entities": [
        {
          "id": "nerField22",
          "span": "kzkzkzkzkkляляляяллялял ляляляляля",
          "found": null
        },
        {
          "id": "nerField13",
          "span": "dfhdfhdfhdf  sdgsdg sdf gsd",
          "found": null
        }
      ]
    }
  ]
}

"pdf/b80bd9b1-21e0-4e28-a58e-f695a48d1537"

Команда принимает результат анализа документа и возвращает ссылку на сгенерированный отчет. Входные данные аналогичны результату анализа с одной правкой: в поля "span" нужно указывать конкретные выделенные строки, а не объекты-спаны.

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

Команда Путь
riskchecker_kafka_ExportAnalysis Kafka Topic "risk_checker_commands"

SortAnalysis

На входе список рисков из результата анализа и ID шаблона выгрузки / На выходе упорядоченный список рисков

{
  "templateId": "templateRisks.docx",
  "risks": [
    {
      "id": "code2",
      "degree": "riskDegree_low",
      "recommendation": "Recommendation 2",
      "riskType": "Complex",
      "name": "RiskStub1",
      "entities": [
        {
          "id": "code21",
          "name": "code21",
          "span": {
            "start": 25,
            "end": 35
          }
        },
        {
          "id": "code22",
          "name": "code22",
          "span": null
        }
      ]
    },
    {
      "id": "code1",
      "degree": "riskDegree_low",
      "recommendation": "Recommendation 1",
      "riskType": "Simple",
      "name": "RiskStub1",
      "entities": [
        {
          "id": "code11",
          "name": "code11",
          "span": {
            "start": 15,
            "end": 35
          },
          "found": true
        }
      ]
    },
    {
      "id": "code4",
      "degree": "riskDegree_low",
      "recommendation": "Recommendation 4",
      "riskType": "Complex",
      "name": "RiskStub4",
      "entities": []
    }
  ]
}

[
  {
    "id": "code1",
    "degree": "riskDegree_low",
    "recommendation": "Recommendation 1",
    "riskType": "Simple",
    "name": "RiskStub1",
    "entities": [
      {
        "id": "code11",
        "name": "code11",
        "span": {
          "start": 15,
          "end": 20
        },
        "found": true
      }
    ]
  },
  {
    "id": "code2",
    "degree": "riskDegree_low",
    "recommendation": "Recommendation 2",
    "riskType": "Complex",
    "name": "RiskStub1",
    "entities": [
      {
        "id": "code21",
        "name": "code21",
        "span": {
          "start": 25,
          "end": 35
        }
      },
      {
        "id": "code22",
        "name": "code22",
        "span": null
      }
    ]
  },
  {
    "id": "code4",
    "degree": "riskDegree_low",
    "recommendation": "Recommendation 4",
    "riskType": "Complex",
    "name": "RiskStub4",
    "entities": []
  }
]

Команда сортирует список рисков в соответствии с шаблоном выгрузки.

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

Команда Путь
riskchecker_http_SortAnalysis HTTP POST "/riskchecker_http_SortAnalysis"

—Шаблон—

ListAllTemplates

На входе пустой объект / На выходе список шаблонов

{}

[
  {
    "id": "templateRisks.docx",
    "name": "Шаблон отчета по рискам",
    "default": true,
    "format": "docx",
    "grouping": true,
    "notFoundFirst": true,
    "emptyFragment": "Test",
    "created": 1710502104448,
    "createdBy": "00000000-0000-0000-0000-000000000001",
    "modified": 1710502104448,
    "modifiedBy": "00000000-0000-0000-0000-000000000001",
    "version": 1
  }
]

Команда возвращает список всех шаблонов отчетов.

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

Команда Путь
riskchecker_http_ListAllTemplates HTTP POST "/riskchecker_http_ListAllTemplates"

Маршруты сервиса анализа

Сервис реализует маршруты для прямого обращения ML-сервисов (нельзя отправить такой запрос через ApiGateway).

Путь На входе На выходе Конфигурации Описание
/model-mapping {} Map[string, string] default/extended Маппинг ID сущности -> ID модели Эмбедики
/model-mapping-customers {} Map[string, string] extended Маппинг ID сущности -> ID модели пользователей

Объекты сервиса анализа

Типы данных, которые принимает на вход команд сервис или возвращает в результате работы команды.

—Риск—

Risk

Обобщенный вид для всех типов рисков.

Возможные типы:

В таблице ниже в колонках "Простой" и "Сложный" указано, обязательно ли поле в том или ином типе рисков. Да - обязательно, нет - необязательно, прочерк - отсутствует в рисках данного типа.

Поле Тип Простой Сложный Описание
riskType string да да Тип риска
name string да да Наименование риска
id string да да id риска
degree string да да Степень риска
documentTypes string да да Тип документа
documentSubjects string да да Предмет документа
mutualSettlementsTypes string да да Вид взаиморасчетов
entities NamedEntity[] да да ID сущностей
found boolean да - Найдена или нет
recommendation string да да Рекомендация
requirement Requirement да да Требование чек-листа
active boolean да да Активный ли риск
archived boolean да да Архивирован или нет
created TimeStamp да да Время создания
createdBy UserId да да Кем создан
modified TimeStamp да да Время последнего изменения
modifiedBy UserId да да Кто последний раз изменил
version number да да Версия

Requirement

Информация о требовании чек-листа

Поле Тип Обязательное Описание
id int да Id сущности
text string да Текст требования
name string да Название чек листа
section string да Название раздела чек-листа
version number да Версия

RequirementDto

Информация о требовании чек листа для создания риска

Поле Тип Обязательное Описание
text string да Текст требования
name string да Название чек листа
section string да Название раздела чек-листа

RiskMigrationDto

Общие поля:

Поле Тип Обязательное Описание
riskType "SimpleRisk" или "ComplexRisk" да Какой тип риска
name string да Название риска
id string да id риска
active boolean нет Активный ли риск (при создании дефолтно false)
degree string да Степень риска
recommendation string да Рекомендация
requirementId int да Id требования
documentTypes Map[string, boolean] да Тип документа
documentSubjects Map[string, boolean] да Предмет документа
mutualSettlementsTypes Map[string, boolean] да Вид взаиморасчетов

SimpleRisk:

Поле Тип Обязательное Описание
entityId string да Поле именованной сущности
found boolean да Присутствует ли сущность в тексте

ComplexRisk:

Поле Тип Обязательное Описание
entities Map[String, Boolean] да Поля именованных сущностей и признак, найдена ли она

SetRiskActive (DTO)

Поле Тип Обязательное Описание
riskId string да Id риска
active boolean да Новое значение активности риска
version int да Версия

SetRiskArchived (DTO)

Поле Тип Обязательное Описание
riskId string да Id риска
archived boolean да Новое значение архивности риска
version int да Версия

UpdateSimpleRiskDto

Поле Тип Обязательное Описание
id string да id риска
name string да Название риска
degree string да Степень риска
recommendation string да Рекомендация
requirement Requirement да Требование чек-листа
riskInputData RiskInputData да Данные о документах риска
entityId string да Код сущности
found boolean да Найдена или нет
version int да Версия

UpdateComplexRiskDto

Поле Тип Обязательное Описание
id string да id риска
name string да Название риска
degree string да Степень риска
riskInputData RiskInputData нет Данные о документах риска
entities RiskToEntity[] да Сущности риска
recommendation string да Рекомендация
requirement Requirement да Требование
version int да Версия

CreateSimpleRiskDto

Поле Тип Обязательное Описание
id string да Id риска
name string да Название риска
degree string да Степень риска
entityId string да Код сущности
found boolean да Найдена или нет
show boolean да Показывать или нет
riskInputData RiskInputData да Данные о документах риска
recommendation string да Рекомендация
requirementDto RequirementDto да Требование

RiskInputData

Поле Тип Обязательное Описание
documentTypes string[] да Тип документа
documentSubjects string[] да Предмет документа
mutualSettlementsTypes string[] да Вид взаиморасчетов

RiskStoreDto

Плоское представление риска без связанных объектов

Поле Тип Обязательное Описание
riskType string да Тип риска
name string да Наименование риска
id string да id риска
degree string да Степень риска
recommendation string да Рекомендация
active boolean да Активный ли риск
archived boolean да Архивирован или нет
created TimeStamp да Время создания
createdBy UserId да Кем создан
modified TimeStamp да Время последнего изменения
modifiedBy UserId да Кто последний раз изменил
version number да Версия

—Именованная сущность—

NamedEntity

Информация о сущности

Поле Тип Обязательное Описание
id string да Код сущности
name string да Название сущности
static boolean да Признак привязки к Marker
projects Project[] да Список проектов
archived boolean да Признак архивности
parentId string нет Код родительской сущности
created TimeStamp да Время создания сущности
createdBy UserId да Id пользователя, который создал сущность
modified TimeStamp да Время последнего изменения сущности
modifiedBy UserId да Id пользователя, который последний раз редактировал сущность
version number да Версия объекта
risks List[RiskStoreDto] да Риски использующие эту сущность

NamedEntityUpsertDto

Информация о сущности для импорта

Поле Тип Обязательное Описание
code string да Код сущности
name string да Название сущности
static boolean да Признак привязки к Marker

CreateNamedEntityDto

Информация для изменения имени сущности

Поле Тип Обязательное Описание
entityId string да Id сущности
name string да Название сущности

UpdateNamedEntityDto

Информация для изменения имени сущности

Поле Тип Обязательное Описание
entityId string да Id сущности
name string да Название сущности
version int да Версия

SetEntityArchived (DTO)

Поле Тип Обязательное Описание
entityId string да Id сущности
archived boolean да Новое значение архивности риска
version int да Версия

RiskToEntity

Поле Тип Обязательное Описание
id string да Id сущности
found boolean да Найдено ли условие
show boolean да Показывать ли в результатах

UploadResult

Результат загрузки сущностей из файла

Поле Тип Обязательное Описание
input int да Количество сущностей в файле
succeed int да Количество успешно импортированных сущностей
failed int да Количество сущностей, не найденных в Marker
failedEntities NamedEntityUpsertDto[] нет Список не импортированных сущностей

Project

Информация о проекте

Поле Тип Обязательное Описание
id uuid да ID проекта
name string да Название проекта

—Модель—

ListModelsEntity

Поле Тип Обязательное Описание
entityId string да Id сущности
nameEntity string да Название сущности
models List[ModelVersionInfo] да Модели сущности

ModelVersionInfo

Поле Тип Обязательное Описание
modelId string да Id модели
number int да Номер модели
name string да Название модели
displayName string да Название модели с версией
recall int да Полнота модели
precision int да Точность модели
fScore int да F мера
active boolean да Активность модели
activated TimeStamp нет Дата активации модели
created TimeStamp да Дата обучения модели
version int да Версия

—Анализ—

GetAnalysis (DTO)

Запрос анализа документа

Поле Тип Обязательное Описание
url string да Ссылка на анализируемый файл
originalUrl string нет Ссылка на файл до конвертации в pdf
documentType string нет Тип документа
documentSubject string нет Предмет документа
mutualSettlementsType string нет Вид взаиморасчетов
templateId string нет Id шаблона выгрузки, нужно для первичной сортировки
headerFooter HeaderFooter нет Информация о верхнем и нижнем колонтитуле

RiskAnalysis

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

Поле Тип Обязательное Описание
id string да id риска
degree string да Степень риска
recommendation string да Рекомендация
riskType string да Тип риска
entities AnalysisEntity[] да Список сущностей

AnalysisEntity

Информация о сущности в результате анализа документа

Поле Тип Обязательное Описание
id uuid да ID сущности
span TextSpan нет Позиция в тексте
found boolean да Присутствует ли сущность в тексте (только простые риски)
name string да Название сущности
subNers AnalysisEntity[] нет Список подсущностей сущности
recommendation string нет Рекомендация

TextSpan

Позиция сущности в тексте

Поле Тип Обязательное Описание
start int да Позиция первого символа сущности от начала текста
length int да Длина сущности в символах

HeaderFooter

Информация о колонтитулах документа.

Поле Тип Обязательное Описание
defaultHeader double да Высота верхнего колонтитула по умолчанию
defaultFooter double да Высота нижнего колонтитула по умолчанию
pages PageHeaderFooter да Список страниц

PageHeaderFooter

Информация о колонтитулах страницы

Поле Тип Обязательное Описание
header double да Высота верхнего колонтитула
footer double да Высота нижнего колонтитула
number int да Номер страницы

AnalysisInput

Входные данные для отчета по анализу

Поле Тип Обязательное Описание
fileName string да Имя возвращаемого файла
templateId string нет Id шаблона, который нужно применить к файлу
risks RiskAnalysisInput[] да Выделенные риски

RiskAnalysisInput

Информация по отдельному риску в результате анализа документа (входные данные для отчета)

Поле Тип Обязательное Описание
id string да id риска
degree string да Степень риска
recommendation string да Рекомендация
riskType string да Тип риска
entities AnalysisEntityInput[] да Список сущностей

AnalysisEntityInput

Информация о сущности в результате анализа документа (входные данные для отчета)

Поле Тип Обязательное Описание
id uuid да ID сущности
span string нет Выделенный текст, соответствующий сущности
found boolean да Присутствует ли сущность в тексте (только простые риски)
name string да Название сущности
subNers AnalysisEntityInput[] нет Список подсущностей сущности

SortAnalysisDTO

Поле Тип Обязательное Описание
risks List[RiskAnalysis] да Список рисков
templateId string нет Id шаблона выгрузки

—Шаблон—

TemplateStoreDTO

Поле Тип Обязательное Описание
id string да Id шаблона
name string да Название шаблона
default boolean да Является ли шаблоном по умолчанию
format "docx" \ "pdf" да
grouping boolean да Группировка рисков
notFoundFirst boolean да Показывать ли не найденные риски первыми
emptyFragment string нет Фрагмент для пустого отчета
created TimeStamp да Время создания
createdBy UserId да Кем создан
modified TimeStamp да Время последнего изменения
modifiedBy UserId да Кто последний раз изменил
version int да Версия

Lamp: сервисы интеллектуализации

Фреймворк для интеллектуальных функций. Используется для извлечения исходного текста из PDF-документов.

lamp-router

Сервис выступает точкой входа в систему lamp, принимает запросы и проводит их по маршрутам. Также обеспечивает кэширование.

Локальный запуск сервиса

Для нужд разработки contract и marker достаточно переменных среды:

Переменная Тип Описание
ROUTER_ROUTES json array string Route JSON с описанием маршрутов
ROUTER_SERVICES_JSON json string JSON с указанием адресов сервисов

Взаимодействие с lamp-router

Установка клиента lamp-router

val lampClient: Seq[ModuleID] = Seq(
  "com.embedika.lamp" %% "proto20"       % lamp20ProtoVersion,
  "com.embedika.lamp" %% "lamp20-client" % lamp20ClientVersion,
)

Взаимодействие с lamp-router выполняется через клиент, api клиента довольно простое. Стоит учитывать, что клиент и router не преобразуют данные, поэтому полученные из клиента байты нужно преобразовать согласно используемому маршруту самостоятельно.

Если ответ в формате json, то нужно провести десериализацию, если protobuf, то нужно извлечь данные в подходящий класс.

Модели сервиса lamp-router

Route

Поле Тип Обязательное Описание
name string да Название
nodes Array[ServiceNode \ BeginNode ] да

ServiceNode

Узел для работы с сервисами Lamp

Поле Тип Обязательное Описание
name string да Название
out string да Выход
params Map нет Параметры

BeginNode

Узел с фиксированным именем "begin"

Поле Тип Обязательное Описание
out string да Выход

extraction-pdfium

Сервис извлечения текста из pdf файлов с использованием pdfium.

Локальный запуск сервиса

Поддерживаемые переменные среды:

Переменная Тип Значение по умолчанию Описание
EXTRACTION_PDFIUM_EOL_SEPARATOR string "\u205F" Строка которую нужно заменить на EXTRACTION_PDFIUM_EOL_SEPARATOR_REPLACEMENT
EXTRACTION_PDFIUM_EOL_SEPARATOR_REPLACEMENT string "\u2005" Строка на которую нужно заменить EXTRACTION_PDFIUM_EOL_SEPARATOR
EXTRACTION_PDFIUM_EOL_PAGE_SEPARATOR string "\u205F" Строка через которую склеивается экстракция с разных страниц

Также сервис поддерживает переменные среды play framework.

Параметры маршрутов

В поле params в узле маршрута extraction-pdfium можно указать следующие параметры:

Параметр Тип Обязательное Описание
requestType "proto" \ "file" да
responseType "proto" \ "json" \ "file"

Взаимодействие с extraction-pdfium

Можно работать через lamp-router или напрямую. При работе через lamp-router вызывается метод process.

/process

Принимает MultiPartFormData.

Параметр Тип Описание
data BytesMessage или MultiPartFile Файл pdf в формате protobuf
params Map[String, String] Параметры маршрута

Возвращаемое значение зависит от параметра responseType.

Модели сервиса extraction-pdfium

ExtractionMessage

Поле Тип Обязательное Описание
content string да Текст
fromPdfExtractor true да Секретный параметр, значение которого где-то полезно, но это не точно
Input Output