petshy/system_design.md

# 猫咪翻译器 V2 系统设计文档

## 1. 系统架构概述

猫咪翻译器 V2 采用基于 YAMNet 深度学习模型的双层架构，实现猫叫声检测和意图识别的分离，并支持用户自定义训练和持续学习。系统由以下主要模块组成：

```
+---------------------------+
|      用户界面层           |
|  (CLI或简单GUI界面)       |
+---------------------------+
            |
+---------------------------+
|      音频输入模块         |
| (文件输入/麦克风实时输入) |
+---------------------------+
            |
+---------------------------+
|     预处理与特征提取模块   |
| (对数梅尔频谱图、分段)    |
+---------------------------+
            |
+---------------------------+
|     猫叫声检测模型        |
| (YAMNet迁移学习)          |
+---------------------------+
            |
+---------------------------+
|     意图分类模型          |
| (YAMNet嵌入向量+分类器)   |
+---------------------------+
            |
+---------------------------+
|     用户反馈与持续学习模块 |
| (增量训练、模型更新)      |
+---------------------------+
            |
+---------------------------+
|     数据管理模块          |
| (模型、用户数据、配置)    |
+---------------------------+
```

## 2. 模块详细设计

### 2.1 音频输入模块

**功能**：支持本地音频文件分析和实时麦克风输入。

**设计要点**：
- 使用 `librosa` 处理本地音频文件
- 使用 `pyaudio` 实现实时麦克风输入
- 统一音频格式：16kHz 采样率，单声道，[-1.0, 1.0] 范围
- 实现音频流处理和缓冲机制

**接口设计**：
```python
class AudioInput:
    def load_from_file(self, file_path: str) -> Tuple[np.ndarray, int]:
        """加载音频文件并转换为16kHz单声道格式"""
        pass
        
    def start_microphone_capture(self) -> None:
        """开始麦克风捕获"""
        pass
        
    def stop_microphone_capture(self) -> None:
        """停止麦克风捕获"""
        pass
        
    def get_audio_chunk(self) -> Optional[np.ndarray]:
        """获取一个音频数据块"""
        pass
```

### 2.2 预处理与特征提取模块

**功能**：对输入音频进行预处理，提取对数梅尔频谱图特征。

**设计要点**：
- 实现音频分段，每段0.96秒，重叠0.48秒
- 提取对数梅尔频谱图特征，替代MFCC
- 实现静音检测和噪声过滤
- 准备适合YAMNet输入的格式

**接口设计**：
```python
class AudioProcessor:
    def preprocess(self, audio_data: np.ndarray) -> np.ndarray:
        """音频预处理：重采样、归一化等"""
        pass
        
    def segment_audio(self, audio_data: np.ndarray) -> List[np.ndarray]:
        """将音频分割为重叠的片段"""
        pass
        
    def extract_log_mel_spectrogram(self, audio_data: np.ndarray) -> np.ndarray:
        """提取对数梅尔频谱图特征"""
        pass
        
    def detect_silence(self, audio_data: np.ndarray) -> bool:
        """检测音频片段是否为静音"""
        pass
```

### 2.3 猫叫声检测模型

**功能**：从环境音频中识别出猫的叫声。

**设计要点**：
- 基于YAMNet的迁移学习模型
- 二分类：猫叫声 vs 非猫叫声
- 使用YAMNet的嵌入向量作为特征输入
- 添加简单的分类层进行猫叫声检测

**接口设计**：
```python
class CatSoundDetector:
    def __init__(self, yamnet_model_path: str = 'https://tfhub.dev/google/yamnet/1'):
        """初始化猫叫声检测器"""
        pass
        
    def load_model(self, model_path: Optional[str] = None) -> None:
        """加载预训练模型"""
        pass
        
    def detect(self, audio_data: np.ndarray) -> Dict[str, Any]:
        """检测音频是否包含猫叫声"""
        pass
        
    def train(self, features: List[np.ndarray], labels: List[int]) -> None:
        """训练或微调模型"""
        pass
        
    def save_model(self, model_path: str) -> None:
        """保存模型"""
        pass
```

### 2.4 意图分类模型

**功能**：分析猫叫声并识别其意图和情绪。

**设计要点**：
- 使用YAMNet提取的1024维嵌入向量作为特征
- 多分类模型，支持基础情感和固定短语识别
- 可为每只猫训练个性化模型
- 支持置信度评估

**接口设计**：
```python
class CatIntentClassifier:
    def __init__(self, num_classes: int, yamnet_model_path: str = 'https://tfhub.dev/google/yamnet/1'):
        """初始化意图分类器"""
        pass
        
    def load_model(self, model_path: str, cat_name: Optional[str] = None) -> None:
        """加载预训练模型"""
        pass
        
    def predict(self, features: np.ndarray) -> Dict[str, Any]:
        """预测猫叫声的意图"""
        pass
        
    def train(self, features: List[np.ndarray], labels: List[int], cat_name: Optional[str] = None) -> None:
        """训练或微调模型"""
        pass
        
    def save_model(self, model_path: str, cat_name: Optional[str] = None) -> None:
        """保存模型"""
        pass
```

