Извлечение текста через NextPDF Connect (Pro)

Кратко

Используйте extract_text, чтобы извлечь текст из существующего PDF для индексирования, анализа или дальнейшей обработки. Провайдер инструментов Pro регистрирует new ExtractTextTool() с протокольным именем extract_text, и на этой странице эта привязка проверяется повторно. extract_text — это инструмент уровня Pro. При запуске сервер проверяет его через class_exists() и регистрирует только при установленном пакете Pro. Вы можете запросить обычный вывод, диапазон страниц или постранично сегментированный структурированный вывод.

Установка

composer require nextpdf/server
composer require nextpdf/pro

Привяжите транспорт. Прежде чем полагаться на инструмент, подтвердите его наличие через diagnostic.capabilities.

Концептуальный обзор

Извлечение считывает операторы вывода текста из потока содержимого в порядке их следования (ISO 32000-2 §9.4). Вывод отражает закодированный порядок чтения (ISO 32000-2 §9.10). Отсканированный PDF без текстового слоя возвращает мало текста или не возвращает его вовсе. Это свойство исходного файла, а не дефект инструмента. format: "plain" возвращает одну строку. format: "structured" возвращает постраничные объекты с количеством символов. page_range ограничивает обрабатываемые страницы.

Поверхность API

Инструмент	Уровень	Роль	Класс риска
`extract_text`	Pro	Извлечение текста (простой / структурированный / диапазон)	Безопасно
`parse_pdf`	Core (включается переменной окружения)	Низкоуровневая структура (количество страниц, метаданные)	Безопасно

Имена инструментов — это протокольные имена из реестра. Эталонный список приведён в каталоге инструментов. Доступные инструменты зависят от установленного уровня.

Пример кода — быстрый старт

extract_text с source (путь, доступный серверу для чтения) и format: "plain".
extract_text с page_range: "1-3" для подмножества.
extract_text с format: "structured" для постранично сегментированного вывода.

Пример кода — продакшен

Используйте parse_pdf (или предыдущий вызов extract_text без ограничений), чтобы узнать количество страниц перед запросом диапазона. Для генерации с дополненной выборкой (RAG) или индексирования предпочтительнее format: "structured": так каждая страница разбивается на фрагменты независимо. Для зашифрованного источника укажите параметр password. Количество символов считается в кодовых точках UTF-8, а не в байтах.

Граничные случаи и подводные камни

Отсутствует источник. Неверный путь возвращает ошибку “файл не найден”. Используйте абсолютные пути, доступные серверу для чтения.
Отсканированный PDF. Без текстового слоя извлечение возвращает пустой или почти пустой текст. Сначала выполните оптическое распознавание символов (OCR) для исходного файла.
Страница за пределами диапазона. Диапазон за пределами документа отклоняется с указанием фактического количества страниц.
Зашифрованный источник. Укажите параметр password.
Pro отсутствует. Если установлен только Core, инструмент extract_text не регистрируется. Проверьте через diagnostic.capabilities.

Производительность

Извлечение масштабируется вместе с размером документа, а бюджет допускает большие входные данные. Для любого создаваемого артефакта профиль — structural, поскольку этот инструмент возвращает текст, а не PDF.

Замечания по безопасности

Извлечённый текст может содержать конфиденциальную информацию. Считайте результат конфиденциальным и передавайте его только по доверенному каналу. Инструмент не выполняет запись в файловую систему. Он считывает исходный путь с привилегиями сервера, поэтому ограничивайте пути, которые может передавать вызывающая сторона.

Соответствие

Утверждение	Спецификация	Пункт	reference_id (идентификатор ссылки)
Текст выводится текстовыми операторами в порядке потока.	ISO 32000-2	§9.4
Извлечение отражает закодированный порядок чтения.	ISO 32000-2	§9.10

Этот рецепт не утверждает, что извлечённый текст сохраняет точный логический порядок чтения для документа без тегов. Речь идёт именно о закодированном порядке.

Коммерческий контекст

extract_text — это инструмент уровня Pro, который регистрируется только тогда, когда пакет Pro разрешается при запуске сервера.

Доступность транспортов

Транспорт	Доступен	Примечания
MCP (stdio) — стандартный ввод-вывод	Да (Pro)	Большой объём текста увеличивает размер кадра stdio.
REST	Да (Pro)	Где поддерживается, передавайте большие результаты потоком.
gRPC	Да (Pro)	Для большого объёма текста действуют ограничения на размер сообщения.

Класс риска HITL

extract_text относится к классу Safe (только чтение, без побочных эффектов) и никогда не запрашивает подтверждение.

JSON-конверт шлюза подтверждения

Операция извлечения только для чтения никогда не запрашивает подтверждение:

{ "allowed": true }