feat: first commit

2025-10-08 20:39:09 +08:00
commit 80f0e7f8d7
82 changed files with 12216 additions and 0 deletions
--- a/system_design.md
+++ b/system_design.md
@@ -0,0 +1,367 @@
+# 猫咪翻译器 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. 未来扩展
+
+- 添加更多情感和短语类别
+- 实现云端数据共享功能
+- 开发更完善的图形用户界面
+- 支持更多宠物类型
+- 集成到智能家居系统