~/tools / Embeddings y búsqueda (RAG) / RAG Text Chunker

RAG Text Chunker — Divide texto en fragmentos solapados para RAG y crea una petición /api/embed de Ollama

Divide un documento largo en fragmentos (chunks) con una longitud máxima y un solapamiento (overlap) antes de crear sus embeddings para RAG o búsqueda semántica. El texto se corta primero por párrafos, después por líneas, frases y espacios, y solo se corta dentro de una palabra cuando nada más encaja. Obtienes los fragmentos y un comando curl listo para ejecutar con el /api/embed de Ollama, con todos los fragmentos en una sola petición. Nada sale de tu navegador.

Las longitudes están en caracteres. La ventana de contexto del modelo está en tokens, y cuántos tokens usa un texto depende del modelo, así que deja un margen.

Comando curl

Ejecútalo en una máquina que pueda llegar a Ollama. La respuesta tiene un vector por fragmento, en este orden.

curl http://localhost:11434/api/embed -d '{
  "model": "embeddinggemma",
  "input": [
    "Embeddings turn text into numeric vectors. You can store them in a vector database and search them with cosine similarity, or use them in a RAG pipeline.\n\nThe length of each vector depends on the embedding model. Use the same model when you index your documents and when you embed a question.\n\n",
    "Ollama'\''s /api/embed endpoint takes a single string or an array of strings. By default, input that is longer than the model'\''s context window is truncated. Set truncate to false to get an error instead.\n\n",
    "Split long documents into smaller chunks before you embed them, so that each chunk fits in the context window and a search can return the part that answers the question."
  ],
  "truncate": false
}'

Fragmentos

3 fragmentos. El más largo tiene 294 caracteres.

  1. #0 · 294 caracteres · empieza en la posición 0

    Embeddings turn text into numeric vectors. You can store them in a vector database and search them with cosine similarity, or use them in a RAG pipeline. The length of each vector depends on the embedding model. Use the same model when you index your documents and when you embed a question.

  2. #1 · 202 caracteres · empieza en la posición 294

    Ollama's /api/embed endpoint takes a single string or an array of strings. By default, input that is longer than the model's context window is truncated. Set truncate to false to get an error instead.

  3. #2 · 169 caracteres · empieza en la posición 496

    Split long documents into smaller chunks before you embed them, so that each chunk fits in the context window and a search can return the part that answers the question.

Cuerpo JSON para /api/embed

{
  "model": "embeddinggemma",
  "input": [
    "Embeddings turn text into numeric vectors. You can store them in a vector database and search them with cosine similarity, or use them in a RAG pipeline.\n\nThe length of each vector depends on the embedding model. Use the same model when you index your documents and when you embed a question.\n\n",
    "Ollama's /api/embed endpoint takes a single string or an array of strings. By default, input that is longer than the model's context window is truncated. Set truncate to false to get an error instead.\n\n",
    "Split long documents into smaller chunks before you embed them, so that each chunk fits in the context window and a search can return the part that answers the question."
  ],
  "truncate": false
}

Campos de la petición tal como figuran en la referencia de la API de Ollama para /api/embed, comprobados el 2026-11-04. Ollama API: Generate embeddings

Todo se hace en tu navegador. La herramienta solo escribe el comando y no envía nada.

El endpoint /api/embed de Ollama acepta una sola cadena o un array de cadenas, y la referencia de la API dice que, por defecto, la entrada más larga que la ventana de contexto del modelo se trunca. Por eso, un documento largo enviado como una sola cadena puede perder su final sin ningún error, y un único vector para un documento entero dificulta que una búsqueda devuelva la parte que responde a una pregunta. La solución habitual es dividir el documento en fragmentos más pequeños y crear el embedding de cada uno. Esta herramienta divide el texto en el límite más grande que quepa: primero las líneas en blanco entre párrafos, después los saltos de línea, luego los finales de frase (incluidos 。!?), después los espacios, y los caracteres sueltos solo como último recurso. Conserva los separadores, de modo que los fragmentos unidos de nuevo dan el texto original. Un solapamiento repite el final de un fragmento al comienzo del siguiente, en piezas completas, de manera que una frase cortada en un límite aparezca entera en un fragmento. Las longitudes se cuentan en caracteres. El resultado es una petición /api/embed con todos los fragmentos en el array input, con truncate en false si quieres un error en lugar de un truncamiento silencioso. La división se comprobó con ejemplos contados a mano y confirmando que cada fragmento es un trozo del texto original en la posición indicada.

