字庫使用指南

目錄

1. 概述
2. 選用原則
3. 術語的選擇與撰寫
4. 基本設定
5. 各場景的設定方式
6. 生效時機
7. 注意事項
8. 數量限制
9. 存檔前驗證字庫
10. 設定範例
11. 常見問題排查

概述

字庫由三個獨立區塊組成，作用於辨識與翻譯流程的不同階段：

三者作用階段不同，功能不可互相取代。同一詞彙若同時需要正確辨識與固定譯名，須於 terminology 與 translation_dict 兩處分別設定。

一次 config 至少須提供其中一個區塊，三者可單獨或組合使用。

術語庫如何參與同音校正

傳入 terminology 後，術語會成為同音比對的依據。逐字稿中讀音相同或相近、但用字不同的片段會被修正回術語的寫法：

不需要事先列出可能的錯字 —— 比對依據是讀音，涵蓋範圍不受你想得到幾種錯法限制。

中英混合術語：CVD製程 這類術語，比對只作用在中文部分，英文原樣保留。

適用語言：同音比對僅適用於中文（繁體與簡體皆可，兩者讀音相同因此互通）。日文、韓文、英文的術語不會參與同音比對 —— 這些語言的錯字請改用 fuzzy_correction 明確列出。

比對範圍：讀音相同與相近的寫法都涵蓋，包含前鼻音與後鼻音（jin／jing）、捲舌與不捲舌等口音差異。例如術語為「晶圓廠」時，逐字稿的「金圓廠」會被修正。

常見詞保護：若逐字稿中該片段本身就是常見詞（例如「金元」「反案」），即使讀音與術語相同也不會被改動 —— 這是為了避免正常語句被誤改。要強制修正這類錯字，請用 fuzzy_correction 明確列出：明確列出的錯字不受常見詞保護限制。

fuzzy_correction 通常不需手動設定。三種情況才需要：錯字本身是常見詞（被常見詞保護擋下）、錯字與正確詞讀音差距很大（例如外語品牌名被辨識成音韻無關的詞）、或該語言不參與同音比對（日、韓、英文）。

另有一種用法不必列錯字：中文術語超過 terminology 的 500 筆上限時，可以放進 fuzzy_correction、只給 correct，一樣依讀音自動比對（規則上限 4000 條）。

兩個術語讀音相同時（例如同時登記「公事包」與「公式包」），已登記的兩個詞本身不受影響，但未登記的第三種同音寫法會被歸給其中一個，且無法預期歸給哪一個。這類情形可由 字庫驗證 API 在存檔前找出。

衝突代碼：homophone_conflict

選用原則

術語的選擇與撰寫

字庫的實際效果取決於選詞。本節原則適用於 terminology 與 fuzzy_correction。

適合納入的術語

優先納入會反覆出現的詞彙；單次提及者效益有限。

不建議納入的內容

字庫並非條目愈多愈準確。納入過多常見詞彙會提高誤替換的機率。

撰寫方式

術語比對的對象為實際說出的內容，而非正式全稱。

寫法較實際說出的內容更完整時，將無法比對。

以拉丁字母書寫的內容（英文、越南文、西班牙文等），比對以完整單字為單位——登記的寫法不會套用到更長單字的一部分。例如登記 wafer 不會影響逐字稿中的 wafers；兩種形式都需要時請分別登記。此規則僅作用於拉丁字母，中文、日文、韓文不受影響。

中文術語無大小寫問題；繁簡體差異由系統自動處理，無須重複登記兩種寫法。

導入建議

初次設定建議先納入 10–30 個最關鍵的詞彙，實際錄製一場後檢視逐字稿，再據以增補或移除：辨識仍有誤者補入字庫，造成誤替換者（通常為過於常見的詞彙）則移除。

固定週會或同一專案的會議，字庫內容通常變動有限，可重複沿用。

基本設定

{
  "type": "voice-translation",
  "data": {
    "action": "config",
    "terminology": {
      "zh-TW": [
        { "term": "語者分離" },
        { "term": "第三季營運計劃" }
      ],
      "en-US": [
        { "term": "diarization" }
      ]
    }
  }
}

設定成功後回傳 config_updated 事件。

注意：僅在設定被接受時觸發。設定被拒絕時回傳的是 type: "error"，客戶端需一併監聽，否則會誤判為無回應。

各場景的設定方式

三種場景使用相同的字庫格式與規則，差異僅在傳送方式。

即時錄音與廣播

廣播主講端為一般 WebSocket 連線，config action 無額外限制或行為差異。觀眾端不提供字庫設定。

可於 start 之前或錄音進行中傳送。

音檔匯入

欄位名稱與即時錄音相同，但值為 JSON 字串而非物件：

