SpeechRecognition/test/real/README_故障排查.md

端到端测试故障排查指南

⚠️ 测试卡住的常见原因

1. 首次运行下载模型（最常见）

症状：CPU 占用不高，测试长时间无响应

原因：

• FunASR 模型首次运行需要下载（约 1-2GB）
• 下载速度取决于网络
• 下载过程中测试会卡住等待模型加载

解决方案：

# 手动预下载模型
python -c "from app.asr.asr_service import ASRService; ASRService()"

或等待 10-30 分钟（取决于网络）

---

2. 模型加载缓慢

症状：CPU 占用低，内存占用逐渐上升

原因：

• ASR 模型很大（Paraformer 约 200MB+）
• CPU 加载模型需要时间（30 秒 -2 分钟）
• 首次加载会初始化多个组件

解决方案：

• 耐心等待首次加载
• 后续测试会快很多（模型已缓存）
• 使用 GPU 可加速（如果有）

---

3. 音频/视频文件过大

症状：处理时间超长

原因：

• 长音频处理时间与长度成正比
• 1 分钟音频 ≈ 10-30 秒处理时间（CPU）
• 视频需要先提取音频

解决方案：

# 在 test_config.yaml 中使用较小的测试文件
test_files:
  primary_video: "input/short.AVI"  # 使用短文件

---

4. pytest-timeout 未安装

症状：测试卡住后不会自动超时

解决方案：

pip install pytest-timeout

---

🔍 快速诊断命令

检查测试环境

python test/real/check_e2e.py

运行最简单的测试（不卡）

# 只运行文件验证测试（立即完成）
pytest test/real/test_real_e2e.py::TestVideoFileValidation -v

# 只运行错误处理测试（不依赖 ASR）
pytest test/real/test_real_e2e.py::TestErrorHandling -v

运行单个 ASR 测试（带详细输出）

# -s 显示 print 输出，便于观察进度
pytest test/real/test_real_e2e.py::TestASRRecognition::test_recognize_audio_file -v -s --timeout=600

查看模型缓存

# 检查模型是否已下载
dir app\asr /s /b | findstr ".pt"

---

🚀 推荐的测试流程

第一步：预下载模型（重要！）

# 在运行测试前，先手动加载一次模型
python -c "from app.asr.asr_service import ASRService; s = ASRService(); print('模型加载完成')"

第二步：运行快速验证测试

# 验证测试环境正常
pytest test/real/test_real_e2e.py::TestVideoFileValidation -v
pytest test/real/test_real_e2e.py::TestAudioFileValidation -v
pytest test/real/test_real_e2e.py::TestErrorHandling -v

第三步：运行单个 ASR 测试

# 使用短音频文件测试
pytest test/real/test_real_e2e.py::TestASRRecognition::test_recognize_audio_file -v -s

第四步：运行完整测试

# 所有端到端测试
pytest test/real/ -v -s --timeout=600

---

📊 预期处理时间参考

测试类型	文件大小	CPU 时间	GPU 时间
文件验证	-	<1 秒	<1 秒
错误处理	-	<1 秒	<1 秒
ASR 识别（短音频）	10MB	30-60 秒	10-20 秒
ASR 识别（长音频）	50MB	2-5 分钟	30-60 秒
视频转码	100MB	1-3 分钟	30-60 秒

---

💡 优化建议

1. 使用更小的测试文件

# test_config.yaml
test_files:
  primary_video: "input/short.AVI"  # 使用短文件

2. 跳过慢速测试

# 只运行快速测试
pytest test/real/ -v -m "not slow"

3. 并行测试（如果多个文件）

pip install pytest-xdist
pytest test/real/ -v -n 4  # 4 个进程并行

4. 使用 GPU（如果有）

# 在 asr_service.py 中
service = ASRService(device='cuda')

---

🆘 仍然卡住怎么办？

方法 1：查看堆栈跟踪

按 Ctrl+C 中断测试，查看卡在哪里

方法 2：增加超时时间

pytest test/real/ -v --timeout=1200  # 20 分钟超时

方法 3：使用更短的测试文件

# 修改 test_config.yaml
primary_video: "input/short.AVI"

方法 4：检查日志

# 查看详细输出
pytest test/real/ -v -s 2>&1 | tee test.log

---

✅ 正常测试的标志

1. 首次运行：

   • 模型下载：10-30 分钟（网络依赖）
   • 模型加载：30 秒 -2 分钟
   • 后续运行：快 10 倍

2. 处理过程：

   • CPU 占用：50-100%（正常推理）
   • 内存占用：2-4GB（模型加载）
   • 磁盘 IO：中等（读写临时文件）

3. 完成标志：

   • 看到 ✓ 标记
   • 显示处理时间
   • 生成结果文件

---

📝 测试输出示例

test/real/test_real_e2e.py::TestASRRecognition::test_recognize_audio_file

使用测试音频：VID_20251031_132320_019_mono.wav (5.23 MB)

开始测试音频识别：VID_20251031_132320_019_mono.wav
音频识别耗时：45.32 秒
✓ 音频识别成功，task_id: abc123...

PASSED [100%]

---

🔗 相关文档

• 测试配置文件 - 修改测试文件路径
• 测试代码 - 查看测试逻辑
• pytest 文档 - pytest 使用