第一層
字形
字的寫法與異體。同一個意思可能有幾個寫法，系統要先知道它們是同一個字，才不會把同義詞當成不同項目。
Three layers
字庫的三層：字形、讀音與情境讀法
把「字庫」當成一個字典檔案，是最常見的誤解。能否讀對，取決於三層資料是否齊備。
第二層
讀音
粵拼、聲調與異讀。多音字在不同詞語中有不同讀法，單看字面無法決定，必須連同上下文一起記錄。
第三層
情境讀法
同一個詞在品牌名、地名與日常用語中可能有不同讀法。這一層最常被忽略，也最影響專有名詞的表現。
Public resources
可直接使用的公開資源
以下資源來自學術機構與開源社群，各有用途與授權限制。我們只列類別與用途，不作排名，也不建議在未確認授權前大量抓取。
| 資源 | 用途 | 有沒有 API | 授權要留意 |
|---|---|---|---|
| 香港中文大學人文電算研究中心「粵語審音配詞字庫」 | 查單字讀音、同音字與配詞示例，適合核對正讀。 | 網頁查詢，沒有公開 API。 | 學術機構網站，引用時註明來源；大量抓取前先徵詢。 |
| 香港語言學學會粵拼方案（LSHK Jyutping） | 粵拼的標準拼寫與聲調標示方式，是大部分系統的共同基礎。 | 文件與方案公開，沒有託管查詢服務。 | 方案本身可自由採用；引用時標明來源。 |
| 粵典（words.hk） | 以詞為單位的粵語詞典，附讀音、釋義與用法示例。 | 網站查詢；資料集另有授權安排。 | 字典內容有版權，商用前先看授權條款。 |
| PyCantonese | Python 函式庫，提供粵語拼音轉換、分詞與語料工具。 | 離線函式庫，自行部署。 | 開源授權，需保留授權聲明。 |
| Canto-HK-G2P | 字形轉讀音（G2P）工具，處理香港語境下的數字、日期與中英夾雜。 | 離線工具，自行部署。 | 開源專案，使用前確認授權與維護狀態。 |
外部連結 opens in a new tab；各站內容與授權條款可能更新，商用前請自行核對最新版本。
Proper nouns
專有名詞的五類讀音規則
專有名詞出錯，往往不是引擎不認識那個字，而是沒有一條規則說明「在這個情況下應該讀哪一個音」。
| 類別 | 規則 | 例子 |
|---|---|---|
| 人名 | 以本人慣用讀法為準，姓氏與名字分開記錄。 | 「岑」在姓氏場合讀 sam4，不用同音常用字替代。 |
| 品牌 | 品牌名可自訂讀法，需與官方發音一致。 | 英文品牌名保留英文讀音，不逐字譯成中文。 |
| 地名 | 香港地名以本地慣讀為準，與字面正讀可能不同。 | 「大嶼山」的嶼讀 jyu4，不讀 jyu5。 |
| 縮寫 | 逐個字母讀，或按行業慣例整詞讀，兩者要事先指定。 | 「HKMA」逐字母讀，不作單詞發音。 |
| 中英夾雜 | 英語部分保留原音，前後粵語按語序連接。 | 「這個 app 的 login 頁」中 app 與 login 保留英文讀音。 |
Vocabulary rules
自訂詞彙：50 詞、單詞 30 字、提示 200 字
詞表的作用是引導語音辨識偏向你的專有名詞。它有明確上限，也有副作用，所以格式與範圍要一起設計。
| 項目 | 規則 | 實務建議 |
|---|---|---|
| 詞數上限 | 50 個詞，超出部分會被忽略。 | 只放真正會影響業務判斷的專有名詞，不要當成常用詞表。 |
| 單詞長度 | 每個詞不超過 30 字。 | 過長的句子不是專有名詞，請拆成詞。 |
| 提示總長 | 整段提示不超過 200 字。 | 提示越長，越容易出現朗誦詞表的情況。 |
| 詞庫分域 | 兩本獨立詞庫：轉寫頁與會議記錄各自一套設定。 | 不同場景用不同詞表，避免互相干擾。 |
| 開通方式 | Beta・按帳號開通，不是自助開放功能。 | 先申請試用，確認範圍後再接入生產流程。 |
加詞後請重新檢視一次實際生效的詞數與提示長度；被截斷的詞不會有錯誤提示，只會靜靜地不生效。
Acceptance
驗收流程：用固定音檔證明加詞有用
驗收的目標不是「新詞讀對了」，而是「新詞讀對，而其他段落沒有退步」。以下四步可以直接照做。
- 01
準備固定音檔
選十至二十段真實錄音，涵蓋不同講者、語速與收音條件；同一批音檔在全流程中保持不變。
- 02
逐詞標記對錯
先跑一次基準，記錄每個目標詞是否正確；加詞後再跑一次，用同一把尺逐詞比對。
- 03
分類結果
把變化分成修正、退步、無變化三類。退步集中出現在某些段落時，先檢查音質與詞表長度。
- 04
回歸與定案
只有當修正明顯多於退步，而且退步不涉及關鍵欄位（金額、日期、姓名），才把詞表定案。
Failure modes
四種常見失效模式
以下情況在實務中反覆出現，通常不是引擎壞了，而是輸入條件把它推向錯誤方向。
| 情況 | 會發生什麼 | 處理方式 |
|---|---|---|
| 低碼率＋短詞表 | 引擎傾向把音硬套成詞表內的詞，出現朗誦式輸出。 | 先提升錄音碼率與收音質素，再考慮加詞。 |
| 重複詞 | 同一詞以不同寫法重複出現，浪費上限並分散權重。 | 去重後只保留一種寫法，必要時用提示說明變體。 |
| 詞太長 | 超過長度上限的項目被靜默丟棄，等於沒有加入。 | 拆成短詞，逐個測試是否真正影響辨識。 |
| 英文縮寫 | 逐字母與整詞讀法混用，結果不穩定。 | 在詞表中明確指定讀法，並用固定音檔驗收。 |
FAQ
常見問題
字庫與詞庫有何分別？
字庫處理「這個字怎樣讀」：字形、粵拼、異讀與情境讀法。詞庫處理「這個詞在這個場景應該聽成什麼」：一組專有名詞與提示，用來引導語音辨識。前者是語言知識，後者是使用者在某個產品場景的設定。
詞表可以放多少個詞？
每個詞庫上限 50 個詞，單詞不超過 30 字，整段提示不超過 200 字。超出上限的詞會被忽略，不會報錯，所以加詞後要核對實際生效的數量。
加入詞彙會不會令其他字變差？
有可能。音頻碼率偏低而詞表又短的時候，辨識引擎有時會傾向把聽到的音硬套成詞表內的詞，反而令原本正確的句子出錯。所以每次加詞都要做回歸測試，確認原本正確的段落沒有退步，而不是只看新詞有沒有變對。
有沒有現成的粵語發音 API？
公開的粵語讀音資源不少，但多數是查詢用的字典或離線資料集，而不是可直接接入產品的雲端介面。本站的粵語詞庫屬 Beta，按帳號開通，並非開放自助 API；如要用於生產環境，請先聯絡我們討論範圍。
如何知道加詞有沒有效？
用固定音檔做前後對比：同一批錄音在加詞前後各跑一次，逐詞標記「修正／退步／無變化」，再計算淨變化。只憑一兩句感覺「好像好了」不算驗收，因為個別修正很容易伴隨其他段落退步。