modeling_zhaocui/final/Q1/README.md

Q1 多模态对齐与训练接口

final/Q1 收纳了 math/Q1 的 Q1 方法、模型比较结果，以及从附件一 100 条样本导出的训练特征。Q1 及后续题目可以复用同一套模态对齐定义。

对齐与特征

• 文本：每词一个 768 维 BERT-base-uncased 末四层均值向量。主版本使用固定转写的 CTC Viterbi 词区间和样本内相对质量权重；另存 B2 前向–后向词占据后验版本。
• 音频：74 维，包括 40 维 log-Mel、13 维 MFCC、13 维 ΔMFCC、8 维韵律/谱特征。特征提取 hop 为 10 ms。
• 视觉：35 维，包括 17 个 MediaPipe blendshape 代理、6 维头姿、6 维近似视线、6 维面部几何；采样率为 5 Hz。B1 对姿态采用 SO(3) 均值，对视线采用归一化向量均值。代理量不是 OpenFace AU。
• 三种模态先依真实时间戳投影到 0.1 秒公共时间网格，再按每条片段的物理时长划为 50 个等宽时间箱。time_bounds_s 保存每个箱的片段内秒数边界，掩码表示各维是否观测到。
• 特征保持原始尺度。训练时只用训练视频组拟合标准化参数；缺失值位置虽填零，但必须使用掩码。

文件

• features/aligned_50.pkl：标准训练文件，含 metadata 和 all。主要数组维度为 text (100,50,768)、audio (100,50,74)、vision (100,50,35)。包括文本后验替代视图、逐维掩码、覆盖率、时间边界、标签、样本/视频 ID 和源视频 SHA-256。
• features/native_grid.npz：保留 0.1 秒网格上的变长 B1 特征。用 offsets[i]:offsets[i+1] 读取第 i 条样本；时间边界是片段内秒数。
• features/sample_feature_manifest.csv：300 行样本-模态追溯表，含原始/观测时长、维数、抽取粒度、公共网格长度、50 箱导出粒度和源视频哈希。
• features/sample_alignment_summary.csv、features/word_alignment_posterior.csv：逐样本和逐词对齐信息；feature_manifest.json、feature_names.json 记录版本、模型和字段定义。
• results/model_comparison/：Q1 的 B0–B4 对照结果、报告与典型样本对齐图。

标签 classification_labels 为 0/1/2（负面/中性/正面），regression_labels 保留原始连续情感值。数据集未提供新的训练/验证划分；请按 video_id 分组切分，避免同一原视频泄漏到两边。所有时间均相对于片段起点。

Python 调用

固定形状数组可直接交给后续训练代码：

from api import load_aligned50, group_holdout_indices

payload = load_aligned50(text_variant="hard")  # 或 text_variant="posterior"
features = payload["all"]
train_idx, valid_idx = group_holdout_indices(payload, validation_fraction=0.2, seed=42)
text = features["text"][train_idx]       # (N_train, 50, 768)
audio = features["audio"][train_idx]     # (N_train, 50, 74)
vision = features["vision"][train_idx]   # (N_train, 50, 35)
text_mask = features["text_mask"][train_idx]
labels = features["classification_labels"][train_idx]

PyTorch Dataset 接口返回每条样本的张量、标签、掩码和分组 ID：

from torch.utils.data import DataLoader, Subset
from api import Q1TorchDataset, group_holdout_indices

dataset = Q1TorchDataset(text_variant="hard")
train_idx, valid_idx = group_holdout_indices(dataset.payload, seed=42)
train_loader = DataLoader(Subset(dataset, train_idx.tolist()), batch_size=16, shuffle=True)
batch = next(iter(train_loader))

重新生成

在仓库根目录运行：

cd final/Q1
uv sync
uv run python compare_models.py
uv run python export_features.py --cache-dir cache/native --run-manifest results/model_comparison/run_manifest.json

若复用当前 math/Q1 中已生成的缓存，可将导出命令改为：

uv run python export_features.py --cache-dir ../../math/Q1/cache/native --run-manifest ../../math/Q1/results/model_comparison/run_manifest.json

uv.lock、虚拟环境、缓存和原始数据不随本目录提交。首次从原始视频重新抽取特征时，需能够访问 BERT、Wav2Vec2 和 MediaPipe 模型权重。