Skip to Content
Primo RPA AI ServerРазработчикамПошаговое руководство по APIЗадачи NLP

Задачи NLP

Описание

Взаимодействие с компонентом Задачи NLP выполняется в несколько этапов:

  1. Проверяется доступность навыка распознавания документа для указанного ключа маршрутизации.
  2. После отправки запроса возвращается идентификатор задачи.
  3. Необходимо периодически проверять список готовых запросов, пока идентификатор задачи не появится в списке.
  4. После завершения обработки можно получить данные NLP-запроса по его идентификатору.

Ключ маршрутизации

Для обработки запроса необходимо указать ключ маршрутизации. Он передаётся в параметре modelType маршрута запроса:

POST /inference/nlp/{modelType}/async

Ключ маршрутизации можно получить в Портале при создании навыка.

Если указать ключ маршрутизации, который не настроен на сервере, запрос завершится ошибкой.

Авторизация

Каждый запрос в данном разделе требует указания заголовка Authorization. Подробнее см. в разделе Авторизация.

Проверка готовости навыка

Проверка готовности навыка выполняется методом:

GET /inference/nlp/{modelType}/status

В параметре маршрута modelType необходимо указать ключ маршрутизации. Например: nlp-extr-xxxx для навыка Экстракция, где xxxx — произвольное сочетание цифр и латинских букв.

Пример запроса:

GET /inference/nlp/{modelType}/status HTTP/1.1
Host: ai-server-endpoint:44392
Accept: text/plain
Authorization: ••••••

Если модель готова принимать запросы, сервер вернёт JSON следующего вида:

{
    "isServerLicensed": true,
    "isModelTypeRunning": true,
    "isAgentLicensed": true
}

Описание полей ответа:

  • isServerLicensed Показывает наличие лицензии на сервере. Если сервер работает без лицензии, значение будет false.
  • isModelTypeRunning Показывает, настроен ли указанный ключ маршрутизации. Если modelType не настроен в Портале, значение будет false, а поле isAgentLicensed не вернётся в ответе.
  • isAgentLicensed Показывает наличие лицензии у Агентов на Целевых машинах. Если ключ маршрутизации настроен, но Агенты работают без лицензии, значение будет false.

Создать запрос

Запрос создаётся методом POST /inference/nlp/{modelType}/async

Запрос может отправляться с типом содержимого multipart/form-data или application/json.

POST /inference/nlp/nlp-extr-xxxx/async HTTP/1.1
Host: ai-server-endpoint:44392
Accept: text/plain
Authorization: ••••••
Content-Length: 238
Content-Type: application/json; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
{
  "ResponseSchema": [
    "ИНН", "Дата письма"
  ],
  "ImageFile": "[BASE64]",
  "ResponseLength": 256
}

При успешном создании запроса сервер возвращает идентификатор задачи (key):

{
    "key": "23b3bfbf-952d-4f57-9c71-a065622250ef",
    "createdAt": "2025-12-22T19:27:58.2668447+03:00",
    "expiresAt": "2025-12-23T19:27:58.2668447+03:00",
    "modelType": "nlp-extr-xxxx",
    "files": [
        {
            "id": "097ebac8-a7f6-4eab-97b5-19b1a696b292",
            "originalFileName": "img.jpeg",
            "extension": ".jpeg",
            "contentType": "image/jpeg",
            "contentLength": 340121,
            "type": "Image",
            "sourceFileType": "jpg",
            "fileType": "jpg"
        }
    ]
}
ℹ️

Метод /sync выполняет запрос синхронно: обработка длится до завершения генерации ответа моделью.

Ответ возвращается в режиме Transfer-Encoding: chunked и содержит «сырые» данные модели без дополнительной обработки.

Поля запроса

Основные поля:

ПолеОписаниеПримечания
ImageИзображение / документjpg, jpeg, png, pdf, tiff
Prompt**Запрос к модели—
SystemMessageСистемный промптПереопределяет системный промпт навыка
ResponseLengthДлина ответа в токенахОбязательное поле
TemperatureТемпература ответаЧем ниже, тем меньше вариативность
MinPПорог выбора токенов0 = любой, 1 = самый вероятный
MatchResponseSchemaПроверка соответствия ответа схемеРезультат → result.isMatchingResponseSchema
RequestGroupГруппа приоритизацииПроизвольная строка-маркер
ThinkФлаг рассуждения моделиТолько для поддерживаемых моделей
ℹ️

** Обязательно укажите либо запрос к модели (поле Prompt), либо изображение/документ (поле Image). Запрос без Prompt и без Image получит ответ 400 Bad Request.

