realTimeVTT/docs/故障排除.md

# 故障排除指南

## 常见问题及解决方案

### 1. 安装和环境问题

#### 问题：Python 版本不兼容

**错误信息**:
```
requires-python = ">=3.12.10" but the current Python version is 3.11.x
```

**解决方案**:
1. 升级 Python 到 3.12+
   ```bash
   # macOS 使用 Homebrew
   brew install python@3.12
   
   # 或使用 pyenv
   pyenv install 3.12.10
   pyenv local 3.12.10
   ```

2. 验证 Python 版本
   ```bash
   python --version
   # 应显示 Python 3.12.x
   ```

#### 问题：uv 包管理器未安装

**错误信息**:
```
command not found: uv
```

**解决方案**:
```bash
# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或使用 pip
pip install uv

# 验证安装
uv --version
```

#### 问题：PyAudio 安装失败

**错误信息**:
```
ERROR: Failed building wheel for pyaudio
portaudio.h: No such file or directory
```

**解决方案**:

**macOS**:
```bash
# 安装 portaudio
brew install portaudio

# 重新安装依赖
uv sync --reinstall
```

**Linux (Ubuntu/Debian)**:
```bash
# 安装系统依赖
sudo apt-get update
sudo apt-get install portaudio19-dev python3-dev

# 重新安装依赖
uv sync --reinstall
```

### 2. 模型相关问题

#### 问题：模型文件缺失

**错误信息**:
```
错误: 缺少模型文件
缺少的文件:
  - /path/to/models/encoder-epoch-99-avg-1.onnx
  - /path/to/models/decoder-epoch-99-avg-1.onnx
  - /path/to/models/joiner-epoch-99-avg-1.onnx
  - /path/to/models/tokens.txt
```

**解决方案**:
1. 下载模型文件
   ```bash
   uv run python main.py --download-model
   ```

2. 选择合适的模型（推荐中英双语模型）

3. 等待下载完成（可能需要几分钟）

4. 验证模型文件
   ```bash
   ls -la models/
   # 应该看到 .onnx 和 tokens.txt 文件
   ```

#### 问题：模型下载失败

**错误信息**:
```
下载失败: HTTP Error 404
网络连接超时
```

**解决方案**:
1. 检查网络连接
2. 使用代理（如果需要）
   ```bash
   export https_proxy=http://proxy.example.com:8080
   uv run python main.py --download-model
   ```

3. 手动下载模型文件
   - 访问 sherpa-onnx 官方模型库
   - 下载对应的模型文件
   - 放置到 `models/` 目录

#### 问题：模型加载失败

**错误信息**:
```
RuntimeError: Failed to load model
ONNX Runtime error
```

**解决方案**:
1. 检查模型文件完整性
   ```bash
   # 检查文件大小，不应该为0
   ls -lh models/*.onnx
   ```

2. 重新下载模型
   ```bash
   rm -rf models/*.onnx
   uv run python main.py --download-model
   ```

3. 检查系统资源
   - 确保有足够内存（建议4GB+）
   - 检查磁盘空间

### 3. 音频设备问题

#### 问题：无法初始化音频设备

**错误信息**:
```
错误: 无法初始化音频设备
OSError: [Errno -9996] Invalid input device
```

**解决方案**:
1. 检查音频设备
   ```bash
   uv run python main.py --list-devices
   ```

2. 确保麦克风权限
   - **macOS**: 系统偏好设置 → 安全性与隐私 → 麦克风
   - **Linux**: 检查用户是否在 audio 组中
     ```bash
     groups $USER
     # 如果没有 audio 组，添加用户
     sudo usermod -a -G audio $USER
     ```

3. 测试麦克风
   ```bash
   # macOS
   say "测试音频" && echo "如果听到声音，音频输出正常"
   
   # Linux
   arecord -d 3 test.wav && aplay test.wav
   ```

#### 问题：音频设备被占用

**错误信息**:
```
OSError: [Errno -9988] Stream callback result
Device is busy
```

**解决方案**:
1. 关闭其他音频应用
2. 重启音频服务
   ```bash
   # macOS
   sudo killall coreaudiod
   
   # Linux
   pulseaudio -k && pulseaudio --start
   ```

3. 检查进程占用
   ```bash
   lsof | grep audio
   ```

#### 问题：音频质量差

**现象**:
- 识别准确率低
- 大量识别错误
- 部分结果为空

