# Q1：模态对齐与特征分支

本目录按《E题V2》第四章构建 Q1 对齐特征。规格核对与限制见 [`V2_REVIEW.md`](V2_REVIEW.md)，可供后续训练读取的主特征包位于 `features_v2/`。

Q1 物理时间与附件二 `unaligned_50.pkl` 的相对进程现在共用 [`UNIFIED_ADAPTER.md`](UNIFIED_ADAPTER.md) 所述接口和投影核；Relative 模式的详细假设见 [`UNALIGNED_ADAPTER.md`](UNALIGNED_ADAPTER.md)。

## V2 特征包

- 100 个样本、300 条模态明细；主物理时间视图为 0.1 秒，并保留真实末段长度。
- 文本采用冻结 BERT 词级特征；音频 74 维；视觉采用 OpenFace 2.2.0 的 35 维输出。
- 原生词、音频窗、视频帧与源索引均保留；另提供逐词 CTC 后验、50 段相位视图、多尺度视图、B4 语音视图和物理时间查询矩阵。
- 每个时间视图包含均值、方差、计数、逐维物理覆盖率、掩码和独立质量摘要。质量加权只影响特征汇聚，不改变物理覆盖率。
- B4 Wav2Vec2 视图通过接口从本机 `cache/native/` 按需读取；不复制进主包。
- 特征文件共 44,321,715 字节（约 42.27 MiB）。`feature_manifest.json` 记录配置哈希、源运行信息及精确字节数。

## 读取接口

```python
from q1_io import load_sample, get_view, csr_from_sample

sample = load_sample("video_id/clip_id")
primary = get_view(sample, "audio", "sec")
multiscale = get_view(sample, "audio", "multi", context_s=0.3)
posterior_text = get_view(sample, "text", "posterior")
word_to_audio = csr_from_sample(sample, "query_word_audio_H_time")
b4_speech = get_view(sample, "speech", "sec")
```

`get_view` 支持 `sec`、`word`、`phase50`、`multi` 和文本专用 `posterior`。多尺度视图从原生行按窗口重新聚合；`speech` 视图依赖本机原生缓存。清单文件为 `features_v2/manifest_q1.jsonl`、`sample_summary.csv` 和 `modality_summary.csv`。

## 重建和五折探针

在仓库根目录运行：

```bash
uv run --project math/Q1 python math/Q1/build_v2.py
uv run --project math/Q1 python math/Q1/compare_v2.py
```

特征重建依赖 `cache/native/`、`source_cache_manifest.json`、附件一视频及本机模型资源。`build_v2.py` 复用 `compare_models.py` 中的标签读取、缓存解析和数据结构；V2 对照入口是 `compare_v2.py`。B0–B4 五折 `video_id` 分组探针写入 `results/model_comparison_v2/`，每折缩放器只在训练视频组拟合；报告包含 Accuracy、Macro-F1、MAE、RMSE 和 Pearson。无人工词边界真值时，不报告边界误差或 CTC 后验校准率。

词到原生音频窗和视频帧的 `H_time` 查询矩阵示例可用 `visualize_alignment.py` 重绘；默认展示样本 `-iRBcNs9oI8/8`，也可通过 `--sample-id` 指定样本。图与样本清单写入 `results/`。