# 模型设置界面使用指南

## 概述

新增的模型设置界面允许用户方便地配置和管理离线ASR、在线ASR（语音识别）和TTS（语音合成）模型，无需手动编辑代码或配置文件。

## 访问方式

### 菜单栏访问
- 点击菜单栏 **设置(S)** → **模型设置(M)...**
- 快捷键：`Ctrl+M`

### 界面布局

模型设置对话框采用标签页设计，包含五个主要部分：

## 1. 离线语音识别标签页

### 模型选择
- **预设模型下拉框**：
  - `自定义`：手动指定模型路径
  - `Paraformer中文模型`：自动配置中文识别模型
  - `Whisper多语言模型`：支持多语言识别

### 模型路径配置
- **模型文件**：选择 `.onnx` 格式的模型文件
- **词汇表文件**：选择对应的 `tokens.txt` 文件

### 模型信息显示
- 显示模型文件大小、修改时间和状态
- **测试模型**按钮：验证模型是否可用（功能待实现）

## 2. 在线语音识别标签页

### 模型选择
- **预设模型下拉框**：
  - `自定义`：手动指定模型路径
  - `Streaming Paraformer中英文模型`：实时中英文识别
  - `Streaming Zipformer中英文模型`：另一种实时识别模型

### 模型路径配置
- **编码器文件**：选择 `encoder.onnx` 文件
- **词汇表文件**：选择对应的 `tokens.txt` 文件

### 模型信息显示
- 显示模型文件大小、修改时间和状态
- **测试模型**按钮：验证在线识别模型功能

## 3. 语音唤醒 (KWS) 标签页

### 模型选择
- **预设模型下拉框**：
  - `自定义`：手动指定模型路径
  - `Zipformer Wenetspeech 3.3M`：默认中文关键词检测模型
  - `Zipformer Gigaspeech`：英文关键词检测模型

### 模型路径配置
- **模型文件**：选择 `.onnx` 格式的KWS模型文件
- **词汇表文件**：选择对应的 `tokens.txt` 文件
- **关键词文件**：选择 `keywords.txt` 文件，定义可检测的关键词

### 模型信息显示
- 显示模型文件大小、修改时间和状态
- **测试模型**按钮：验证语音唤醒模型功能

## 4. 语音合成 (TTS) 标签页

### 模型选择
- **预设模型下拉框**：
  - `自定义`：手动指定模型路径
  - `MeloTTS中英文混合`：支持中英文混合合成
  - `VITS中文模型`：仅支持中文

### 模型路径配置
- **模型文件**：选择 `.onnx` 格式的TTS模型
- **词汇表文件**：选择 `tokens.txt` 文件
- **词典文件**：选择 `lexicon.txt` 文件
- **字典目录**：选择包含jieba分词数据的 `dict` 目录
- **数据目录**：选择 `espeak-ng-data` 目录（用于英文发音）

### 模型信息显示
- 显示模型详细信息和状态
- **测试模型**按钮：验证TTS模型功能

## 5. 高级设置标签页

### 路径设置
- **数据根目录**：设置模型文件的根目录
  - 默认：`~/.config/QSmartAssistant/Data`

### 功能设置
- **启动时自动扫描模型**：程序启动时自动检测可用模型
- **启用详细日志**：输出更多调试信息

## 使用流程

### 首次配置
1. 打开模型设置对话框
2. 选择合适的预设模型类型
3. 系统会自动填充默认路径
4. 检查路径是否正确，必要时手动调整
5. 点击**保存**应用设置

### 自定义配置
1. 在模型选择中选择**自定义**
2. 手动浏览并选择各个文件路径
3. 确保所有必需文件都已选择
4. 保存设置

### 模型验证
- 选择文件后，模型信息区域会显示文件状态
- 绿色状态表示文件存在且可用
- 红色状态表示文件不存在或有问题

## 配置存储

### 自动保存
- 设置会自动保存到系统配置文件
- 下次启动程序时会自动加载上次的配置

### 配置位置
- Windows: 注册表
- macOS/Linux: `~/.config/QSmartAssistant/`

## 预设模型路径

### ASR模型
```
Paraformer中文模型:
├── model.int8.onnx          # 模型文件
└── tokens.txt               # 词汇表
```

### TTS模型

#### MeloTTS中英文混合
```
vits-melo-tts-zh_en/
├── model.int8.onnx          # 模型文件
├── tokens.txt               # 词汇表
├── lexicon.txt              # 词典
└── dict/                    # jieba字典目录
    ├── jieba.dict.utf8
    ├── hmm_model.utf8
    └── ...
```

#### VITS中英文混合
```
vits-zh-en/
├── vits-zh-en.onnx          # 模型文件
├── tokens.txt               # 词汇表
├── lexicon.txt              # 词典
└── espeak-ng-data/          # 英文发音数据
```

#### VITS中文模型
```
vits-zh-aishell3/
├── vits-aishell3.int8.onnx  # 模型文件
├── tokens.txt               # 词汇表
└── lexicon.txt              # 词典
```

## 功能按钮

### 主要操作
- **保存**：应用当前设置并关闭对话框
- **取消**：放弃更改并关闭对话框
- **重置默认**：恢复所有设置为默认值

### 辅助功能
- **扫描模型**：自动搜索系统中的可用模型（待实现）
- **浏览**：打开文件/目录选择对话框
- **测试模型**：验证模型配置（待实现）

## 注意事项

### 文件要求
1. 所有模型文件必须存在且可读
2. 文件路径不能包含特殊字符
3. 确保有足够的磁盘空间

### 性能考虑
1. 大型模型加载时间较长
2. 建议使用SSD存储模型文件
3. 内存不足时可能导致加载失败

### 兼容性
1. 仅支持ONNX格式的模型
2. 确保模型版本与sherpa-onnx兼容
3. 不同模型可能有不同的输入要求

## 故障排除

### 常见问题
1. **模型加载失败**
   - 检查文件路径是否正确
   - 确认文件权限
   - 验证模型格式

2. **设置不生效**
   - 确保点击了保存按钮
   - 重启程序重新加载配置
   - 检查配置文件权限

3. **性能问题**
   - 尝试使用较小的模型
   - 增加系统内存
   - 关闭其他占用资源的程序

### 获取帮助
- 查看程序日志输出
- 检查模型文件完整性
- 参考sherpa-onnx官方文档