~/tools / Embeddings e busca (RAG) / RAG Text Chunker

RAG Text Chunker — Divida texto em pedaços sobrepostos para RAG e monte uma requisição /api/embed do Ollama

Divida um documento longo em pedaços (chunks) com um comprimento máximo e uma sobreposição (overlap) antes de criar os embeddings para RAG ou busca semântica. O texto é cortado primeiro nos parágrafos, depois nas linhas, frases e espaços, e só é cortado dentro de uma palavra quando nada mais serve. Você recebe os pedaços e um comando curl pronto para executar com o /api/embed do Ollama, com todos os pedaços em uma única requisição. Nada sai do seu navegador.

Os comprimentos estão em caracteres. A janela de contexto do modelo está em tokens, e quantos tokens um texto usa depende do modelo, então deixe uma margem.

Comando curl

Execute em uma máquina que alcance o Ollama. A resposta tem um vetor por pedaço, nesta ordem.

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
}'

Pedaços

3 pedaços. O mais longo tem 294 caracteres.

  1. #0 · 294 caracteres · começa na posição 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 · começa na posição 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 · começa na posição 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.

Corpo 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 da requisição conforme a referência da API do Ollama para /api/embed, conferidos em 2026-11-04. Ollama API: Generate embeddings

Tudo é feito no seu navegador. A ferramenta apenas escreve o comando e não envia nada.

O endpoint /api/embed do Ollama aceita uma única string ou um array de strings, e a referência da API diz que, por padrão, a entrada mais longa que a janela de contexto do modelo é truncada. Por isso, um documento longo enviado como uma única string pode perder o final sem nenhum erro, e um único vetor para um documento inteiro dificulta que uma busca devolva a parte que responde a uma pergunta. A solução habitual é dividir o documento em pedaços menores e criar o embedding de cada um. Esta ferramenta divide o texto no maior limite que couber: primeiro as linhas em branco entre parágrafos, depois as quebras de linha, depois os finais de frase (incluindo 。!?), depois os espaços, e caracteres isolados apenas como último recurso. Ela mantém os separadores, de modo que os pedaços juntos novamente dão o texto original. Uma sobreposição repete o final de um pedaço no início do seguinte, em peças inteiras, para que uma frase cortada em um limite apareça inteira em um pedaço. Os comprimentos são contados em caracteres. O resultado é uma requisição /api/embed com todos os pedaços no array input, com truncate em false se você quiser um erro em vez de um truncamento silencioso. A divisão foi conferida com exemplos contados à mão e confirmando que cada pedaço é um trecho do texto original na posição mostrada.

A lógica principal desta ferramenta é de código aberto, sob a licença MIT. github.com/seigo5555/toolkitbox-lib/src/text-chunk.ts

Casos de uso

  • Preparar um manual, um FAQ ou um README para uma busca RAG no seu próprio servidor Ollama, e criar os embeddings de todos os pedaços em uma única requisição
  • Encontrar um tamanho de pedaço que mantenha os parágrafos juntos, mudando o tamanho e observando onde caem os limites
  • Garantir que nada seja cortado em silêncio: ative truncate false, e o Ollama devolve um erro quando um pedaço é longo demais para o modelo

Como usar

  1. Cole o texto. Separe os parágrafos com uma linha em branco para que sejam mantidos juntos quando possível.
  2. Defina o comprimento máximo do pedaço e a sobreposição em caracteres, o nome do modelo de embeddings e o endereço do seu servidor Ollama, se não for http://localhost:11434.
  3. Copie o comando curl e execute-o em uma máquina que alcance o Ollama. A resposta contém um vetor por pedaço, na mesma ordem. O Embedding Similarity Calculator deste site pode compará-los.

FAQ

Que tamanho de pedaço devo usar?

Não existe um único tamanho certo. Cada pedaço precisa caber na janela de contexto do modelo, que é contada em tokens, e pedaços menores permitem que uma busca aponte para um trecho mais específico. Comece com um tamanho que mantenha um ou dois parágrafos juntos e depois compare os resultados da busca com o Embedding Similarity Calculator.

Por que caracteres e não tokens?

Cada modelo de embeddings tem seu próprio tokenizador, então o mesmo texto corresponde a quantidades diferentes de tokens em modelos diferentes, e uma ferramenta de navegador não consegue contá-los com exatidão para todos os modelos. A biblioteca do Ollama lista a janela de contexto de cada modelo em tokens; por exemplo, mostra 2K para embeddinggemma e nomic-embed-text e 512 para mxbai-embed-large e all-minilm. Deixe uma margem e use truncate false para encontrar os pedaços que são longos demais.

O que faz truncate false?

A referência da API do Ollama diz que truncate é true por padrão, o que trunca as entradas que excedem a janela de contexto. Com false, o Ollama devolve um erro. A ferramenta acrescenta "truncate": false quando a caixa está marcada, para que um pedaço longo demais falhe de forma visível em vez de ser encurtado.

Como funciona a sobreposição?

Quando um novo pedaço começa, as últimas peças do pedaço anterior (frases, linhas ou palavras) são repetidas no início dele, desde que caibam no comprimento da sobreposição e que o pedaço fique dentro do máximo. As peças nunca são cortadas para preencher a sobreposição, então a sobreposição real pode ser menor que o número que você definiu.

Ela entende Markdown, HTML ou código?

Não. Ela trata tudo como texto simples e divide nos parágrafos, linhas, frases e espaços. Remova a marcação que você não quer nos embeddings antes de colar o texto.

Meu texto é enviado para algum lugar?

Não. O texto é dividido no seu navegador, e a ferramenta apenas escreve o comando. Nada é enviado até que você mesmo o execute.

Artigos relacionados

Relacionados