petshy/user_guide.md

猫咪翻译器 V2 用户指南

简介

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

安装

系统要求

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

依赖项安装

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

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

使用方法

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

分析音频文件

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

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

实时麦克风分析

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

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

添加训练样本

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

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

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

训练模型

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

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

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

处理用户反馈

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

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

导出用户数据

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

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

导入用户数据

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 并且麦克风设备正常工作。在某些系统上，可能需要安装额外的依赖：

# 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 命令备份和恢复数据。