什么是用户词典
使用用户词典，你可以让 VOICEVOX 记住专有名词和专业术语的读音。注册的词在语音合成时会以恰当的发音朗读。
Laravel VOICEVOX 的用户词典功能是基于 VOICEVOX Core 的 UserDict 的原生实现。词典数据以 JSON 形式持久化到 storage/voicevox/user_dict.json。
由于使用了与官方 VOICEVOX 引擎独立的存储，在 Laravel 侧注册的词不会同步到官方引擎侧（反之亦然）。
storage/voicevox/user_dict.json。若想使用其他路径，可在 config/voicevox.php 中修改。
// config/voicevox.php
return [
'core' => [
'user_dict' => storage_path('voicevox/user_dict.json'),
],
];
基本使用
添加词
通过 dict() helper 的 add() 注册词。
use function Revolution\Voicevox\dict;
$uuid = dict()->add(
surface: 'Laravel',
pronunciation: 'ララベル',
accentType: 0,
);
// 返回不带 "-" 的 UUID
// 例如："550e8400e29b41d4a716446655440000"
surface（必需）：表记pronunciation（必需）：读音（仅片假名）accentType（必需）：重音型（0 = 平板，1 以上 = 重音位置）wordType（可选）：词类（COMMON_NOUN、PROPER_NOUN、VERB、ADJECTIVE、SUFFIX）priority（可选）：优先级（默认 5）
重音型
更新词
use function Revolution\Voicevox\dict;
dict()->update(
wordUuid: '550e8400-e29b-41d4-a716-446655440000',
surface: 'Laravel',
pronunciation: 'ラレベル',
accentType: 1,
);
删除词
use function Revolution\Voicevox\dict;
dict()->delete('550e8400-e29b-41d4-a716-446655440000');
获取所有词
use function Revolution\Voicevox\dict;
$words = dict()->all();
// 或
$words = dict()->toArray();
导入词典
use function Revolution\Voicevox\dict;
$json = file_get_contents('other_user_dict.json');
dict()->import($json, override: false);
// override: true 时会覆盖
dict()->import($json, override: true);
导出词典
use function Revolution\Voicevox\dict;
$json = dict()->toJson();
file_put_contents('exported_dict.json', $json);
通过引擎 API 访问
如果已启动 Laravel VOICEVOX 的引擎 API，也可以通过 HTTP 操作用户词典。此时不会 fallback 到官方引擎，而是使用原生词典。
获取所有词
curl http://localhost:50513/user_dict
添加词
curl -X POST "http://localhost:50513/user_dict_word?surface=Laravel&pronunciation=ララベル&accent_type=0"
更新词
curl -X PUT "http://localhost:50513/user_dict_word/{uuid}?surface=Laravel&pronunciation=ラレベル&accent_type=1"
删除词
curl -X DELETE "http://localhost:50513/user_dict_word/{uuid}"
导入词典
curl -X POST "http://localhost:50513/import_user_dict?override=false" \
-H "Content-Type: application/json" \
-d @other_dict.json
指定 override=true 时，会先清空所有现有词典再进行导入。
注册词典后的语音合成
注册到用户词典中的词，在语音合成时会自动被参考。
use function Revolution\Voicevox\{dict, talk};
dict()->add(
surface: 'Laravel',
pronunciation: 'ララベル',
accentType: 0,
);
$response = talk('Laravelで開発するのは楽しいです', id: 1)->generate(id: 1);
$response->storeAs('native', 'laravel.wav');
注意事项
pronunciation 请仅使用片假名指定。不能使用平假名或汉字。
- Laravel 版的用户词典与官方 VOICEVOX 引擎的用户词典是分开管理的。
- 词的添加、更新、删除会立即保存到 JSON 文件中。
- 若不确定重音型，可先尝试
0（平板）。
故障排查
词未生效
- 请确认存储目录具有写入权限
- 请确认
storage/voicevox/user_dict.json 已被正确创建
- 请确认片假名表记是否正确
不清楚词典文件的位置
$path = config('voicevox.core.user_dict');
echo $path;
想重置词典
rm storage/voicevox/user_dict.json
$path = config('voicevox.core.user_dict');
if (file_exists($path)) {
unlink($path);
}