Дополнительно:

  • Файл контекста в 1 из 3 форм: ContextFileId, ContextFile, Context. Позволяет переопределить контекст навыка.
    • Пример ContextFileId: “8A4858EB-11C2-4BED-A807-78F65EA0A4DE”.
    • Пример ContextFile: "[{\"input\":\"Запрос отправлен в 20:31.\",\"keys\":[\"когда отправлен запрос\"],\"output\":{\"когда отправлен запрос":\"20:31\"}}]"
    • Пример Context: 
      [
  {
    "input": "Запрос отправлен в 20:31.",
    "keys": ["когда отправлен запрос"],
    "output": {
      "когда отправлен запрос": "20:31"
    }
  }
]
    • Может отсутствовать
    • Должна отсутствовать для навыка Файнтюнинг
  • Схема ответа в 1 из 3 форм: ResponseSchemaJson, ResponseSchema. Позволяет структурировать ответ модели.
    • Пример ResponseSchemaJson: "[\"ИНН\", \"Дата письма\"]"
    • Пример ResponseSchema: ["ИНН", "Дата письма"]
    • Может отсутствовать для навыков OCR, Генерация
    • Должна отсутствовать для навыка Файнтюнинг

Проверка готовых запросов

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

GET /inference/nlp/ready

GET /inference/nlp/ready HTTP/1.1
Host: ai-server-endpoint:44392
Accept: text/plain
Authorization: ••••••

Сервер возвращает список идентификаторов готовых запросов в формате JSON:

["23b3bfbf-952d-4f57-9c71-a065622250ef"]
ℹ️

Запрос появляется в этом списке, когда у него появляется флаг IsReady в поле Result.

Получить запрос

Получить данные запроса можно методом:

GET /inference/nlp/{requestKey},

где {requestKey} — идентификатор запроса, полученный на предыдущем шаге.

Пример:

GET /inference/nlp/23b3bfbf-952d-4f57-9c71-a065622250ef HTTP/1.1
Host: ai-server-endpoint:44392
Accept: text/plain
Authorization: ••••••

Сервер возвращает JSON с результатами обработки запроса:

{
    "key": "23b3bfbf-952d-4f57-9c71-a065622250ef",
    "createdAt": "2025-12-22T19:27:58.2668447+03:00",
    "expiresAt": "2025-12-23T19:27:58.2668447+03:00",
    "modelType": "nlp-extr-xxxx",
    "result": {
        "streamingStartedAt": "2025-12-22T19:28:02.639923+03:00",
        "updatedAt": "2025-12-22T19:28:03.2439793+03:00",
        "streamingCompletedAt": "2025-12-22T19:23:03.2439793+03:00",
        "isReady": true,
        "isFailed": false,
        "isMatchingResponseSchema": null,
        "rawAnswer": "{\"ИНН\": \"1234567890\", \"Дата письма\": \"14-07-2025\"}\n",
        "answer": "{\"ИНН\": \"1234567890\", \"Дата письма\": \"14-07-2025\"}\n"
    },
    "files": [
        {
            "id": "097ebac8-a7f6-4eab-97b5-19b1a696b292",
            "originalFileName": "img.jpeg",
            "extension": ".jpeg",
            "contentType": "image/jpeg",
            "contentLength": 340121,
            "type": "Image",
            "sourceFileType": "jpg",
            "fileType": "jpg"
        }
    ],
    "isPostProcessingRequired": false
}

Обратите внимание на следующие поля:

  • expiresAt — дата и время удаления запроса с сервера. По умолчанию запрос хранится 1 час. Значение можно изменить в параметре ClearRequestsService > DefaultExpirationSeconds файла конфигурации Api.Inference.

    Даже если запрос не успел обработаться за отведённое время, он всё равно будет удалён с сервера.

  • result.isReady — статус готовности результата.

    • true — результат полностью готов.
    • false — обработка ещё продолжается.

  • result.isFailed — статус обработки запроса.

    • true — во время обработки произошла ошибка.
    • false — запрос обработан успешно.

  • result.isMatchingResponseSchema — соответствует ли ответ заданной схеме (ResponseSchema).

    • true — ответ соответствует схеме.
    • false — модель вернула ответ со структурой, отличающейся от ожидаемой.
    • null — проверка не выполнялась.

  • result.rawAnswer — сырой ответ модели без постобработки. Может отличаться от answer, если применяется постпроцессинг (например, Fine-tuning или нормализация результата).

Умный OCRАгентская система