Agrupación por lotes y fragmentación
En esta página
El desafío de los grandes volúmenes
Cuando trabajas con miles de documentos, no puedes codificarlo todo en una única llamada a la API. Debes gestionar el procesamiento por lotes (agrupar elementos para procesarlos) y la fragmentación (dividir el texto). Estas dos técnicas son esenciales para construir sistemas de búsqueda semántica escalables.
Aunque ambos conceptos suenan similares, resuelven problemas opuestos. La fragmentación se ocupa de un único documento demasiado grande para ser codificado eficazmente en su totalidad; el procesamiento por lotes gestiona demasiados documentos para caber en una sola solicitud. Un manual técnico de trescientas páginas pertenece a la primera categoría, una exportación de veinte mil tickets a la segunda, y un proyecto real casi siempre implica ambas.
Procesamiento por lotes: trabajar en grupos
La API mistral-embed acepta una lista de entradas, pero existen límites prácticos (tamaño de la solicitud, recuento de tokens). La solución consiste en dividir tu corpus en lotes e iterar sobre ellos. La siguiente función hace exactamente eso, mostrando el progreso, un detalle crítico cuando codificar un corpus completo lleva varios minutos y necesitas saber si el proceso avanza o se ha bloqueado.
import numpy as np
from mistralai.client import Mistral
client = Mistral(api_key=api_key)
def get_embeddings_by_chunks(data, chunk_size=25):
"""Codifica una lista grande de textos en lotes."""
chunks = [data[x:x + chunk_size] for x in range(0, len(data), chunk_size)]
embeddings = []
for i, chunk in enumerate(chunks):
print(f"Lote {i+1}/{len(chunks)} ({len(chunk)} textos)...")
response = client.embeddings.create(
model="mistral-embed",
inputs=chunk,
)
embeddings.extend([d.embedding for d in response.data])
return embeddings
# Ejemplo con 1000 documentos
documents = [f"Documento número {i} con contenido variado." for i in range(1000)]
all_embeddings = get_embeddings_by_chunks(documents, chunk_size=50)
print(f"Total: {len(all_embeddings)} embeddings de {len(all_embeddings[0])} dimensiones")
El uso de extend en lugar de append garantiza que el orden de los vectores coincida exactamente con el orden del texto de entrada. Esto te permite recuperar el documento original a partir de un índice simple más adelante.
Optimización del tamaño del lote
El tamaño óptimo del lote depende de la longitud media de tus textos: cincuenta títulos de artículos y cincuenta informes completos no pesan lo mismo en tokens. En lugar de elegir una constante al azar, estímala a partir del propio corpus.
def optimal_batch_size(documents, max_tokens_per_batch=16000):
"""Estima el tamaño óptimo del lote."""
# Estimación aproximada: 1 token ~ 4 caracteres en inglés
avg_chars = sum(len(d) for d in documents) / len(documents)
avg_tokens = avg_chars / 4
batch_size = max(1, int(max_tokens_per_batch / avg_tokens))
return min(batch_size, 100) # Límite en 100
# Ajustar según tu corpus
batch_size = optimal_batch_size(documents)
print(f"Tamaño de lote recomendado: {batch_size}")
El límite en 100 no es cosmético: más allá de ese punto, un único lote fallido provoca una pérdida significativa de trabajo, y la memoria consumida por la respuesta se vuelve sustancial.
Fragmentación: división del texto
Los textos largos deben dividirse en fragmentos antes de ser codificados. Existen varias estrategias, cada una con sus ventajas, y la elección impacta directamente en la calidad de la respuesta: un fragmento que comienza en mitad de una frase produce un vector impreciso, lo que deriva en resultados de búsqueda borrosos.
División por caracteres (simple)
El método más directo corta cada N caracteres, independientemente del contenido. Su mérito es la previsibilidad y la velocidad, lo que lo hace aceptable para un prototipo o para texto sin estructura clara.
def chunk_by_chars(text, chunk_size=2048, overlap=200):
"""Divide el texto en fragmentos con solapamiento."""
chunks = []
start = 0
while start < len(text):
end = start + chunk_size
chunk = text[start:end]
chunks.append(chunk)
start = end - overlap # Solapamiento para contexto
return chunks
long_text = "Un documento muy largo..." * 500
chunks = chunk_by_chars(long_text, chunk_size=2048, overlap=200)
print(f"{len(chunks)} fragmentos creados")
División por párrafos (recomendada)
La división por párrafos respeta la unidad de significado pretendida por el autor. En la documentación de producto, cada párrafo suele cubrir un punto específico; mantenerlo intacto genera un fragmento capaz de responder a una pregunta por sí mismo. La función acumula párrafos hasta que se supera el tamaño máximo y luego cierra el fragmento actual.
def chunk_by_paragraphs(text, max_chunk_size=2048):
"""Divide respetando los límites de los párrafos."""
paragraphs = text.split("\n\n")
chunks = []
current_chunk = ""
for para in paragraphs:
if len(current_chunk) + len(para) + 2 > max_chunk_size:
if current_chunk:
chunks.append(current_chunk.strip())
current_chunk = para
else:
current_chunk += "\n\n" + para if current_chunk else para
if current_chunk:
chunks.append(current_chunk.strip())
return chunks
División por frases
Cuando el texto carece de párrafos utilizables —una transcripción de llamada, un registro de ejecución—, la frase se convierte en la unidad de significado disponible más pequeña. La división sigue entonces la misma lógica de acumulación, basándose en la puntuación de final de frase.
import re
def chunk_by_sentences(text, max_chunk_size=1500):
"""Divide respetando los límites de las frases."""
# Dividir por puntuación de final de frase
sentence_pattern = r'(?<=[.!?])\s+'
sentences = re.split(sentence_pattern, text)
chunks = []
current_chunk = ""
for sentence in sentences:
if len(current_chunk) + len(sentence) + 1 > max_chunk_size:
if current_chunk:
chunks.append(current_chunk.strip())
current_chunk = sentence
else:
current_chunk += " " + sentence if current_chunk else sentence
if current_chunk:
chunks.append(current_chunk.strip())
return chunks
Solapamiento
El solapamiento entre fragmentos evita cortar una idea por la mitad. Al añadir un solapamiento del 10 % al 20 % del tamaño del fragmento, conservas el contexto entre piezas adyacentes. Imagina un procedimiento donde el paso 4 termina en el carácter 2040 y la consecuencia se explica inmediatamente después: sin solapamiento, ningún fragmento contiene ambas mitades del razonamiento y la búsqueda nunca recuperará la respuesta completa.
Los valores siguientes sirven como puntos de partida probados dependiendo del tipo de contenido:
# Parámetros recomendados por tipo de contenido
PARAMS = {
"articles": {"chunk_size": 1500, "overlap": 200},
"documentation": {"chunk_size": 1000, "overlap": 150},
"conversations": {"chunk_size": 500, "overlap": 50},
"code": {"chunk_size": 2000, "overlap": 300},
}
Las conversaciones bajan a 500 caracteres porque un turno de palabra es breve, y un fragmento mayor mezclaría múltiples temas; el código sube a 2000 con un solapamiento generoso porque una función pierde significado si su firma se separa de su cuerpo.
Canalización completa: fragmentar + lotes + incrustar
Así es como combinar la fragmentación y el procesamiento por lotes en una canalización de producción. El elemento que no debes descuidar es chunk_metadata: sin él, obtienes vectores huérfanos incapaces de indicar de qué documento proceden, y nunca podrás citar tus fuentes en la respuesta final.
def pipeline_embed(documents, chunk_size=1500, overlap=200, batch_size=50):
"""Canalización completa: fragmentar, lotes, incrustar."""
# 1. Fragmentar todos los documentos
all_chunks = []
chunk_metadata = [] # Rastrear documento origen
for doc_idx, doc in enumerate(documents):
chunks = chunk_by_paragraphs(doc, max_chunk_size=chunk_size)
for chunk_idx, chunk in enumerate(chunks):
all_chunks.append(chunk)
chunk_metadata.append({
"doc_index": doc_idx,
"chunk_index": chunk_idx,
})
print(f"{len(documents)} documentos -> {len(all_chunks)} fragmentos")
# 2. Codificar en lotes
embeddings = get_embeddings_by_chunks(all_chunks, chunk_size=batch_size)
# 3. Devolver resultados estructurados
return {
"chunks": all_chunks,
"embeddings": np.array(embeddings),
"metadata": chunk_metadata,
}
# Uso
result = pipeline_embed(documents)
print(f"Incrustaciones: {result['embeddings'].shape}")
Ejecuta esta canalización con una docena de tus documentos reales e inspecciona all_chunks visualmente antes de codificar nada a gran escala. Una mala división es inmediatamente visible al leer, mientras que nunca aparece en la forma de la matriz.
Puntos clave
- El procesamiento por lotes te permite codificar miles de documentos sin exceder los límites de la API
- La fragmentación divide textos largos para mejorar la granularidad semántica
- Un solapamiento del 10–20 % entre fragmentos preserva el contexto
- La división por párrafos o frases es preferible a la división por caracteres
- Mantén los metadatos (documento origen, posición) para cada fragmento