realTimeVTT/docs/故障排除.md

故障排除指南

常见问题及解决方案

1. 安装和环境问题

问题：Python 版本不兼容

错误信息:

requires-python = ">=3.12.10" but the current Python version is 3.11.x

解决方案:

1. 升级 Python 到 3.12+

   # macOS 使用 Homebrew
   brew install python@3.12
   
   # 或使用 pyenv
   pyenv install 3.12.10
   pyenv local 3.12.10
   

2. 验证 Python 版本

   python --version
   # 应显示 Python 3.12.x
   

问题：uv 包管理器未安装

错误信息:

command not found: uv

解决方案:

# 安装 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:

# 安装 portaudio
brew install portaudio

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

Linux (Ubuntu/Debian):

# 安装系统依赖
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. 下载模型文件

   uv run python main.py --download-model
   

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

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

4. 验证模型文件

   ls -la models/
   # 应该看到 .onnx 和 tokens.txt 文件
   

问题：模型下载失败

错误信息:

下载失败: HTTP Error 404
网络连接超时

解决方案:

1. 检查网络连接

2. 使用代理（如果需要）

   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. 检查模型文件完整性

   # 检查文件大小，不应该为0
   ls -lh models/*.onnx
   

2. 重新下载模型

   rm -rf models/*.onnx
   uv run python main.py --download-model
   

3. 检查系统资源

   • 确保有足够内存（建议4GB+）
   • 检查磁盘空间

3. 音频设备问题

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

错误信息:

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

解决方案:

1. 检查音频设备

   uv run python main.py --list-devices
   

2. 确保麦克风权限

   • macOS: 系统偏好设置 → 安全性与隐私 → 麦克风
   • Linux: 检查用户是否在 audio 组中

     groups $USER
     # 如果没有 audio 组，添加用户
     sudo usermod -a -G audio $USER
     

3. 测试麦克风

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

问题：音频设备被占用

错误信息:

OSError: [Errno -9988] Stream callback result
Device is busy

解决方案:

1. 关闭其他音频应用

2. 重启音频服务

   # macOS
   sudo killall coreaudiod
   
   # Linux
   pulseaudio -k && pulseaudio --start
   

3. 检查进程占用

   lsof | grep audio
   

问题：音频质量差

现象:

• 识别准确率低
• 大量识别错误
• 部分结果为空

解决方案:

1. 检查麦克风设置

   • 调整麦克风音量（建议70-80%）
   • 减少背景噪音
   • 保持适当距离（20-30cm）

2. 调整音频参数

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

3. 环境优化

   • 选择安静环境
   • 避免回音
   • 使用外接麦克风（如果可能）

4. 识别相关问题

问题：识别结果为空

现象:

[14:30:25] 
[14:30:28] 

解决方案:

1. 检查音频输入

   uv run python main.py --log-level DEBUG
   # 查看是否有音频数据输入
   

2. 调整端点检测参数

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

3. 测试语音清晰度

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

问题：识别延迟过高

现象:

• 说话后几秒才显示结果
• 实时性差

解决方案:

1. 调整音频缓冲

   # 减少缓冲区大小
   class AudioConfig:
       chunk_size = 512  # 减少延迟
       samples_per_read = 800
   

2. 优化系统性能

   • 关闭不必要的程序
   • 确保CPU使用率不过高
   • 使用SSD存储

3. 调整线程数

   class ModelConfig:
       num_threads = 2  # 根据CPU核心数调整
   

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

现象:

• 英文单词识别为中文
• 中文识别为英文
• 混合语言断句错误

解决方案:

1. 确保使用中英双语模型

2. 调整断句处理

   # 在语音识别器中
   self.enable_punctuation = True  # 启用断句处理
   

3. 语言切换提示

   • 在语言切换时稍作停顿
   • 避免频繁切换语言

5. 性能问题

问题：内存使用过高

现象:

• 系统内存占用持续增长
• 程序运行缓慢
• 系统卡顿

解决方案:

1. 监控内存使用

   # 运行时监控
   top -p $(pgrep -f "python main.py")
   

2. 调整缓冲区大小

   class AudioConfig:
       chunk_size = 1024  # 减少缓冲区
   

3. 定期清理

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

问题：CPU使用率过高

现象:

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

解决方案:

1. 调整线程数

   class ModelConfig:
       num_threads = 1  # 减少线程数
   

2. 降低处理频率

   class AudioConfig:
       samples_per_read = 3200  # 增加处理间隔
   

3. 使用性能分析

   uv run python -m cProfile main.py
   

6. 文件和权限问题

问题：无法创建输出文件

错误信息:

PermissionError: [Errno 13] Permission denied: 'output/transcription.txt'

解决方案:

1. 检查目录权限

   ls -la output/
   chmod 755 output/
   

2. 创建输出目录

   mkdir -p output logs
   

3. 检查磁盘空间

   df -h .
   

问题：日志文件过大

现象:

• logs/app.log 文件过大
• 磁盘空间不足

解决方案:

1. 配置日志轮转

   import logging.handlers
   
   handler = logging.handlers.RotatingFileHandler(
       'logs/app.log', maxBytes=10*1024*1024, backupCount=5
   )
   

2. 清理旧日志

   find logs/ -name "*.log" -mtime +7 -delete
   

3. 调整日志级别

   uv run python main.py --log-level WARNING
   

7. 网络相关问题

问题：模型下载网络错误

错误信息:

ConnectionError: HTTPSConnectionPool
SSL: CERTIFICATE_VERIFY_FAILED

解决方案:

1. 检查网络连接

2. 配置代理

   export https_proxy=http://proxy:port
   export http_proxy=http://proxy:port
   

3. 跳过SSL验证（不推荐）

   import ssl
   ssl._create_default_https_context = ssl._create_unverified_context
   

8. 系统特定问题

macOS 特定问题

问题：麦克风权限被拒绝

解决方案:

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

问题：Gatekeeper 阻止运行

解决方案:

# 允许运行未签名的应用
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工具

   sudo apt-get install alsa-utils
   

2. 配置音频

   alsamixer  # 调整音频设置
   

3. 重启音频服务

   sudo systemctl restart alsa-state
   

调试技巧

1. 启用详细日志

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

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

2. 测试音频输入

# 创建测试脚本 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. 性能监控

# 创建性能监控脚本 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. 收集诊断信息

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

# 创建诊断脚本
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
• 参与社区讨论

---

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