Передача файлов через S3

Описание

Обычно файл передаётся вместе с запросом — телом multipart/form-data или в виде base64 внутри JSON.

Если файл уже лежит в S3-хранилище заказчика, его можно не пересылать через API. Вместо содержимого файла в запросе указывается путь к объекту в этом хранилище, а AI Server забирает файл самостоятельно.

Вариант поддерживают четыре метода:

Синхронный метод NLP (POST /inference/nlp/{modelType}/sync) передачу файлов через S3 не поддерживает.

Авторизация

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

Предварительная настройка

Передача файлов через S3 работает только после того, как администратор настроил подключение на Портале: Настройки → Внешний S3 (/settings/external-s3).

В разделе Подключение указываются адрес S3-сервера (Endpoint), Access Key, Secret Key, а также флаги SSL и Force Path Style. Поддерживаются хранилища Amazon S3 и MinIO.

В разделе Правила нужно включить правило «Файлы запросов» и задать путь в формате bucket/path/to/folder — имя бакета и, при необходимости, префикс внутри него. Кнопка «Проверить доступ» проверяет, что по указанному пути есть доступ.

Соседнее правило «Документы пакетной обработки» отвечает за обратное направление — выгрузку сформированных PDF из AI Server в S3. На приём файлов оно не влияет.

Путь к файлу

Путь в запросе указывается относительно пути, заданного в правиле «Файлы запросов». Бакет в запросе не повторяется.

Например, если в настройках задан путь my-bucket/incoming:

Имя файла в пути становится исходным именем файла запроса (originalFileName в ответе).

Поддерживаемые форматы

Допустимые расширения: .bmp, .jpeg, .jpg, .png, .tif, .tiff, .pdf.

Поля запроса

Умный OCR

Для файла из S3 используется отдельный метод:

POST /inference/smartOcr/json

Тип содержимого: application/json. Тип модели, как и при обычной загрузке, передаётся в заголовке modelType.

POST /inference/smartOcr/json HTTP/1.1
Host: ai-server-endpoint:44392
modelType: anytext
Accept: text/plain
Authorization: ••••••
Content-Type: application/json

{
    "fileS3Url": "2026/09/invoice-01.png"
}

При успешном создании запроса сервер возвращает 201 Created и идентификатор запроса:

"e1f19acc-f9a2-435c-9c9b-38c4a09a7468"

Дальнейшие шаги — проверка готовых запросов и получение результата — не отличаются от обычного сценария.

Задачи NLP

Используется тот же метод, что и при обычной загрузке:

POST /inference/nlp/{modelType}/async

Вместо поля Image указывается ImageS3Url. Поле доступно и в application/json, и в multipart/form-data.

POST /inference/nlp/nlp-extr-xxxx/async HTTP/1.1
Host: ai-server-endpoint:44392
Accept: text/plain
Authorization: ••••••
Content-Type: application/json

{
  "ResponseSchema": [
    "ИНН", "Дата письма"
  ],
  "ImageS3Url": "2026/09/letter.pdf",
  "ResponseLength": 256
}

Ответ такой же, как при обычной загрузке: информация о запросе с идентификатором в поле key.

Агентская система

Используется тот же метод, что и при обычной загрузке:

POST /inference/agentSystem/{routingKey}/async

Пути к файлам передаются списком в поле fileS3Urls.

POST /inference/agentSystem/agsys-xxxx/async HTTP/1.1
Host: ai-server-endpoint:44392
Accept: text/plain
Authorization: ••••••
Content-Type: application/json

{
    "Prompt": "Сравни документы",
    "FileS3Urls": [
        "2026/09/act-01.pdf",
        "2026/09/act-02.pdf"
    ]
}

Поля files и fileS3Urls можно использовать вместе — файлы попадут в запрос в одном списке: сначала переданные в files, затем взятые из S3.

Ответ такой же, как при обычной загрузке: информация о запросе с идентификатором в поле key.

Пакетная обработка

Файлы из S3 добавляются в уже созданный пакет отдельным методом:

POST /inference/packages/{requestKey}/files/json

Тип содержимого: application/json.

POST /inference/packages/e1f19acc-f9a2-435c-9c9b-38c4a09a7468/files/json HTTP/1.1
Host: ai-server-endpoint:44392
Accept: application/json
Authorization: ••••••
Content-Type: application/json

{
    "fileS3Urls": [
        "2026/09/invoice-01.png",
        "2026/09/invoice-02.pdf"
    ]
}

Сервер возвращает массив идентификаторов добавленных файлов:

[
  "d353c73d-c1f9-4dc5-bdd1-9a73565e566c",
  "a7b8c9d0-e1f2-4a3b-8c5d-6e7f8a9b0c1d"
]

Метод можно вызывать несколько раз, а также совмещать с обычной загрузкой через POST /inference/packages/{requestKey}/files. Как и при обычной загрузке, файлы нельзя добавлять после запуска обработки.

Ожидание загрузки файлов

В отличие от остальных компонентов, файлы пакета скачиваются из S3 сразу после добавления, в фоне, а не в момент запуска обработки. Метод возвращает ответ, не дожидаясь скачивания.

Обработка ошибок

Ошибки разделяются на две группы в зависимости от того, когда они обнаруживаются.

При создании запроса — сервер отвечает сразу:

• 400 Bad Request — правило «Файлы запросов» не настроено, путь не указан, расширение файла не поддерживается или одновременно заданы файл и путь к нему в S3.
• 422 Unprocessable Entity — попытка запустить обработку пакета до того, как его файлы скачались из S3.

При обработке запроса — файл читается из S3 уже после того, как запрос принят, поэтому ошибка чтения не возвращается в ответе на создание запроса. Если объекта нет в хранилище, или он недоступен, запрос завершается с ошибкой, и её текст возвращается в результате запроса.

Наличие объекта по указанному пути на момент создания запроса не проверяется.