廣東話字庫與自訂詞彙 API 實戰：粵拼、異讀、專有名詞點樣教得識

一句答你：廣東話「字庫」唔係一本字典咁簡單，而係三層資料——字形（點寫）、讀音（點讀）、情境（幾時讀邊個音）。 你做 ASR，最重要的是第三層；你做 TTS，最痛的是第二層；你做人手校對，最花時間的是第一層。

大部分團隊講「廣東話字庫」，其實講緊三樣唔同嘅東西，然後互相聽唔明。工程師想要一份「粵拼對照表」；營運想要一份「公司專有名詞清單」；編輯想要一份「口語字點寫」。呢篇會先把三層分開，再講實務：五個免費資源點揀、專有名詞五類規則、語音辨識嘅自訂詞彙點準備，同一個唔會自欺嘅 A/B 驗收流程。

Key Takeaways

• 字庫分三層：字形、讀音、情境讀法。搞亂層數，就會出現「查得到字但讀錯音」。
• 免費資源各有用途：查讀音用審音配詞字庫、查拼音方案用粵拼、查口語詞義用粵典、做批次處理用 PyCantonese。
• 「有網頁查詢」唔等於「有 API」；「開源」唔等於「商用授權自動 OK」。
• 專有名詞唔需要一個大詞庫；需要一份小型、精準、分行業嘅詞表。
• ASR 詞表有硬上限（50 詞、單詞 ≤30 字、提示 ≤200 字），塞爆只會互相干擾。
• 加詞之後一定要跑 A/B：有修正、零回歸，才算成功。

廣東話字庫三層：唔好再用一本字典嘅心態

三個層次嘅維護節奏完全唔同：字形一年改幾次；讀音跟字典版本；情境讀法每個新客戶、每個新產品都要更新。所以真正需要「系統化」嘅係第三層，唔係第一層。

先講清兩個成日被混用嘅詞：字庫 係指一份「字／詞 → 讀音」嘅對照資料，用嚟解決「呢個字點讀」；場景詞表 係指一份只屬於某個團隊、某個項目嘅專名清單，用嚟解決「呢個陌生人名點解要聽得明」。兩者唔可以互相代替：查得到讀音，唔代表引擎喺你嘅會議入面聽得返出嚟。

為何第三層最影響 ASR

語音辨識嘅錯誤，大部分唔係「唔識聽音」，而係「揀錯同音字」。而揀字嘅依據係語言模型對「呢個詞有幾常見」嘅判斷。你公司名、產品代號、同事花名，永遠唔會係常見詞——所以佢一定會被同音字取代。

呢個問題唔可以靠「換一個更強嘅引擎」解決，因為對任何引擎嚟講，你嘅專名都係低頻詞。正解係話佢知呢啲詞存在，即係自訂詞彙（hotwords）。

五個免費資源點揀（同各自嘅限制）

兩個常見誤解：

1. 「官網有得查，就等於有 API。」 大部分學術字庫只提供網頁查詢，冇對外 API；你要大量處理，就要自己想辦法（匯出、抄表、或者用開源套件）。
2. 「開源就係免費商用。」 唔一定。每個專案嘅授權條款唔同，商用前要逐個核，尤其是你要把資料嵌入產品嘅時候。

專有名詞五類規則

規則可以總結成一句：「睇得明嘅保留原形，讀得出嘅先轉粵拼。」 英文縮寫唔需要粵拼；中文專名需要讀音；兩者都唔應該被「翻譯」成另一個語言。

語音辨識嘅自訂詞彙：規則同上限

自訂詞彙嘅原理係「提示」而唔係「命令」：你把一堆可能出現嘅詞交畀引擎，佢會喺解碼時提高呢啲詞嘅機會率。所以：

• 只放真正需要嘅詞。常用詞唔需要提示，放咗只會干擾其他判斷。
• 詞表要短而精。港嘢現時嘅上限係 50 個詞、單詞 ≤30 字、提示總長 ≤200 字。
• 分場景。港嘢嘅詞庫分兩本：playground（轉錄頁／實時聽寫）同 meeting（會議批次轉寫）。同一間公司，會議同客服錄音嘅專名可以完全唔同，唔應該共用一本。

供應狀態講清楚： 詞庫功能現階段係 Beta，按帳號開通，唔係所有帳戶預設見到。介面喺語音轉錄頁；如果你登入後見唔到詞庫入口，即係你嘅帳號未開通，可以聯絡我哋申請。

