UniBPM AI Integration Guide

Назначение

Данная документация описывает интеграцию AI (LLM) в UniBPM:

автоматическая обработка текстов
классификация и маршрутизация заявок
извлечение структурированных данных
генерация писем, комментариев и документов
подготовка данных для принятия решений в BPMN

Документ предназначен для:

DevOps инженеров
системных администраторов
аналитиков и архитекторов процессов

Зачем это нужно

AI в UniBPM используется для:

автоматической классификации входящих обращений
извлечения структурированных данных из текста
подготовки данных для принятия решений в BPMN
генерации ответов клиентам
подготовки внутренних комментариев
формирования описаний задач
создания текстовых документов и шаблонов
снижения нагрузки на операторов

Пример:

“Прошу выставить счет на оплату лицензии” → classification = PAYMENT_REQUEST

Архитектура

BPMN Process ↓ External Task (ai.extract / ai.generate) ↓ unibpm-integration-runtime ↓ unibpm-external-task-ai ↓ unibpm-ai-core ↓ LLM Provider ↓ OpenAI | YandexGPT

Основные компоненты

BPMN

определяет бизнес-процесс
вызывает AI через Service Task

unibpm-integration-runtime

исполняет External Task
управляет воркерами

unibpm-external-task-ai

реализует AI-обработчики
поддерживает действия:
- ai.extract
- ai.generate
- (в будущем) ai.decide

unibpm-ai-core

взаимодействие с LLM
работа с промптами
единый формат результата

LLM Provider

UniBPM поддерживает подключение различных LLM-провайдеров.

На текущий момент поддерживаются:

OpenAI
YandexGPT

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

Каждый провайдер требует собственные параметры подключения (API-ключ, модель и т.д.).

Как это работает

BPMN вызывает Service Task (ai.extract или ai.generate)
External Task Worker получает задачу
Загружается prompt (inline или по promptKey)
Формируется запрос к LLM
Получается ответ
Результат сохраняется в переменные процесса

Контекст выполнения (AI Context)

Зачем нужен контекст

В ряде сценариев AI должен анализировать не только входной текст, но и связанные бизнес-данные:

данные заявки (Ticket)
комментарии (Comment)
вложения (Attachment)

Это позволяет:

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

Как включить контекст

Контекст включается через Extension Properties в BPMN:

uni.context=true
uni.context.comments.limit=0
uni.context.attachments.limit=3

Что происходит при выполнении

Если uni.context=true, runtime:

Определяет ticketId из External Task
Загружает данные заявки (Ticket)
Загружает комментарии заявки
Загружает вложения (метаданные)
Передаёт контекст в AI-обработчик

Ограничения

uni.context.comments.limit — количество комментариев (по умолчанию 0)
uni.context.attachments.limit — количество вложений (по умолчанию 0)
значение 0 означает, что соответствующие данные не загружаются в контекст
значение N > 0 означает, что загружается не более N объектов

Работа с вложениями

В AI-контекст передаются только метаданные вложений.

Для получения содержимого используется API:

GET /api/attachment/read/{attachmentId}

В типовом сценарии:

выбираются релевантные вложения (например, PDF резюме)
содержимое извлекается
преобразуется в plain text
добавляется в prompt

Практический пример

Использование контекста для обработки заявки:

input: текст обращения
context:
- ticket (описание, поля)
- comments (история обсуждения)
- attachments (резюме, документы)

→ AI может:

классифицировать заявку
извлечь данные из вложений
подготовить summary

Паттерны

AI Extract

text → structured JSON

AI Generate

input + prompt → generated text

Используется для:

подготовки писем
подготовки комментариев
генерации описаний задач
генерации документов и шаблонов

Результатом является текст, сформированный LLM.

Настройка

application.yaml

unibpm:
  integration:
    connectors:
      ai:
        enabled: true

  ai:
    provider: openai

    openai:
      api-key: ${OPENAI_API_KEY}
      base-url: https://api.openai.com
      model: gpt-5.4-mini
      temperature: 0.2
      max-tokens: 1000
      timeout-seconds: 30

Выбор LLM-провайдера

UniBPM поддерживает несколько LLM-провайдеров.

Выбор выполняется через свойство:

