feat: first commit

optimized_user_guide.md

@@ -0,0 +1,164 @@
+# 猫咪翻译器优化版使用指南
+
+## 简介
+
+猫咪翻译器优化版是在原有猫咪翻译器V2基础上，根据米兰大学研究团队的最佳实践进行全面优化的系统。本系统集成了时序调制特征、统计静音检测、混合特征提取和DAG-HMM分类方法，显著提高了猫叫声检测和意图分类的准确率。
+
+## 系统优化亮点
+
+1. **时序调制特征提取**：基于米兰大学研究，实现了捕捉猫叫声时序调制特征的提取方法
+2. **统计模型静音检测**：优化了静音检测算法，提高了猫叫声分割的准确性
+3. **混合特征提取器**：结合MFCC、YAMNet嵌入和时序调制特征，创建更全面的声学特征表示
+4. **DAG-HMM与优化特征集成**：将最佳分类方法与优化特征结合，实现最高准确率
+5. **调整梅尔滤波器数量**：从64调整到23，与米兰大学研究一致，更适合猫叫声分析
+
+## 安装依赖
+
+```bash
+pip install numpy==1.24.3 librosa==0.10.1 scikit-learn==1.3.0 tensorflow==2.12.0 pyaudio==0.2.13 matplotlib==3.7.2 hmmlearn==0.3.0 sounddevice==0.4.6
+```
+
+## 使用方法
+
+### 1. 分析音频文件
+
+```bash
+python optimized_main.py analyze path/to/audio.wav --detector models/optimized_cat_detector_svm.pkl --intent-model models/optimized_dag_hmm_temporal_modulation.pkl --feature-type temporal_modulation
+```
+
+参数说明：
+- `--detector`: 猫叫声检测器模型路径
+- `--intent-model`: 意图分类器模型路径
+- `--feature-type`: 特征类型，可选 'temporal_modulation'(推荐), 'mfcc', 'yamnet', 'hybrid'
+- `--threshold`: 猫叫声检测阈值，默认0.5
+
+### 2. 实时麦克风分析
+
+```bash
+python optimized_main.py live --detector models/optimized_cat_detector_svm.pkl --intent-model models/optimized_dag_hmm_temporal_modulation.pkl --duration 3.0 --interval 1.0
+```
+
+参数说明：
+- `--duration`: 每次录音持续时间（秒）
+- `--interval`: 分析间隔时间（秒）
+- `--device`: 录音设备ID（可选）
+
+### 3. 添加训练样本
+
+```bash
+# 添加猫叫声样本
+python optimized_main.py add-sample path/to/cat_sound.wav "快乐" --is-cat-sound --cat "我的猫咪"
+
+# 添加非猫叫声样本
+python optimized_main.py add-sample path/to/non_cat_sound.wav "环境噪音"
+```
+
+### 4. 训练猫叫声检测器
+
+```bash
+python optimized_main.py train-detector --cat-samples samples/cat_sounds --non-cat-samples samples/non_cat_sounds --model-type svm --output models/my_cat_detector.pkl
+```
+
+参数说明：
+- `--model-type`: 模型类型，可选 'svm'(推荐), 'rf', 'nn'
+
+### 5. 训练意图分类器
+
+```bash
+python optimized_main.py train-intent --samples intent_samples --feature-type temporal_modulation --output models/my_intent_classifier.pkl
+```
+
+样本目录结构：
+```
+intent_samples/
+├── 快乐_满足/
+│   ├── sample1.wav
+│   ├── sample2.wav
+├── 愤怒/
+│   ├── sample1.wav
+│   ├── sample2.wav
+...
+```
+
+### 6. 系统验证
+
+```bash
+# 验证意图分类器
+python optimized_system_validator.py --test-files test_data/manifest.json --validate-intent --intent-feature-type temporal_modulation --plot
+
+# 验证猫叫声检测器
+python optimized_system_validator.py --test-files test_data/manifest.json --validate-detector --detector-model-type svm --plot
+
+# 同时验证两者
+python optimized_system_validator.py --test-files test_data/manifest.json --validate-intent --validate-detector --plot
+```
+
+测试文件JSON格式：
+```json
+[
+  {"path": "path/to/audio1.wav", "intent": "快乐", "is_cat_sound": true},
+  {"path": "path/to/audio2.wav", "intent": "愤怒", "is_cat_sound": true},
+  {"path": "path/to/audio3.wav", "is_cat_sound": false}
+]
+```
+
+## 特征类型选择指南
+
+1. **时序调制特征 (temporal_modulation)**：
+   - 优势：最适合猫叫声分析，捕捉时序模式
+   - 推荐用于：意图分类，尤其是区分不同情感状态
+
+2. **MFCC特征 (mfcc)**：
+   - 优势：计算效率高，适合资源受限设备
+   - 推荐用于：简单场景和快速原型开发
+
+3. **YAMNet嵌入 (yamnet)**：
+   - 优势：通用声音识别能力强
+   - 推荐用于：复杂环境中的猫叫声检测
+
+4. **混合特征 (hybrid)**：
+   - 优势：结合所有特征的优点，最全面
+   - 推荐用于：追求最高准确率，不考虑计算资源
+
+## 模型类型选择指南
+
+1. **SVM**：
+   - 优势：小样本(10-30)效果好，训练快，模型小
+   - 推荐用于：初始阶段，样本数量有限时
+
+2. **随机森林(RF)**：
+   - 优势：中等样本(30-100)效果好，特征重要性分析
+   - 推荐用于：需要了解关键声学特征时
+
+3. **神经网络(NN)**：
+   - 优势：大样本(100+)效果最佳，持续学习能力强
+   - 推荐用于：长期使用，有大量样本时
+
+4. **DAG-HMM**：
+   - 优势：最适合猫叫声时序分析，准确率最高
+   - 推荐用于：意图分类，尤其是与时序调制特征结合
+
+## 性能优化建议
+
+1. 每个类别收集至少10个高质量样本
+2. 使用统计静音检测进行精确分段
+3. 对于意图分类，优先使用时序调制特征+DAG-HMM组合
+4. 对于猫叫声检测，在样本数量<30时使用SVM，>100时考虑神经网络
+5. 定期使用系统验证工具评估性能并调整参数
+
+## 故障排除
+
+1. **未检测到猫叫声**：
+   - 降低检测阈值（--threshold 0.3）
+   - 确保录音质量良好，背景噪音较小
+   - 添加更多当前环境下的猫叫声样本
+
+2. **意图分类不准确**：
+   - 为特定意图添加更多样本
+   - 尝试不同特征类型，特别是temporal_modulation
+   - 调整DAG-HMM参数（状态数和混合成分数）
+
+3. **系统运行缓慢**：
+   - 使用计算效率更高的特征类型（如mfcc）
+   - 减少音频分段重叠
+   - 降低采样率（但不低于16kHz）