### 2.5 用户反馈与持续学习模块

**功能**：支持用户为特定猫咪的叫声添加标签并训练模型。

**设计要点**：
- 实现标签添加和管理机制
- 设计增量学习算法
- 基于用户反馈自动更新模型
- 支持多猫咪个性化模型管理

**接口设计**：
```python
class UserTrainer:
    def __init__(self, user_data_dir: str):
        """初始化用户训练器"""
        pass
        
    def add_label(self, audio_data: np.ndarray, label: str, 
                 label_type: str, cat_name: Optional[str] = None) -> str:
        """添加标签"""
        pass
        
    def train_model(self, model_type: str = 'both', 
                   cat_name: Optional[str] = None) -> str:
        """训练模型"""
        pass
        
    def process_user_feedback(self, audio_data: np.ndarray, 
                             predicted_label: str, correct_label: str,
                             cat_name: Optional[str] = None) -> None:
        """处理用户反馈"""
        pass
        
    def export_user_data(self, export_path: str) -> str:
        """导出用户数据"""
        pass
        
    def import_user_data(self, import_path: str, overwrite: bool = False) -> bool:
        """导入用户数据"""
        pass
```

### 2.6 数据管理模块

**功能**：管理模型、用户数据和配置信息的存储和访问。

**设计要点**：
- 使用TensorFlow SavedModel格式保存模型
- 支持TFLite模型转换
- 使用JSON存储配置和元数据
- 实现数据备份和恢复机制

**接口设计**：
```python
class DataManager:
    def __init__(self, base_dir: str = "./data"):
        """初始化数据管理器"""
        pass
        
    def save_model(self, model: Any, path: str) -> str:
        """保存模型"""
        pass
        
    def load_model(self, path: str) -> Any:
        """加载模型"""
        pass
        
    def convert_to_tflite(self, model_path: str, output_path: str) -> None:
        """将模型转换为TFLite格式"""
        pass
        
    def save_config(self, config: Dict[str, Any], path: str) -> str:
        """保存配置"""
        pass
        
    def load_config(self, path: str) -> Dict[str, Any]:
        """加载配置"""
        pass
        
    def backup_user_data(self, backup_path: Optional[str] = None) -> str:
        """备份用户数据"""
        pass
        
    def restore_user_data(self, backup_path: str) -> bool:
        """恢复用户数据"""
        pass
```

## 3. 数据流设计

### 3.1 音频文件分析流程

1. 用户提供音频文件路径
2. 音频输入模块加载并预处理音频
3. 预处理模块分割音频并提取特征
4. 猫叫声检测模型判断是否包含猫叫声
5. 对检测为猫叫声的片段，意图分类模型进行意图识别
6. 返回分析结果

### 3.2 实时麦克风分析流程

1. 用户启动实时分析
2. 音频输入模块开始麦克风捕获
3. 系统持续获取音频块并缓冲
4. 预处理模块处理缓冲区音频并提取特征
5. 猫叫声检测模型判断是否包含猫叫声
6. 对检测为猫叫声的片段，意图分类模型进行意图识别
7. 实时显示分析结果

### 3.3 用户训练流程

1. 用户提供音频文件和标签
2. 系统处理音频并提取特征
3. 用户训练模块保存特征和标签
4. 用户请求训练模型
5. 系统加载保存的特征和标签
6. 训练或微调相应模型
7. 保存更新后的模型

### 3.4 用户反馈流程

1. 系统进行预测
2. 用户提供反馈（正确或纠正预测）
3. 系统记录反馈
4. 当累积足够的反馈时，自动触发增量训练
5. 更新模型

## 4. 模型设计

### 4.1 猫叫声检测模型

```
YAMNet基础模型
    |
提取1024维嵌入向量
    |
Dense层(256, ReLU)
    |
Dropout(0.3)
    |
Dense层(2, Softmax) -> [非猫叫声, 猫叫声]
```

### 4.2 意图分类模型

```
YAMNet基础模型
    |
提取1024维嵌入向量
    |
Dense层(512, ReLU)
    |
Dropout(0.4)
    |
Dense层(256, ReLU)
    |
Dropout(0.3)
    |
Dense层(num_classes, Softmax) -> [情感1, 情感2, ..., 短语1, 短语2, ...]
```

## 5. 依赖项

- Python 3.8+
- TensorFlow 2.11+
- TensorFlow Hub
- TensorFlow IO
- librosa
- pyaudio
- numpy
- pandas
- matplotlib

## 6. 部署考虑

### 6.1 本地部署

- 支持Windows、macOS和Linux
- 提供命令行界面
- 可选的简单GUI界面

### 6.2 移动端部署（可选）

- 使用TensorFlow Lite转换模型
- 优化模型大小和推理速度
- 提供Android/iOS示例代码

## 7. 未来扩展

- 添加更多情感和短语类别
- 实现云端数据共享功能
- 开发更完善的图形用户界面
- 支持更多宠物类型
- 集成到智能家居系统