Задачи NLP

Описание

Взаимодействие с компонентом Задачи NLP строится по следующей схеме:

1. Проверка готовности навыка на распознавание документа с указанным ключом маршрутизации
2. Отправка NLP-запроса и получение его идентификатора
3. Получение данных NLP-запроса по идентификатору
4. (Подождать)
5. (Повторить п.3, пока нет флага Result.IsReady)

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

Чтобы сервер мог обработать запрос, нужно указать ключ маршрутизации (часть 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. Если указанный modelType не настроен в Портале, isModelTypeRunning примет значение false, а поле isAgentLicensed пропадет из JSON. Если ключ маршрутизации настроен на Целевых машинах (одной или нескольких), но их Агенты работают без лицензии, 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
}

Если запрос будет успешно создан, сервер вернёт в ответе его идентификатор (поле modelType):

{
    "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"
        }
    ]
}

Поля запроса.

• Файл контекста в 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, Генерация
  • Должна отсутствовать для навыка Файнтюнинг

• Image – изображение / документ. Поддерживаются форматы: jpg, jpeg, png, pdf, tiff.

• Prompt** – запрос к модели.

• SystemMessage – системный промпт. Позволяет переопределить значение системного промпта, заданного для навыка.

• ResponseLength* – длина ответа. Максимальная длина ответов модели в токенах (для русского языка 1 слово примерно 1.5 токена). Обязательное поле.

• Temperature – температура ответа. Чем ниже температура, тем меньше вариативность в генерации.

• MinP – параметр min_p. Дополнительный параметр, определяющий порог в диапазоне выбора токенов (0 - любой, 1 - самый вероятный).

• MatchResponseSchema – проверка соответствия ответа модели схеме запроса. Если указано true, json-схема ответа будет проверена на соответствие схеме (ResponseSchemaJson / ResponseSchema). Результат проверки отразится на поле result > isMatchingResponseSchema в ответе.

• RequestGroup – группа приоритизации. Произвольная строка-маркер. Если указано, запросы на обработку разных групп будут поступать в общую очередь по 1 запросу из каждой группы за раз. Например, создайте 100 запросов с RequestGroup = “background” и затем 1 запрос с RequestGroup = “express”: последний будет обработан не дожидаясь завершения обработки запросов группы “background”.

• Think – флаг “рассуждение” языковой модели. Если модель поддерживает рассуждение, позволяет указать соответствующий флаг при отправке запроса.

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

Получить запрос можно методом 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
}

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

1. expiresAt: Когда запрос будет удален с сервера. Стандартное время – 1 час – можно перенастроить в параметре ClearRequestsService > DefaultExpirationSeconds файла конфигурации Api.Inference.

2. result > isReady: Готовность ответа. Если true, ответ полностью готов.

3. result > isFailed: Корректно ли обработан запрос. Если false, при обработке запроса произошла ошибка.

4. result > isMatchingResponseSchema: Ответ соответствует схеме запроса (ResponseSchema). Если false, модель вернула ответ с нестандартной схемой.

5. result > rawAnswer: Сырой ответ модели. Отличается от answer, когда ответ модели проходит постпроцессинг (навык Файнтюнинг).