Skip to content

testing_guide.md

Latest commit

 

History

History
400 lines (287 loc) · 9.24 KB

testing_guide.md

File metadata and controls

400 lines (287 loc) · 9.24 KB

Cross-Modal Project Testing Guide

本文档提供项目中所有测试脚本的使用指南和参数说明。

目录

1. 3D模型测试 (test_models_3d.py)

1.1 测试概述

位置: tests/test_models_3d.py

测试覆盖:

  • A. 模型初始化和前向传播
  • B. 动态输出尺寸适配
  • C. 批处理功能
  • D. 模型保存/加载
  • E. 与3D数据集集成
  • F. 损失函数计算
  • G. GPU/CPU兼容性
  • H. 训练冒烟测试（可选）

1.2 基础测试命令

1.2.1 标准测试（不含训练）

运行测试 A-G，验证模型基础功能：

uv run python tests/test_models_3d.py

预期输出:

  • ✅ 所有基础测试通过
  • 生成前向传播可视化：images/test_3d_models_forward_pass.png

1.3 训练冒烟测试

1.3.1 快速验证（推荐首次测试）

用途: 快速验证训练流程是否正常（约 1 分钟）

uv run python tests/test_models_3d.py --train-smoke --epochs 2 --n-train 8 --n-val 2

参数说明:

  • --train-smoke: 启用训练冒烟测试
  • --epochs 2: 仅训练 2 轮
  • --n-train 8: 使用 8 个训练样本
  • --n-val 2: 使用 2 个验证样本

1.3.2 标准测试（默认配置）

用途: 标准训练冒烟测试（约 3-5 分钟）

# OperatorMapper3D 模型（默认）
uv run python tests/test_models_3d.py --train-smoke

# LSTMMapper3D 模型
uv run python tests/test_models_3d.py --train-smoke --model lstm

默认参数:

  • 模型: OperatorMapper3D
  • 训练轮数: 5 epochs
  • 批次大小: 4
  • 学习率: 1e-4
  • 训练样本: 32
  • 验证样本: 8
  • 图像尺寸: 64x64

输出文件:

  • results/smoke_test_operator_trained.png (OperatorMapper3D)
  • results/smoke_test_lstm_trained.png (LSTMMapper3D)

1.3.3 高分辨率测试

用途: 测试大尺寸图像生成能力

uv run python tests/test_models_3d.py --train-smoke \
    --img-size 128 \
    --nx 31 \
    --ny 31 \
    --sig-len 800 \
    --epochs 10

参数说明:

  • --img-size 128: 输出 128x128 图像
  • --nx 31: 空间维度 X = 31
  • --ny 31: 空间维度 Y = 31
  • --sig-len 800: 时间序列长度 = 800

1.3.4 GPU 加速测试

用途: 利用 GPU 加速训练（需要 CUDA）

uv run python tests/test_models_3d.py --train-smoke \
    --device cuda \
    --batch-size 16 \
    --epochs 20 \
    --n-train 128 \
    --n-val 32

参数说明:

  • --device cuda: 强制使用 GPU
  • --batch-size 16: 增大批次（GPU 内存允许）
  • --n-train 128: 更多训练样本

1.4 完整参数列表

参数 类型 默认值 说明
--train-smoke flag False 启用训练冒烟测试
--model str operator 模型类型: operator 或 lstm
--epochs int 5 训练轮数
--batch-size int 4 批次大小
--lr float 1e-4 学习率
--nx int 21 空间维度 X
--ny int 21 空间维度 Y
--sig-len int 500 时间序列长度
--img-size int 64 输出图像尺寸
--n-train int 32 训练样本数
--n-val int 8 验证样本数
--device str auto 设备: cuda/cpu/auto

1.5 推荐测试场景

场景 1: 快速验证（~1分钟）

uv run python tests/test_models_3d.py --train-smoke --epochs 2 --n-train 8 --n-val 2

场景 2: 标准功能测试（~3-5分钟）

uv run python tests/test_models_3d.py --train-smoke

场景 3: LSTM vs Operator 对比

# OperatorMapper3D
uv run python tests/test_models_3d.py --train-smoke --model operator --epochs 10

# LSTMMapper3D
uv run python tests/test_models_3d.py --train-smoke --model lstm --epochs 10

场景 4: 完整功能测试（~10分钟）

uv run python tests/test_models_3d.py --train-smoke \
    --epochs 20 \
    --batch-size 8 \
    --n-train 128 \
    --n-val 32 \
    --img-size 128

2. 3D数据集测试 (test_dataset.py)

2.1 测试概述

位置: tests/test_dataset.py

测试覆盖:

  • 3D 数据集基础功能
  • 3D 频谱图转换
  • 完整可视化（9 个子图）

2.2 运行测试

uv run python tests/test_dataset.py

2.3 输出说明

控制台输出:

  • ✅ Test 1: 3D Dataset Basic Functionality
  • ✅ Test 2: 3D Spectrogram Transform
  • ✅ Visualization: 3D Dataset Complete Analysis

生成文件:

  • images/dataset_3d_visualization.png

