> ## 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 VOICEVOX 的用户词典功能是基于 VOICEVOX Core 的 UserDict 的原生实现。词典数据以 JSON 形式持久化到 `storage/voicevox/user_dict.json`。

<Info>
  由于使用了与官方 VOICEVOX 引擎独立的存储，在 Laravel 侧注册的词不会同步到官方引擎侧（反之亦然）。
</Info>

## 配置

默认保存在 `storage/voicevox/user_dict.json`。若想使用其他路径，可在 `config/voicevox.php` 中修改。

```php theme={null}
// config/voicevox.php

return [
    'core' => [
        'user_dict' => storage_path('voicevox/user_dict.json'),
    ],
];
```

## 基本使用

### 添加词

通过 `dict()` helper 的 `add()` 注册词。

```php theme={null}
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`）

#### 重音型

* `0`：平板重音
* `1`：第一拍
* `2`：第二拍
* `3`：第三拍

### 更新词

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

dict()->update(
    wordUuid: '550e8400-e29b-41d4-a716-446655440000',
    surface: 'Laravel',
    pronunciation: 'ラレベル',
    accentType: 1,
);
```

### 删除词

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

dict()->delete('550e8400-e29b-41d4-a716-446655440000');
```

### 获取所有词

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

$words = dict()->all();
// 或
$words = dict()->toArray();
```

### 导入词典

```php theme={null}
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);
```

### 导出词典

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

$json = dict()->toJson();
file_put_contents('exported_dict.json', $json);
```

## 通过引擎 API 访问

如果已启动 Laravel VOICEVOX 的引擎 API，也可以通过 HTTP 操作用户词典。此时不会 fallback 到官方引擎，而是使用原生词典。

### 获取所有词

```bash theme={null}
curl http://localhost:50513/user_dict
```

### 添加词

```bash theme={null}
curl -X POST "http://localhost:50513/user_dict_word?surface=Laravel&pronunciation=ララベル&accent_type=0"
```

### 更新词

```bash theme={null}
curl -X PUT "http://localhost:50513/user_dict_word/{uuid}?surface=Laravel&pronunciation=ラレベル&accent_type=1"
```

### 删除词

```bash theme={null}
curl -X DELETE "http://localhost:50513/user_dict_word/{uuid}"
```

### 导入词典

```bash theme={null}
curl -X POST "http://localhost:50513/import_user_dict?override=false" \
  -H "Content-Type: application/json" \
  -d @other_dict.json
```

<Tip>
  指定 `override=true` 时，会先清空所有现有词典再进行导入。
</Tip>

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

注册到用户词典中的词，在语音合成时会自动被参考。

```php theme={null}
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');
```

## 注意事项

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

* Laravel 版的用户词典与官方 VOICEVOX 引擎的用户词典是分开管理的。
* 词的添加、更新、删除会立即保存到 JSON 文件中。
* 若不确定重音型，可先尝试 `0`（平板）。

## 故障排查

### 词未生效

1. 请确认存储目录具有写入权限
2. 请确认 `storage/voicevox/user_dict.json` 已被正确创建
3. 请确认片假名表记是否正确

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

```php theme={null}
$path = config('voicevox.core.user_dict');
echo $path;
```

### 想重置词典

```bash theme={null}
rm storage/voicevox/user_dict.json
```

```php theme={null}
$path = config('voicevox.core.user_dict');
if (file_exists($path)) {
    unlink($path);
}
```


## Related topics

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