**解决方案**:
1. 检查麦克风设置
   - 调整麦克风音量（建议70-80%）
   - 减少背景噪音
   - 保持适当距离（20-30cm）

2. 调整音频参数
   ```python
   # 在 src/config.py 中调整
   class AudioConfig:
       chunk_size = 2048  # 增加缓冲区大小
       samples_per_read = 3200  # 调整读取样本数
   ```

3. 环境优化
   - 选择安静环境
   - 避免回音
   - 使用外接麦克风（如果可能）

### 4. 识别相关问题

#### 问题：识别结果为空

**现象**:
```
[14:30:25] 
[14:30:28] 
```

**解决方案**:
1. 检查音频输入
   ```bash
   uv run python main.py --log-level DEBUG
   # 查看是否有音频数据输入
   ```

2. 调整端点检测参数
   ```python
   # 在 src/config.py 中调整
   class ModelConfig:
       rule1_min_trailing_silence = 1.0  # 减少静音检测时间
       rule2_min_trailing_silence = 0.5
       rule3_min_utterance_length = 100   # 减少最小语音长度
   ```

3. 测试语音清晰度
   - 说话清晰、语速适中
   - 避免方言或口音过重
   - 尝试标准普通话或英语

#### 问题：识别延迟过高

**现象**:
- 说话后几秒才显示结果
- 实时性差

**解决方案**:
1. 调整音频缓冲
   ```python
   # 减少缓冲区大小
   class AudioConfig:
       chunk_size = 512  # 减少延迟
       samples_per_read = 800
   ```

2. 优化系统性能
   - 关闭不必要的程序
   - 确保CPU使用率不过高
   - 使用SSD存储

3. 调整线程数
   ```python
   class ModelConfig:
       num_threads = 2  # 根据CPU核心数调整
   ```

#### 问题：中英文混合识别错误

**现象**:
- 英文单词识别为中文
- 中文识别为英文
- 混合语言断句错误

**解决方案**:
1. 确保使用中英双语模型
2. 调整断句处理
   ```python
   # 在语音识别器中
   self.enable_punctuation = True  # 启用断句处理
   ```

3. 语言切换提示
   - 在语言切换时稍作停顿
   - 避免频繁切换语言

### 5. 性能问题

#### 问题：内存使用过高

**现象**:
- 系统内存占用持续增长
- 程序运行缓慢
- 系统卡顿

**解决方案**:
1. 监控内存使用
   ```bash
   # 运行时监控
   top -p $(pgrep -f "python main.py")
   ```

2. 调整缓冲区大小
   ```python
   class AudioConfig:
       chunk_size = 1024  # 减少缓冲区
   ```

3. 定期清理
   ```python
   # 在识别器中添加清理逻辑
   def cleanup_memory(self):
       import gc
       gc.collect()
   ```

#### 问题：CPU使用率过高

**现象**:
- CPU使用率持续100%
- 系统风扇高速运转
- 其他程序响应缓慢

**解决方案**:
1. 调整线程数
   ```python
   class ModelConfig:
       num_threads = 1  # 减少线程数
   ```

2. 降低处理频率
   ```python
   class AudioConfig:
       samples_per_read = 3200  # 增加处理间隔
   ```

3. 使用性能分析
   ```bash
   uv run python -m cProfile main.py
   ```

### 6. 文件和权限问题

#### 问题：无法创建输出文件

**错误信息**:
```
PermissionError: [Errno 13] Permission denied: 'output/transcription.txt'
```

**解决方案**:
1. 检查目录权限
   ```bash
   ls -la output/
   chmod 755 output/
   ```

2. 创建输出目录
   ```bash
   mkdir -p output logs
   ```

3. 检查磁盘空间
   ```bash
   df -h .
   ```

#### 问题：日志文件过大

**现象**:
- logs/app.log 文件过大
- 磁盘空间不足

**解决方案**:
1. 配置日志轮转
   ```python
   import logging.handlers
   
   handler = logging.handlers.RotatingFileHandler(
       'logs/app.log', maxBytes=10*1024*1024, backupCount=5
   )
   ```

2. 清理旧日志
   ```bash
   find logs/ -name "*.log" -mtime +7 -delete
   ```

3. 调整日志级别
   ```bash
   uv run python main.py --log-level WARNING
   ```

### 7. 网络相关问题

#### 问题：模型下载网络错误

**错误信息**:
```
ConnectionError: HTTPSConnectionPool
SSL: CERTIFICATE_VERIFY_FAILED
```

