# 猫咪翻译器 V2 用户指南

## 简介

猫咪翻译器 V2 是一个基于 YAMNet 深度学习模型的猫叫声分析系统，能够识别猫咪的情感状态和意图。系统采用双层架构，先检测猫叫声，再分析其意图，大幅提高了识别准确率。同时，系统支持用户自定义训练，可以根据特定猫咪的叫声特点进行个性化调整。

## 安装

### 系统要求

- Python 3.8 或更高版本
- 至少 4GB 内存
- 支持 Windows、macOS 和 Linux

### 依赖项安装

```bash
# 创建虚拟环境（推荐）
python -m venv venv
source venv/bin/activate  # Linux/macOS
# 或
venv\Scripts\activate  # Windows

# 安装依赖
pip install tensorflow tensorflow-hub librosa numpy pyaudio soundfile
```

## 使用方法

猫咪翻译器 V2 提供了命令行界面，支持多种操作模式。

### 分析音频文件

```bash
python main.py analyze path/to/audio.wav [--cat 猫咪名称]
```

分析指定的音频文件，检测是否包含猫叫声，并识别其情感和意图。如果指定了猫咪名称，将使用该猫咪的个性化模型（如果存在）。

### 实时麦克风分析

```bash
python main.py live [--cat 猫咪名称]
```

启动实时麦克风分析模式，持续监听并分析环境声音，检测猫叫声并识别其意图。按 Ctrl+C 停止。

### 添加训练样本

```bash
python main.py add-sample path/to/audio.wav 标签名称 [--type emotion|phrase] [--cat 猫咪名称] [--custom-phrase 自定义短语]
```

添加一个训练样本，用于后续模型训练。

- `--type`: 标签类型，可以是 `emotion`（情感）或 `phrase`（短语），默认为 `emotion`
- `--cat`: 猫咪名称，用于个性化模型
- `--custom-phrase`: 自定义短语，仅当标签为 `custom` 且类型为 `phrase` 时使用

### 训练模型

```bash
python main.py train [--type emotion|phrase|both] [--cat 猫咪名称]
```

使用已添加的训练样本训练模型。

- `--type`: 模型类型，可以是 `emotion`（情感）、`phrase`（短语）或 `both`（两者），默认为 `both`
- `--cat`: 猫咪名称，用于训练特定猫咪的个性化模型

### 处理用户反馈

```bash
python main.py feedback path/to/audio.wav 预测标签 正确标签 [--type emotion|phrase] [--cat 猫咪名称] [--custom-phrase 自定义短语]
```

处理用户反馈，用于改进模型。系统会记录反馈，并在累积足够的反馈后自动触发增量训练。

### 导出用户数据

```bash
python main.py export path/to/export.zip
```

将用户数据（包括训练样本、模型和配置）导出到指定文件，便于备份或迁移。

### 导入用户数据

```bash
python main.py import path/to/export.zip [--overwrite]
```

从指定文件导入用户数据。

- `--overwrite`: 是否覆盖现有数据，默认为 False

## 情感类别

系统默认支持以下情感类别：

1. 快乐/满足
2. 颐音
3. 愤怒
4. 打架
5. 叫妈妈
6. 交配鸣叫
7. 痛苦
8. 休息
9. 狩猎
10. 警告
11. 关注我

## 短语类别

系统默认支持以下短语类别：

1. 喂我
2. 我想出去
3. 我想玩
4. 我很无聊
5. 我很饿
6. 我渴了
7. 我累了
8. 我不舒服

用户可以通过添加自定义短语来扩展短语类别。

## 个性化训练

为了获得最佳效果，建议为每只猫咪创建个性化模型：

1. 使用 `add-sample` 命令添加特定猫咪的叫声样本
2. 使用 `train` 命令训练该猫咪的个性化模型
3. 使用 `--cat` 参数指定猫咪名称进行分析

## 持续学习

系统支持持续学习，通过以下方式不断改进：

1. 使用 `feedback` 命令提供反馈
2. 系统会记录反馈，并在累积足够的反馈后自动触发增量训练
3. 也可以手动使用 `train` 命令触发训练

## 故障排除

### 麦克风不工作

确保已安装 PyAudio 并且麦克风设备正常工作。在某些系统上，可能需要安装额外的依赖：

```bash
# Ubuntu/Debian
sudo apt-get install portaudio19-dev
pip install pyaudio

# macOS
brew install portaudio
pip install pyaudio
```

### 模型训练失败

确保有足够的训练样本（至少 5 个）和至少 2 个不同的类别。

### 识别准确率低

1. 添加更多特定猫咪的训练样本
2. 使用高质量的录音，减少背景噪音
3. 确保录音中包含完整的猫叫声

## 数据隐私

所有数据和模型都存储在本地，不会上传到任何服务器。您可以使用 `export` 和 `import` 命令备份和恢复数据。