Pagefind 的詞幹還原警告是假線索 — 讓日文複合詞搜尋失效的是斷詞不一致

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 種支援詞幹還原的語言。

斷詞是反過來的問題:先找出詞的邊界到底在哪裡。日文與中文書寫時不放空格,所以在進索引之前,得先有東西判斷「画像変換」是兩個詞而不是一個。英文從不需要這一步,因為空格早就把這件事做完了。

兩種語言的斷詞與詞幹還原兩個並排的欄位。英文靠空格切開後,再把 repositories 還原成 repository。日文先由字典切成四個詞元,接著抵達詞幹還原那一格,該格以虛線灰底呈現,因為並不存在對應的演算法。建置時的警告講的正是這個空格子。英文git repositories斷詞靠空格,不需處理詞幹還原Snowball 的英文規則gitrepository日文画像を変換する斷詞Lindera + UniDic詞幹還原沒有,將來也不會有画像を変換する建置時的提示指的是灰色那格。日文搜尋從來不經過它。
英文送進來時已經切好,只需要修掉字尾。日文送進來是一整串沒有斷點的字,得先切開。警告講的是修字尾那一步,而日文根本不會經過它。

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.1
charabia-0.9.9/src/segmenter/japanese.rs -> lindera 0.43.3 + lindera-unidic

中文用 Jieba,日文用搭配 UniDic 詞典的 Lindera。警告沒有提到的那項能力,一直都在。

光看警告永遠不會想到要做的量測

光讀提示得不出結論,所以我改為直接量測搜尋本身。我建置了網站,透過 Pagefind 的 JavaScript API 直接查詢每個語系的索引,再把每個詞的筆數和含有該詞的日文文章數量對照。如果一個詞出現在八個頁面而搜尋回傳八筆,這個語言就是正常的。

在 1.5.2 上,日文大部分確實正常:

查詢含有該詞的頁數筆數是否正確
ドキュメント4747是
ブラウザ3838是
画像2121是
コンポーネント1919是
リポジトリ491否

リポジトリ 不是什麼冷僻的詞,它出現在這個網站的 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 詞典。兩者一旦不一致,輸的是查詢那一端。

兩本字典對同一個複合詞的分歧一個日文複合詞分成兩條路徑。索引端由 Lindera 以單一詞儲存。查詢端由瀏覽器的 Intl.Segmenter 切成四個片段,其中只有最後一段在整站的索引裡。由於每個詞都必須命中,含有該複合詞的頁面被排除,反而是那唯一真實存在的片段把一個不相關的頁面拉了回來。同一個詞,一邊進索引,一邊當查詢ガベージコレクション索引端(建置時)Rust 執行檔內的 Lindera + UniDicガベージコレクション以單一詞儲存查詢端(瀏覽器)使用瀏覽器 ICU 的 Intl.Segmenterガベージコレクション切成四段,只有最後一段在索引裡✗ 不是每個詞都對得上所有查詢詞都必須命中,因此真正含有該詞的頁面被排除,換回來的是一個模糊比對的猜測。
一個複合詞,兩本詞典。Lindera 把它整個存起來,ICU 把它切成四段,其中只有最後一段是索引裡的詞。所有查詢詞都必須命中,因此含有這個複合詞的頁面被擠掉,而唯一在索引裡查得到的片段 コレクション 拉回了別的頁面。

缺陷就出在這裡。碎片 ガ、ベ、ージ 都不是索引裡的詞,而 Pagefind 要求每個查詢詞都要命中,所以含有這個複合詞的文章被排除了。留下來的是模糊比對找到的東西,有時候什麼都找不到。

在測試過的每個詞上,Intl.Segmenter 保住整個詞時搜尋就精確,把詞切碎時搜尋就出錯。

把詞打完,才是壞掉的那一刻

因為前綴查得到、完整的詞卻查不到,這個缺陷的表現格外折磨人。我依序搜尋了 ガベージコレクション 的每個前綴,並檢查含有這個詞的兩篇文章是否都在結果裡:

把詞打完的瞬間,正確結果就消失了十個欄位,對應輸入一個日文複合詞的每一次按鍵。下一列是回傳的筆數,再下一列是真正含有該詞的兩篇文章是否都在結果中。第一次按鍵時在,第二次不在,第三到第八次連續六次都在,最後兩次則完全沒有回傳結果。輸入的字元,每欄一次按鍵回傳筆數兩篇正確的文章是否都在其中ガ59✓ベ51✗ー2✓ジ2✓コ2✓レ2✓ク2✓シ2✓ョ0✗ン0✗打到一半找得到,打完整個詞反而兩篇都不見了。
兩篇正確的文章連續六次按鍵都在結果裡,最後兩次消失。中途停手的使用者找得到,把詞打完的使用者找不到。

使用者因為想要精確而受罰。這也是這個缺陷長期沒被發現的原因:把查詢打到一半的人看到的是一個正常運作的搜尋,而任何日誌都沒提過這個缺陷。

中文其實也壞了,只是我一開始沒發現。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.01.5.2
リポジトリ49 筆,全部正確1 筆,錯誤的頁面
ガベージコレクション2 筆,都正確0 筆
ドキュメント4747

所以這個退步是真的,把版本鎖回 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 / 01 / 0
repository / repositories38 / 3838 / 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.21.6.0
搜尋35135
環境變數10010 篇全部找到,共 16 筆
快取2424 篇全部找到,共 31 筆24 筆,剛好

在日文上,修補現在只會改變排序。下表的「排在前面」是指:假設含有該詞的頁面有 N 篇,前 N 筆結果裡有幾篇是正確的頁面。

查詢含有該詞的頁數未修補的 1.6.0(排在前面)修補後的 1.6.0(排在前面)
ガベージコレクション202
ワークツリー313
型チェック948
環境変数1083
依存関係1286
ブランチ保護221

瀏覽器仍然會把片假名複合詞切碎,未修補的 1.6.0 會把命中碎片的頁面排在含有完整詞的頁面前面。漢字複合詞則相反:ICU4X 現在在索引端切詞的方式和瀏覽器切查詢的方式一樣,所以把查詢整個送過去,排序反而會變差。

在技術部落格上,片假名外來語是比較常被搜尋的詞,所以我保留了這個修補。另外,從 1.6.0 起,詞幹還原的提示也只有在加上 --verbose 執行時才會印出來。

總結

  • 每次建置都會印出來的警告,不是你正在追的那個缺陷的證據。這一則警告是準確的、永久的,而且和缺陷無關。真正的缺陷就在警告旁邊,卻什麼日誌都沒留下。
  • 詞幹還原和斷詞解的是相反的問題。英文送進來已經切好,需要修掉字尾;日文送進來沒有斷點,需要先切開。一個工具完全可以缺了詞幹還原而把斷詞做得很好。
  • 用一本詞典建索引、用另一本詞典查詢的搜尋引擎,會剛好在那兩本詞典意見不合的詞上失敗。而且失敗的樣子是一個看似合理的錯誤答案,不是空結果。
  • 測完整的詞,不要測前綴。前綴查詢把這個缺陷藏得滴水不漏,而隨手檢查搜尋框的人實際打的正是前綴。
  • 不會讀的語言,用數的來驗證。把頁數和搜尋筆數對照起來不需要任何閱讀能力,而小語料庫藏起來的中文失敗,也是這樣抓到的。
  • Pagefind 1.6.0 改用 ICU4X 建索引,修好了漏掉結果的問題。現在從斷詞清單裡拿掉 ja,片假名的排序會變好,漢字的排序會變差。每次升級 Pagefind,我都會重新量測一次這個取捨。

參考連結

分享這篇文章