unibpm.ai.provider=openai

Поддерживаемые значения:

openai
yandex

Пример конфигурации YandexGPT:

unibpm:
  ai:
    provider: yandex

    yandex:
      api-key: ${YANDEX_API_KEY}
      project-id: ${YANDEX_PROJECT_ID}
      base-url: https://ai.api.cloud.yandex.net
      model: yandexgpt-5.1/latest
      temperature: 0.3
      max-tokens: 1000
      timeout-seconds: 30

Использование в BPMN

AI Extract

uni.connector=ai
uni.action=extract
uni.version=v1

AI Generate

uni.connector=ai
uni.action=generate
uni.version=v1

Extension Properties

Обязательные

uni.connector=ai
uni.action=<extract|generate>

Настройка prompt

ai.in.promptKey=inbox-triage

или

ai.in.promptText=Classify incoming request

Дополнительно может использоваться:

ai.in.promptVersion=v1

Источник входных данных

ai.in.input=${input}

или

uni.context=true

Схема результата

ai.in.schema=${schema}

Выходная переменная

ai.out.result=classificationResult

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

ai.in.model=gpt-5.4-mini
ai.in.temperature=0.2
ai.in.maxTokens=1000

Параметры являются необязательными.

Если они не указаны, используются значения из application.yaml.

Пояснение параметров модели

ai.in.model — идентификатор модели LLM, которая будет использоваться для выполнения запроса.
ai.in.temperature — степень вариативности ответов модели.
- 0.0–0.3 — максимально предсказуемые и стабильные ответы.
- 0.4–0.7 — умеренная вариативность.
- 0.8+ — более творческие и менее предсказуемые ответы.
Для задач классификации и извлечения данных рекомендуется использовать значения 0.0–0.3.
ai.in.maxTokens — максимальное количество токенов, которое модель может сгенерировать в ответе. Ограничивает размер результата и помогает контролировать стоимость запросов.

Токен — условная единица текста, используемая LLM для подсчёта объёма входных и выходных данных.

Источник входных данных (input)

AI-операции (extract и generate) могут получать входные данные двумя способами.

Вариант 1. Переменная процесса

ai.in.input=${input}

В этом случае в AI передаётся содержимое переменной процесса input.

Вариант 2. Контекст заявки

uni.context=true

Если свойство ai.in.input отсутствует или пустое, входные данные автоматически формируются из контекста заявки (при условии, что включён uni.context=true).

Приоритет источников данных:

ai.in.input
uni.context=true

Если не указан ни один источник данных, выполнение задачи завершится ошибкой конфигурации.

Формат контекста

При использовании uni.context=true AI получает структуру вида:

{
  "ticketId": "...",
  "ticket": { ... },
  "comments": [
    {
      "id": "...",
      "body": "Комментарий пользователя"
    }
  ],
  "attachments": [
    {
      "id": "...",
      "fileName": "resume.pdf",
      "contentType": "application/pdf"
    }
  ]
}

Схема результата (schema)

Данный раздел относится только к операции ai.extract.

Свойство ai.in.schema определяет структуру JSON, которую должна вернуть модель.

Свойство ai.in.schema используется только для операции ai.extract.

Для операции ai.generate схема результата не используется.

Пример:

{
  "type": "object",
  "properties": {
    "classification": {
      "type": "string"
    },
    "summary": {
      "type": "string"
    }
  }
}

Рекомендуется всегда задавать schema для операций извлечения данных. Это существенно повышает предсказуемость ответа модели.

Типовой сценарий классификации заявки

Создается заявка.
Заявка запускает BPMN-процесс.
Процесс вызывает Service Task ai.extract.
AI анализирует текст заявки и доступный контекст.
AI возвращает:
- classification
- summary
BPMN использует classification для дальнейшей маршрутизации через Gateway.

Пример:

ACCESS_RESTORE → группа поддержки доступа

PAYMENT_REQUEST → финансовый отдел

VACATION_REQUEST → HR

Полный пример AI Extract

Переменные процесса

{
  "input": {
    "subject": "Не могу войти в систему",
    "body": "После смены пароля перестал работать вход"
  },
  "schema": {
    "type": "object",
    "properties": {
      "classification": {
        "type": "string"
      },
      "summary": {
        "type": "string"
      }
    }
  }
}

