Extrair conteúdo textual com o NextPDF Connect (Pro)

Visão geral

Use extract_text para extrair texto de um PDF existente para indexação, análise ou processamento posterior. O provedor de ferramentas Pro registra new ExtractTextTool() com o nome de protocolo extract_text, e esta página confirma novamente essa vinculação. extract_text é uma ferramenta do nível Pro. Na inicialização, o servidor a verifica com class_exists() e a registra somente quando o pacote Pro está instalado. Você pode solicitar uma saída em texto puro, limitar a um intervalo de páginas ou obter uma saída estruturada segmentada por página.

Instalação

composer require nextpdf/server
composer require nextpdf/pro

Vincule um transporte. Antes de depender da ferramenta, confirme sua disponibilidade com diagnostic.capabilities.

Visão conceitual

A extração lê os operadores de exibição de texto do fluxo de conteúdo (content stream) na ordem do fluxo (ISO 32000-2 §9.4). A saída reflete a ordem de leitura codificada (ISO 32000-2 §9.10). Um PDF digitalizado sem camada de texto retorna pouco ou nenhum texto. Isso reflete o arquivo de origem, não um defeito da ferramenta. format: "plain" retorna uma única string. format: "structured" retorna objetos por página com contagens de caracteres. page_range restringe as páginas processadas.

Superfície da API

Ferramenta	Nível	Função	Nível de risco
`extract_text`	Pro	Extrair texto (puro / estruturado / intervalo)	Seguro
`parse_pdf`	Core (controlado por variável de ambiente)	Estrutura de baixo nível (contagem de páginas, metadados)	Seguro

Os nomes das ferramentas correspondem aos nomes de protocolo do registro. O catálogo de ferramentas é o catálogo oficial. As ferramentas disponíveis dependem do nível instalado.

Exemplo de código — Início rápido

extract_text com source (um caminho legível pelo servidor) e format: "plain".
extract_text com page_range: "1-3" para um subconjunto.
extract_text com format: "structured" para saída segmentada por página.

Exemplo de código — Produção

Use parse_pdf (ou um extract_text sem limite executado anteriormente) para obter a contagem de páginas antes de solicitar um intervalo. Para geração aumentada por recuperação (RAG) ou indexação, prefira format: "structured" para manter cada página segmentada de forma independente. Para uma origem criptografada, forneça o parâmetro de senha. As contagens de caracteres são contagens de pontos de código UTF-8, não de bytes.

Casos extremos & pegadinhas

Origem ausente. Um caminho inválido retorna um erro de arquivo não encontrado. Use caminhos absolutos que o servidor consiga ler.
PDF digitalizado. Sem uma camada de texto, a extração retorna texto vazio ou quase vazio. Execute primeiro o reconhecimento óptico de caracteres (OCR) na origem.
Página fora do intervalo. Um intervalo que ultrapassa o documento é rejeitado, com a contagem real de páginas.
Origem criptografada. Forneça o parâmetro de senha.
Pro ausente. Com apenas o Core, extract_text não é registrado. Verifique com diagnostic.capabilities.

Desempenho

A extração escala conforme o tamanho do documento, e o orçamento comporta entradas grandes. O perfil é structural para qualquer artefato produzido, porque esta ferramenta retorna texto, não um PDF.

Notas de segurança

O texto extraído pode conter conteúdo sensível. Trate o resultado como confidencial e retorne-o somente por um canal confiável. A ferramenta não grava no sistema de arquivos. Ela lê o caminho de origem com os privilégios do servidor; portanto, restrinja quais caminhos um chamador pode passar.

Conformidade

Afirmação	Especificação	Cláusula	reference_id
O texto é exibido por operadores de texto na ordem do fluxo.	ISO 32000-2	§9.4
A extração reflete a ordem de leitura codificada.	ISO 32000-2	§9.10

Esta receita não afirma que o texto extraído preserva fielmente a ordem lógica de leitura em um documento sem marcação (untagged). A ordem considerada é a ordem codificada.

Contexto comercial

extract_text é uma ferramenta do nível Pro, registrada somente quando o pacote Pro é resolvido durante a inicialização do servidor.

Disponibilidade por transporte

Transporte	Disponível	Observações
MCP (stdio)	Sim (Pro)	Textos grandes aumentam o quadro stdio.
REST	Sim (Pro)	Transmita resultados grandes por streaming onde houver suporte.
gRPC	Sim (Pro)	Limites de tamanho de mensagem se aplicam a textos grandes.

Nível de risco HITL

extract_text é Seguro (somente leitura, sem efeitos colaterais) e nunca exige confirmação.

Envelope JSON do gate de confirmação

A extração de somente leitura nunca exige confirmação:

{ "allowed": true }