~/tools / Embedding e ricerca (RAG) / RAG Text Chunker

RAG Text Chunker — Dividi il testo in pezzi sovrapposti per RAG e costruisci una richiesta /api/embed di Ollama

Dividi un documento lungo in pezzi (chunk) con una lunghezza massima e una sovrapposizione (overlap) prima di crearne gli embedding per RAG o ricerca semantica. Il testo viene tagliato prima in corrispondenza dei paragrafi, poi di righe, frasi e spazi, e solo all'interno di una parola quando nient'altro va bene. Ottieni i pezzi e un comando curl pronto da eseguire per l'/api/embed di Ollama, con tutti i pezzi in un'unica richiesta. Nulla lascia il tuo browser.

Le lunghezze sono in caratteri. La finestra di contesto del modello è in token, e quanti token usa un testo dipende dal modello, quindi lascia un margine.

Comando curl

Eseguilo su una macchina che raggiunge Ollama. La risposta ha un vettore per pezzo, in quest'ordine.

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

Pezzi

3 pezzi. Il più lungo ha 294 caratteri.

  1. #0 · 294 caratteri · inizia alla posizione 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 caratteri · inizia alla posizione 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 caratteri · inizia alla posizione 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 per /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
}

Campi della richiesta come indicati nel riferimento dell'API di Ollama per /api/embed, verificati il 2026-11-04. Ollama API: Generate embeddings

Tutto avviene nel tuo browser. Lo strumento si limita a scrivere il comando e non invia nulla.

L'endpoint /api/embed di Ollama accetta una singola stringa o un array di stringhe, e il riferimento dell'API dice che, per impostazione predefinita, l'input più lungo della finestra di contesto del modello viene troncato. Un documento lungo inviato come singola stringa può quindi perdere la parte finale senza alcun errore, e un solo vettore per un intero documento rende difficile per una ricerca restituire la parte che risponde a una domanda. La soluzione abituale è dividere il documento in pezzi più piccoli e creare l'embedding di ciascuno. Questo strumento divide il testo al confine più grande che sia adatto: prima le righe vuote tra i paragrafi, poi gli a capo, poi le fini di frase (inclusi 。!?), poi gli spazi, e i singoli caratteri solo come ultima risorsa. Conserva i separatori, così i pezzi rimessi insieme ridanno il testo originale. Una sovrapposizione ripete la fine di un pezzo all'inizio del successivo, per parti intere, in modo che una frase tagliata a un confine compaia intera in un pezzo. Le lunghezze sono contate in caratteri. Il risultato è una richiesta /api/embed con tutti i pezzi nell'array input, con truncate impostato su false se vuoi un errore invece di un troncamento silenzioso. La divisione è stata verificata con esempi contati a mano e controllando che ogni pezzo sia un tratto del testo originale nella posizione indicata.

La logica principale di questo strumento è open source, con licenza MIT. github.com/seigo5555/toolkitbox-lib/src/text-chunk.ts

Casi d'uso

  • Preparare un manuale, delle FAQ o un README per una ricerca RAG sul tuo server Ollama, e creare gli embedding di tutti i pezzi in un'unica richiesta
  • Trovare una dimensione dei pezzi che mantenga uniti i paragrafi, cambiando la dimensione e osservando dove cadono i confini
  • Assicurarti che nulla venga tagliato in silenzio: attiva truncate false, e Ollama restituisce un errore quando un pezzo è troppo lungo per il modello

Utilizzo

  1. Incolla il testo. Separa i paragrafi con una riga vuota così restano uniti quando possibile.
  2. Imposta la lunghezza massima del pezzo e la sovrapposizione in caratteri, il nome del modello di embedding e l'indirizzo del tuo server Ollama se non è http://localhost:11434.
  3. Copia il comando curl ed eseguilo su una macchina che raggiunge Ollama. La risposta contiene un vettore per pezzo, nello stesso ordine. L'Embedding Similarity Calculator di questo sito può confrontarli.

FAQ

Quale dimensione dei pezzi devo usare?

Non esiste un'unica dimensione giusta. Ogni pezzo deve stare nella finestra di contesto del modello, che si conta in token, e pezzi più piccoli permettono a una ricerca di indicare un passaggio più specifico. Parti da una dimensione che tenga uniti uno o due paragrafi, poi confronta i risultati di ricerca con l'Embedding Similarity Calculator.

Perché caratteri e non token?

Ogni modello di embedding ha un proprio tokenizer, quindi lo stesso testo corrisponde a un numero diverso di token in modelli diversi, e uno strumento nel browser non può contarli con esattezza per ogni modello. La libreria di Ollama elenca la finestra di contesto di ciascun modello in token; per esempio, mostra 2K per embeddinggemma e nomic-embed-text e 512 per mxbai-embed-large e all-minilm. Lascia un margine e usa truncate false per individuare i pezzi troppo lunghi.

Che cosa fa truncate false?

Il riferimento dell'API di Ollama dice che truncate è true per impostazione predefinita, il che tronca gli input che superano la finestra di contesto. Con false, Ollama restituisce un errore. Lo strumento aggiunge "truncate": false quando la casella è spuntata, così un pezzo troppo lungo fallisce in modo evidente invece di essere accorciato.

Come funziona la sovrapposizione?

Quando inizia un nuovo pezzo, le ultime parti del pezzo precedente (frasi, righe o parole) vengono ripetute al suo inizio, purché stiano nella lunghezza della sovrapposizione e il pezzo resti entro il massimo. Le parti non vengono mai tagliate per riempire la sovrapposizione, quindi la sovrapposizione effettiva può essere più corta del numero che hai impostato.

Capisce Markdown, HTML o codice?

No. Tratta tutto come testo semplice e divide in corrispondenza di paragrafi, righe, frasi e spazi. Rimuovi il markup che non vuoi negli embedding prima di incollare il testo.

Il mio testo viene inviato da qualche parte?

No. Il testo viene diviso nel tuo browser, e lo strumento si limita a scrivere il comando. Non viene inviato nulla finché non lo esegui tu stesso.

Articoli correlati

Correlati