Extension Properties

uni.connector=ai
uni.action=extract
uni.version=v1

ai.in.promptKey=aiExtract
ai.in.input=${input}
ai.in.schema=${schema}

ai.out.result=classificationResult

Результат

После выполнения Service Task в переменную classificationResult будет сохранён объект AiExecutionResult.

Полный пример AI Generate

Переменные процесса

{
  "input": {
    "clientMessage": "Здравствуйте, хочу узнать подробнее про UniBPM"
  }
}

Extension Properties

uni.connector=ai
uni.action=generate
uni.version=v1

ai.in.promptKey=replyToCustomer
ai.in.input=${input}

ai.out.result=generatedResult

Результат

После выполнения Service Task в переменную generatedResult будет сохранён объект AiExecutionResult.

Пример:

{
  "success": true,
  "result": {
    "text": "Здравствуйте! Спасибо за интерес к UniBPM..."
  },
  "model": "gpt-5.4-mini"
}

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

${generatedResult.result.text}

Результат

Результат операции сохраняется в переменную процесса, указанную в ai.out.result.

Пример ответа:

{
  "success": true,
  "result": {
    "classification": "PAYMENT_REQUEST",
    "summary": "Запрос на оплату лицензии"
  },
  "model": "gpt-5.4-mini",
  "usage": {
    "inputTokens": 123,
    "outputTokens": 25,
    "totalTokens": 148
  }
}

Поле result содержит результат выполнения AI-операции.

Для ai.extract:

содержит данные, извлечённые согласно schema.

Для ai.generate:

содержит сгенерированный текст;
текст доступен в поле result.text.

Статистика использования токенов

Поле usage содержит информацию о расходе токенов:

inputTokens — количество токенов, переданных модели во входном запросе (prompt, input, контекст, схема результата).
outputTokens — количество токенов, сгенерированных моделью в ответе.
totalTokens — суммарное количество токенов (inputTokens + outputTokens).

Эти показатели полезны для:

контроля стоимости использования LLM;
анализа производительности запросов;
поиска слишком больших prompt или контекстов.

Для получения непосредственно извлечённых данных обычно используется:

${classificationResult.result}

Например:

{
  "classification": "ACCESS_RESTORE",
  "summary": "Запрос на восстановление доступа"
}

Дополнительно могут возвращаться:

success — признак успешного выполнения
rawText — исходный ответ модели
model — использованная модель
promptKey — идентификатор промпта
promptVersion — версия промпта
usage — статистика использования токенов
error — информация об ошибке при неуспешном выполнении

Мониторинг

Отслеживать:

ошибки
таймауты
время ответа

Типовые ошибки

apiKey не задан
prompt не найден
timeout
некорректный JSON

Масштабирование

горизонтально через runtime
увеличение числа воркеров

Стоимость

Зависит от количества запросов и токенов

Roadmap

ai.decide
structured generation
retry
кэширование
аудит

UniBPM AI Integration Guide

Назначение

Зачем это нужно

Архитектура

Основные компоненты

BPMN

unibpm-integration-runtime

unibpm-external-task-ai

unibpm-ai-core

LLM Provider

Как это работает

Контекст выполнения (AI Context)

Зачем нужен контекст

Как включить контекст

Что происходит при выполнении

Ограничения

Работа с вложениями

Практический пример

Рекомендации

Паттерны

AI Extract

AI Generate

Настройка

application.yaml

Выбор LLM-провайдера

Использование в BPMN

AI Extract

AI Generate

Extension Properties

Обязательные

Настройка prompt

Источник входных данных

Схема результата

Выходная переменная

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

Пояснение параметров модели

Источник входных данных (input)

Вариант 1. Переменная процесса

Вариант 2. Контекст заявки

Формат контекста

Схема результата (schema)

Типовой сценарий классификации заявки

Полный пример AI Extract

Переменные процесса

Extension Properties

Результат

Полный пример AI Generate

Переменные процесса

Extension Properties

Результат

Результат

Статистика использования токенов

Мониторинг

Типовые ошибки

Рекомендации

Масштабирование

Стоимость

Roadmap