Разметка

Разметка передаёт в SmartCPD фактический результат вызова и используется для оценки качества и дальнейшего обучения детекции. Назначение разметки, способы сопоставления с вызовом и связь с контрольными группами описаны в разделе «Разметка результатов вызовов» руководства по эксплуатации.

Источники разметки должны быть доверенными и идентифицируемыми. Источником может быть агент, IVR-система, определяющая в том числе факт вступления человека в диалог, или иная внешняя система.

Опциональное поле source позволяет однозначно определить источник, проставивший разметку. Это необходимо для контроля качества данных и возможного исключения ложной или недостоверной разметки на этапе обучения системы детекции. Значение source не обязано быть человекочитаемым: достаточно стабильного уникального идентификатора конкретного источника.

Архитектурная роль и поток данных#

Разметка является внешним фактическим результатом, но технически обрабатывается в общем контуре CDR. В SmartCPD 6.0 отдельного сервиса markup-api нет: Markup API, сопоставление с вызовом и хранение разметки реализованы в cdr-collector.

CDR остается источником основной выборки вызовов в разделе «Статистика». Разметка присоединяется к соответствующему CDR как обогащение и используется для фильтрации, поиска расхождений и анализа качества. Наличие разметки не создает отдельный вызов и не заменяет факты, сохраненные в CDR.

Общий поток обработки:

1. Внешняя система, портал или Markup uploader передает запись в tenant-scoped Markup API.
2. cdr-collector проверяет формат, tenant context и права доступа.
3. Запись сопоставляется ровно с одним существующим CDR того же клиента.
4. После сопоставления cdr-collector сохраняет разметку со внутренней связью по sip_trace_id.
5. Несопоставленные, неоднозначные и повторные записи возвращаются отправителю с кодом причины и не сохраняются как самостоятельные данные.

Внешнему источнику не требуется получать или передавать sip_trace_id. Архитектурное место контура и взаимодействие компонентов описаны в разделе «Контур разметки» документа «Архитектура».

Сопоставление с вызовом и ограничения загрузки#

Разметка сопоставляется с вызовом непосредственно во время загрузки. Каждая запись должна соответствовать ровно одному вызову в CDR того же клиента.

Для одного вызова принимается одна запись разметки. Если разметка для найденного вызова уже сохранена, новая запись отклоняется с кодом duplicate.

Для всех способов сопоставления поиск выполняется только среди вызовов за последние 10 дней относительно момента загрузки. Границы этого интервала рассчитываются по времени сервера CDR Collector и не зависят от переданного клиентом ts. Если ts старше 10 дней, запись отклоняется до поиска вызова с кодом too_old.

Способ сопоставления задаётся полем call_id_type:

Предпочтительно использовать sip или custom: идентификатор позволяет надёжнее связать данные контакт-центра с конкретным вызовом SmartCPD. time_phone предназначен для интеграций, в которых общий идентификатор вызова передать невозможно.

Если подходящий вызов не найден, запись отклоняется с кодом not_found. Если условиям соответствуют несколько вызовов, запись отклоняется с кодом ambiguous.

Результаты разметки#

Поле result содержит нормализованный фактический результат вызова. Поддерживаются следующие значения:

Интеграция разметки должна передавать фактические результаты human и robot: они необходимы для обучения детекции и оценки ошибок первого и второго типа. Остальные результаты сохраняются для статистического анализа и не заменяют обратную связь human и robot.

Необязательное поле original_result содержит исходный бизнес-результат вызова из системы — источника разметки. Оно может использоваться для выявления потенциально недостоверных данных. Например, если исходный результат подразумевает разговор с человеком, а в поле result передано значение robot, такое расхождение является основанием дополнительно проверить достоверность разметки.

Способы загрузки#

API#

Для интеграции внешней системы с SmartCPD разметку можно передавать в формате JSON через Markup API. Методы, авторизация, ограничения запросов и форматы ответов описаны в разделе «Markup API» документа External API.

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

CSV#

CSV-файл можно загрузить в разделе «Статистика» портала. Актуальный пример файла доступен там же по кнопке Скачать шаблон.

Состав и правила заполнения столбцов приведены в справочнике полей. Требования к запросу и формат CSV-ответа с отклонёнными или необработанными строками описаны в разделе «Загрузка CSV» документа External API.

Контейнер Markup uploader#

Для регулярного получения разметки из системы заказчика используется cdr-collector-markup-uploader. Он читает новые строки из подготовленного представления или таблицы в PostgreSQL или Oracle и передаёт их в Markup API.

Требования к источнику данных и правила последовательного чтения описаны в разделе «Markup uploader».

Markup uploader#

