~/tools / 嵌入與搜尋(RAG) / RAG Text Chunker
RAG Text Chunker — 為 RAG 切分文字,並建立 Ollama /api/embed 請求
在為 RAG 或語意搜尋產生 embedding 之前,先把長文件切成有最大長度與重疊的區塊(chunk)。文字會先依段落切開,接著依換行、句子與空格,只有在別無他法時才會在單字中間切斷。你會得到這些區塊,以及一個可直接執行、把所有區塊放進同一次請求的 Ollama /api/embed curl 指令。資料不會離開你的瀏覽器。
長度以字元計算。模型的上下文視窗以 token 計算,而一段文字佔用多少 token 取決於模型,所以請預留一些餘裕。
curl 指令
請在能連到 Ollama 的機器上執行。回應會依此順序,為每個區塊各給一個向量。
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
}'區塊
共 3 個區塊,最長的有 294 個字元。
#0 · 294 個字元 · 起始於偏移量 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.
#1 · 202 個字元 · 起始於偏移量 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.
#2 · 169 個字元 · 起始於偏移量 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.
/api/embed 的 JSON 內容
{
"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
}請求欄位依 Ollama API 參考文件中 /api/embed 所載,於 2026-11-04 確認。 Ollama API: Generate embeddings
所有處理都在你的瀏覽器中完成。工具只負責寫出指令,不會傳送任何東西。
Ollama 的 /api/embed 端點接受單一字串或字串陣列,而 API 參考文件指出,預設情況下超出模型上下文視窗的輸入會被截斷。因此,把長文件當成單一字串送出,結尾可能在沒有任何錯誤的情況下遺失;而且整份文件只產生一個向量,也讓搜尋很難只回傳能回答問題的那一部分。常見的做法是把文件切成較小的區塊,再為每個區塊產生 embedding。本工具會在放得下的最大邊界處切開文字:先是段落之間的空行,然後是換行,接著是句子結尾(包含 。!?),再來是空格,只有在最後手段時才會逐字元切開。它會保留分隔符號,所以把區塊接回去就會得到原始文字。重疊會把一個區塊的結尾,以完整片段為單位,重複放在下一個區塊的開頭,讓在邊界被切開的句子,至少能完整出現在其中一個區塊裡。長度以字元數計算。輸出是一個把所有區塊放進 input 陣列的 /api/embed 請求;如果你希望遇到過長時出現錯誤而不是被默默截斷,可把 truncate 設為 false。切分結果已用人工數過的範例驗證,並確認每個區塊都是原始文字在所示位置的一段。
這個工具的核心邏輯以 MIT 授權開放原始碼。 github.com/seigo5555/toolkitbox-lib/src/text-chunk.ts
使用情境
- 為你自己的 Ollama 伺服器上的 RAG 搜尋準備手冊、FAQ 或 README,並用一次請求為所有區塊產生 embedding
- 調整大小並觀察邊界落在哪裡,找出能讓段落保持在一起的區塊大小
- 確保不會有內容被默默截掉:開啟 truncate false,當區塊對模型來說太長時,Ollama 會回傳錯誤
使用方法
- 貼上文字。段落之間請用空行分隔,這樣會盡可能讓它們保持在一起。
- 以字元數設定區塊的最大長度與重疊,填入 embedding 模型名稱,如果你的 Ollama 伺服器不是 http://localhost:11434,也請填入它的位址。
- 複製 curl 指令,在能連到 Ollama 的機器上執行。回應會依相同順序,為每個區塊各給一個向量。本站的 Embedding Similarity Calculator 可以比較這些向量。
FAQ
區塊大小該設多少?
沒有唯一正確的大小。每個區塊都必須放進以 token 計算的模型上下文視窗,而區塊越小,搜尋就越能指向更具體的段落。可以先從能讓一兩個段落保持在一起的大小開始,再用 Embedding Similarity Calculator 比較搜尋結果。
為什麼用字元數而不是 token 數?
每個 embedding 模型都有自己的分詞器(tokenizer),所以同一段文字在不同模型中的 token 數不同,瀏覽器中的工具也無法替每個模型精確計算。Ollama 模型庫以 token 為單位列出各模型的上下文視窗;例如,embeddinggemma 與 nomic-embed-text 是 2K,mxbai-embed-large 與 all-minilm 是 512。請預留一些餘裕,並用 truncate false 找出太長的區塊。
truncate false 會做什麼?
Ollama API 參考文件指出,truncate 預設為 true,會截斷超出上下文視窗的輸入。設為 false 時,Ollama 會改為回傳錯誤。勾選這個選項時,工具會加上 "truncate": false,讓太長的區塊明確地失敗,而不是被縮短。
重疊是怎麼運作的?
當新的區塊開始時,前一個區塊最後的幾個片段(句子、行或單字)會重複放在它的開頭,條件是這些片段在重疊長度之內,且區塊不超過最大長度。片段不會為了湊滿重疊而被切開,所以實際的重疊可能比你設定的數字短。
它看得懂 Markdown、HTML 或程式碼嗎?
看不懂。它把所有內容都當成純文字,並在段落、換行、句子與空格處切開。如果有不想放進 embedding 的標記,請在貼上文字之前先移除。
我的文字會被傳送到任何地方嗎?
不會。文字是在你的瀏覽器中切分的,工具只負責寫出指令。在你自己執行之前,不會有任何東西被送出。