可视化内容（3x3 网格）:

  1. a) 时域信号: 中心点的时间序列
  2. b) 空间分布: 某时刻的 2D 空间快照（4x 插值）
  3. b2) 3D 空间: 3D 曲面可视化
  4. c1) 频谱图: 单点 STFT 频谱
  5. c2) 频谱能量: 平均频谱能量空间分布（4x 插值）
  6. c3) 主频分布: 主导频率空间分布
  7. d1) 缺陷标签: 2D 缺陷图像
  8. d2) 3D 缺陷: 3D 缺陷分布曲面
  9. d3) 叠加分析: 频谱能量 + 缺陷轮廓叠加

3. Legacy模型测试 (test_models.py)

3.1 测试概述

位置: src/cross_modal/legacy/test_models.py

测试覆盖:

  • BaseModel 接口
  • LSTMMapper 功能
  • OperatorMapper 功能
  • 损失函数（Dice, Combined, BCE）
  • 向后兼容性

3.2 运行测试

uv run python src/cross_modal/legacy/test_models.py

3.3 测试详情

测试项目:

  1. ✅ LSTM映射器: 前向传播、参数统计
  2. ✅ 算子映射器: 低秩分解、正则化
  3. ✅ Dice损失: 损失值范围、完美预测
  4. ✅ 组合损失: BCE + Dice 加权组合
  5. ✅ 损失函数工厂: 动态创建损失函数
  6. ✅ 向后兼容性: 接口一致性验证

4. 常见问题

4.1 导入错误

问题: ImportError: cannot import name 'XXX'

解决方案:

  1. 检查 __init__.py 是否正确导出类
  2. 验证导入路径是否正确
  3. 确保已安装项目依赖：uv sync

4.2 CUDA 相关错误

问题: RuntimeError: CUDA out of memory

解决方案:

# 减小批次大小
uv run python tests/test_models_3d.py --train-smoke --batch-size 2

# 或使用 CPU
uv run python tests/test_models_3d.py --train-smoke --device cpu

4.3 可视化不显示

问题: plt.show() 不显示图像

解决方案:

  • 测试脚本使用 matplotlib.use('Agg') 后端
  • 图像自动保存到 images/ 和 results/ 目录
  • 直接查看保存的 PNG 文件即可

4.4 训练时间过长

问题: 训练冒烟测试耗时超出预期

解决方案:

# 使用最小配置
uv run python tests/test_models_3d.py --train-smoke \
    --epochs 2 \
    --batch-size 2 \
    --n-train 4 \
    --n-val 2 \
    --nx 11 \
    --ny 11 \
    --sig-len 300 \
    --img-size 32

4.5 参数验证失败

问题: 模型保存/加载后输出不一致

解决方案:

  • 测试已使用 model.eval() + torch.no_grad()
  • 容差设置为 atol=1e-5, rtol=1e-4
  • 如仍失败，检查 Dropout 是否正确关闭

5. 测试流程建议

5.1 首次测试

# 1. 测试数据集
uv run python tests/test_dataset.py

# 2. 测试基础模型功能
uv run python tests/test_models_3d.py

# 3. 快速训练验证
uv run python tests/test_models_3d.py --train-smoke --epochs 2 --n-train 8

5.2 日常开发测试

# 标准训练测试
uv run python tests/test_models_3d.py --train-smoke

5.3 发布前完整测试

# 1. Legacy 模型测试
uv run python src/cross_modal/legacy/test_models.py

# 2. 数据集测试
uv run python tests/test_dataset.py

# 3. 3D 模型完整测试（两种模型）
uv run python tests/test_models_3d.py --train-smoke --model operator --epochs 20
uv run python tests/test_models_3d.py --train-smoke --model lstm --epochs 20

6. 输出文件位置

文件类型 路径 说明
数据集可视化 images/dataset_3d_visualization.png 3D 数据集 9 宫格分析
前向传播测试 images/test_3d_models_forward_pass.png 未训练模型前向传播
训练结果 (Operator) results/smoke_test_operator_trained.png OperatorMapper3D 训练后预测
训练结果 (LSTM) results/smoke_test_lstm_trained.png LSTMMapper3D 训练后预测
训练日志 results/*.log 训练过程日志
模型检查点 results/*.pth 训练后的模型权重

7. 性能参考

硬件环境: 标准配置（CPU: i7, GPU: RTX 3060, RAM: 16GB）

测试场景 CPU 时间 GPU 时间 内存占用
基础测试（A-G） ~30秒 ~15秒 ~2GB
快速冒烟（2 epochs） ~1分钟 ~30秒 ~3GB
标准冒烟（5 epochs） ~3-5分钟 ~1-2分钟 ~4GB
完整测试（20 epochs） ~10-15分钟 ~3-5分钟 ~6GB

8. 更新日志

  • 2024-01-XX: 初始版本，包含 3D 模型和数据集测试指南
  • 2024-01-XX: 添加训练冒烟测试参数说明
  • 2024-01-XX: 补充常见问题和性能参考

维护者: Cross-Modal Project Team
最后更新: 2024-01-XX