cdr-collector-markup-uploader — контейнер для автоматической загрузки разметки из базы данных в SmartCPD. Он последовательно читает новые строки из заранее подготовленного и определённым образом структурированного представления или таблицы, а затем пакетами передаёт их в Markup API.

Контейнер можно развернуть:

• в составе стека SmartCPD;
• отдельно от стека, в инфраструктуре заказчика.

Отдельное размещение подходит, в частности, для интеграции с облачной установкой SmartCPD: uploader получает данные непосредственно из базы данных заказчика и передаёт их в SmartCPD через публичный сетевой интерфейс.

Для одной установки SmartCPD можно запустить несколько независимых экземпляров uploader. Это необходимо, если разметка поступает из нескольких баз данных, представлений или таблиц либо для источников используются разные способы сопоставления с вызовом. Например, один экземпляр может загружать разметку по SIP Call-ID, другой — по идентификатору из отдельного SIP-заголовка, а третий — по времени и номеру телефона.

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

Потребление ресурсов#

Значения приведены для одного экземпляра контейнера cdr-collector-markup-uploader:

• RAM: ориентировочно 60 MB.
• CPU: потребление незначительно; выделение отдельного vCPU не требуется.

Требования к базе данных и источнику#

Uploader поддерживает:

• PostgreSQL версии 14 и выше;
• Oracle Database 12c и выше.

Для подключения к Oracle используется формат Easy Connect вида host:port/service_name. Подключение через локальную конфигурацию TNS не поддерживается.

Источником разметки может быть представление или таблица. Имя источника задаётся при настройке экземпляра uploader; при необходимости его можно указать вместе со схемой, например integration.scpd_markup.

Тип сопоставления применяется ко всем строкам источника и задаётся в настройках экземпляра uploader; отдельный столбец call_id_type в источнике не требуется.

Для строковых значений действуют те же ограничения и допустимые значения, что и для API. Источник может содержать дополнительные столбцы: uploader их не обрабатывает.

При запуске uploader проверяет в метаданных источника наличие всех обязательных столбцов и опционального столбца source. Если обязательного столбца нет или метаданные прочитать невозможно, uploader завершает работу с ошибкой. Если отсутствует только source, разметка загружается без источника. Пользователю БД необходим доступ к метаданным источника.

Последовательная выборка по ts#

Поле ts используется не только для сопоставления разметки с вызовом, но и как курсор последовательного чтения источника данных. Uploader считает значения ts монотонно возрастающими: после обработки строки следующая выборка начинается со значений, которые больше последнего сохранённого ts.

При каждом запуске цикла выбираются строки из интервала:

ts > last_processed_ts AND ts <= now - delay

Параметр DELAY_LAG задаёт задержку между текущим временем и верхней границей выборки. По умолчанию она составляет 30 секунд. Такая задержка позволяет компенсировать допустимые колебания времени появления новых строк: uploader не приближается к текущему времени ближе заданного интервала и даёт источнику завершить формирование записей.

Строки читаются по возрастанию ts, а после успешной обработки сохраняется максимальный обработанный ts. Строка, которая появилась позднее со значением ts, меньшим либо равным сохранённому курсору, выбрана не будет. Поэтому DELAY_LAG необходимо устанавливать не меньше максимальной ожидаемой задержки появления строки, а уже доступные строки не должны изменять ts.

То же ограничение относится к позднему изменению result, original_result или source в уже обработанной строке: uploader не перечитывает пройденный диапазон.

Запрос с фильтрацией и сортировкой по ts должен выполняться эффективно; обычно для этого требуется соответствующий индекс в исходных таблицах.

Хранение состояния и проблемных записей#

Для штатной эксплуатации uploader необходим постоянный (persistent) каталог, заданный переменной DATA_DIR. В нём сохраняется файл last.processed.json с позицией последней обработанной записи. После перезапуска или пересоздания контейнер продолжает чтение с сохранённой позиции.

Если persistent-каталог отсутствует или его содержимое потеряно, uploader не может восстановить предыдущую позицию и начинает чтение с глубины, заданной параметром INIT_LOOKBACK. Для каждого экземпляра uploader необходимо использовать отдельный каталог.

Каталог DATA_DIR можно разместить:

• в именованном Docker volume;
• в отдельном каталоге хоста через bind mount;
• в общем persistent-хранилище, доступном ноде размещения контейнера.

При включённом параметре SAVE_REJECTED uploader создаёт внутри DATA_DIR подкаталог rejected и сохраняет в нём отклонённые и необработанные записи. Вместе с исходными данными сохраняются статус и причина обработки, что позволяет проанализировать проблемные записи и при необходимости исправить источник данных или настройки интеграции.

Установка в стек SmartCPD#