**解决方案**:
1. 检查网络连接
2. 配置代理
   ```bash
   export https_proxy=http://proxy:port
   export http_proxy=http://proxy:port
   ```

3. 跳过SSL验证（不推荐）
   ```python
   import ssl
   ssl._create_default_https_context = ssl._create_unverified_context
   ```

### 8. 系统特定问题

#### macOS 特定问题

**问题：麦克风权限被拒绝**

**解决方案**:
1. 系统偏好设置 → 安全性与隐私 → 隐私 → 麦克风
2. 添加终端或Python到允许列表
3. 重启应用

**问题：Gatekeeper 阻止运行**

**解决方案**:
```bash
# 允许运行未签名的应用
sudo spctl --master-disable

# 或针对特定文件
xattr -d com.apple.quarantine /path/to/file
```

#### Linux 特定问题

**问题：ALSA 错误**

**错误信息**:
```
ALSA lib pcm_dmix.c:1032:(snd_pcm_dmix_open) unable to open slave
```

**解决方案**:
1. 安装ALSA工具
   ```bash
   sudo apt-get install alsa-utils
   ```

2. 配置音频
   ```bash
   alsamixer  # 调整音频设置
   ```

3. 重启音频服务
   ```bash
   sudo systemctl restart alsa-state
   ```

## 调试技巧

### 1. 启用详细日志

```bash
# 启用调试模式
uv run python main.py --log-level DEBUG

# 查看日志文件
tail -f logs/app.log
```

### 2. 测试音频输入

```python
# 创建测试脚本 test_audio.py
import pyaudio
import numpy as np

def test_audio():
    p = pyaudio.PyAudio()
    
    # 列出设备
    for i in range(p.get_device_count()):
        info = p.get_device_info_by_index(i)
        print(f"Device {i}: {info['name']}")
    
    # 测试录音
    stream = p.open(
        format=pyaudio.paInt16,
        channels=1,
        rate=16000,
        input=True,
        frames_per_buffer=1024
    )
    
    print("开始录音5秒...")
    frames = []
    for _ in range(int(16000 / 1024 * 5)):
        data = stream.read(1024)
        frames.append(np.frombuffer(data, dtype=np.int16))
    
    stream.stop_stream()
    stream.close()
    p.terminate()
    
    audio_data = np.concatenate(frames)
    print(f"录音完成，数据长度: {len(audio_data)}")
    print(f"音频范围: {audio_data.min()} 到 {audio_data.max()}")

if __name__ == "__main__":
    test_audio()
```

### 3. 性能监控

```python
# 创建性能监控脚本 monitor.py
import psutil
import time

def monitor_performance():
    process = psutil.Process()
    
    while True:
        cpu_percent = process.cpu_percent()
        memory_info = process.memory_info()
        memory_mb = memory_info.rss / 1024 / 1024
        
        print(f"CPU: {cpu_percent:.1f}%, 内存: {memory_mb:.1f}MB")
        time.sleep(1)

if __name__ == "__main__":
    monitor_performance()
```

## 获取帮助

### 1. 收集诊断信息

运行以下命令收集系统信息：

```bash
# 创建诊断脚本
cat > diagnose.py << 'EOF'
import sys
import platform
import subprocess

print("=== 系统信息 ===")
print(f"操作系统: {platform.system()} {platform.release()}")
print(f"Python版本: {sys.version}")
print(f"架构: {platform.machine()}")

print("\n=== Python包信息 ===")
try:
    result = subprocess.run(['uv', 'pip', 'list'], capture_output=True, text=True)
    print(result.stdout)
except:
    print("无法获取包信息")

print("\n=== 音频设备信息 ===")
try:
    import pyaudio
    p = pyaudio.PyAudio()
    for i in range(p.get_device_count()):
        info = p.get_device_info_by_index(i)
        print(f"设备 {i}: {info['name']} (输入通道: {info['maxInputChannels']})")
    p.terminate()
except Exception as e:
    print(f"音频设备检测失败: {e}")
EOF

python diagnose.py
```

### 2. 提交问题报告

在提交问题时，请包含：

1. 详细的错误信息
2. 系统诊断信息
3. 重现步骤
4. 预期行为
5. 实际行为
6. 相关日志文件

### 3. 社区支持

- 查看项目文档
- 搜索已知问题
- 提交 GitHub Issue
- 参与社区讨论

---

如果以上解决方案都无法解决您的问题，请收集详细的错误信息和系统诊断信息，然后提交问题报告。