Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Agrupamento e Fragmentação

Aula 4 de 18 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. O Desafio dos Grandes Volumes
  2. Agrupamento: Processamento em Lotes
  3. Fragmentação: Divisão do Texto
  4. Sobreposição
  5. Pipeline Completo: Fragmentar + Agrupar + Incorporar
  6. Pontos-chave

O Desafio dos Grandes Volumes

Quando trabalha com milhares de documentos, não consegue codificar tudo numa única chamada à API. Tem de gerir o agrupamento (processamento em lotes) e a fragmentação (divisão do texto). Estas duas técnicas são essenciais para construir sistemas de pesquisa semântica à escala.

Os dois conceitos parecem semelhantes, mas resolvem problemas opostos. A fragmentação lida com um único documento demasiado grande para ser codificado eficazmente na sua totalidade; o agrupamento lida com demasiados documentos para caberem num único pedido. Um manual técnico de trezentas páginas enquadra-se na primeira categoria, uma exportação de vinte mil tickets na segunda, e um projeto do mundo real envolve quase sempre ambos.

Agrupamento: Processamento em Lotes

A API mistral-embed aceita uma lista de entradas, mas existem limites práticos (tamanho do pedido, contagem de tokens). A solução consiste em dividir o seu corpus em lotes e percorrer esse ciclo. A função abaixo faz exatamente isso, apresentando o progresso — um detalhe crítico quando a codificação de um corpus completo demora vários minutos e precisa de saber se o processo está a avançar ou 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 uma grande lista de textos em 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

# Exemplo com 1000 documentos
documents = [f"Documento número {i} com conteúdo 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])} dimensões")

Utilizar extend em vez de append garante que a ordem dos vetores corresponde exatamente à ordem do texto de entrada. Isto permite-lhe recuperar o documento original a partir de um índice simples mais tarde.

Otimização do Tamanho do Lote

O tamanho ideal do lote depende do comprimento médio dos seus textos: cinquenta títulos de artigos e cinquenta relatórios completos não pesam o mesmo em tokens. Em vez de escolher uma constante ao acaso, estime-a a partir do próprio corpus.

def optimal_batch_size(documents, max_tokens_per_batch=16000):
    """Estima o tamanho ideal do lote."""
    # Estimativa aproximada: 1 token ~ 4 caracteres em 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)  # Limite máximo de 100

# Ajuste com base no seu corpus
batch_size = optimal_batch_size(documents)
print(f"Tamanho de lote recomendado: {batch_size}")

O limite máximo de 100 não é cosmético: além desse valor, um único lote falhado causa uma perda significativa de trabalho, e a memória consumida pela resposta torna-se substancial.

Fragmentação: Divisão do Texto

Textos longos devem ser divididos em fragmentos antes da codificação. Existem várias estratégias, cada uma com as suas vantagens, e a escolha impacta diretamente a qualidade da resposta: um fragmento que começa no meio de uma frase produz um vetor impreciso, levando a resultados de pesquisa pouco nítidos.

Divisão Baseada em Caracteres (Simples)

O método mais direto corta a cada N caracteres, independentemente do conteúdo. O seu mérito é a previsibilidade e a velocidade, tornando-o aceitável para um protótipo ou para texto sem estrutura clara.

def chunk_by_chars(text, chunk_size=2048, overlap=200):
    """Divide o texto em fragmentos com sobreposição."""
    chunks = []
    start = 0
    while start < len(text):
        end = start + chunk_size
        chunk = text[start:end]
        chunks.append(chunk)
        start = end - overlap  # Sobreposição para contexto
    return chunks

long_text = "Um documento muito longo..." * 500
chunks = chunk_by_chars(long_text, chunk_size=2048, overlap=200)
print(f"{len(chunks)} fragmentos criados")

Divisão Baseada em Parágrafos (Recomendada)

A divisão baseada em parágrafos respeita a unidade de significado pretendida pelo autor. Na documentação de produtos, cada parágrafo cobre geralmente um ponto específico; mantê-lo intacto produz um fragmento capaz de responder a uma pergunta por si só. A função acumula parágrafos até que o tamanho máximo seja excedido, fechando então o fragmento atual.

def chunk_by_paragraphs(text, max_chunk_size=2048):
    """Divide respeitando os limites dos parágrafos."""
    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

Divisão Baseada em Frases

Quando o texto carece de parágrafos utilizáveis — uma transcrição de chamada, um registo de execução — a frase torna-se a menor unidade de significado disponível. A divisão segue então a mesma lógica de acumulação, baseando-se na pontuação de fim de frase.

import re

def chunk_by_sentences(text, max_chunk_size=1500):
    """Divide respeitando os limites das frases."""
    # Dividir na pontuação de fim 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

Sobreposição

A sobreposição entre fragmentos impede que uma ideia seja cortada ao meio. Ao adicionar uma sobreposição de 10% a 20% do tamanho do fragmento, preserva o contexto entre peças adjacentes. Imagine um procedimento onde o passo 4 termina no caractere 2040 e a consequência é explicada imediatamente a seguir: sem sobreposição, nenhum fragmento contém ambas as metades do raciocínio, e a pesquisa nunca recuperará a resposta completa.

Os valores abaixo servem como pontos de partida comprovados, dependendo do tipo de conteúdo:

# Parâmetros recomendados por tipo de conteúdo
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},
}

As conversas descem para 500 caracteres porque uma intervenção de fala é curta, e um fragmento maior misturaria múltiplos tópicos; o código sobe para 2000 com uma sobreposição generosa porque uma função perde significado se a sua assinatura for separada do seu corpo.

Pipeline Completo: Fragmentar + Agrupar + Incorporar

Eis como combinar fragmentação e agrupamento num pipeline de produção. O elemento que não deve negligenciar é o chunk_metadata: sem ele, obtém vetores órfãos incapazes de indicar de qual documento provêm, e nunca conseguirá citar as suas fontes na resposta final.

def pipeline_embed(documents, chunk_size=1500, overlap=200, batch_size=50):
    """Pipeline completo: fragmentar, agrupar, incorporar."""
    # 1. Fragmentar todos os documentos
    all_chunks = []
    chunk_metadata = []  # Rastrear documento de origem

    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 em lotes
    embeddings = get_embeddings_by_chunks(all_chunks, chunk_size=batch_size)

    # 3. Devolver resultados estruturados
    return {
        "chunks": all_chunks,
        "embeddings": np.array(embeddings),
        "metadata": chunk_metadata,
    }

# Utilização
result = pipeline_embed(documents)
print(f"Embeddings: {result['embeddings'].shape}")

Execute este pipeline numa dúzia dos seus documentos reais e inspecione o all_chunks visualmente antes de codificar qualquer coisa à escala. Uma má divisão é imediatamente visível ao ler, ao passo que nunca aparece na forma da matriz.

Pontos-chave

  • O agrupamento permite codificar milhares de documentos sem exceder os limites da API
  • A fragmentação divide textos longos para uma melhor granularidade semântica
  • Uma sobreposição de 10–20% entre fragmentos preserva o contexto
  • A divisão por parágrafos ou frases é preferível à divisão por caracteres
  • Mantenha metadados (documento de origem, posição) para cada fragmento