Этот вариант предназначен для установки uploader в том же окружении, где развёрнут контур SmartCPD. Контейнер запускается как сервис Docker Swarm в составе стека: он автоматически запускается вместе со стеком, а Docker Swarm управляет его перезапуском и размещением. Логи сервиса попадают во встроенный контур observability SmartCPD.

Параметры самого контура берутся из общей конфигурации SmartCPD. К ним относятся имя стека, версия образа, каталог общих данных, URL Markup API, настройки proxy и доверенного сертификата, а также runtime-параметры, включая UID и GID пользователя контейнера. При изменении этих параметров достаточно повторно сгенерировать и применить конфигурацию основного стека; повторно настраивать каждый экземпляр uploader не требуется.

Каталог для данных uploader создаётся node setup-скриптами в Shared data root. Если установка SmartCPD выполнена по штатной процедуре и сгенерированные node setup-скрипты применены, создавать каталог или настраивать права вручную не требуется.

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

1. Развернуть SmartCPD и убедиться, что стек работает.
2. Подготовить источник данных в соответствии с требованиями к базе данных и источнику.
3. В портале SmartCPD создать API-ключ с привилегией cdr.canEdit. Порядок создания и использования API-ключей описан в разделе «Авторизация» документа External API.
4. Подготовить параметры подключения и учётные данные пользователя БД, имеющего доступ на чтение строк и метаданных источника.
5. Определить глубину первой выборки. Она не должна превышать 240 часов.

Настройка выполняется на manager-ноде Docker Swarm из каталога setup установленного SmartCPD:

./smartcpd-markup-uploader-setup.sh

Скрипт запрашивает:

• имя экземпляра uploader;
• тип, адрес, порт, имя сервиса или базы данных и часовой пояс БД;
• имя пользователя и пароль БД;
• имя представления или таблицы;
• способ сопоставления разметки;
• API-ключ SmartCPD;
• глубину первой выборки.

Имя экземпляра по умолчанию — default. Для каждого дополнительного источника или способа сопоставления скрипт нужно запустить повторно и указать новое уникальное имя.

Для каждого экземпляра рядом со скриптом создаётся файл:

smartcpd-markup-uploader-<instance>.env

Файл содержит настройки экземпляра и ссылки на созданные Docker secrets. Пароли и API-токены непосредственно в нём не сохраняются.

После настройки экземпляров необходимо заново сгенерировать конфигурацию и применить стек:

./smartcpd-setup.sh generate
./smartcpd-setup.sh deploy

Команда generate находит все файлы smartcpd-markup-uploader-*.env, формирует для них сервисы и добавляет их в итоговую конфигурацию стека.

Дополнительные параметры#

Дополнительные параметры контейнера, в том числе расширенные параметры подключения к БД, задаются для соответствующего сервиса через compose.override.yml. Общий механизм описан в разделе «Использование compose.override.yml» документа по установке.

Доступные переменные окружения перечислены в справочнике переменных Markup uploader.

Удаление экземпляра#

Чтобы удалить экземпляр uploader:

1. Удалить его файл конфигурации:

   rm smartcpd-markup-uploader-<instance>.env

2. Удалить соответствующий сервис Docker Swarm и убедиться, что он отсутствует:

   docker service rm <stack_name>_markup-uploader-<instance>
   docker service ls --filter name=<stack_name>_markup-uploader-<instance>

3. Обновить сгенерированную конфигурацию:

   ./smartcpd-setup.sh generate

После ручного удаления сервиса выполнять deploy не требуется. Команда generate удаляет экземпляр из итоговой конфигурации и предотвращает его повторное создание при следующем deployment стека.

Независимая установка#

Независимая установка применяется, когда uploader необходимо разместить вне окружения SmartCPD. Например:

• источник данных находится в отдельном сетевом контуре;
• заказчик использует облачную установку SmartCPD;
• база данных с разметкой доступна из инфраструктуры заказчика, но недоступна непосредственно из сети SmartCPD.

В этом варианте контейнер подключается к базе данных в локальном контуре источника и передаёт разметку в SmartCPD через публичную сеть. Для подключения к публичному интерфейсу SmartCPD необходимо использовать HTTPS. Шифрование и проверка TLS-сертификата выполняются в соответствии с конфигурацией публичного интерфейса SmartCPD.

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

1. Подготовить источник данных в соответствии с требованиями к базе данных и источнику.
2. В портале SmartCPD создать API-ключ с привилегией cdr.canEdit.
3. Подготовить параметры подключения и учётные данные пользователя БД, имеющего доступ на чтение строк и метаданных источника.
4. Определить способ сопоставления и глубину первой выборки. Глубина не должна превышать 240 часов.