詞表好壞對照

一個可跑嘅詞表清洗函數

以下係純資料處理（唔涉及任何 API 呼叫），你可以直接放入自己嘅 pipeline。規則同產品一致：去空白、去重、丟太長、截到 50 個、總長 ≤200 字。

MAX_TERMS = 50
MAX_TERM_CHARS = 30
MAX_HINT_CHARS = 200

def clean_terms(raw):
    """把使用者輸入整理成合法詞表。永不拋錯，寧願少放，唔好放錯。"""
    if isinstance(raw, str):
        # 支援換行或逗號分隔
        raw = raw.replace("，", ",").replace("\n", ",").split(",")

    seen, terms, total = set(), [], 0
    for item in raw or []:
        term = str(item).strip().strip("、,，")
        if not term or len(term) > MAX_TERM_CHARS:
            continue            # 太長 = 唔係專有名詞，靜靜丟棄
        key = term.casefold()
        if key in seen:
            continue            # 去重（大小寫不敏感）
        if total + len(term) + 1 > MAX_HINT_CHARS:
            break               # 總長到頂就停，唔好硬塞
        seen.add(key)
        terms.append(term)
        total += len(term) + 1
        if len(terms) >= MAX_TERMS:
            break
    return terms

用法示例（同上面嘅程式碼一致）：clean_terms("港嘢, Canto-Gen\n陳嘉詠，KPI") 回 ["港嘢", "Canto-Gen", "陳嘉詠", "KPI"]——逗號、全角逗號、換行三種分隔符都食，大小寫重複會先去重。

呢個函數有三個設計決定值得講：唔拋錯（壞資料唔應該令整個轉寫失敗）、先丟太長再算總長（避免一個超長字串食晒額度）、大小寫不敏感去重（KPI 同 kpi 對引擎嚟講係同一個詞）。

A/B 驗收：點知加詞有冇用

加詞之後，最常出現嘅兩種結果：①目標詞修好了 ②其他本來正確嘅字變成錯（回歸）。第二種更危險，因為你唔會即刻發現。

回歸（regression） 係指加詞之後，原本正確嘅字變成錯——你只會盯住目標詞，所以呢種副作用最容易被漏掉。下面嘅流程就係為咗將呢個副作用變成一個可量度嘅數字。

流程（30 分鐘可完成）：

1. 固定音檔：揀一段 3–5 分鐘、包含大部分目標詞嘅錄音。以後每次都用同一段。
2. 先跑 baseline：唔加詞，儲存逐字稿。
3. 逐詞標記：對每個目標詞，記「正確／錯誤」；同時抽查 10 個非目標詞，記「有冇由對變錯」。
4. 加詞再跑：同一個音檔、同一個語言設定，只改詞表。
5. 計算三欄：修正數、回歸數、無變化數。
6. 判斷：有修正、零回歸 才值得上線；有回歸就逐個詞剔除，找出係邊個詞搞事（通常係太短、太常見、或者同其他詞撞音）。

失效模式：一項已驗證，其餘四項要你自己跑

以下五種情況由「自訂詞彙＝解碼提示」呢個機制推導出嚟。第一項係我哋用小樣本測試過、方向上確認到嘅失效模式（具體樣本數同百分比屬未公開嘅測試資料）；其餘四項屬設計推論——即係由機制推導出嚟嘅預期行為，你未必每次都撞到，但撞到就知點處理。你可以逐項用上面嘅 A/B 流程自己確認。

• 【實測】低碼率音檔＋短詞表：音檔壓得太厲害（≤32 kbps，電話線嗰種質素）而詞表又短嘅時候，引擎有時會傾向「照讀詞表」而唔係真正轉寫內容。呢個形態我哋喺同一批音檔上重複見到過，可以當係一個可靠嘅預警訊號。同一輪測試亦見到加詞之後目標詞有修正、而且回歸數可以維持喺零——即係「詞表有數得嘅效果」呢件事企得穩。具體樣本數同百分比屬未公開嘅測試資料。解法係提高音檔碼率，或者加長詞表覆蓋率。
• 詞表混入常用詞（設計推論）：常用詞本身唔會錯，加咗只會令解碼偏向佢，預期會令其他位置變差。點樣自己驗：只加一個常用詞，跑一次 A/B，睇回歸數有冇郁。
• 同音衝突（設計推論）：兩個專名讀音相同（例如「嘉詠」同「嘉泳」），詞表幫唔到分辨；要靠上文或者人手覆核。點樣自己驗：兩個詞一齊入表、同一個音，睇引擎揀邊個。
• 英文縮寫（設計推論）：Q3、PR 呢類要保留原形，唔應該被當成中文詞提示。點樣自己驗：單獨加 Q3，睇佢係咪照讀字母。
• 一次改太多變數（設計推論）：同時換音檔、換語言設定、換詞表，你唔會知道邊個改動有效。點樣自己驗：一次只改一樣，改完即刻記低。

