需要用 TRIBE v2 从视频/音频/文本预测 fMRI…

用 Meta TRIBE v2 多模态基础模型对自然刺激进行推理、训练，并映射到 fsaverage5 皮层表面。

适用场景

解决思路

1. 仅做推理时安装：`pip install -e .`
2. 需要脑可视化（PyVista & Nilearn）时安装：`pip install -e ".[plotting]"`
3. 需要完整训练依赖（PyTorch Lightning、W&B 等）时安装：`pip install -e ".[training]"`
4. 从视频推理：`from tribev2 import TribeModel`；`model = TribeModel.from_pretrained("facebook/tribev2", cache_folder="./cache")`；`df = model.get_events_dataframe(video_path="path/to/video.mp4")`；`preds, segments = model.predict(events=df)`；`print(preds.shape)` 得到 fsaverage5 上的 `(n_timesteps, n_vertices)`。
5. 多模态输入（video + audio + text）：同样加载模型后，`df = model.get_events_dataframe(video_path="path/to/video.mp4", audio_path="path/to/audio.wav", text_path="path/to/script.txt")`；`audio_path` 可选且会覆盖视频音轨，`text_path` 可选且自动对齐时间；再 `preds, segments = model.predict(events=df)`。
6. 纯文本预测：加载模型后，`df = model.get_events_dataframe(text_path="path/to/narration.txt")`；`preds, segments = model.predict(events=df)`。
7. 脑表面可视化：加载模型、构建 events 并预测后，`from tribev2.plotting import plot_brain_surface`；`plot_brain_surface(preds[0], backend="nilearn")`，也可 `backend="pyvista"`。
8. 从头训练前设置环境变量：`export DATAPATH="/path/to/studies"`；`export SAVEPATH="/path/to/output"`；`export SLURM_PARTITION="your_slurm_partition"`。
9. 使用 LLaMA 3.2 所需 HuggingFace 认证：`huggingface-cli login` 并粘贴 HuggingFace read token；需先在 `https://huggingface.co/meta-llama/Llama-3.2-3B` 申请访问权限。
10. 本地快速测试训练：`python -m tribev2.grids.test_run`。
11. 在 Slurm 上跑完整网格搜索：皮层表面模型用 `python -m tribev2.grids.run_cortical`；皮层下区域用 `python -m tribev2.grids.run_subcortical`。
12. 加载预训练权重：`from tribev2 import TribeModel`；`model = TribeModel.from_pretrained("facebook/tribev2", cache_folder="./cache")`。
13. 构建 events dataframe：`df = model.get_events_dataframe(video_path=None, audio_path=None, text_path=None)`；可传入视频 `.mp4`、音频 `.wav`、文本 `.txt` 路径，内部处理词级时间、分块等。
14. 运行预测：`preds, segments = model.predict(events=df)`；`preds` 是形状为 `(n_timesteps, n_vertices)` 的 `np.ndarray`，`segments` 是分段元数据 dict 列表。
15. 按项目结构定位模块：`main.py` 实验管线 Data、TribeExperiment；`model.py` FmriEncoder 多模态→fMRI Transformer；`pl_module.py` PyTorch Lightning 训练模块；`demo_utils.py` TribeModel 与推理辅助；`eventstransforms.py` 事件变换（词提取、分块）；`utils.py` 多研究加载、划分、被试加权；`utils_fmri.py` 表面投影（MNI / fsaverage）与 ROI 分析；`grids/defaults.py` 默认实验配置；`grids/test_run.py` 本地测试入口；`plotting/` 脑可视化后端；`studies/` 数据集定义（Algonauts2025、Lahner2024 等）。
16. 修改默认配置：编辑 `tribev2/grids/defaults.py` 或设置环境变量；关键字段包括 `datapath`（可用 DATAPATH 覆盖）、`savepath`（可用 SAVEPATH 覆盖）、`slurm_partition`（可用 SLURM_PARTITION 覆盖）、`model: "FmriEncoder"`、`modalities: ["video", "audio", "text"]`、`surface: "fsaverage5"`（约 20k vertices）。
17. 用 PyTorch Lightning 自定义实验：`from tribev2.main import Data, TribeExperiment`；`from tribev2.pl_module import TribePLModule`；`import pytorch_lightning as pl`；`experiment = TribeExperiment(datapath="/path/to/studies", savepath="/path/to/output", modalities=["video", "audio", "text"])`；`data = Data(experiment)`；`module = TribePLModule(experiment)`；`trainer = pl.Trainer(max_epochs=50, accelerator="gpu", devices=4)`；`trainer.fit(module, data)`。
18. 处理 fMRI 表面投影：`from tribev2.utils_fmri import project_to_fsaverage, get_roi_mask`；`surface_data = project_to_fsaverage(mni_data, target="fsaverage5")`。
19. 获取 ROI mask 并提取区域响应：`roi_mask = get_roi_mask(roi_name="V1", surface="fsaverage5")`；`v1_responses = preds[:, roi_mask]`；输出形状 `(n_timesteps, n_v1_vertices)`。
20. 对多个视频批量预测：加载模型后遍历 `video_paths = ["video1.mp4", "video2.mp4", "video3.mp4"]`；对每个视频执行 `df = model.get_events_dataframe(video_path=vp)`、`preds, segments = model.predict(events=df)`，并 `all_predictions.append(preds)`；得到 `list of (n_timesteps_i, n_vertices) arrays`。
21. 提取特定脑区预测：加载模型并预测后，`ac_mask = get_roi_mask("auditory_cortex", surface="fsaverage5")`；`auditory_responses = preds[:, ac_mask]`，形状 `(n_timesteps, n_ac_vertices)`。
22. 访问分段时序元数据：`preds, segments = model.predict(events=df)`；遍历 `for i, seg in enumerate(segments):`，打印 `seg['onset']`、`seg['duration']` 和 `preds[i].shape`。
23. 解决 LLaMA 3.2 access denied：先在 `https://huggingface.co/meta-llama/Llama-3.2-3B` 申请访问；再 `huggingface-cli login`；使用有 read 权限的 HuggingFace token。
24. 解决推理时 CUDA out of memory：`import torch`；加载模型后 `model.to("cpu")`，在较小机器上用 CPU 推理。
25. 解决缺少可视化依赖：`pip install -e ".[plotting]"`，安装 pyvista 与 nilearn 后端。
26. 解决 Slurm 训练未提交：检查环境变量 `echo $DATAPATH $SAVEPATH $SLURM_PARTITION`；或直接编辑 `tribev2/grids/defaults.py`。
27. 解决无音轨视频报错：单独提供音频或改用纯文本模式；例如 `df = model.get_events_dataframe(video_path="silent_video.mp4", audio_path="separate_audio.wav")`。

适用边界 · 注意事项

• 没有安装 TRIBE v2 代码、没有 HuggingFace/LLaMA 3.2 访问权限，或无法安装 PyTorch/PyTorch Lightning 等依赖时。
• 不需要预测 fMRI/皮层表面响应，或没有视频/音频/文本自然刺激数据时。
• 需要非 fMRI 的通用多模态表征、或不需要 fsaverage5 表面映射时。