В приведённом ниже примере указана версия образа для SmartCPD 6.0.0. Актуальная версия для устанавливаемого релиза указывается в Release Notes и в переменной CDR_COLLECTOR_MARKUP_UPLOADER_VERSION файла versions.env, входящего в поставку SmartCPD.

Создайте файл compose.yml:

services:
  markup-uploader:
    image: cr.repo.altuera.ru/smartcpd/prod/cdr-collector-markup-uploader:6.0.0
    restart: unless-stopped
    environment:
      LOG_LEVEL: info
      LOG_FORMAT: plain

      DB_ENGINE: postgres
      DB_TZ: Europe/Moscow
      DB_HOST: db.example.com
      DB_PORT: "5432"
      DB_NAME: customer
      DB_USER: smartcpd_markup
      DB_PASSWORD: "change-me"
      DB_VIEW_NAME: integration.scpd_markup

      CALL_ID_TYPE: sip
      INIT_LOOKBACK: 24h

      MARKUP_API_URL: https://smartcpd.example.com/api/cdr
      MARKUP_API_TOKEN: "change-me"

      DATA_DIR: /data
      SAVE_REJECTED: "true"
    volumes:
      - markup-uploader-data:/data

volumes:
  markup-uploader-data:
    # Чтобы использовать bind mount вместо Docker volume,
    # создайте каталог на хосте и раскомментируйте параметры:
    # driver: local
    # driver_opts:
    #   type: none
    #   o: bind
    #   device: /opt/smartcpd/markup-uploader-data

Замените в примере:

• параметры DB_* — на параметры подключения к базе данных источника;
• DB_VIEW_NAME — на имя подготовленного представления или таблицы;
• CALL_ID_TYPE — на используемый способ сопоставления;
• INIT_LOOKBACK — на необходимую глубину первой выборки;
• MARKUP_API_URL — на публичный адрес SmartCPD с путём /api/cdr;
• MARKUP_API_TOKEN — на созданный в портале API-ключ.

Файл compose.yml содержит пароль БД и API-ключ в открытом виде. Ограничьте доступ к нему средствами файловой системы хоста.

Запустите контейнер:

docker compose up -d

По умолчанию Compose создаёт именованный Docker volume markup-uploader-data. Чтобы сразу хранить данные в заданном каталоге хоста, перед первым запуском создайте этот каталог и раскомментируйте driver и driver_opts в объявлении volume.

Для тонкой настройки добавьте необходимые переменные непосредственно в секцию environment файла compose.yml. Полный перечень приведён в справочнике переменных Markup uploader.

Обновление независимой установки#

Обновление независимо установленного uploader следует выполнять с учётом требований соответствующего релиза из Release Notes и общего документа «Обновление SmartCPD».

Как минимум необходимо изменить тег образа в compose.yml на актуальную версию из поставочного файла versions.env, а затем загрузить образ и пересоздать сервис:

docker compose pull
docker compose up -d

Persistent volume с каталогом DATA_DIR при таком обновлении сохраняется и продолжает содержать текущую позицию чтения.

Справочники#

Поля API и CSV#

Размер каждого строкового значения не должен превышать 4 KiB. Для JSON API дополнительные неизвестные поля не допускаются, а для CSV допустимы только перечисленные поля и служебные столбцы upload_status и reason.

Коды обработки#

При частично успешной загрузке JSON API возвращает записи в массивах rejected и unprocessed. В CSV для тех же состояний используется столбец upload_status:

Поле reason содержит код причины:

rejected является окончательным результатом обработки конкретной записи в рамках запроса. unprocessed не означает отклонение: после внутренней ошибки обработка пакета прекращается, а результат для оставшихся записей ещё не определён.

При автоматической загрузке из БД uploader останавливает текущий цикл, сохраняет позицию перед первой записью unprocessed и начинает следующую загрузку с неё. Отклонённые и необработанные записи сохраняются в каталоге rejected; поле status позволяет отличить окончательно отклонённые записи от необработанных. Вместе с исходными полями сохраняются index, status и reason.

Переменные окружения Markup uploader#

В таблицах перечислены переменные окружения контейнера cdr-collector-markup-uploader. Значения интервалов времени задаются в формате Go duration, например 30s, 15m или 24h.

Обработка разметки и хранение состояния#

Если DATA_DIR не задан или его содержимое не сохраняется, после перезапуска uploader теряет сохранённую позицию и снова начинает чтение на глубине INIT_LOOKBACK. Для каждого экземпляра uploader необходимо использовать отдельный persistent-каталог.

Markup API#

Для передачи токена достаточно одной из переменных MARKUP_API_TOKEN или MARKUP_API_TOKEN_FILE.

Подключение к базе данных#

HTTP, TLS и proxy#

Логирование#