terminology:      '{"zh-TW":[{"term":"語者分離"}]}'
fuzzy_correction: '{"zh-TW":[{"correct":"語者分離","incorrect":["語這分離"]}]}'
translation_dict: '{"en-US":[{"source":"語者分離","target":"Speaker Diarization"}]}'

注意：匯入場景傳入物件將被拒絕。詳細規格見音檔匯入端點文件。

生效時機

錄音中更新任一區塊都無須重新連線，當前辨識不受中斷。更新術語庫時，回應另帶 terminology_effective: "next_turn"，表示新術語自下一句起生效。

三個區塊皆為整批覆蓋。 重送 config 為取代而非疊加；新增單一術語時，須連同既有術語一併送出。

注意事項

本節每一項都對應一種可由 字庫驗證 API 在存檔前偵測的狀況，段末以 衝突代碼 標示對應的代碼。

錯誤變體同時是正確詞時，正常文字會被改壞

若某個字串同時是甲規則的錯誤變體與乙規則的正確詞（或術語庫的術語），使用者正常說出這個詞時，也會被改成甲規則的正確詞。

{
  "fuzzy_correction": {
    "zh-TW": [
      { "correct": "報價", "incorrect": ["抱歉"] },
      { "correct": "抱歉" }
    ]
  }
}

上例會讓「他說抱歉」變成「他說報價」。這是本節唯一會把正確文字改錯的狀況，且不會產生任何錯誤訊息。

同一個詞同時登記為術語庫的術語與模糊詞的正確詞則沒有問題——兩者是不同機制（辨識加權與事後校正），一起使用是好做法。

衝突代碼：variant_shadows_term

兩個大小寫旗標的語意相反

兩者預設值皆為 false，但代表的行為相反。設定錯誤不會產生任何錯誤訊息，僅會產生與預期相反的比對行為。實作時請勿共用同一變數，亦不可將其中一方的值直接鏡射至另一方。

同一個錯誤變體若在多條規則設定了不同的 case_insensitive，取嚴格優先。

衝突代碼：case_flag_conflict

驗證失敗時三個區塊都不會套用

三個區塊的驗證在任何一項套用之前一次做完。任一區塊驗證失敗即回錯，三個區塊都不會套用，設定維持原狀。

例如送出合法的術語庫與超量的翻譯字典，將收到錯誤，而術語庫也不會生效。修正後重送完整 config 即可（三個區塊都是整批覆蓋，不會與先前的設定疊加）。

字庫綁定語言，未使用的條目仍佔用額度

術語與校正規則以語言代碼為 key，僅套用於語言代碼相符的內容。登記於 zh-TW 的規則不會作用於英文句子。

比對以語族為單位——語言代碼第一個連字號之前的部分相同即屬同族。因此登記於 zh-CN 的規則對 zh-TW 的內容同樣生效，反之亦然；zh-TW 與 ja-JP 則互不影響。

語言代碼留空的條目套用於所有語言。 這通常不是本意——請確認每一筆都填了語言代碼。

登記於本次未使用語言之下的條目仍計入數量上限。多語言字庫請以合計規劃。

同一語族下重複登記同一個術語同樣各自佔用額度（例如 zh-TW 與 zh-CN 各登記一次）。校正行為不受影響，但會白白消耗術語庫的數量。

衝突代碼：duplicate_term

加權值超出範圍會被自動調整

術語的 boost 有效範圍為 0.5 至 5.0。超出範圍時兩條路徑的行為不同：

同一份字庫在兩條路徑得到不同結果，是這一項最容易踩到的地方。

衝突代碼：boost_out_of_range（回應帶 value 與實際生效的 clamped_to）

錯誤變體重複時僅一條生效

碰撞以 incorrect（錯誤變體）判斷，而非 correct：

• 只有一條會生效，且不保證是哪一條（包含登記順序）。
• 大小寫旗標取嚴格優先——只要有任一條未開啟 case_insensitive，該變體即以嚴格比對處理。

同一 correct 拆分為多條規則屬安全用法（各條 incorrect 不重複即可）。若資料中存在同一錯誤變體對應不同正確詞的情形，後出現者將被忽略且無提示——字庫驗證 API 可在送出前找出這類重複。

衝突代碼：variant_ambiguous

錯誤變體與自己的正確詞相同時不會有作用

incorrect 內若出現與該條 correct 相同的字串，這一筆不會產生任何作用（開啟 case_insensitive 時，僅大小寫不同也算相同）。不影響結果，但會佔用數量額度。

衝突代碼：variant_equals_term

翻譯字典為提示而非替換

translation_dict 以提示方式引導譯文用詞，屬盡力而為，不保證每句遵守；條目愈多，穩定遵守的比例愈低。此為提示式字典的固有限制，不因上限放寬而改變。