驗收示例

我哋唔會貼「加詞後準確率提升 X%」呢類數字做賣點——冇公開測試集嘅百分比唔可以比較。我哋自己嘅測試用嘅係小樣本，具體樣本數同百分比屬未公開嘅測試資料；但方向上確認咗兩件事：加詞之後目標詞會修好，而且回歸數可以維持喺零。

下面呢三項就係一張可重現嘅驗收表長咩樣——用你自己嘅音檔跑，output 就係你團隊嘅「詞表 baseline」：

• 同一段 5 分鐘會議錄音，加詞前後嘅逐詞對錯表（20 個目標詞）。
• 回歸檢查結果（10 個非目標詞，加詞後有冇變差）。
• 不同碼率（32 kbps vs 64 kbps）對詞表效果嘅影響。

你可以用上面嘅流程自己跑一次。跑完之後，你手上嘅表就係你團隊嘅「詞表 baseline」，之後每次加詞都用同一段音檔對比。想睇完整嘅測試集砌法（8 類難點、WER／CER 點計、評分表點填），可以讀廣東話語音轉文字實測。

同 TTS 讀音控制有咩分別

好多人把「ASR 詞表」同「TTS 讀音詞典」混為一談。兩者方向相反：

• ASR 詞表：幫引擎聽得明你講嘅專名（輸入方向）。
• TTS 讀音：幫引擎讀得啱你寫嘅字（輸出方向）。

如果你關心嘅係「AI 把聲讀錯我公司名」，你要睇嘅係多音字同異讀嘅處理，可以參考廣東話多音字攻略同廣東話讀音字典點用。如果你要處理嘅係「會議錄音轉出嚟嘅人名錯」，就係本文講嘅 ASR 詞表。

常見問題 FAQ

字庫同詞庫有咩分別？

字庫通常指「字→讀音」嘅對照（例如粵拼表）；詞庫指「詞→意思／用法」嘅集合（例如粵典）。實際做事嘅時候，你要嘅係第三樣：場景詞表——你團隊會出現嘅專有名詞清單。

詞表可以放幾多個詞？

港嘢現時上限 50 個詞、單詞 ≤30 字、提示總長 ≤200 字。超過就會截斷或者丟棄，所以唔好把整個客戶資料庫倒入去。

加咗詞會唔會令其他字變差？

有可能，呢個叫回歸。所以每次加詞都要跑 A/B，並且明確要求「回歸數 = 0」。有回歸就逐個詞剔除，通常係太短、太常見、或者同其他詞撞音。

有冇現成粵語發音 API？

有免費查詢資源（審音配詞字庫、粵拼方案、粵典），但多數係網頁查詢或開源套件，唔一定提供托管式 REST API。要放入產品，通常要自己封裝一層，或者用有公開 API 嘅語音服務。

點知加詞有冇用？

用同一段固定音檔跑兩次（加詞前／後），逐詞標對錯，計「修正／回歸／無變化」。有修正、零回歸，才算有效。

英文同數字要唔要放入詞表？

英文縮寫一般唔需要（引擎多數會保留原形），但如果經常被轉成中文字，就值得放。數字唔應該放——數字讀法應該由語言設定處理，放數字入詞表反而容易造成奇怪輸出。

想試下自己嘅專有名詞？

先睇廣東話語音轉文字上架公告了解產品範圍，再用語音轉錄頁跑一段你嘅錄音；詞庫入口需要帳號開通，可以聯絡我哋申請 Beta。想先打好讀音基礎，可以讀粵拼入門同廣東話人名讀音指南。

---

本文由港嘢內容團隊編輯審閱（editorial review，2026-10-25）。想了解我哋嘅背景，可以睇關於港嘢；詞庫開通同技術問題，可以用上面同一張聯絡表格。