Pagefind 的詞幹還原警告是假線索 — 讓日文複合詞搜尋失效的是斷詞不一致
Pagefind 每次建置都警告日文與中文缺少詞幹還原。真正的缺陷在別處:查詢端與索引端的斷詞器不一致,回傳了錯誤的頁面。

本頁目錄
引言
這個網站每次建置都會印出同樣兩則提示,而我已經讀過去好幾個星期了:
Note: Pagefind doesn't support stemming for the language ja-jp.Search will still work, but will not match across root words.ja-jp 一則,zh-tw 一則,en-us 則什麼都沒有。後來我終於問了這則提示讓人想問的問題:這是 Pagefind 在日文與中文上真正的限制嗎,能不能修?我要的是誠實的答案而不是讓人安心的答案,因為在這個部落格上,搜尋是任何人找到舊文章的唯一途徑。
誠實的答案分成兩半。這個警告是永久的、無害的,而且講的是從來沒壞掉的那一半。
在這則警告底下,藏著一個什麼都不會印出來的真缺陷。在 Pagefind 1.5 上,用日文複合詞搜尋會回傳錯誤的文章,而且回得理直氣壯。我對 Pagefind 建置好的打包檔加了一行修補,修好了這個問題。後來 Pagefind 1.6.0 在上游修好了漏掉結果的問題,現在這個修補只會改變結果的排列順序。
詞幹還原是給英文的,斷詞是給日文的
這兩個詞聽起來可以互換,實際上描述的是相反的問題。
詞幹還原會削掉字尾,讓各種變化形收斂到同一個字根。搜尋 repository 也能命中 repositories 就是靠詞幹還原;英文靠在字尾加字母來表達文法,所以削字尾的做法行得通。Pagefind 用詞幹還原函式庫 Snowball 來做這一步,並在多語言搜尋文件裡列出了 33 種支援詞幹還原的語言。
斷詞是反過來的問題:先找出詞的邊界到底在哪裡。日文與中文書寫時不放空格,所以在進索引之前,得先有東西判斷「画像変換」是兩個詞而不是一個。英文從不需要這一步,因為空格早就把這件事做完了。
Snowball 沒有中文、日文或韓文的演算法,將來也不會有,因為對一個不靠字尾變化的語言來說,削掉字尾不是有意義的操作。所以這則提示是準確且永久的,同時也和這個問題無關:日文搜尋完全不依賴提示所指的那一步。
斷詞那一半是有支援的。pagefind 的 npm 套件會安裝 extended 執行檔,也就是內建 CJK 斷詞器的那個版本,建置輸出的第一行就寫著:
Running Pagefind v1.5.2 (Extended)1.5.2 的 extended 執行檔帶著詞典,所以有 55 MB。把執行檔裡的字串抽出來,就看得到裡面裝了什麼:
charabia-0.9.9/src/segmenter/chinese.rs -> jieba-rs 0.8.1charabia-0.9.9/src/segmenter/japanese.rs -> lindera 0.43.3 + lindera-unidic中文用 Jieba,日文用搭配 UniDic 詞典的 Lindera。警告沒有提到的那項能力,一直都在。
光看警告永遠不會想到要做的量測
光讀提示得不出結論,所以我改為直接量測搜尋本身。我建置了網站,透過 Pagefind 的 JavaScript API 直接查詢每個語系的索引,再把每個詞的筆數和含有該詞的日文文章數量對照。如果一個詞出現在八個頁面而搜尋回傳八筆,這個語言就是正常的。
在 1.5.2 上,日文大部分確實正常:
| 查詢 | 含有該詞的頁數 | 筆數 | 是否正確 |
|---|---|---|---|
ドキュメント | 47 | 47 | 是 |
ブラウザ | 38 | 38 | 是 |
画像 | 21 | 21 | 是 |
コンポーネント | 19 | 19 | 是 |
リポジトリ | 49 | 1 | 否 |
リポジトリ 不是什麼冷僻的詞,它出現在這個網站的 49 篇文章裡。而它回傳的那唯一一筆,是一篇關於語言模型歷史、通篇沒有這個詞的文章。
回傳零筆的搜尋,至少讓你知道搜尋失敗了。リポジトリ 的搜尋卻交回了一個錯誤的答案。
索引裡有完整的詞,查詢卻從來沒拿完整的詞去查
Pagefind 為 リポジトリ 回傳的摘要本身就說明了一切。被高亮的是 リレー,一個只是看起來有點像的無關詞。引擎沒能比對到任何詞,於是退而改用模糊比對。
下一個測試把索引端和查詢端的問題分開來看。用複合詞 ガベージコレクション 的前綴 ガベージ 去搜,含有這個複合詞的兩篇文章都會回傳。用完整的詞去搜,兩篇都不見了。
比較短的查詢找到了比較長、比較精確的查詢找不到的東西。平常是越長、越精確的查詢越容易命中,這裡卻整個顛倒過來,而既然索引明顯保有整個複合詞,問題就落在查詢端。
我去查瀏覽器把這些查詢切成了什麼樣子,一行程式碼就看出了機制:
[...new Intl.Segmenter('ja-JP', { granularity: 'word' }).segment('ガベージコレクション')] .filter((s) => s.isWordLike) .map((s) => s.segment);// ['ガ', 'ベ', 'ージ', 'コレクション']
// リポジトリ -> ['リ', 'ポジ', 'トリ']// ドキュメント -> ['ドキュメント']// 画像 -> ['画像']Pagefind 1.5.0 開始在瀏覽器裡用 Intl.Segmenter(瀏覽器內建的斷詞 API)切查詢,發行說明給的理由是查詢應該和內容用同樣的方式切開。但在 1.5 上,兩端用的不是同一本詞典。
切索引的是 Rust 執行檔裡的 Lindera 與 UniDic,切查詢的則是使用者瀏覽器內建的 ICU 詞典。兩者一旦不一致,輸的是查詢那一端。
コレクション 拉回了別的頁面。缺陷就出在這裡。碎片 ガ、ベ、ージ 都不是索引裡的詞,而 Pagefind 要求每個查詢詞都要命中,所以含有這個複合詞的文章被排除了。留下來的是模糊比對找到的東西,有時候什麼都找不到。
在測試過的每個詞上,Intl.Segmenter 保住整個詞時搜尋就精確,把詞切碎時搜尋就出錯。
把詞打完,才是壞掉的那一刻
因為前綴查得到、完整的詞卻查不到,這個缺陷的表現格外折磨人。我依序搜尋了 ガベージコレクション 的每個前綴,並檢查含有這個詞的兩篇文章是否都在結果裡:
使用者因為想要精確而受罰。這也是這個缺陷長期沒被發現的原因:把查詢打到一半的人看到的是一個正常運作的搜尋,而任何日誌都沒提過這個缺陷。
中文其實也壞了,只是我一開始沒發現。ICU 把「儲存庫」切成「儲存」和「庫」,Jieba 則用自己的一套切法,把繁體中文切成短單位。語料庫還小的時候兩邊的切法大致一致,但以現在的語料庫來說,「搜尋」出現在 35 篇 zh-TW 文章裡,1.5.2 只回傳了一筆;「環境變數」出現在 10 篇裡,1.5.2 一筆都沒有回傳。
退回 1.4 修好了搜尋,卻弄壞了搜尋框
既然查詢端斷詞是 1.5.0 才引入的,1.4.0 就不該有這個缺陷。我用 pnpm dlx pagefind@1.4.0 對同一份建置結果重建索引並執行同樣的查詢,證實了這一點:
| 查詢 | 1.4.0 | 1.5.2 |
|---|---|---|
リポジトリ | 49 筆,全部正確 | 1 筆,錯誤的頁面 |
ガベージコレクション | 2 筆,都正確 | 0 筆 |
ドキュメント | 47 | 47 |
所以這個退步是真的,把版本鎖回 1.4.0 很有吸引力,但那條路走不通。這個網站的搜尋介面是 pagefind-searchbox 這個 Web 元件,而 1.4.0 附帶的 pagefind-searchbox 會呼叫一個連 1.4.0 自己的 pagefind.js 都沒有定義的函式:
TypeError: s.createInstance is not a function我用 cache: 'reload' 重新抓過每一個檔案,得到的還是同樣的錯誤,可見並不是伺服器送了過期的檔案。
找到可行的做法之前,我先試了兩種,都失敗了。把查詢用引號寫成 "リポジトリ" 並不能繞過斷詞,它回傳零筆,因為被引號框住的詞組同樣是由那些被切碎的碎片組成的。
只修補 pagefind.js 裡的語言清單,產出的檔案和原版一個位元組都不差,看起來就像修補默默失敗了。它並沒有失敗。從 1.5.0 起搜尋在 Web Worker 裡執行,而 pagefind-worker.js 自己也帶著一份同樣的語言清單。只修其中一個檔案,使用者看得到的變化是零。
從一份清單裡拿掉一個語言
判斷本身是三行最小化過的 JavaScript:
needsWordSegmentation = (lang) => { if (!lang) return false; const primaryLang = lang.split('-')[0].toLowerCase(); return ['zh', 'ja', 'th'].includes(primaryLang);};沒有設定選項可以切換這個判斷。--force-language 也不是替代方案,因為它會把整個網站當成單一語言建索引,依 <html lang> 分開的索引就被壓成了一份,而那正是讓 /ja/search 不會回傳英文文章的機制。
所以做法是改寫建置後打包檔裡的那份清單,兩個檔案都要改,而且只針對日文。我決定直接上這個修補而不是等上游修好,scripts/patch-pagefind-ja.ts 現在會作為 pnpm build 的一部分,在每次執行 pagefind 之後執行。
改寫建置輸出是一種權宜做法,而權宜做法會安靜地爛掉。所以這支腳本被寫成會大聲失敗:
- 找不到那份清單時,讓建置失敗,並在訊息裡點名原因。默默部署一份沒被修補的打包檔,等於讓這支腳本要修的那個缺陷原封不動地回來。
- Pagefind 不是當初量測的版本時,發出警告。
- 在未經驗證的版本上,清單如果已經寫著
['zh', 'th'],視為致命錯誤。這份清單有可能是上游自己改的,而不是這支腳本先前修補的結果;果真如此,腳本就會什麼都沒改,卻以 exit 0 正常結束。
我也把 pagefind 鎖成了精確版本。pagefind 原本用的是 ^ 版本範圍(caret range,會自動接受新的 1.x 版本),這個 repo 的 Dependabot 會自動合併,而且沒有必要通過的狀態檢查。只要 Pagefind 出了一版改變最小化輸出的形狀,這一版就會自己合併進來,接著擋下每一次 production 環境部署,包括和搜尋毫無關係的文章發布。
基於同樣的理由,我沒有把版本不一致視為致命錯誤:那樣做不是在防止這種中斷,而是在製造它。
修補在 1.5.2 上改變了什麼
| 查詢 | 未修補的 1.5.2 | 修補後的 1.5.2 |
|---|---|---|
リポジトリ | 1 筆,錯誤的頁面 | 49 筆,全部正確 |
ガベージコレクション | 0 筆 | 2 筆,都正確 |
ドキュメント / アーキテクチャ / コンポーネント | 47 / 9 / 19 | 沒有變化 |
ワークツリー | 3 篇全部找到 | 3 篇只找到 1 篇 |
搜尋 / 環境變數(zh-TW) | 1 / 0 | 1 / 0 |
repository / repositories | 38 / 38 | 38 / 38 |
中文沒有被動到,所以中文的失敗照樣存在,英文也照樣做詞幹還原。代價在 ワークツリー 那一列:Lindera 把這個複合詞拆開存進索引,所以把查詢整個送過去時,三篇文章漏掉了兩篇。
Pagefind 1.6.0 改用 ICU4X 建索引,修補只剩下調整排序
Pagefind 1.6.0 把 Lindera 和 Jieba 換成了 ICU4X。ICU4X 是用 Rust 重寫的 ICU 函式庫,而 Chromium 的 Intl.Segmenter 正是建立在 ICU 之上。extended 執行檔從 55 MB 縮小到 12 MB,裡面的字串現在出現的是 icu_segmenter-2.3.0。
1.6.0 的發行說明寫道,索引端的斷詞「和瀏覽器使用的 Intl.Segmenter 接近了許多」(中譯),維護者也關閉了追蹤這個不一致的上游 issue (Pagefind/pagefind#1237)。
在這個語料庫上,不論有沒有修補,1.6.0 在兩種語言都能找到所有該找到的頁面。中文也因此恢復了:
| zh-TW 查詢 | 含有該詞的頁數 | 1.5.2 | 1.6.0 |
|---|---|---|---|
搜尋 | 35 | 1 | 35 |
環境變數 | 10 | 0 | 10 篇全部找到,共 16 筆 |
快取 | 24 | 24 篇全部找到,共 31 筆 | 24 筆,剛好 |
在日文上,修補現在只會改變排序。下表的「排在前面」是指:假設含有該詞的頁面有 N 篇,前 N 筆結果裡有幾篇是正確的頁面。
| 查詢 | 含有該詞的頁數 | 未修補的 1.6.0(排在前面) | 修補後的 1.6.0(排在前面) |
|---|---|---|---|
ガベージコレクション | 2 | 0 | 2 |
ワークツリー | 3 | 1 | 3 |
型チェック | 9 | 4 | 8 |
環境変数 | 10 | 8 | 3 |
依存関係 | 12 | 8 | 6 |
ブランチ保護 | 2 | 2 | 1 |
瀏覽器仍然會把片假名複合詞切碎,未修補的 1.6.0 會把命中碎片的頁面排在含有完整詞的頁面前面。漢字複合詞則相反:ICU4X 現在在索引端切詞的方式和瀏覽器切查詢的方式一樣,所以把查詢整個送過去,排序反而會變差。
在技術部落格上,片假名外來語是比較常被搜尋的詞,所以我保留了這個修補。另外,從 1.6.0 起,詞幹還原的提示也只有在加上 --verbose 執行時才會印出來。
總結
- 每次建置都會印出來的警告,不是你正在追的那個缺陷的證據。這一則警告是準確的、永久的,而且和缺陷無關。真正的缺陷就在警告旁邊,卻什麼日誌都沒留下。
- 詞幹還原和斷詞解的是相反的問題。英文送進來已經切好,需要修掉字尾;日文送進來沒有斷點,需要先切開。一個工具完全可以缺了詞幹還原而把斷詞做得很好。
- 用一本詞典建索引、用另一本詞典查詢的搜尋引擎,會剛好在那兩本詞典意見不合的詞上失敗。而且失敗的樣子是一個看似合理的錯誤答案,不是空結果。
- 測完整的詞,不要測前綴。前綴查詢把這個缺陷藏得滴水不漏,而隨手檢查搜尋框的人實際打的正是前綴。
- 不會讀的語言,用數的來驗證。把頁數和搜尋筆數對照起來不需要任何閱讀能力,而小語料庫藏起來的中文失敗,也是這樣抓到的。
- Pagefind 1.6.0 改用 ICU4X 建索引,修好了漏掉結果的問題。現在從斷詞清單裡拿掉
ja,片假名的排序會變好,漢字的排序會變差。每次升級 Pagefind,我都會重新量測一次這個取捨。
參考連結
- Pagefind: Multilingual search(含有支援與不支援詞幹還原的語言清單)
- Pagefind 1.5.0 發行說明(查詢端以
Intl.Segmenter斷詞就是在這一版引入的) - Pagefind 1.6.0 發行說明(索引端的斷詞改用 ICU4X 的版本)
- Pagefind issue:索引端的 Lindera 與查詢端的 Intl.Segmenter 在日文複合詞上不一致 (Pagefind/pagefind#1237)
- MDN: Intl.Segmenter(Pagefind 用來切查詢的瀏覽器 API)
- Snowball(支撐 Pagefind 各語言詞幹還原的函式庫)


