marc mayol
← Volver al blog

Chonkie: cómo trocear texto para RAG con chunkers y Pipeline

Chonkie: cómo trocear texto para RAG con chunkers y Pipeline

Cuando trabajamos con sistemas de IA generativa o RAG (Retrieval-Augmented Generation), uno de los grandes retos es el contexto. Los modelos no procesan textos infinitos. Hay que dividirlos, y hacerlo bien no es trivial: si cortas demasiado, pierdes coherencia; si cortas poco, saturas el modelo y empeoras la búsqueda.

Ahí entra Chonkie, una librería open source que automatiza el chunking, es decir, la división de textos en fragmentos con sentido. En este artículo explico cómo funciona, qué estrategias ofrece, cómo se usa su Pipeline con código probado en la versión actual y qué ha cambiado desde que escribí la primera versión de este texto.

Qué es Chonkie

Chonkie es una librería de Python para trocear texto antes de indexarlo en un sistema RAG. Ofrece una decena de estrategias de troceado, herramientas para añadir solapamiento o embeddings a cada fragmento y conectores para exportar el resultado o guardarlo en una base vectorial. Licencia MIT. Y pesa poco.

El proyecto nació en noviembre de 2024 como proyecto personal de Bhavnick Minhas, harto de reescribir el mismo código de troceado en cada aplicación RAG. Luego llegó Shreyash Nigam. Crearon la empresa, pasaron por Y Combinator en 2025 y hoy mantienen la librería junto a un servicio en la nube opcional. El código está en GitHub y la documentación en docs.chonkie.ai.

Su punto de diseño más claro es instalar solo lo que necesitas. Según su README, el paquete base pesa unos 505 KB y unos 49 MB instalado, frente a los 80 a 171 MB de alternativas que arrastran muchas dependencias:

pip install chonkie                 # base: token, fast, sentence, recursive...
pip install "chonkie[semantic]"     # troceado semántico con embeddings
pip install "chonkie[chroma]"       # conector con ChromaDB
pip install "chonkie[all]"          # todo, no recomendado en producción

Cómo funciona

Chonkie organiza el proceso en etapas que se pueden combinar: traer los documentos, prepararlos, trocearlos, refinar los fragmentos y guardarlos. Cada etapa tiene sus componentes con nombres propios, y en las versiones actuales se pueden encadenar todos con un objeto Pipeline.

Las 6 etapas, de los Fetchers a los Handshakes, con el nombre que les da la librería:

EtapaComponentePara qué sirve
TraerFetchersLeer archivos o carpetas
PrepararChefsLimpiar texto, Markdown o tablas antes de trocear
TrocearChunkersDividir el texto con una estrategia concreta
RefinarRefineriesAñadir solapamiento entre fragmentos o calcular embeddings
ExportarPortersGuardar en JSON o como dataset de Hugging Face
GuardarHandshakesEnviar a Chroma, Qdrant, pgvector, Pinecone, Weaviate, Milvus y otras

Las estrategias de troceado

Chonkie ofrece estrategias que van de lo más simple, cortar por tamaño, a lo más caro, pedir a un LLM que decida dónde cortar. Casi siempre bastan las tres o cuatro primeras; el resto solo compensa si has medido que mejoran la recuperación en tus datos.

Los chunkers disponibles en la versión 1.7:

Un detalle que conviene saber: si no indicas tokenizador, Chonkie cuenta caracteres. Si quieres que chunk_size=512 signifique 512 tokens de tu modelo, pasa tokenizer="gpt2" o el que uses (acepta tiktoken, tokenizers y transformers).

Un ejemplo sencillo

El uso más directo sigue siendo crear un chunker, por ejemplo RecursiveChunker(chunk_size=512), y llamarlo con el texto. Cada fragmento devuelto trae su texto, su número de tokens y su posición exacta en el original, lo que permite enlazar después la respuesta del modelo con el párrafo de origen.

from chonkie import RecursiveChunker

texto = "La inteligencia artificial transforma industrias enteras. Pero entenderla requiere precisión y contexto."

chunker = RecursiveChunker(chunk_size=512)
chunks = chunker(texto)

for c in chunks:
    print(c.text, c.token_count, c.start_index, c.end_index)

Con esas 6 líneas, RecursiveChunker deja el texto en fragmentos coherentes, listos para calcular embeddings o enviarlos a un modelo.

