modeling_zhaocui/final/README.md

复杂场景下多模态情感识别：独立运行项目

本目录包含题目 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 的视频目录。若使用其他数据根目录，在运行项目命令前设置：

$env:FINAL_DATA_DIR = "D:\task-data"

export FINAL_DATA_DIR="/data/task-data"

安装环境

需要 Python 3.11 或更新版本。在 final/ 的上级目录执行下列命令。Q1 的 OpenFace 特征提取脚本调用 Windows PowerShell；Q2/Q3 可在 Windows、Linux 或 WSL 上运行。

python -m venv final/.venv

Windows PowerShell：

final\.venv\Scripts\Activate.ps1
python -m pip install -r final/requirements.txt

Linux 或 WSL：

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 二进制文件。

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 个样本可直接通过接口读取：

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，以匹配报告中的对比实验。数学分支各方案的目标函数与内部留组选择设置记录在模型代码及 数学运行清单。

从空的结果目录开始训练。若目标目录已存在非空结果，脚本会停止以免覆盖：

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 归档保留逐情景指标和模型参数；逐行遮蔽/测试门控审计及官方测试单样本明细可由完整重训重新生成，未放入紧凑归档。

把两次运行的结果重新汇总到统一对比表：

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。

Q3：分层反事实证据归因

Q3 复用 Q2 已训练的 EarlyConcat + BiGRU、MoFE-7 + MLP Router 检查点和同一套训练集 robust scaler，不重新拟合模型。第一轮含三个解释方案：E0 对 EarlyConcat 做精确三模态 Shapley 与局部遮蔽；E1 把 MoFE Router 当作待检验的内部信号；E2 对同一个 MoFE 检查点做精确 Shapley、交互和局部遮蔽。E1/E2 的预测完全相同，比较的是解释方式。

在项目根目录设置附件位置后运行。项目默认查找 final/data/；也可以将 FINAL_DATA_DIR 指向包含附件 2、附件 4 文件夹的根目录：

$env:FINAL_DATA_DIR = "D:\task-data"
python -m final.q3.run_experiments --output-dir final/output/q3/first_round --device auto

export FINAL_DATA_DIR="/data/task-data"
python -m final.q3.run_experiments --output-dir final/output/q3/first_round --device auto

完整运行使用官方验证集生成预测指标、误差归因和分类 margin 的 Shapley。只想快速检查附件 4 可增加 --skip-validation；不抽取候选视频帧可增加 --no-frames。每次运行请给一个新的空输出目录。

主要产物：

• attachment4_predictions.csv：20 个附件 4 样本在 E0/E1/E2 下的预测和类别概率。
• attachment4_modal_shapley.csv、attachment4_pairwise_interactions.csv：分类 logit 与强度回归的模态贡献、绝对贡献比例、配对交互和 Shapley 完备性残差。
• attachment4_local_evidence.csv、attachment4_router_local_evidence.csv：1/3/5 个相对进程 bin 的局部遮蔽响应与 MoFE Router 位置分数。
• attachment4_evidence_segments.csv：每个方案的代表性文本、音频和视觉证据段；evidence_frames/ 中保存由进度比例估算位置抽取的候选帧。
• faithfulness_by_sample.csv、q3_method_comparison.csv：删除/保留检验、0–70% 删除曲线、尺度稳定性和 Router–Shapley 一致性汇总。
• validation_predictions.csv、validation_errors.csv、validation_error_attribution.csv：官方验证集预测、误差样本和分类 margin 归因。
• explanation_cards/、typical_explanation_card.md、evidence_profiles/：逐样本解释卡、代表卡和 3×50 局部证据图。

想先查看文本、音频波形、视频帧中的遮蔽位置，再查看对应时间 bin 上七个 MoFE expert 的 Router 权重热力图，可运行：

python -m final.q3.plot_router_heatmaps --output-dir final/output/q3

它输出附件 4 样本 02、03 的完整输入和受控残缺对照图：蓝色斜线表示输入被遮蔽，下面按 T、A、V、TA、TV、AV、TAV 顺序显示 expert 的 α[t,e]。详细定义与限制见 Q3 实验说明，实验图也已收录在 REPORTS.md。

三种输入模态只有 8 个 coalition，脚本完整枚举而非近似 SHAP。分类解释固定使用完整输入的预测类别 logit，回归解释使用情感强度输出。局部证据是单模态窗口被遮蔽前后的 logit 差；正值表示该窗口支持当前预测，负值表示该窗口反对当前预测。Router 权重只描述路由机制，不能直接解释成预测贡献。

附件 4 特征行没有物理时间戳。文本可以回溯到 tokenizer token 和来源行；音频/视觉证据保留来源行与归一化进程。若视频可读，候选帧位置由相对进程乘视频时长估算，供人工回看，不表示特征已经物理时间对齐。删除/保留检验使用模型训练时见过的 mask 接口，但孤立稀疏遮蔽仍可能偏离训练分布；报告会把 10% 保留结果标为诊断，主要删除曲线范围限制在最多删除 70%。

细节和解释边界见 Q3 实验说明（q3/README.md）与 REPORTS.md。

模型与对齐约定

• 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/Q3 表格和结果摘要保存在 output/、experiments/ 与 REPORTS.md。若要重建所有模型权重和预测，按上面的 Q1、Q2、Q3 顺序运行相应入口；Q1 原生视觉特征还需要单独准备 OpenFace 2.2.0。