跳转到主要内容
使用用户词典,你可以将专有名词和专业术语的读音注册到官方 VOICEVOX 引擎。在客户端模式下,Laravel 侧不保存词典,而是直接使用所连接的官方引擎所管理的用户词典 API。

概览

客户端模式的用户词典通过 Voicevox Facade 操作。内部会向官方 VOICEVOX 引擎的 /user_dict/user_dict_word/import_user_dict 发送 HTTP 请求。 官方引擎的词典数据按 OS 保存在用户目录。VOICEVOX 应用(产品版)macOS 构建版通常保存在以下位置。
通过 Docker 启动官方引擎时也保存在容器内的用户目录中。只要一直使用同一个容器,即使重启数据也会保留。但如果像 docker run --rm 那样每次都创建临时容器,容器结束时词典会丢失。若需要可靠地持久化词典,请通过 Docker volume 挂载容器内的用户目录。 它与原生模式的 storage/voicevox/user_dict.json 是分开管理的。Laravel 侧的 config('voicevox.core.user_dict') 不会在客户端模式下使用。

前置准备

启动官方 VOICEVOX 引擎。
可通过 VOICEVOX_URL 修改连接地址。

基本使用

添加词

通过 Voicevox::addWord() 注册词汇。

参数

获取所有词

可获取所有已注册的词。

更新词

使用添加时返回的 UUID 进行更新。

删除词

导入词典

可以导入符合官方引擎用户词典格式的数组。override: false(默认)会保留现有的词,导入新增词。
如需导出词典,可将 Voicevox::userDict() 的结果保存为 JSON。

注册词典后的语音合成

注册到用户词典中的词,在官方引擎进行语音合成时会自动参考。

与引擎 API 的对应关系

Voicevox Facade 的各方法与官方引擎的 API 相对应。

与原生模式的区别

注意事项

pronunciation 请使用片假名指定。不能使用平假名或汉字。
  • 客户端模式下会更新官方引擎侧的词典。不会保存到 Laravel 项目的 storage 中。
  • 使用 docker run --rm 等每次创建临时容器时,容器结束时词典会丢失。
  • 添加时返回的 UUID 是 a1b2c3d4-0000-0000-0000-000000000000 这样带连字符的格式。

故障排查

词未生效

  1. 请确认官方 VOICEVOX 引擎已启动。
  2. 请确认 VOICEVOX_URL 指向正确的连接地址。
  3. 请确认读音是否为片假名。
  4. 请确认没有在 Docker 中重新启动到另一个容器。

不清楚词典文件的位置

在 macOS 构建版中请确认以下位置。
在 Docker 中会保存在官方引擎的用户目录(容器内)。如需持久化,请通过 Docker volume 挂载容器内的用户目录。
最后修改于 2026年7月18日