字庫設計成兩種類型,因為「希望模型理解術語並融入語境」與「無論如何都要把某個字串改成另一個字串」是兩個不同的需求。前者要在模型生成階段介入,後者要在生成完成後執行;混為一談會犧牲其中一種準確度。本章逐一說明兩者特性,並指出兩者結合與互斥的場景。

vocabulary：軟性引導

vocabulary 字庫的 term 結構為 { variants: { 'zh-TW': ..., en: ..., 'ja-JP': ... } },表達同一概念在不同語言的對應寫法。當輸入命中其中任一語言的詞彙時,對應其他語言的詞彙會作為「偏好譯詞」交給模型,模型仍會依語境決定最終選用什麼字。

• 適用場景：品牌術語、產品名、行業專有名詞、有官方譯法的術語。
• 保留語境彈性：模型可依上下文選擇最自然的形式（單複數、變化形、敬語等）。
• 雙向對譯：任一語言命中都會帶出其他語言的對應詞。
• 可用於翻譯與語音辨識端點,並與 SSE 模式相容。

forced_replacement：硬性後處理

forced_replacement 字庫的 term 結構為 { language, from, to, case_sensitive? },表達單一語言的字串替換規則。模型完成輸出後,系統會依規則對輸出做字串替換,確保 from 不會出現在最終結果。

• 適用場景：品牌名拼寫一致性、固定縮寫展開、屏蔽特定字、合規/法務必須的術語替換。
• 輸出絕對保證：規則命中時 from 一定會被改寫成 to。
• 單向 + 單語：每條規則屬於單一語言（language 欄位）,只在輸出語言為該語言時生效;case_sensitive 預設 false。
• **SSE 模式不支援**：與 stream=true 互斥（同時送出回 400 validation_error）。

兩者比較

• 介入時點：vocabulary 在生成階段、forced_replacement 在生成完成後。
• 輸出保證：vocabulary 偏好但不保證、forced_replacement 100% 命中保證。
• 語言維度：vocabulary 多語對譯（一個 term 含多語）、forced_replacement 單語規則（一個 term 屬一個語言）。
• 與 SSE 互動：vocabulary 完全相容、forced_replacement 互斥（觸發 400）。
• 可同時掛載：JSON 模式可同時掛 vocabulary + forced_replacement;SSE 模式只能掛 vocabulary。
• 更新規則：vocabulary 為覆蓋式更新 `variants`（至少 1 個變體）；forced_replacement term 更新時 `from` / `to` / `case_sensitive` 三欄至少一，`language` 不可改（PATCH 送出 language 欄位回 400 `validation_error`）。

設計取捨

vocabulary 與 forced_replacement 在實作上是兩條完全獨立的路徑,共用的只有「字庫」這個對外名稱。建立字庫時 type 必須二選一,且建立後不可變更（PATCH 不接受 type 欄位）。如果一份名詞同時需要兩種行為,請建立兩個字庫並同時掛上;如果情境相互排斥,請依場景分別呼叫不同設定。

常見限制

• type 在建立後不可變更（PATCH 不接受 type 欄位）。
• 字庫名稱在同一 API Key 持有者內必須唯一,重複建立回 409 duplicate_name。
• 批次新增 term 每批最多 250 筆,超過回 400 bad_request（details.reason 為 batch_too_large）。
• forced_replacement 與 stream=true 互斥;同時送出回 400 validation_error,SSE 模式下 meta.forced_replacement_count 恆為 0。
• 字庫僅限建立它的帳戶使用;指定的字庫不存在時回 404 dictionary_not_found。