Skip to main content
使用使用者字典可將專有名詞或專業術語的讀音登記於官方 VOICEVOX 引擎。在 Client 模式下,Laravel 端不會儲存字典,而是直接使用連線目標官方引擎所管理的使用者字典 API。

概觀

Client 模式的使用者字典透過 Voicevox Facade 操作。內部會對官方 VOICEVOX 引擎的 /user_dict/user_dict_word/import_user_dict 發送 HTTP 請求。 官方引擎的字典資料儲存於各 OS 的使用者區。VOICEVOX 應用(產品版)macOS 的 build 版通常儲存於下列位置。
若以 Docker 啟動官方引擎,也會儲存於容器內的使用者區。只要繼續使用同一個容器,即使重啟資料也會維持。但若使用 docker run --rm 之類每次建立臨時容器,容器結束時字典會遺失。若要確實持久化字典,請以 Docker volume 掛載容器內的使用者區。 與 Native 模式的 storage/voicevox/user_dict.json 為分開管理。Laravel 端的 config('voicevox.core.user_dict') 不會用於 Client 模式。

事前準備

啟動官方 VOICEVOX 引擎。
連線目標可透過 VOICEVOX_URL 變更。

基本用法

新增詞彙

可透過 Voicevox::addWord() 登記詞彙。

參數

取得所有詞彙

可取得已登記的所有詞彙。

更新詞彙

以新增時回傳的 UUID 進行更新。

刪除詞彙

匯入字典

可匯入官方引擎使用者字典格式的陣列。override: false(預設)會保留現有詞彙,並追加匯入的詞彙。
若要匯出字典,可將 Voicevox::userDict() 的結果保存為 JSON。

字典登記後的語音合成

登記於使用者字典的詞彙會在官方引擎進行語音合成時自動參照。

與 Engine API 的對應

Voicevox Facade 的各方法對應於官方引擎的 API。

與 Native 模式的差異

注意事項

pronunciation 請以片假名指定。無法使用平假名或漢字。
  • 在 Client 模式下更新的是官方引擎端的字典。不會儲存於 Laravel 專案的 storage
  • 若使用 docker run --rm 每次建立臨時容器,容器結束時字典會遺失。
  • 新增時回傳的 UUID 為 a1b2c3d4-0000-0000-0000-000000000000 這類含 - 的格式。

疑難排解

詞彙未反映

  1. 確認官方 VOICEVOX 引擎是否已啟動。
  2. 確認 VOICEVOX_URL 指向正確的連線目標。
  3. 確認讀音是否為片假名。
  4. 確認是否在 Docker 中重新啟動了不同的容器。

找不到字典檔案位置

macOS 的 build 版請確認以下位置。
Docker 中會儲存於官方引擎的使用者區(容器內)。若需持久化,請將容器內的使用者區以 Docker volume 掛載。
最後修改於 2026年8月2日