GonkaGate Плагин PDF Inputs

Выберите pdf-text или native для PDF inputs через плагин file-parser.

Используйте file-parser только когда /v1/chat/completions запросу нужно явно выбрать PDF engine. Если bare PDF inputs уже работают как нужно, не передавайте плагин и оставьте server-managed обработку PDF в GonkaGate.

Минимальный рабочий запрос

request.json

{
  "model": "qwen/qwen3-235b-a22b-instruct-2507-fp8",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "file",
          "file": {
            "filename": "sample.pdf",
            "file_data": "data:application/pdf;base64,<base64-pdf>"
          }
        },
        {
          "type": "text",
          "text": "Summarize the attached PDF."
        }
      ]
    }
  ],
  "plugins": [
    {
      "id": "file-parser",
      "pdf": { "engine": "pdf-text" }
    }
  ]
}

Результат: запрос жёстко фиксирует локальный pdf-text для этого PDF. GonkaGate извлекает текст до вызова upstream-модели.

Как выбрать PDF engine

Вариант	Что делает GonkaGate	Когда выбирать	Когда не выбирать
Не передавать плагин или не передавать `pdf.engine`	Использует server-managed auto selection. Сейчас это обычно сводится к локальному `pdf-text`.	Когда bare PDF support уже достаточно и запросу не нужен фиксированный engine.	Когда нужно жёстко зафиксировать локальный парсинг или явно запросить `native`.
`pdf-text`	Локально парсит PDF, извлекает текст до upstream-вызова и может добавить file annotations в non-stream ответ.	Когда нужна предсказуемая text extraction из public `http/https` URL или `data:application/pdf;base64,...`.	Когда выбранный model path должен получить исходный PDF для native handling.
`native`	Прокидывает исходный PDF file и плагин `file-parser` upstream без изменений.	Когда выбранный model path действительно должен поддерживать native PDF input и локальная text extraction не нужна.	Когда вы рассчитываете на fallback к локальному парсингу. Явный `native` завершается `pdf_native_unavailable`, если native handling недоступен.

Что меняется в запросе и ответе

pdf-text работает только локально. GonkaGate извлекает текст до вызова upstream-модели и убирает локальный override из payload, который уходит upstream.
В non-stream ответах после pdf-text могут появляться reusable file annotations в choices[].message.annotations[].
В streaming-режиме остаётся обычный chat-completions SSE без PDF annotations.
native сохраняет исходный file part и отправляет plugins: [{ "id": "file-parser", "pdf": { "engine": "native" } }] upstream без изменений.

Поддерживаемые источники и практические лимиты

pdf-text поддерживает public http/https URL и data:application/pdf;base64,....
Private и local URL блокируются специально.
OCR пока не поддерживается. Textless или scanned PDF могут завершиться pdf_input_text_unavailable.
Текущие лимиты по умолчанию: до 5 PDF на запрос и до 1 MiB на один файл.
Слишком большой request body может завершиться HTTP 413 payload_too_large ещё до старта PDF parsing.

Как saved plugin settings влияют на запрос

Authenticated-запросы могут унаследовать saved default для file-parser, если включена plugin settings policy.

Enabled saved setting может подставить default PDF engine, даже если сам запрос не отправляет file-parser.
Locked settings могут отклонить несовместимый request override с 400 invalid_request_error и code=plugin_override_blocked.
Disabled saved file-parser setting означает только «нет сохранённого engine preference». Bare PDF support это не выключает.

Частые ошибки

Ошибка	Что это значит	Что делать дальше
`400 pdf_engine_not_supported`	В запросе указан неподдерживаемый engine, например `mistral-ocr`.	Использовать только `pdf-text` или `native`.
`400 pdf_native_unavailable`	Запрос явно попросил `native`, но выбранный model/runtime сейчас не умеет native PDF handling.	Убрать engine для auto handling или переключиться на `pdf-text`.
`400 plugin_override_blocked`	Locked saved plugin settings конфликтуют с request override.	Убрать override или привести запрос к saved account policy.
`400 pdf_input_not_supported` или `400 pdf_input_invalid_data_url`	Источник PDF невалиден для `pdf-text`.	Использовать public `http/https` URL или корректный `data:application/pdf;base64,...` payload.
`400 pdf_input_text_unavailable`	PDF не содержит пригодного текста, а OCR недоступен.	Передать text-based PDF или обработать документ вне GonkaGate.
`413 payload_too_large` или `400 pdf_input_too_large`	Body или файл превышают активный size budget.	Уменьшить размер/количество файлов или использовать URL mode вместо больших data URL.

См. также

Plugins Overview для сравнения плагинов и правил активации.
Structured Outputs, если после извлечения текста следующий шаг это возврат JSON по контракту.
Chat Completions API reference для точной схемы file content-part и plugins.

PDF Inputs