La lógica principal de esta herramienta es de código abierto, con licencia MIT. github.com/seigo5555/toolkitbox-lib/src/text-chunk.ts

Casos de uso

  • Preparar un manual, unas preguntas frecuentes (FAQ) o un README para una búsqueda RAG en tu propio servidor de Ollama, y crear los embeddings de todos los fragmentos en una sola petición
  • Encontrar un tamaño de fragmento que mantenga juntos los párrafos, cambiando el tamaño y viendo dónde caen los límites
  • Asegurarte de que nada se corta en silencio: activa truncate false, y Ollama devuelve un error cuando un fragmento es demasiado largo para el modelo

Cómo usarlo

  1. Pega el texto. Separa los párrafos con una línea en blanco para que se mantengan juntos cuando sea posible.
  2. Establece la longitud máxima del fragmento y el solapamiento en caracteres, el nombre del modelo de embeddings y la dirección de tu servidor de Ollama si no es http://localhost:11434.
  3. Copia el comando curl y ejecútalo en una máquina que pueda llegar a Ollama. La respuesta contiene un vector por fragmento, en el mismo orden. El Embedding Similarity Calculator de este sitio puede compararlos.

FAQ

¿Qué tamaño de fragmento debo usar?

No hay un único tamaño correcto. Cada fragmento debe caber en la ventana de contexto del modelo, que se cuenta en tokens, y los fragmentos más pequeños permiten que una búsqueda señale un pasaje más concreto. Empieza con un tamaño que mantenga juntos uno o dos párrafos y después compara los resultados de búsqueda con el Embedding Similarity Calculator.

¿Por qué caracteres y no tokens?

Cada modelo de embeddings tiene su propio tokenizador, así que el mismo texto son distintas cantidades de tokens en distintos modelos, y una herramienta de navegador no puede contarlos con exactitud para todos los modelos. La biblioteca de Ollama lista la ventana de contexto de cada modelo en tokens; por ejemplo, muestra 2K para embeddinggemma y nomic-embed-text y 512 para mxbai-embed-large y all-minilm. Deja un margen y usa truncate false para encontrar los fragmentos que son demasiado largos.

¿Qué hace truncate false?

La referencia de la API de Ollama dice que truncate vale true por defecto, lo que trunca las entradas que superan la ventana de contexto. Con false, Ollama devuelve un error. La herramienta añade "truncate": false cuando la casilla está marcada, de modo que un fragmento demasiado largo falle de forma visible en lugar de acortarse.

¿Cómo funciona el solapamiento?

Cuando empieza un nuevo fragmento, las últimas piezas del fragmento anterior (frases, líneas o palabras) se repiten al comienzo, siempre que quepan dentro de la longitud de solapamiento y que el fragmento no supere el máximo. Las piezas nunca se cortan para llenar el solapamiento, así que el solapamiento real puede ser más corto que el número que establezcas.

¿Entiende Markdown, HTML o código?

No. Trata todo como texto plano y divide por párrafos, líneas, frases y espacios. Quita el marcado que no quieras en los embeddings antes de pegar el texto.

¿Se envía mi texto a algún sitio?

No. El texto se divide en tu navegador, y la herramienta solo escribe el comando. No se envía nada hasta que lo ejecutes tú mismo.

Artículos relacionados

Relacionados