Chunky - Kit de Ferramentas de Chunking para RAG
Chunky é um toolkit de código aberto para construir pipelines de ingestão confiável de RAG, focado no estágio de chunking frequentemente negligenciado. Converte PDFs para Markdown, limpa documentos, deixa você inspecionar chunks e comparar estratégias de chunking lado a lado, e enriquece metadados de chunks para aplicações LLM. Como a qualidade de recuperação é limitada por como os documentos são divididos, o valor do Chunky é tornar a etapa de chunking visível e ajustável em vez de um padrão cego.
Instalação
| Método | Comando |
|---|
| pip | pip install chunky |
| uv | uv add chunky |
| From source | git clone https://github.com/GiovanniPasq/chunky && cd chunky && pip install -e . |
| Verificar | python -c "import chunky; print('ok')" |
Estágios do Pipeline
| Estágio | Propósito |
|---|
| Converter | Transforme PDFs/docs em Markdown limpo |
| Limpar | Remova boilerplate, corrija artefatos |
| Chunk | Divida texto usando uma estratégia escolhida |
| Inspecionar | Visualize os chunks resultantes |
| Comparar | Execute múltiplas estratégias e compare |
| Enriquecer | Anexe metadados (cabeçalhos, origem, posição) |
Converter e Limpar
import chunky
# Converta um PDF para Markdown limpo
md = chunky.to_markdown("report.pdf")
# Limpe artefatos comuns (cabeçalhos/rodapés, hifenação, ruído)
md = chunky.clean(md)
| Função | Descrição |
|---|
to_markdown(path) | Converta um documento para Markdown |
clean(text) | Remova boilerplate e normalize |
Estratégias de Chunking
| Estratégia | Divide em |
|---|
| Tamanho fixo | N tokens/caracteres com sobreposição |
| Recursivo | Parágrafos → sentenças → palavras conforme necessário |
| Markdown / ciente de cabeçalho | Estrutura do documento (#, ##, seções) |
| Semântico | Limites de similaridade de embedding |
| Refinamento ciente de token | Mescle chunks pequenos, divida grandes |
chunks = chunky.chunk(
md,
strategy="header_aware",
max_tokens=512,
overlap=64,
repeat_headers=True, # carregue cabeçalhos de seção entre divisões de tabela
)
for c in chunks:
print(len(c.tokens), c.metadata["heading"])
Inspecionar e Comparar
O diferencial: veja e compare o que cada estratégia produz antes de se comprometer.
# Inspecione limites e tamanhos de chunk
chunky.inspect(chunks) # tamanhos, sobreposições, limites
# Compare estratégias no mesmo documento
report = chunky.compare(
md,
strategies=["fixed", "recursive", "header_aware", "semantic"],
max_tokens=512,
)
print(report) # por-estratégia stats: contagem, distribuição de tamanho, fragmentação
| Função | Mostra |
|---|
inspect(chunks) | Distribuição de tamanho, sobreposição, limites |
compare(text, strategies=[...]) | Métricas de estratégia lado a lado |
| Metadado | Uso em recuperação |
|---|
| Caminho de cabeçalho | Expansão de contexto / filtragem |
| Origem + página | Citações |
| Posição/índice | Ordenação e busca de vizinho |
| Contagem de token | Gerenciamento de orçamento na hora de prompt |
enriched = chunky.enrich(chunks, source="report.pdf")
# cada chunk.metadata agora carrega caminho de cabeçalho, página, origem, índice
Fluxos de Trabalho Comuns
# Ponta a ponta: PDF → Markdown limpo → chunks cientes de cabeçalho → enriquecido
import chunky
md = chunky.clean(chunky.to_markdown("manual.pdf"))
chunks = chunky.chunk(md, strategy="header_aware", max_tokens=512, overlap=64)
chunks = chunky.enrich(chunks, source="manual.pdf")
# embed chunk.text, armazene chunk.metadata ao lado em seu BD vetorial
# Escolha uma estratégia com evidência, não adivinhação
print(chunky.compare(md, strategies=["recursive", "header_aware", "semantic"]))
Chunky vs Outras Abordagens
| Aspecto | Chunky | Divisores padrão de framework | Docling |
|---|
| Comparação de estratégia | Primeira classe | Manual | Limitada |
| Conversão + limpeza | Construída | Separada | Construída |
| Melhor para | Ajustar a etapa de chunking | Início rápido | Parse completo + chunk |
Combina bem com Docling para análise e seu BD vetorial para armazenamento — o trabalho do Chunky é acertar a divisão.
Recursos
