~/tools / Embeddings et recherche (RAG) / RAG Text Chunker

RAG Text Chunker — Découpez du texte en morceaux chevauchants pour le RAG et créez une requête /api/embed d'Ollama

Découpez un long document en morceaux (chunks) d'une longueur maximale donnée, avec un chevauchement (overlap), avant d'en créer les embeddings pour du RAG ou de la recherche sémantique. Le texte est coupé d'abord aux paragraphes, puis aux lignes, aux phrases et aux espaces, et il n'est coupé à l'intérieur d'un mot que lorsque rien d'autre ne convient. Vous obtenez les morceaux et une commande curl prête à l'emploi pour le /api/embed d'Ollama, avec tous les morceaux dans une seule requête. Rien ne quitte votre navigateur.

Les longueurs sont en caractères. La fenêtre de contexte du modèle est en tokens, et le nombre de tokens d'un texte dépend du modèle ; gardez donc une marge.

Commande curl

Exécutez-la sur une machine qui peut joindre Ollama. La réponse contient un vecteur par morceau, dans cet ordre.

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

Morceaux

3 morceaux. Le plus long compte 294 caractères.

  1. #0 · 294 caractères · commence à la position 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 caractères · commence à la position 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 caractères · commence à la position 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.

Corps JSON pour /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
}

Champs de la requête tels que donnés dans la référence de l'API d'Ollama pour /api/embed, vérifiés le 2026-11-04. Ollama API: Generate embeddings

Tout se fait dans votre navigateur. L'outil se contente d'écrire la commande et n'envoie rien.

Le endpoint /api/embed d'Ollama accepte une chaîne unique ou un tableau de chaînes, et la référence de l'API indique que, par défaut, une entrée plus longue que la fenêtre de contexte du modèle est tronquée. Un long document envoyé en une seule chaîne peut donc perdre sa fin sans aucune erreur, et un seul vecteur pour un document entier rend difficile pour une recherche de renvoyer la partie qui répond à une question. La solution habituelle consiste à découper le document en morceaux plus petits et à créer l'embedding de chacun. Cet outil coupe le texte à la plus grande frontière qui convient : d'abord les lignes vides entre paragraphes, puis les sauts de ligne, puis les fins de phrase (y compris 。!?), puis les espaces, et les caractères isolés seulement en dernier recours. Il conserve les séparateurs, de sorte que les morceaux remis bout à bout redonnent le texte d'origine. Un chevauchement répète la fin d'un morceau au début du suivant, par pièces entières, afin qu'une phrase coupée à une frontière apparaisse entière dans un morceau. Les longueurs sont comptées en caractères. Le résultat est une requête /api/embed avec tous les morceaux dans le tableau input, avec truncate à false si vous voulez une erreur plutôt qu'une troncature silencieuse. Le découpage a été vérifié sur des exemples comptés à la main et en confirmant que chaque morceau est un extrait du texte d'origine à la position indiquée.

Le cœur de cet outil est open source, sous licence MIT. github.com/seigo5555/toolkitbox-lib/src/text-chunk.ts

Cas d'usage

  • Préparer un manuel, une FAQ ou un README pour une recherche RAG sur votre propre serveur Ollama, et créer les embeddings de tous les morceaux en une seule requête
  • Trouver une taille de morceau qui garde les paragraphes ensemble, en modifiant la taille et en regardant où tombent les frontières
  • S'assurer que rien n'est coupé en silence : activez truncate false, et Ollama renvoie une erreur quand un morceau est trop long pour le modèle

Utilisation

  1. Collez le texte. Séparez les paragraphes par une ligne vide pour qu'ils restent ensemble autant que possible.
  2. Réglez la longueur maximale des morceaux et le chevauchement en caractères, le nom du modèle d'embeddings et l'adresse de votre serveur Ollama si ce n'est pas http://localhost:11434.
  3. Copiez la commande curl et exécutez-la sur une machine qui peut joindre Ollama. La réponse contient un vecteur par morceau, dans le même ordre. L'Embedding Similarity Calculator de ce site peut les comparer.

FAQ

Quelle taille de morceau dois-je utiliser ?

Il n'existe pas de taille idéale unique. Chaque morceau doit tenir dans la fenêtre de contexte du modèle, qui se compte en tokens, et des morceaux plus petits permettent à une recherche de désigner un passage plus précis. Commencez par une taille qui garde un ou deux paragraphes ensemble, puis comparez les résultats de recherche avec l'Embedding Similarity Calculator.

Pourquoi des caractères et pas des tokens ?

Chaque modèle d'embeddings a son propre tokenizer, si bien qu'un même texte représente un nombre de tokens différent selon les modèles, et un outil de navigateur ne peut pas les compter exactement pour chaque modèle. La bibliothèque d'Ollama indique la fenêtre de contexte de chaque modèle en tokens ; par exemple, elle affiche 2K pour embeddinggemma et nomic-embed-text et 512 pour mxbai-embed-large et all-minilm. Gardez une marge, et utilisez truncate false pour repérer les morceaux trop longs.

Que fait truncate false ?

La référence de l'API d'Ollama indique que truncate vaut true par défaut, ce qui tronque les entrées qui dépassent la fenêtre de contexte. Avec false, Ollama renvoie une erreur. L'outil ajoute "truncate": false quand la case est cochée, afin qu'un morceau trop long échoue bruyamment plutôt que d'être raccourci.

Comment fonctionne le chevauchement ?

Quand un nouveau morceau commence, les dernières pièces du morceau précédent (phrases, lignes ou mots) sont répétées à son début, tant qu'elles tiennent dans la longueur de chevauchement et que le morceau reste dans le maximum. Les pièces ne sont jamais coupées pour remplir le chevauchement ; le chevauchement réel peut donc être plus court que le nombre que vous avez réglé.

Comprend-il le Markdown, le HTML ou le code ?

Non. Il traite tout comme du texte brut et coupe aux paragraphes, aux lignes, aux phrases et aux espaces. Supprimez le balisage dont vous ne voulez pas dans les embeddings avant de coller le texte.

Mon texte est-il envoyé quelque part ?

Non. Le texte est découpé dans votre navigateur, et l'outil se contente d'écrire la commande. Rien n'est envoyé tant que vous ne l'exécutez pas vous-même.

Articles liés

Voir aussi