examples/README.md

示例和使用教程

本目录包含了情绪与生理状态变化预测模型的完整示例和使用教程，帮助用户快速上手使用项目。

目录结构

examples/
├── README.md                    # 本文件 - 示例目录说明
├── sample_data.json            # JSON格式示例数据
├── sample_data.csv             # CSV格式示例数据
├── quick_start.py              # 快速开始教程
├── training_tutorial.py        # 详细训练教程
├── inference_tutorial.py       # 推理教程
├── data/                       # 教程生成的数据目录
├── models/                     # 教程生成的模型目录
├── training_outputs/           # 训练教程输出目录
└── inference_outputs/          # 推理教程输出目录

文件说明

示例数据文件

sample_data.json

• 格式: JSON格式，包含10个样本的完整数据
• 内容: 每个样本包含7维输入特征和5维输出标签
• 用途: 用于快速测试和演示模型功能

sample_data.csv

• 格式: CSV格式，包含20个样本的完整数据
• 内容: 包含表头，便于批量处理和数据分析
• 用途: 用于批量测试和数据分析

教程脚本

quick_start.py - 快速开始教程

目的: 为新用户提供最简单的上手体验

功能:

• 生成合成训练数据
• 训练基础模型
• 进行推理预测
• 解释预测结果

运行方式:

cd examples
python quick_start.py

输出:

• examples/data/training_data.csv - 训练数据
• examples/models/quick_start_model.pth - 训练好的模型
• examples/models/quick_start_preprocessor.pkl - 数据预处理器

training_tutorial.py - 详细训练教程

目的: 深入演示模型训练的完整流程

功能:

• 数据准备和探索性分析
• 数据预处理和特征工程
• 模型配置和架构选择
• 训练过程监控和可视化
• 模型评估和验证
• 超参数调优示例

运行方式:

cd examples
python training_tutorial.py

输出:

• examples/training_outputs/ - 训练过程的所有输出文件
  • train_data.csv, val_data.csv, test_data.csv - 数据分割
  • feature_distribution.png - 特征分布图
  • label_distribution.png - 标签分布图
  • correlation_heatmap.png - 相关性热力图
  • training_curves.png - 训练曲线
  • prediction_visualization.png - 预测结果可视化
  • preprocessor.pkl - 数据预处理器
  • best_model.pth - 最佳训练模型
  • training_history.json - 训练历史记录
  • evaluation_results.json - 评估结果
  • hyperparameter_tuning.json - 超参数调优结果

inference_tutorial.py - 推理教程

目的: 全面演示模型推理的各种方法和技巧

功能:

• 单样本推理
• 批量推理
• 不同输入格式处理（列表、NumPy数组、字典、JSON、CSV）
• 结果解释和可视化
• 性能优化和基准测试
• 实际应用场景演示

运行方式:

cd examples
python inference_tutorial.py

输出:

• examples/inference_outputs/ - 推理过程的所有输出文件
  • single_inference_results.json - 单样本推理结果
  • batch_inference_results.json - 批量推理结果
  • prediction_distributions.png - 预测分布对比图
  • test_input.json, test_input.csv - 测试输入文件
  • result_interpretations.json - 结果解释
  • performance_optimization.json - 性能优化结果
  • real_world_scenarios.json - 实际应用场景结果

数据格式说明

输入特征（7维）

1. user_pleasure (float, [-1, 1]) - 用户快乐度
2. user_arousal (float, [-1, 1]) - 用户激活度
3. user_dominance (float, [-1, 1]) - 用户支配度
4. vitality (float, [0, 100]) - 活力水平
5. current_pleasure (float, [-1, 1]) - 当前快乐度
6. current_arousal (float, [-1, 1]) - 当前激活度
7. current_dominance (float, [-1, 1]) - 当前支配度

输出标签（5维）

1. delta_pleasure (float, [-0.5, 0.5]) - 快乐度变化量
2. delta_arousal (float, [-0.5, 0.5]) - 激活度变化量
3. delta_dominance (float, [-0.5, 0.5]) - 支配度变化量
4. delta_pressure (float, [-0.3, 0.3]) - 压力变化量
5. confidence (float, [0, 1]) - 预测置信度

使用建议

初学者

1. 从 quick_start.py 开始，了解基本流程
2. 查看 sample_data.json 了解数据格式
3. 运行 inference_tutorial.py 学习推理方法

进阶用户

1. 运行 training_tutorial.py 学习完整训练流程
2. 修改配置文件进行自定义训练
3. 使用 inference_tutorial.py 中的性能优化技巧

开发者

1. 参考教程代码集成到自己的项目
2. 使用提供的工具函数进行数据处理
3. 根据实际需求调整模型架构

常见问题

Q: 如何使用自己的数据？

A: 参考 training_tutorial.py 中的数据预处理部分，确保数据格式符合要求。

Q: 如何调整模型架构？

A: 修改 configs/model_config.yaml 中的网络架构参数，或直接在代码中修改 PADPredictor 的初始化参数。

Q: 如何提高预测精度？

A: 参考 training_tutorial.py 中的超参数调优部分，尝试不同的学习率、批次大小等参数。

Q: 如何进行批量推理？

A: 使用 inference_tutorial.py 中演示的 predict_batch 方法。

Q: 如何解释预测结果？

A: 参考 inference_tutorial.py 中的结果解释函数，了解各项指标的含义。

依赖要求

运行教程脚本需要安装以下依赖：

• Python 3.8+
• PyTorch
• NumPy
• Pandas
• Matplotlib
• Seaborn
• scikit-learn
• loguru
• PyYAML

安装命令：

pip install torch numpy pandas matplotlib seaborn scikit-learn loguru pyyaml

联系方式

如有问题或建议，请通过以下方式联系：

• 项目仓库: [GitHub仓库链接]
• 问题反馈: [Issues链接]
• 文档: [文档链接]

---

注意: 这些教程和示例主要用于学习和演示目的。在实际生产环境中使用时，请根据具体需求进行调整和优化。