辞書を 2 種類用意しているのは、「モデルに用語を理解させ文脈に織り込んでほしい」と「特定文字列は何があっても別文字列に置き換えたい」がまったく別の要件だからです。前者は生成段階で介入する必要があり、後者は生成完了後に実行する必要があります。1 つの仕組みに統合すると、いずれかの精度が犠牲になります。本章では両者の特性と、併用・排他のシーンを順に整理します。

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 は多言語対訳（1 term で複数言語）、forced_replacement は単一言語（1 term は 1 言語）。
• SSE との相互作用：vocabulary は完全互換、forced_replacement は排他（400 を発生）。
• 同時指定：JSON モードでは vocabulary + forced_replacement の併用可、SSE モードでは vocabulary のみ可。
• 更新規則：vocabulary は `variants` 全体を上書き（最低 1 件のバリアント必須）。forced_replacement は `from` / `to` / `case_sensitive` のいずれか必須、`language` は不変（PATCH に language を含めると 400 `validation_error`）。

設計上のトレードオフ

vocabulary と forced_replacement は実装上まったく独立したパスで、共有しているのは対外名称「辞書」のみです。type は作成時に選択し、以降変更不可（PATCH は type を受け付けない）。同じ語彙セットで両方の挙動が必要な場合は 2 つの辞書を作成し、同時に指定してください。シーンが排他的な場合は、用途ごとに別構成で呼び出します。

主な制限

• type は作成後変更不可（PATCH は type を受け付けない）。
• 辞書名は同一 API キー保有者内で一意。重複は 409 duplicate_name。
• term の一括作成は 1 バッチ 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。