> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 客户端模式 - 用户词典 - VOICEVOX for Laravel

> 介绍在 VOICEVOX for Laravel 的客户端模式下操作官方引擎的用户词典，注册专有名词和术语读音的方法。

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

## 概览

客户端模式的用户词典通过 `Voicevox` Facade 操作。内部会向官方 VOICEVOX 引擎的 `/user_dict`、`/user_dict_word`、`/import_user_dict` 发送 HTTP 请求。

官方引擎的词典数据按 OS 保存在用户目录。VOICEVOX 应用（产品版）macOS 构建版通常保存在以下位置。

```text theme={null}
~/Library/Application Support/voicevox-engine/user_dict.json
```

通过 Docker 启动官方引擎时也保存在容器内的用户目录中。只要一直使用同一个容器，即使重启数据也会保留。但如果像 `docker run --rm` 那样每次都创建临时容器，容器结束时词典会丢失。若需要可靠地持久化词典，请通过 Docker volume 挂载容器内的用户目录。

它与原生模式的 `storage/voicevox/user_dict.json` 是分开管理的。Laravel 侧的 `config('voicevox.core.user_dict')` 不会在客户端模式下使用。

## 前置准备

启动官方 VOICEVOX 引擎。

```shell theme={null}
docker pull voicevox/voicevox_engine:cpu-latest
docker run --rm -p '127.0.0.1:50021:50021' voicevox/voicevox_engine:cpu-latest
```

可通过 `VOICEVOX_URL` 修改连接地址。

```env theme={null}
VOICEVOX_URL=http://127.0.0.1:50021
```

## 基本使用

### 添加词

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

```php theme={null}
use Revolution\Voicevox\Voicevox;

$uuid = Voicevox::addWord(
    surface: 'Laravel',
    pronunciation: 'ララベル',
    accentType: 0,
);

// 客户端模式下会返回带 "-" 的 UUID
// 例如："a1b2c3d4-0000-0000-0000-000000000000"
```

#### 参数

| 参数              | 类型           | 说明                                                          |
| --------------- | ------------ | ----------------------------------------------------------- |
| `surface`       | string       | 表记（实际的单词字符串）                                                |
| `pronunciation` | string       | 读音（仅片假名）                                                    |
| `accentType`    | int          | 重音型（0 = 平板，1 以上 = 重音位置）                                     |
| `wordType`      | string\|null | 词类（`COMMON_NOUN`、`PROPER_NOUN`、`VERB`、`ADJECTIVE`、`SUFFIX`） |
| `priority`      | int\|null    | 优先级                                                         |

### 获取所有词

可获取所有已注册的词。

```php theme={null}
use Revolution\Voicevox\Voicevox;

$words = Voicevox::userDict();

/*
[
    "a1b2c3d4-0000-0000-0000-000000000000" => [
        "surface" => "Laravel",
        "pronunciation" => "ララベル",
        "accent_type" => 0,
        "word_type" => "COMMON_NOUN",
        "priority" => 5,
    ],
    ...
]
*/
```

### 更新词

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

```php theme={null}
use Revolution\Voicevox\Voicevox;

Voicevox::updateWord(
    wordUuid: 'a1b2c3d4-0000-0000-0000-000000000000',
    surface: 'Laravel',
    pronunciation: 'ラレベル',
    accentType: 1,
);
```

### 删除词

```php theme={null}
use Revolution\Voicevox\Voicevox;

Voicevox::deleteWord('a1b2c3d4-0000-0000-0000-000000000000');
```

### 导入词典

可以导入符合官方引擎用户词典格式的数组。`override: false`（默认）会保留现有的词，导入新增词。

```php theme={null}
use Revolution\Voicevox\Voicevox;

$words = json_decode(file_get_contents('other_user_dict.json'), true);

Voicevox::importUserDict($words, override: false);

// override: true 时会替换现有词典
Voicevox::importUserDict($words, override: true);
```

如需导出词典，可将 `Voicevox::userDict()` 的结果保存为 JSON。

```php theme={null}
$json = json_encode(Voicevox::userDict(), JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);

file_put_contents('exported_user_dict.json', $json);
```

## 注册词典后的语音合成

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

```php theme={null}
use Revolution\Voicevox\Voicevox;

Voicevox::addWord(
    surface: 'Laravel',
    pronunciation: 'ララベル',
    accentType: 0,
);

$response = Voicevox::talk('Laravelで開発するのは楽しいです', id: 1)->generate(id: 1);

$response->storeAs('client', 'laravel.wav');
```

## 与引擎 API 的对应关系

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

| Laravel                      | 官方引擎 API                             |
| ---------------------------- | ------------------------------------ |
| `Voicevox::userDict()`       | `GET /user_dict`                     |
| `Voicevox::addWord()`        | `POST /user_dict_word`               |
| `Voicevox::updateWord()`     | `PUT /user_dict_word/{word_uuid}`    |
| `Voicevox::deleteWord()`     | `DELETE /user_dict_word/{word_uuid}` |
| `Voicevox::importUserDict()` | `POST /import_user_dict`             |

## 与原生模式的区别

| 项目        | 客户端模式                                                          | 原生模式                                        |
| --------- | -------------------------------------------------------------- | ------------------------------------------- |
| 使用方式      | `Voicevox` Facade                                              | `dict()` helper                             |
| 保存位置      | 官方引擎的用户目录                                                      | Laravel 的 `storage/voicevox/user_dict.json` |
| macOS 示例  | `~/Library/Application Support/voicevox-engine/user_dict.json` | `storage/voicevox/user_dict.json`           |
| 添加时的 UUID | 带 `-`                                                          | Core 返回时不带 `-`                              |
| 引擎进程      | 需要                                                             | 不需要（需要 FFI）                                 |

## 注意事项

<Warning>
  `pronunciation` 请使用片假名指定。不能使用平假名或汉字。
</Warning>

* 客户端模式下会更新官方引擎侧的词典。不会保存到 Laravel 项目的 `storage` 中。
* 使用 `docker run --rm` 等每次创建临时容器时，容器结束时词典会丢失。
* 添加时返回的 UUID 是 `a1b2c3d4-0000-0000-0000-000000000000` 这样带连字符的格式。

## 故障排查

### 词未生效

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

### 不清楚词典文件的位置

在 macOS 构建版中请确认以下位置。

```text theme={null}
~/Library/Application Support/voicevox-engine/user_dict.json
```

在 Docker 中会保存在官方引擎的用户目录（容器内）。如需持久化，请通过 Docker volume 挂载容器内的用户目录。


## Related topics

- [客户端模式 - 预设 - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/client-presets.md)
- [客户端模式：Talk（文本语音合成） - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/client-talk.md)
- [原生模式 - 用户词典 - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/native-user-dict.md)
- [客户端模式：Song（歌声合成） - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/client-song.md)
- [开始使用 - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/getting-started.md)