186 lines
12 KiB
Markdown
186 lines
12 KiB
Markdown
# 复杂场景下多模态情感识别：独立运行项目
|
||
|
||
本目录包含题目 Q1、Q2、Q3 所需的模型、数据适配、训练、验证、推理、解释和实验记录代码。运行代码只依赖本目录；官方原始附件、预训练模型权重和 OpenFace 可执行程序需按下文准备，未复制进项目。
|
||
|
||
## 目录
|
||
|
||
| 路径 | 内容 |
|
||
|---|---|
|
||
| `adapter/` | 统一多模态对齐接口；区分真实时间对齐与未对齐序列的相对进程投影 |
|
||
| `model/` | 每个数学模型与保留的深度学习模型各自独立的定义文件 |
|
||
| `q1/` | Q1 原生特征提取、物理时间特征包构建、五折对照和可视化 |
|
||
| `q2/math/` | 数学方案 C0–C7、训练、缺失控制评估及附件 3 预测 |
|
||
| `q2/deep_learning/q2/` | EarlyConcat + BiGRU、MoFE-7 + MLP Router 及训练协议 |
|
||
| `q3/` | Q3 训练、验证、附件 4 全量预测和逐样本解释卡片 |
|
||
| `output/q1/` | 已整理的 Q1 100 个特征文件、对齐审计和已有结果 |
|
||
| `output/q2/` | 已整理的 Q2 未对齐数据模型对比结果表 |
|
||
| `output/q3/` | Q3 运行后生成的预测、解释和验证结果 |
|
||
| `experiments/q2/` | 本项目最新未对齐 Q2 对比运行、权重和审计结果 |
|
||
| `REPORTS.md` | Q1、Q2 实验结果和方法说明 |
|
||
| `data_paths.py` | 官方附件的默认位置与外部数据根目录设置 |
|
||
|
||
## 准备官方附件
|
||
|
||
把附件按以下目录放入 `final/data/`。也可以把它们放在其他位置，再通过 `FINAL_DATA_DIR` 指向包含这些附件文件夹的根目录。
|
||
|
||
| 附件 | 相对 `FINAL_DATA_DIR` 的目录/文件 |
|
||
|---|---|
|
||
| 附件 1 | `附件1-数据集原始多模态样本/MOSEI数据集部分原始视频-100条/`；内含 `label-100.xlsx` 以及按 `video_id/clip_id.mp4` 组织的视频 |
|
||
| 附件 2 | `附件2-数据集特征文件/aligned_50.pkl` 与 `unaligned_50.pkl` |
|
||
| 附件 3 | `附件3-模态缺失特征样本/对齐版本/` 与 `未对齐版本/`；每个目录含 30 个样本文件 |
|
||
| 附件 4 | `附件4-可解释专项视频样本与特征文件/附件4-可解释专项视频样本与特征文件/未对齐版本/` 及同级 `videos/` |
|
||
|
||
附件 2 的 pickle 文件约数 GB，Q2/Q3 训练需要较大内存；它们不会被复制进项目。附件 3 的未对齐样本缺少数值文本特征及可靠的音视频长度，本项目会从 `raw_text` 重建 BERT 文本表示，并从音视频非零行估计长度；对应限制会写入附件 3 审计 CSV。附件 4 未对齐样本具有数值文本特征和长度字段，可由统一 adapter 转换。
|
||
|
||
默认数据位置是 `final/data/`。Q2、Q3 会直接读取 `FINAL_DATA_DIR`。Q1 命令还需要把 `--data-dir` 指向附件 1 的视频目录。若使用其他数据根目录，在运行项目命令前设置：
|
||
|
||
```powershell
|
||
$env:FINAL_DATA_DIR = "D:\task-data"
|
||
```
|
||
|
||
```bash
|
||
export FINAL_DATA_DIR="/data/task-data"
|
||
```
|
||
|
||
## 安装环境
|
||
|
||
需要 Python 3.11 或更新版本。在 `final/` 的上级目录执行下列命令。Q1 的 OpenFace 特征提取脚本调用 Windows PowerShell；Q2/Q3 可在 Windows、Linux 或 WSL 上运行。
|
||
|
||
```bash
|
||
python -m venv final/.venv
|
||
```
|
||
|
||
Windows PowerShell：
|
||
|
||
```powershell
|
||
final\.venv\Scripts\Activate.ps1
|
||
python -m pip install -r final/requirements.txt
|
||
```
|
||
|
||
Linux 或 WSL：
|
||
|
||
```bash
|
||
source final/.venv/bin/activate
|
||
python -m pip install -r final/requirements.txt
|
||
```
|
||
|
||
也可使用 `uv sync --project final`。GPU 运行需安装与本机 CUDA 驱动匹配的 PyTorch 版本；CPU 可用于功能验证，但完整训练会更慢。首次运行 Q1/Q3 或附件 3 推理时，Transformers 会下载 `google-bert/bert-base-uncased`；Q1 还会用到 `facebook/wav2vec2-base-960h`。无网络环境需预先把权重放入 Hugging Face 缓存。
|
||
|
||
## Q1：构建物理时间对齐特征并比较方案
|
||
|
||
Q1 对附件 1 的 100 个视频生成原生时间特征和统一特征包。视频/音频时间戳来自媒体流与 OpenFace 帧；文本区间来自固定转写的 CTC 单调对齐。五折评估按 `video_id` 分组。分类探针衡量情感信息，不代表人工标注的边界准确率。
|
||
|
||
原生特征提取还需要 OpenFace 2.2.0 Windows 包。将其解压到 `final/q1/cache/openface/OpenFace_2.2.0_win_x64/`，其中应有 `FeatureExtraction.exe` 和 `model/main_clnf_general.txt`。项目提供 `q1/run_openface.ps1` 调用脚本，不附带 OpenFace 二进制文件。
|
||
|
||
```powershell
|
||
if (-not $env:FINAL_DATA_DIR) { $env:FINAL_DATA_DIR = "final/data" }
|
||
$a1 = Join-Path $env:FINAL_DATA_DIR "附件1-数据集原始多模态样本/MOSEI数据集部分原始视频-100条"
|
||
$run = "final/output/q1/rerun"
|
||
|
||
python -m final.q1.compare_models `
|
||
--data-dir $a1 `
|
||
--cache-dir final/q1/cache/native `
|
||
--output-dir "$run/model_comparison" `
|
||
--bootstrap-repeats 2000
|
||
|
||
python -m final.q1.build_v2 `
|
||
--data-dir $a1 `
|
||
--cache-dir final/q1/cache/native `
|
||
--run-manifest "$run/model_comparison/run_manifest.json" `
|
||
--output-dir "$run/features_v2"
|
||
|
||
python -m final.q1.compare_v2 `
|
||
--data-dir $a1 `
|
||
--feature-dir "$run/features_v2" `
|
||
--output-dir "$run/model_comparison_v2" `
|
||
--bootstrap-repeats 2000
|
||
```
|
||
|
||
完整重跑使用独立的 `output/q1/rerun/`，保留随项目提供的现有结果包。
|
||
|
||
主要产物：`output/q1/features_v2/` 中有 100 个样本文件、100 行 `sample_summary.csv`（含样本 ID 和来源时长）、300 行 `modality_summary.csv`（含模态维度、有效时长、对齐粒度和状态）、`manifest_q1.jsonl`、`feature_manifest.json`；`output/q1/` 下的 `typical_sample_correspondence.csv` 和 `typical_sample_frames.jpg` 展示典型样本的转写、物理时间区间、音频来源行和视频帧。`alignment_query_example.png` 对照展示文本词区间到原始音频/视频位置的查询权重。`model_comparison/` 和 `model_comparison_v2/` 中有 OOF 预测、折内指标、组 Bootstrap 和运行清单。
|
||
|
||
已整理的 100 个样本可直接通过接口读取：
|
||
|
||
```python
|
||
from pathlib import Path
|
||
from final.adapter import Q1AlignmentAdapter
|
||
|
||
sample = Q1AlignmentAdapter().from_q1_sample(
|
||
"-iRBcNs9oI8/8",
|
||
feature_dir=Path("final/output/q1/features_v2"),
|
||
)
|
||
features, observed_mask = sample.q2_arrays()
|
||
```
|
||
|
||
## Q2：在题目未对齐数据上训练和比较模型
|
||
|
||
两个训练入口都默认使用附件 2 的 `unaligned_50.pkl`。训练、验证、测试均经 `adapter/` 投影到 50 个相对进程区间；这个坐标只表达模态内部的先后顺序，不是物理秒数。验证集用于模型选择，官方测试集用于最终评估。数学方案会比较 C0–C7 和 C6 单因素诊断；深度学习只保留题目要求的 EarlyConcat + BiGRU 与 MoFE-7 + MLP Router。
|
||
|
||
深度学习两模型共用交叉熵分类损失与 `0.5 × SmoothL1` 强度回归损失，AdamW 学习率 `3e-4`、权重衰减 `1e-3`、最多 12 轮、耐心值 3、梯度裁剪 1.0；训练遮蔽率为 0/10/30/50/70%，覆盖单模态、同步、部分重叠和异步连续缺失。EarlyConcat 使用 128 维模态投影和双向 GRU；MoFE 使用 7 个模态子集专家、MLP Router 和共享双向 GRU。以下命令显式设 batch size 128，以匹配报告中的对比实验。数学分支各方案的目标函数与内部留组选择设置记录在模型代码及 [数学运行清单](experiments/q2/unaligned_math_all_b128/run_manifest.json)。
|
||
|
||
从空的结果目录开始训练。若目标目录已存在非空结果，脚本会停止以免覆盖：
|
||
|
||
```bash
|
||
python -m final.q2.math.train \
|
||
--input-version unaligned_50 \
|
||
--output-dir final/experiments/q2/math_rerun \
|
||
--batch-size 128 \
|
||
--device auto
|
||
|
||
python -m final.q2.deep_learning.q2.train_math_protocol \
|
||
--input-version unaligned_50 \
|
||
--output-dir final/experiments/q2/deep_rerun \
|
||
--batch-size 128 \
|
||
--device auto
|
||
```
|
||
|
||
数学方案默认会用附件 3 未对齐样本生成 30 条 `attachment3_predictions.csv` 和 `attachment3_audit.csv`，预测文件包含极性、情感强度及类别概率。如只检查训练流程，可以增加 `--skip-attachment3`。深度学习运行会输出两模型的官方测试指标、验证缺失情景、AURC-MAE、Bootstrap 区间、权重和运行清单。为满足总附件大小限制，随项目提供的 Q2 归档保留逐情景指标和模型参数；逐行遮蔽/测试门控审计及官方测试单样本明细可由完整重训重新生成，未放入紧凑归档。
|
||
|
||
把两次运行的结果重新汇总到统一对比表：
|
||
|
||
```bash
|
||
python final/compare_unaligned_q2.py \
|
||
--math-dir final/experiments/q2/math_rerun \
|
||
--deep-dir final/experiments/q2/deep_rerun \
|
||
--output-dir final/output/q2
|
||
```
|
||
|
||
结果文件包括 `comparison_validation.csv`（全模型验证对比）、`comparison_test.csv`（预先选出的数学模型及两种深度模型测试结果）、`comparison_aurc.csv`（四种缺失模式的 AURC-MAE）。指标定义、已有对比数值和边界说明见 [REPORTS.md](REPORTS.md)。
|
||
|
||
## Q3：可解释预测与附件 4 输出
|
||
|
||
Q3 使用附件 2 训练集训练 EarlyConcat + BiGRU；只用官方验证集选择 epoch。默认最多 12 轮、耐心值 3、batch size 64，AdamW 学习率 `3e-4`、权重衰减 `1e-3`，目标函数为交叉熵加 `0.5 × SmoothL1` 强度回归。验证选择使用自然缺失、30% 单模态/同步缺失和 50% 异步缺失情景。附件 4 的 20 个未对齐样本经同一 adapter 投影，生成类别、情感分数、三类概率、模态贡献、主导模态及逐样本解释卡片。
|
||
|
||
```bash
|
||
python -m final.q3.train_interpretable \
|
||
--input-version unaligned_50 \
|
||
--attachment4-version unaligned_50 \
|
||
--output-dir final/output/q3 \
|
||
--device auto
|
||
```
|
||
|
||
输出目录包含：
|
||
|
||
- `attachment4_predictions.csv`：20 条完整预测及类别概率。
|
||
- `attachment4_explanations.csv`：预测、各模态遮蔽影响、主导模态和原始转写。
|
||
- `attachment4_local_evidence.csv`：文本 token、音频/视频来源行、归一化进程区间和单位置遮蔽影响。
|
||
- `attachment4_input_audit.csv`：输入哈希、adapter 模式、长度和可见位置审计。
|
||
- `explanation_cards/`：逐样本 Markdown 解释卡；`typical_explanation_card.md` 为置信度接近样本中位数的代表样例。
|
||
- `validation_metrics.json`、`validation_predictions.csv`、`validation_errors.csv`、`validation_diagnostics.png`：验证指标、误差样本和图示。
|
||
|
||
附件 4 未对齐特征没有可靠物理时间戳，因此音频/视频证据位置以归一化进程和原始特征行表示，不伪造秒级时间。模态/位置分数由遮蔽特征前后的模型概率差计算，表示模型敏感性，不是因果效应或情感成因证明。输出中提供源视频相对路径，便于回到原片段查看。
|
||
|
||
## 模型与对齐约定
|
||
|
||
- `model/c0.py` 至 `model/c7_*.py` 分别保存数学方案；C6 的距离、重构和点遮蔽诊断也各有单独文件。
|
||
- `model/early_concat.py` 和 `model/mofe.py` 是仅保留的两种深度学习方案。训练辅助模块从 `model/` 导入模型类，架构定义以此处为准。
|
||
- `adapter/` 有两种坐标语义：Q1 原生数据需媒体时间戳、持续时长和来源哈希，才能物理时间对齐；附件 2 未对齐特征只支持相对进程投影。代码会检查输入证据，不从数组形状推断物理对齐。
|
||
- 未对齐输入没有逐行质量分数时，按可见行质量权重为 1 处理；这一假设写入运行清单。
|
||
|
||
## 实验复现与文件约定
|
||
|
||
训练结果写入传入的 `--output-dir`；建议为每轮实验使用新的空目录。检查点、训练历史、数据/划分哈希、随机种子、特征版本、adapter 审计和验证/测试指标随运行结果保存。官方附件不进入版本库；`final/.gitignore` 已忽略 `data/`、Q1 中间缓存和环境目录。
|
||
|
||
当前已整理的 Q1/Q2 表格和结果摘要保存在 `output/`、`experiments/` 与 [REPORTS.md](REPORTS.md)。若要重建所有模型权重和预测，按上面的 Q1、Q2、Q3 顺序运行相应入口；Q1 原生视觉特征还需要单独准备 OpenFace 2.2.0。
|