需要確定性替換時，請改用 fuzzy_correction。

同一目標語言下同一個 source 登記多筆時，僅最後一筆生效，其餘無提示地被忽略。

衝突代碼：dict_duplicate_source

注意：字典逐條帶入翻譯請求，條目數直接反映於翻譯處理量與費用。實際帶入者僅該目標語言已填譯文的條目（翻成辨識語言時，其他語言有填譯文的條目也會帶入），將譯文分散於不同語言可降低單次帶入量。

字典的其他語言欄也會參與比對

source 以辨識語言（第一個轉錄語言）填寫。除了 source，同一個詞在其他語言填的譯文也會拿來比對原文：

• 句子不是辨識語言時，比對該句語言那一欄。例如 source 為「會議」、ja-JP 填「会議」、en-US 填「meeting」：日文句子裡的「会議」翻成英文時，會套用「meeting」。
• 句子是中文、日文、韓文、泰文等非拉丁字母的語言時，英文欄也會拿來比對句中夾雜的英文詞。
• 翻成辨識語言時，比對到的詞以 source 當譯文。因此字典只要填了其他語言，翻回辨識語言時也會用到字典。
• 無法判斷該句語言時（例如多語言辨識），比對本場其他轉錄語言的欄位。

從其他語言欄比對時：

• 英文詞採整詞比對，例如 mail 不會比對到 email。
• 全大寫的縮寫（如 AI、IT）一律區分大小寫。
• 少於 2 個字的譯文不參與比對。
• 同一個詞對到不同譯文時（例如兩筆的 ja-JP 都填「会議」、但 en-US 填的不同），這個詞不採用。
• 同一個詞出現在多處時，依序以該句語言那一欄、source、英文欄為準。

數量限制

上述為預設值，實際生效上限可依環境調整。 請勿於整合中寫死數字——超限錯誤的 details 同時帶 count（送出數量）與 max（實際上限），一律以 max 為準。

存檔前驗證字庫

前述「注意事項」的各項狀況有一個共同點：都不會產生錯誤訊息。字庫照樣收下、設定照樣成功，只是在錄音或翻譯時安靜地產生非預期結果。

字庫驗證 API（POST /api/v1/glossary/validate）就是用來在使用者按下儲存的當下把這些狀況指出來的：

curl -X POST "https://<即時服務網域>/api/v1/glossary/validate" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -H "Content-Type: application/json" \
  -d '{
    "fuzzy_correction": {
      "zh-TW": [
        { "correct": "報價", "incorrect": ["抱歉"] },
        { "correct": "抱歉" }
      ]
    }
  }'

• 免費，不扣點、不建立任何任務
• 三個字庫區塊皆選填，給什麼驗什麼
• 每筆問題都附是第幾筆，管理介面可直接標記到條目
• 回應不含文案，由貴方依代碼自行組句

建議用法：字庫管理介面在儲存前呼叫一次；編輯過程中若要即時提示，可傳 check_homophones: false 取得毫秒級回應。

本端點驗的是字庫本身。通過驗證不代表音檔匯入一定會接受同一份字庫——匯入另有更嚴格的規則。

設定範例

公司名與產品名

只設定術語庫（同音錯字即可修正）：

{ "terminology": { "zh-TW": [{ "term": "IPEVO" }] } }

若辨識錯誤與正確詞讀音不同（同音比對涵蓋不到），另行補充規則：

{
  "fuzzy_correction": {
    "zh-TW": [{ "correct": "IPEVO", "incorrect": ["ltfo", "愛比"] }]
  }
}

品牌名的大小寫

英文品牌名若可能與一般詞彙衝突，維持預設的嚴格比對：

{
  "fuzzy_correction": {
    "en-US": [
      { "correct": "IPEVO", "incorrect": ["Ipevo", "ipevo"] }
    ]
  }
}

注意：開啟 case_insensitive 將擴大誤替換範圍。例如 ivo 設為忽略大小寫時，人名 Ivo 亦會被替換。

固定專有名詞譯名

{
  "translation_dict": {
    "en-US": [{ "source": "語者分離", "target": "Speaker Diarization" }],
    "ja-JP": [{ "source": "語者分離", "target": "話者分離" }]
  }
}

多語言會議

各語言術語分別登記：

{
  "terminology": {
    "zh-TW": [{ "term": "第三季營運計劃" }],
    "ja-JP": [{ "term": "予算" }],
    "en-US": [{ "term": "quarterly report" }]
  }
}

所有語言的術語以合計計算上限。

常見問題排查

錯誤碼定義見錯誤碼總表；config action 的逐欄位規格見 WebSocket API 文件。

版本：V1.24.1 最後更新：2026-10-07