El Pipeline: todo el flujo en una expresión

El Pipeline llegó en la versión 1.4.0, en octubre de 2025, y es la forma recomendada de montar un flujo completo. Encadena las etapas con métodos como chunk_with, refine_with, export_with o store_in, y se ejecuta con run, que devuelve un Document con sus fragmentos.

from chonkie import Pipeline

pipe = (
    Pipeline()
    .fetch_from("file", dir="./docs", ext=[".md"])
    .process_with("markdown")
    .chunk_with("recursive", chunk_size=512)
    .refine_with("overlap", context_size=64)
    .export_with("json", file="chunks.json")
)

docs = pipe.run()  # una carpeta devuelve una lista de Document
for doc in docs:
    print(len(doc.chunks))

Si no lees archivos, pasa el texto directamente con pipe.run(texts="..."), que devuelve un único Document. Para guardar en una base vectorial, añade por ejemplo .store_in("qdrant", collection_name="docs", url="http://localhost:6333"), y para calcular embeddings .refine_with("embeddings", model="all-MiniLM-L6-v2") (ojo: el nombre es embeddings, en plural). Hay también una versión asíncrona, await pipe.arun(...), para volúmenes altos.

Este código lo he comprobado contra la versión 1.7.0. Si vienes de versiones anteriores a la 1.4, ten en cuenta que el antiguo argumento tokenizer_or_token_counter desapareció y ahora se llama tokenizer en todas partes.

Chonkie frente a otras opciones

Chonkie compite con los divisores de texto de LangChain y LlamaIndex, que ya vienen incluidos si usas esos frameworks. La diferencia está en que Chonkie es una librería especializada e independiente: más estrategias, más ligera y sin obligarte a adoptar un framework entero.

ChonkieLangChain text splittersLlamaIndex node parsers
EnfoqueSolo troceado e ingestaParte de un framework grandeParte de un framework grande
EstrategiasToken, frase, recursivo, semántico, late, código, tablas, neural, LLMRecursivo, por caracteres, por tokens, Markdown, códigoFrases, tokens, semántico, jerárquico
Conectores vectorialesIncluidos como extrasA través del frameworkA través del framework
LicenciaMITMITMIT

Si ya tienes todo montado sobre LangChain o LlamaIndex, sus divisores pueden bastarte. Si quieres una pieza que puedas cambiar sin tocar el resto, Chonkie encaja mejor.

Limitaciones

Chonkie resuelve bien el troceado, pero no lee PDF escaneados, no entiende la maquetación de un documento complejo y no te dice qué estrategia es la mejor para tus datos. Eso te toca a ti. Mide la calidad de la recuperación con preguntas reales y ajusta el chunk_size y el chunker, por ejemplo pasando de RecursiveChunker a SemanticChunker.

Qué ha pasado desde entonces

Desde octubre de 2025 Chonkie ha publicado tres versiones menores con un ritmo de casi una actualización al mes. Ha ganado el Pipeline, el troceado de tablas HTML, un FastChunker, soporte asíncrono nativo, una API que puedes alojar tú mismo y nuevos conversores de documentos. Su repositorio supera las 4.800 estrellas.

Según las notas de versión en GitHub y el historial de PyPI:

El repositorio ahora redirige a la organización feyninc, aunque los enlaces antiguos siguen funcionando. La librería existe también en TypeScript, para quien trabaje en Node.

Si en tu flujo hay que mantener el índice al día cuando cambian los documentos, te interesa leer también cómo encaja RAG en una arquitectura de eventos con LLMs.

Conclusión

Chonkie hace que los modelos lean mejor, porque les da fragmentos con sentido en lugar de cortes arbitrarios. Con el Pipeline, además, el flujo completo de ingesta cabe en unas pocas líneas y cada pieza se puede cambiar sin tocar el resto.

Si quieres profundizar en este tipo de herramientas, te recomiendo el artículo donde comparo Chonkie con Docling, dos enfoques complementarios para procesar documentos en arquitecturas RAG, y el artículo completo sobre Docling.

Si te ha interesado, sigue con Chunking en RAG: estrategias, solapamiento, tamaño y cómo evaluarlo y Chonkie y Docling: dos enfoques complementarios para procesar documentos en pipelines RAG.