字庫操作教學

這裡提供完整的開發指南與最佳實踐，幫助您快速上手。

教學

從建立字庫、新增與批次建立 term、再到把字庫掛上翻譯與辨識端點，整理一段完整的字庫實戰流程。

字庫讓您把專屬詞彙與替換規則固定下來，套用到翻譯或語音辨識結果。本章從類型選擇起步，依序帶您完成建立、新增 term、批次建立、以及在實際請求中啟用字庫。

兩種字庫類型

vocabulary：多語對譯術語表，term 結構為 { variants: { 'zh-TW': ..., en: ..., 'ja-JP': ... } }。命中時作為偏好譯詞提供給模型，屬於軟性引導。
forced_replacement：單語言強制替換規則，term 結構為 { language, from, to, case_sensitive? }。在翻譯或辨識完成後對輸出做字串替換，屬於硬性後處理。
type 在建立時決定，之後不可變更（PATCH 不接受 type 欄位）。

怎麼選？

希望模型理解術語含義並融入語境時用 vocabulary；要求輸出一定包含特定字串（品牌名、固定縮寫展開等）時用 forced_replacement。需要兩者效果可同時掛兩個字庫，但 forced_replacement 在 SSE 模式下不可用。

步驟 1：建立字庫

POST /api/v1/dictionaries 帶入 name（同擁有者唯一）、type（vocabulary 或 forced_replacement）、可選的 description。成功回 201 並回傳完整字庫物件含 id（後續呼叫的 :id）與 entry_count = 0。

建立 vocabulary 字庫範例。

bash

curl -X POST "https://abemono.abestar.com.tw/api/v1/dictionaries" \
  -H "X-API-Key: $ABESTAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Glossary",
    "type": "vocabulary",
    "description": "Term equivalence for marketing copy."
  }'

字庫名稱衝突會回 409

同一 API Key 持有者下不能重名，重複建立會回 409 duplicate_name。建議用日期、語言、用途等後綴避免衝突。

步驟 2：新增 term

term 結構由字庫類型決定。vocabulary 字庫的 term 帶 variants，鍵為語言代碼；forced_replacement 字庫的 term 帶 language、from、to，可選 case_sensitive。

兩種字庫的單筆 term 新增範例。

bash

# Single term — vocabulary dictionary
curl -X POST "https://abemono.abestar.com.tw/api/v1/dictionaries/<DICT_ID>/terms" \
  -H "X-API-Key: $ABESTAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "variants": { "zh-TW": "行銷", "en": "marketing", "ja-JP": "マーケティング" }
  }'

# Single term — forced_replacement dictionary
curl -X POST "https://abemono.abestar.com.tw/api/v1/dictionaries/<DICT_ID>/terms" \
  -H "X-API-Key: $ABESTAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "en",
    "from": "AI",
    "to": "Artificial Intelligence",
    "case_sensitive": false
  }'

需要一次寫入多筆時改用批次端點 POST /api/v1/dictionaries/:id/terms/batch，body 直接放 term 陣列。每批最多 250 筆，超過會回 400 bad_request（details.reason 為 batch_too_large）。即便部分失敗整體仍回 200，逐筆結果由 processed_count / success_count / failed_count / errors[] 表達。

批次新增 term（vocabulary 字庫範例）。

bash

curl -X POST "https://abemono.abestar.com.tw/api/v1/dictionaries/<DICT_ID>/terms/batch" \
  -H "X-API-Key: $ABESTAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    { "variants": { "zh-TW": "行銷", "en": "marketing" } },
    { "variants": { "zh-TW": "業務", "en": "sales" } }
  ]'

步驟 3：在請求中啟用字庫

翻譯與語音辨識端點都接受 vocabulary_dictionary_id 與 forced_replacement_dictionary_id 兩個 UUID 參數。型別不符（vocabulary 與 forced_replacement 互傳）回 400 dictionary_type_mismatch；字庫不存在回 404 dictionary_not_found。

翻譯端點同時掛上 vocabulary 與 forced_replacement 字庫（JSON 模式）。

bash

curl -X POST "https://abemono.abestar.com.tw/api/v1/translations/text" \
  -H "X-API-Key: $ABESTAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "請把這份合約交給法務組長確認。",
    "target_language": "en",
    "vocabulary_dictionary_id": "f3c1e9a2-9c2b-4f7a-9d3a-7e2b8a1c4d5e",
    "forced_replacement_dictionary_id": "1d2e3f4a-5b6c-7d8e-9f0a-1b2c3d4e5f6a"
  }'

SSE 模式不支援 forced_replacement

stream=true 與 forced_replacement_dictionary_id 互斥；同時送出回 400 validation_error。在 SSE 模式下 meta 的 forced_replacement_count 恆為 0。