UniBPM AI Integration Guide

Назначение

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

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

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

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

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

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

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

Пример:

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

Архитектура

BPMN Process ↓ External Task (ai.extract) ↓ unibpm-integration-runtime ↓ unibpm-external-task-ai ↓ unibpm-ai-core ↓ LLM (OpenAI)

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

BPMN

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

unibpm-integration-runtime

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

unibpm-external-task-ai

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

unibpm-ai-core

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

OpenAI

выполняет AI-запросы
требует API-ключ

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

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

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

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

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

данные заявки (Ticket)
вложения
(в будущем) комментарии

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

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

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

Контекст включается через 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)

⚠️ Важно

На текущий момент:

загрузка комментариев временно отключена
причина — несовместимость OpenAPI-контракта (PageComment.sort)

Рекомендуется использовать:

uni.context.comments.limit=0

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

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

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

GET /api/attachment/read/{attachmentId}

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

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

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

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

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

→ AI может:

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

Паттерны

AI Extract

text → structured JSON

Настройка

application.yaml

unibpm: integration: connectors: ai: enabled: true ai: openai: api-key: ${OPENAI_API_KEY} base-url: https://api.openai.com model: gpt-4.1-mini temperature: 0.2 max-tokens: 1000 timeout-seconds: 30

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

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

Extension Properties

ai.in.promptKey=inbox-triage ai.in.input=${input} ai.in.schema=${schema}

Промпты

Хранятся в UniBPM как DefinitionType.PROMPT. Формат — Markdown.

Результат

{ “success”: true, “result”: {…}, “model”: “gpt-4.1-mini” }

Мониторинг

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

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

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

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

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

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

Стоимость

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

Roadmap

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