test/scripts/README.md

355 lines
9.5 KiB
Markdown
Raw Normal View History

2026-09-28 09:00:53 +00:00
# 脚本说明
## 环境同步脚本
## 厂商 GPU 镜像融合打包
NVIDIA 镜像由项目 `Dockerfile.gpu` 完整构建;沐曦、天数、摩尔线程等国产 GPU 推荐先导入厂商官方 vLLM 镜像,再把本项目注入进去生成融合镜像:
```bash
docker load -i metax-vllm-official.tar
docker images | grep -i -E 'metax|maca|vllm'
./scripts/package_vendor_gpu_image.sh \
--vendor metax \
--base-image <沐曦官方vLLM镜像名> \
-v n260-3.7.0.38
docker pull registry.iluvatar.com.cn:10443/customer/sz/vllm0.17.0-4.4.0-x86:v5
./scripts/package_vendor_gpu_image.sh \
--vendor iluvatar \
--base-image registry.iluvatar.com.cn:10443/customer/sz/vllm0.17.0-4.4.0-x86:v5 \
-v vllm0.17.0-4.4.0-v5
docker pull registry.mthreads.com/presale/devtech/vllm_musa:s4000_4.3.5_d0519
./scripts/package_vendor_gpu_image.sh \
--vendor mthreads \
--base-image registry.mthreads.com/presale/devtech/vllm_musa:s4000_4.3.5_d0519 \
-v s4000_4.3.5_d0519
```
沐曦 GPU 的离线交付流程见 `docs/metax_offline_deployment.md`。
天数 GPU 的离线交付流程见 `docs/iluvatar_offline_deployment.md`。
摩尔线程 GPU 的离线交付流程见 `docs/mthreads_offline_deployment.md`。
输出形如:
```text
build-file/qwen3-asr-metax-n260-3.7.0.38-amd64.tar.gz
```
这个压缩包就是可交付给客户的融合镜像。
| 脚本 | 说明 |
|------|------|
| `./scripts/sync_gpu_env.sh` | 同步根目录 NVIDIA CUDA/vLLM 环境 |
| `./scripts/sync_metax_env.sh` | 同步沐曦 MACA 环境;公共依赖来自 `environments/metax`,可选 GPU 栈默认按 `--no-deps` 从沐曦 PyPI 源安装 |
| `./scripts/sync_iluvatar_env.sh` | 同步天数环境公共依赖;GPU 栈使用天数官方 vLLM 镜像或匹配安装包 |
| `./scripts/sync_mthreads_env.sh` | 同步摩尔线程环境公共依赖;GPU 栈使用摩尔线程官方 MUSA vLLM 镜像或匹配安装包 |
| `./scripts/sync_cpu_env.sh` | 同步 CPU Rust 环境 |
| `./scripts/sync_accel_env.sh` | 自动识别 `mx-smi` / `ixsmi` / `mthreads-gmi` / `nvidia-smi` 并调用对应同步脚本 |
沐曦包版本可通过环境变量覆盖:
```bash
METAX_TORCH_SPEC='torch==x.y.z' \
METAX_TORCHAUDIO_SPEC='torchaudio==x.y.z' \
METAX_TORCHVISION_SPEC='torchvision==x.y.z' \
METAX_VLLM_SPEC='vllm==x.y.z' \
./scripts/sync_metax_env.sh
```
沐曦 GPU 栈默认使用 `--no-deps` 且只访问沐曦 PyPI 源,避免回退到 PyPI 后拉取 NVIDIA CUDA 包。
只有确认沐曦源中包含完整 GPU 栈依赖时,才设置:
```bash
METAX_INSTALL_GPU_DEPS=true ./scripts/sync_metax_env.sh
```
查看沐曦源中的包版本:
```bash
./scripts/sync_metax_env.sh --list-versions torch
```
## RMS 音频分析工具
用于分析音频文件的 RMS 能量时序,帮助确定远场声音过滤的最佳阈值。
## 功能特性
- ✅ 支持多种音频格式 (WAV, MP3, FLAC 等)
- ✅ 支持立体声、左声道、右声道选择
- ✅ 生成 RMS 时序图和分布直方图
- ✅ 详细的统计分析和阈值建议
- ✅ 可自定义分块大小(默认 240ms,与流式 ASR 一致)
## 安装依赖
```bash
./scripts/sync_cpu_env.sh
```
## 使用方法
### 基础用法
```bash
# 分析立体声音频(默认)
.venv/bin/python scripts/analyze_audio_rms.py audio.wav
# 仅分析左声道
.venv/bin/python scripts/analyze_audio_rms.py audio.wav --channel left
# 仅分析右声道
.venv/bin/python scripts/analyze_audio_rms.py audio.wav --channel right
```
### 高级用法
```bash
# 自定义阈值
.venv/bin/python scripts/analyze_audio_rms.py audio.wav --threshold 0.015
# 自定义分块大小(例如 160ms)
.venv/bin/python scripts/analyze_audio_rms.py audio.wav --chunk-size 160
# 保存图表到文件
.venv/bin/python scripts/analyze_audio_rms.py audio.wav --output analysis.png
# 仅输出统计信息,不显示图表
.venv/bin/python scripts/analyze_audio_rms.py audio.wav --no-plot
```
### 完整示例
```bash
# 分析右声道,使用 0.015 阈值,保存图表
.venv/bin/python scripts/analyze_audio_rms.py recording.wav \
--channel right \
--threshold 0.015 \
--output rms_analysis.png
```
## 参数说明
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `audio_file` | 必需 | - | 音频文件路径 |
| `--channel` | 可选 | `stereo` | 声道选择: `stereo`, `left`, `right` |
| `--threshold` | 可选 | `0.01` | RMS 能量阈值 |
| `--chunk-size` | 可选 | `240` | 分块大小(毫秒) |
| `--output` | 可选 | - | 保存图表的路径 |
| `--no-plot` | 标志 | - | 不显示图表,仅输出统计 |
## 输出说明
### 统计信息
脚本会输出以下统计信息:
1. **基础统计**
- 最小值、最大值、平均值、中位数、标准差
2. **百分位数**
- P10, P25, P50, P75, P90, P95, P99
3. **阈值分析**
- 超过/低于阈值的帧数和百分比
4. **建议的阈值**
- 保守模式(高灵敏度):P10
- 宽松模式(推荐):P25
- 严格模式(低误触):平均值的 50%
### 可视化图表
生成两个图表:
1. **RMS 时序图**
- 显示整个音频的 RMS 能量变化
- 绿色区域:近场音频(>= 阈值)
- 红色区域:远场音频(< 阈值)
- 红色虚线:当前阈值
2. **RMS 分布直方图**
- 显示 RMS 值的分布情况
- 红色虚线:当前阈值
- 橙色虚线:平均值
- 绿色虚线:中位数
## 使用场景
### 1. 确定初始阈值
录制一段包含近场说话和远场环境音的测试音频,然后:
```bash
.venv/bin/python scripts/analyze_audio_rms.py test_audio.wav
```
查看**建议的阈值**,选择合适的模式。
### 2. 对比不同声道
如果使用立体声麦克风,可以对比左右声道:
```bash
.venv/bin/python scripts/analyze_audio_rms.py audio.wav --channel left --output left.png
.venv/bin/python scripts/analyze_audio_rms.py audio.wav --channel right --output right.png
```
### 3. 验证阈值效果
使用自定义阈值查看过滤效果:
```bash
# 测试宽松模式
.venv/bin/python scripts/analyze_audio_rms.py audio.wav --threshold 0.01
# 测试严格模式
.venv/bin/python scripts/analyze_audio_rms.py audio.wav --threshold 0.015
# 测试保守模式
.venv/bin/python scripts/analyze_audio_rms.py audio.wav --threshold 0.005
```
### 4. 批量分析
如需批量分析多个文件,可以使用简单的循环:
```bash
#!/bin/bash
for file in recordings/*.wav; do
echo "Analyzing: $file"
.venv/bin/python scripts/analyze_audio_rms.py "$file" \
--threshold 0.01 \
--no-plot \
--output "analysis/$(basename "$file" .wav).png"
done
```
## 输出示例
```
==============================================================
音频 RMS 时序分析工具
==============================================================
📁 文件: test_audio.wav
🎚️ 声道: stereo
📊 分块大小: 240ms
🎯 阈值: 0.010000
正在加载音频...
✓ 使用立体声(双声道平均)
✓ 采样率: 16000 Hz
✓ 时长: 30.50 秒
✓ 样本数: 488000
正在分析 RMS 时序 (分块大小: 240ms)...
✓ 分析了 127 个音频块
==============================================================
RMS 统计分析
==============================================================
📊 基础统计:
- 最小值: 0.000234
- 最大值: 0.085432
- 平均值: 0.012567
- 中位数: 0.009234
- 标准差: 0.015678
📈 百分位数:
- P10: 0.002345
- P25: 0.005678
- P50: 0.009234
- P75: 0.015432
- P90: 0.035678
- P95: 0.045678
- P99: 0.075432
🎯 阈值分析 (当前阈值: 0.010000):
- 超过阈值的帧数: 65 (51.2%)
- 低于阈值的帧数: 62 (48.8%)
💡 建议的阈值范围:
- 保守模式 (高灵敏度): 0.002345 (P10)
- 宽松模式 (推荐): 0.005678 (P25)
- 严格模式 (低误触): 0.006284 (平均值的50%)
==============================================================
```
## 调优建议
1. **录制测试音频**
- 包含正常说话(近场)
- 包含远处说话或电视声音(远场)
- 包含安静时刻(环境音)
2. **分析并选择阈值**
- 查看时序图,观察近场和远场的 RMS 差异
- 查看分布直方图,找到明显的分界点
- 参考建议的阈值范围
3. **验证效果**
- 在实际应用中测试选定的阈值
- 如果误触发过多,提高阈值
- 如果正常说话被过滤,降低阈值
4. **微调**
- 宽松模式(0.01)适合大多数场景
- 嘈杂环境使用严格模式(0.015)
- 安静环境使用保守模式(0.005)
## 故障排查
### 问题:无法加载音频文件
```bash
# 安装必要的库
./scripts/sync_cpu_env.sh
# 对于 MP3 文件,可能还需要
./scripts/sync_cpu_env.sh
```
### 问题:中文显示乱码
脚本已配置中文字体,但如果仍然显示乱码:
1. macOS: 会自动使用 'Arial Unicode MS'
2. Windows: 会自动使用 'SimHei'
3. Linux: 需要安装中文字体
### 问题:图表不显示
```bash
# 后台运行或 SSH 连接时使用
python scripts/analyze_audio_rms.py audio.wav --no-plot --output analysis.png
```
## 与远场过滤功能的关系
此工具使用与 `app/utils/audio_filter.py` 相同的 RMS 计算方法,确保分析结果与实际运行时的行为一致。
确定阈值后,在配置文件中设置:
```bash
# docker-compose.yml
environment:
- ASR_NEARFIELD_RMS_THRESHOLD=0.01 # 使用分析得出的阈值
```
或在 `.env` 文件中:
```bash
ASR_NEARFIELD_RMS_THRESHOLD=0.01
```
## 相关文档
- [远场过滤功能文档](../docs/nearfield_filter.md)
- [部署配置指南](../docs/deployment.md)