Chunky - Kit de Herramientas de Chunking para RAG
Chunky es un conjunto de herramientas de código abierto para construir canalizaciones de ingestión RAG confiables, enfocadas en la etapa a menudo descuidada de chunking. Convierte PDFs a Markdown, limpia documentos, te deja inspeccionar chunks y comparar estrategias de chunking lado a lado, y enriquece metadatos de chunk para aplicaciones LLM. Porque la calidad de recuperación está limitada por cómo se dividen los documentos, el valor de Chunky es hacer la etapa de chunking visible y ajustable en lugar de un ciego predeterminado.
Instalación
| Método | Comando |
|---|
| pip | pip install chunky |
| uv | uv add chunky |
| Desde fuente | git clone https://github.com/GiovanniPasq/chunky && cd chunky && pip install -e . |
| Verificar | python -c "import chunky; print('ok')" |
Etapas de Canalización
| Etapa | Propósito |
|---|
| Convertir | Convierte PDFs/docs en Markdown limpio |
| Limpiar | Elimina código estándar, corrige artefactos |
| Dividir | Divide texto usando una estrategia elegida |
| Inspeccionar | Visualiza los chunks resultantes |
| Comparar | Ejecuta múltiples estrategias y compara |
| Enriquecer | Adjunta metadatos (encabezados, fuente, posición) |
Convertir y Limpiar
import chunky
# Convierte un PDF a Markdown limpio
md = chunky.to_markdown("report.pdf")
# Limpia artefactos comunes (encabezados/pies, guionado, ruido)
md = chunky.clean(md)
| Función | Descripción |
|---|
to_markdown(path) | Convierte un documento a Markdown |
clean(text) | Quita código estándar y normaliza |
Estrategias de Chunking
| Estrategia | Se divide en |
|---|
| Tamaño fijo | N tokens/caracteres con solapamiento |
| Recursiva | Párrafos → oraciones → palabras según sea necesario |
| Markdown / consciente de encabezado | Estructura de documento (#, ##, secciones) |
| Semántica | Límites de similitud de incrustación |
| Refinamiento consciente de tokens | Fusiona chunks pequeños, divide grandes |
chunks = chunky.chunk(
md,
strategy="header_aware",
max_tokens=512,
overlap=64,
repeat_headers=True, # lleva encabezados de sección a través de divisiones de tabla
)
for c in chunks:
print(len(c.tokens), c.metadata["heading"])
Inspeccionar y Comparar
El diferenciador: ve y compara lo que produce cada estrategia antes de comprometerse.
# Inspecciona límites de chunk y tamaños
chunky.inspect(chunks) # tamaños, solapamientos, límites
# Compara estrategias en el mismo documento
report = chunky.compare(
md,
strategies=["fixed", "recursive", "header_aware", "semantic"],
max_tokens=512,
)
print(report) # estadísticas por estrategia: conteo, distribución de tamaño, fragmentación
| Función | Muestra |
|---|
inspect(chunks) | Distribución de tamaño, solapamiento, límites |
compare(text, strategies=[...]) | Métricas de estrategia lado a lado |
| Metadatos | Uso en recuperación |
|---|
| Ruta de encabezado | Expansión de contexto / filtrado |
| Fuente + página | Citaciones |
| Posición/índice | Ordenamiento y búsqueda de vecino |
| Conteo de token | Gestión de presupuesto en tiempo de prompt |
enriched = chunky.enrich(chunks, source="report.pdf")
# cada chunk.metadata ahora lleva ruta de encabezado, página, fuente, índice
Flujos de Trabajo Comunes
# De extremo a extremo: PDF → Markdown limpio → chunks conscientes de encabezado → 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")
# incrusta chunk.text, almacena chunk.metadata al lado en tu BD vectorial
# Elige una estrategia con evidencia, no adivinación
print(chunky.compare(md, strategies=["recursive", "header_aware", "semantic"]))
Chunky vs Otros Enfoques
| Aspecto | Chunky | Divisores predeterminados del marco | Docling |
|---|
| Comparación de estrategia | Clase de primera | Manual | Limitada |
| Conversión + limpieza | Integrada | Separada | Integrada |
| Mejor para | Ajuste de etapa de chunking | Inicio rápido | Análisis completo + chunk |
Funciona bien con Docling para análisis y tu BD vectorial para almacenamiento — el trabajo de Chunky es acertar la división.
Recursos
