Trabalhar com documentos em diferentes formatos é um desafio comum ao construir aplicações de IA. Quer esteja a processar PDFs, documentos Word ou ficheiros HTML, extrair texto limpo e estruturado pode ser surpreendentemente difícil. O Docling é uma biblioteca Python que torna este processo simples.
Este guia percorre o essencial da utilização do Docling para processar documentos, com foco em exemplos práticos e boas práticas que pode aplicar de imediato.
Porquê o Docling?
O Docling resolve problemas comuns de processamento de documentos de forma unificada. Oferece suporte multi-formato que funciona sem esforço com PDFs, documentos Word, apresentações PowerPoint, HTML e muito mais. A biblioteca inclui capacidades de OCR que permitem extrair texto mesmo de documentos digitalizados e imagens, tornando-a versátil para vários tipos de documentos.
O que distingue o Docling é a sua funcionalidade de divisão inteligente ("chunking"), que separa os documentos em partes com significado, preservando o contexto, em vez de dividir o texto de forma arbitrária. O resultado é limpo e estruturado, quer precise de formato markdown quer de texto simples. Melhor ainda, o Docling oferece uma API simples e intuitiva, fácil de começar a usar, mesmo para programadores que nunca trabalharam com processamento de documentos.
Como Começar
Primeiro, instale o Docling:
pip install doclingUtilização Básica
Converter um Documento
A forma mais simples de utilizar o Docling é através do DocumentConverter:
from docling.document_converter import DocumentConverter
# Create a converter
converter = DocumentConverter()
# Convert a document
result = converter.convert("document.pdf")
document = result.document
# Export to markdown
markdown_text = document.export_to_markdown()
print(markdown_text)É tudo! O Docling deteta automaticamente o formato do ficheiro e processa-o em conformidade.
Trabalhar com Diferentes Origens de Ficheiros
O Docling consegue processar tanto ficheiros locais como URLs remotos:
from docling.document_converter import DocumentConverter
import requests
import tempfile
converter = DocumentConverter()
# Local file
result = converter.convert("/path/to/document.pdf")
# Remote URL - download first
url = "https://example.com/document.pdf"
response = requests.get(url)
with tempfile.NamedTemporaryFile(suffix='.pdf', delete=False) as tmp:
tmp.write(response.content)
tmp_path = tmp.name
result = converter.convert(tmp_path)
# Don't forget to clean up
import os
os.unlink(tmp_path)Que Formatos São Suportados?
O Docling funciona nativamente com muitos formatos de ficheiro comuns. Processa ficheiros PDF, incluindo documentos digitalizados através de tecnologia OCR. Os formatos do Microsoft Office, como Word (.docx) e PowerPoint (.pptx), são totalmente suportados, tal como formatos web como HTML. Também é possível processar ficheiros Markdown, documentos de texto simples e até ficheiros de imagem (.webp, .webp) através das suas capacidades de OCR integradas.
O DocumentConverter deteta automaticamente o formato do ficheiro e aplica o método de processamento adequado, pelo que não precisa de se preocupar em especificar o tipo explicitamente.
Dividir Documentos em Chunks
Em muitas aplicações de IA, é preciso dividir os documentos em partes mais pequenas ("chunks"). O HybridChunker do Docling torna este processo inteligente e simples.
Divisão Básica em Chunks
from docling.document_converter import DocumentConverter
from docling.chunking import HybridChunker
from transformers import AutoTokenizer
# Convert document
converter = DocumentConverter()
result = converter.convert("document.pdf")
document = result.document
# Set up chunker with your tokenizer
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
chunker = HybridChunker(
tokenizer=tokenizer,
max_tokens=512 # Maximum tokens per chunk
)
# Get chunks
chunks = list(chunker.chunk(document))
# Process chunks
for i, chunk in enumerate(chunks):
print(f"Chunk {i}: {chunk.text[:100]}...")Porquê Usar o HybridChunker?
O HybridChunker oferece uma divisão inteligente de documentos que vai além da simples contagem de caracteres ou palavras. Preserva estruturas naturais do documento, como parágrafos e secções, garantindo que nunca obtém chunks cortados de forma estranha a meio de uma frase. Isto é particularmente importante para manter o significado semântico do texto.
- Preserva estruturas naturais do documento, como parágrafos e secções
- Divisão sensível a tokens que respeita os limites do modelo de embedding
- Tamanhos de chunk configuráveis de acordo com as suas necessidades específicas
- Preserva metadados que indicam a origem de cada chunk
Trabalhar com Metadados
O Docling extrai metadados úteis dos documentos:
from docling.document_converter import DocumentConverter
converter = DocumentConverter()
result = converter.convert("document.pdf")
document = result.document
# Access document metadata
if hasattr(document, 'meta'):
print(f"Document metadata: {document.meta}")
# Chunk with metadata
from docling.chunking import HybridChunker
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
chunker = HybridChunker(tokenizer=tokenizer, max_tokens=512)
for chunk in chunker.chunk(document):
print(f"Text: {chunk.text[:50]}...")
if hasattr(chunk, 'meta'):
print(f"Metadata: {chunk.meta}")Juntando Tudo
Eis um exemplo completo que processa um documento e o prepara para utilização numa aplicação de IA:
from docling.document_converter import DocumentConverter
from docling.chunking import HybridChunker
from transformers import AutoTokenizer
def process_document(file_path, max_tokens=512):
"""Process a document and return chunks ready for embedding."""
# Step 1: Convert document
converter = DocumentConverter()
result = converter.convert(file_path)
document = result.document
# Step 2: Set up chunker
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
chunker = HybridChunker(
tokenizer=tokenizer,
max_tokens=max_tokens
)
# Step 3: Get chunks
chunks = []
for i, chunk in enumerate(chunker.chunk(document)):
chunks.append({
'text': chunk.text,
'index': i,
'source': file_path
})
return chunks
# Usage
chunks = process_document("my_document.pdf")
print(f"Created {len(chunks)} chunks")
for chunk in chunks:
print(f"Chunk {chunk['index']}: {chunk['text'][:50]}...")Dicas Práticas
Processar Vários Documentos
import os
from pathlib import Path
def process_folder(folder_path, max_tokens=512):
"""Process all PDFs in a folder."""
all_chunks = []
for file_path in Path(folder_path).glob("*.pdf"):
try:
chunks = process_document(str(file_path), max_tokens)
all_chunks.extend(chunks)
print(f"Processed {file_path.name}: {len(chunks)} chunks")
except Exception as e:
print(f"Failed to process {file_path.name}: {e}")
return all_chunksExperimente HAQQ AI grátis
Experimente a redação e pesquisa jurídica com IA
Exportar para Diferentes Formatos
O Docling consegue exportar documentos para vários formatos:
from docling.document_converter import DocumentConverter
converter = DocumentConverter()
result = converter.convert("document.pdf")
document = result.document
# Export to markdown
markdown = document.export_to_markdown()
with open("output.md", "w", encoding="utf-8") as f:
f.write(markdown)
# Export to plain text
text = document.export_to_text()
with open("output.txt", "w", encoding="utf-8") as f:
f.write(text)Tratar Erros de Forma Adequada
def safe_process_document(file_path):
"""Process document with error handling."""
try:
converter = DocumentConverter()
result = converter.convert(file_path)
return result.document
except FileNotFoundError:
print(f"File not found: {file_path}")
return None
except Exception as e:
print(f"Error processing {file_path}: {e}")
return NoneConstruir um Sistema de Pesquisa de Documentos
Um dos casos de uso mais comuns do Docling é a construção de sistemas de pesquisa de documentos com IA. Ao combinar o processamento de documentos do Docling com modelos de embedding, é possível criar capacidades de pesquisa semântica poderosas.
from docling.document_converter import DocumentConverter
from docling.chunking import HybridChunker
from transformers import AutoTokenizer, AutoModel
import torch
# Process and embed documents
def build_document_index(file_paths):
converter = DocumentConverter()
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
model = AutoModel.from_pretrained("bert-base-uncased")
chunker = HybridChunker(tokenizer=tokenizer, max_tokens=512)
document_index = []
for file_path in file_paths:
# Convert and chunk
result = converter.convert(file_path)
chunks = list(chunker.chunk(result.document))
# Create embeddings for each chunk
for chunk in chunks:
inputs = tokenizer(chunk.text, return_tensors="pt",
truncation=True, max_length=512)
with torch.no_grad():
embedding = model(**inputs).last_hidden_state.mean(dim=1)
document_index.append({
'text': chunk.text,
'embedding': embedding,
'source': file_path
})
return document_indexDicas de Desempenho
Escolher o Tamanho de Chunk Certo
Ajuste o tamanho do chunk ao seu modelo de embedding:
# For most sentence transformers (512 token limit)
chunker = HybridChunker(tokenizer=tokenizer, max_tokens=512)
# For models with larger context windows
chunker = HybridChunker(tokenizer=tokenizer, max_tokens=2048)Processar Ficheiros em Paralelo
from concurrent.futures import ThreadPoolExecutor
def process_multiple_files(file_paths, max_workers=4):
with ThreadPoolExecutor(max_workers=max_workers) as executor:
results = list(executor.map(process_document, file_paths))
return resultsConclusão
O Docling simplifica o processamento de documentos ao oferecer uma API simples que permite converter qualquer documento com apenas algumas linhas de código. As suas capacidades de divisão inteligente separam os documentos em partes com significado que preservam o contexto e a estrutura, tornando-o ideal para aplicações de IA.
Quer esteja a construir um sistema de pesquisa, um chatbot, uma ferramenta de análise de documentos ou qualquer aplicação de IA que precise de trabalhar com documentos, o Docling fornece a base de que necessita.
A combinação de facilidade de utilização e funcionalidades avançadas torna esta biblioteca numa excelente escolha tanto para prototipagem como para aplicações em produção. Com suporte multi-formato para PDFs, documentos Word, HTML e muito mais, além de OCR integrado para documentos digitalizados, o Docling trata da complexidade do processamento de documentos para que não tenha de o fazer.
Recursos
Pode encontrar o projeto Docling no GitHub, onde tem acesso ao código-fonte e a documentação adicional. Para trabalhar com modelos transformer e tokenizers, consulte a documentação do Hugging Face Transformers. A documentação do Docling fornece informação mais detalhada sobre funcionalidades avançadas e opções de configuração.
