GonkaGate Плагин PDF Inputs

Выберите pdf-text, native и provider poppler или mistral_ocr для PDF inputs.

Используйте file-parser только когда /v1/chat/completions запросу нужно явно выбрать PDF engine или provider для извлечения текста. Если 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-модели.

Для OCR на scanned или image-heavy PDF оставьте engine: "pdf-text" и выберите provider document-processing:

mistral-ocr-provider.json

{
  "id": "file-parser",
  "pdf": { "engine": "pdf-text", "provider": "mistral_ocr" }
}

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

Вариант	Что делает GonkaGate	Когда выбирать	Когда не выбирать
Не передавать `file-parser`	Bare PDF handling остаётся включённым без плагина. Обычно GonkaGate использует server-managed auto selection, но authenticated-запросы могут унаследовать saved `file-parser` default.	Когда bare PDF support уже достаточно и запросу не нужен явный override.	Когда нужно жёстко зафиксировать локальный парсинг, OCR, `native`, или игнорировать saved plugin defaults.
Не передавать `pdf.engine` или `pdf.provider` в плагине	Использует server-managed auto selection для отсутствующей части. Сейчас это обычно сводится к локальному `pdf-text` с default provider.	Когда запрос передаёт `file-parser`, но ему не нужен фиксированный engine или provider.	Когда нужно жёстко зафиксировать локальный парсинг, включить OCR или явно запросить `native`.
`pdf-text` с `poppler` или без provider	Локально парсит PDF и извлекает embedded text до upstream-вызова. В non-stream ответе может добавить file annotations.	Когда нужна быстрая text extraction из text-based PDF по public `http/https` URL или `data:application/pdf;base64,...`.	Когда PDF scanned, textless или image-heavy и нужен OCR.
`pdf-text` с `mistral_ocr`	Запускает Mistral OCR через document-processing service, извлекает текст до upstream-вызова и добавляет billable OCR processing cost только после успешного parse.	Когда PDF scanned, textless или image-heavy, и embedded text extraction недостаточно.	Когда нужен нулевой OCR processing cost или выбранный 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.
provider валиден только вместе с pdf-text. Используйте poppler для embedded-text extraction или mistral_ocr для OCR.
В 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 блокируются специально.
Default provider poppler извлекает embedded text и может завершиться pdf_input_text_unavailable на scanned или textless PDF.
Provider mistral_ocr запускает OCR для scanned или image-heavy PDF и списывает стоимость только после успешного parse.
Повторное использование уже извлечённого PDF text не добавляет новый OCR charge.
Текущие лимиты по умолчанию: до 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 и provider, даже если сам запрос не отправляет file-parser.
Locked settings могут отклонить несовместимый request override с 400 invalid_request_error и code=plugin_override_blocked.
Disabled saved file-parser setting означает только «нет сохранённого engine или provider preference». Bare PDF support это не выключает.

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

Ошибка	Что это значит	Что делать дальше
`400 pdf_engine_not_supported`	В запросе указан неподдерживаемый engine, например `mistral-ocr`.	Для OCR используйте `pdf-text` с `provider: "mistral_ocr"` или выберите `native`.
`400 pdf_provider_not_supported`	В запросе указан неподдерживаемый provider или `provider` передан вместе с `native`.	Использовать `poppler` или `mistral_ocr` только с `engine: "pdf-text"`.
`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`	Default text provider не смог извлечь usable embedded text.	Переключиться на `provider: "mistral_ocr"` для OCR или передать text-based PDF.
`413 payload_too_large` или `400 pdf_input_too_large`	Body или файл превышают активный size budget.	Уменьшить размер/количество файлов или использовать URL mode вместо больших data URL.

См. также

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

PDF Inputs