1. 项目定位与用途
TRIBE v2 是 Meta 研究院推出的多模态脑编码基础模型,定位为“用于硅脑神经科学的基础模型”。其核心用途是预测人类大脑在面对自然刺激(视频、音频、文本)时的 fMRI 血氧水平依赖(BOLD)信号反应。模型将先进的文本、音频和视频表征统一映射到皮层表面,为计算神经科学提供可复现、可扩展的脑活动模拟工具。项目发布预训练权重与开源代码,旨在推动跨模态脑功能研究的标准化与协作。
TRIBE v2 是 Meta 开发的多模态脑编码基础模型,用于预测大脑对视觉、听觉和语言刺激的 fMRI 反应。本文介绍其核心用途、解决的跨模态映射问题、适用场景(神经科学、认知科学),并提供详细安装指南(基础/可视化/训练三档)、Python 使用示例、项目模块结构及关键依赖列表,帮助研究者快速上手应用。
TRIBE v2 是 Meta 开发的多模态脑编码基础模型,采用统一 Transformer 架构预测 fMRI 对视觉、听觉和语言刺激的反应,提供预训练权重与推理接口,推动计算神经科学研究。
TRIBE v2 是 Meta 研究院推出的多模态脑编码基础模型,定位为“用于硅脑神经科学的基础模型”。其核心用途是预测人类大脑在面对自然刺激(视频、音频、文本)时的 fMRI 血氧水平依赖(BOLD)信号反应。模型将先进的文本、音频和视频表征统一映射到皮层表面,为计算神经科学提供可复现、可扩展的脑活动模拟工具。项目发布预训练权重与开源代码,旨在推动跨模态脑功能研究的标准化与协作。
TRIBE v2 主要解决多模态深度学习与神经成像之间的映射问题:如何将视觉、听觉、语言等异构模态的深层特征,有效转换为大脑皮层上 fMRI 测量的预测值。传统脑编码模型常局限于单一感官通道或线性假设,难以捕捉自然刺激下大脑的复杂整合过程。TRIBE v2 通过统一的 Transformer 架构,实现跨模态特征的联合编码,并显式建模血流动力学延迟(补偿 5 秒滞后),从而更准确地模拟真实神经活动。这为验证认知理论、解码感知内容提供了计算基础。
该模型适用于以下研究场景:神经科学研究中,分析与验证不同感官模态(视觉、听觉、语言)对大脑活动的编码方式及跨模态整合机制;计算认知科学领域,构建和测试关于感知、注意、语义处理的计算理论;脑成像数据分析中,将外部刺激时间线与 fMRI 测量关联,进行编码模型比较或解码任务。此外,模型预测的皮层活动图可用于与真实 fMRI 数据对比,评估模型拟合度,或作为先验指导脑机接口与神经调控研究。项目提供的 fsaverage5 标准表面输出便于跨被试比较。
项目提供三种安装配置,通过 pip 基于 pyproject.toml 的 optional-dependencies 实现。基础安装(仅推理)执行 `pip install -e .`,包含核心依赖如 torch、x_transformers、moviepy 等。若需脑可视化功能,使用 `pip install -e ".[plotting]"`,额外安装 nibabel、nilearn、pyvista 等库。完整训练环境则运行 `pip install -e ".[training]"`,加入 PyTorch Lightning、wandb、torchmetrics 等。所有安装均要求 Python 3.11+,依赖版本在 pyproject.toml 中严格 pinned,确保可复现性。仓库未提供 Docker 镜像或 Conda 环境文件。
用户可通过简洁的 Python API 进行推理。首先从 HuggingFace 加载预训练模型:`TribeModel.from_pretrained("facebook/tribev2", cache_folder="./cache")`。然后准备刺激事件数据:调用 `model.get_events_dataframe()` 并传入视频、音频或文本路径;若为文本,系统自动转语音并转写获得词级时间戳。接着执行 `model.predict(events=df)` 得到预测,返回数组形状为 `(时间步, 皮层顶点数)`,对应 fsaverage5 网格约 20k 顶点,且时间上已补偿 5 秒 hemodynamic 滞后。完整可视化分析可参考 Colab 演示笔记本 `tribe_demo.ipynb`。训练新模型需设置环境变量 DATAPATH 和 SAVEPATH,并通过 `python -m tribev2.grids.test_run` 等脚本启动。
TRIBE v2 的实现基于模块化设计:核心模型 `model.py` 定义 FmriEncoder,使用 x_transformers 库构建 Transformer 实现多模态到 fMRI 的映射;`demo_utils.py` 封装 TribeModel 提供高级推理接口;`pl_module.py` 集成 PyTorch Lightning 处理训练循环;`utils.py` 与 `utils_fmri.py` 负责多研究数据加载、分割及表面投影(MNI/fsaverage)与 ROI 分析。训练配置通过 `grids/` 目录管理,支持本地测试与 Slurm 网格搜索。可视化模块 `plotting/` 利用 PyVista 和 Nilearn 渲染皮层与皮层下预测。关键依赖包括 torch、transformers、moviepy、gtts、langdetect、spacy 等,版本在 pyproject.toml 中精确指定,确保环境一致性。模型权重托管于 HuggingFace。
项目提供三种安装方式:基础推理(仅核心依赖)执行 `pip install -e .`;包含脑可视化功能使用 `pip install -e ".[plotting]"`;完整训练环境(含 PyTorch Lightning、W&B)使用 `pip install -e ".[training]"`。所有安装要求 Python 3.11+,依赖版本在 pyproject.toml 中固定。
首先从 HuggingFace 加载模型:`model = TribeModel.from_pretrained("facebook/tribev2")`。然后准备刺激事件:`df = model.get_events_dataframe(video_path="..." / text_path="..." / audio_path="...")`,文本会自动转语音并转写。接着执行 `preds, segments = model.predict(events=df)` 获得预测,`preds` 形状为 `(时间步, 顶点数)`。详细可视化步骤见 Colab 演示笔记本。
预测结果 `preds` 为二维数组,形状 `(n_timesteps, n_vertices)`,对应时间序列与皮层顶点。空间上基于 fsaverage5 标准皮层网格,约 20,000 个顶点。时间上已向前偏移 5 秒以补偿 fMRI 的血流动力学滞后。预测针对“平均”被试(见论文)。
支持。仓库包含完整训练 pipeline:设置 DATAPATH 和 SAVEPATH 环境变量后,可运行 `python -m tribev2.grids.test_run` 进行本地测试,或使用 `run_cortical.py` / `run_subcortical.py` 在 Slurm 上进行网格搜索。训练依赖需通过 `.[training]` 额外安装。具体数据格式要求参考 `tribev2/studies/` 中的数据集定义。
模型支持视频、音频和文本三种输入。当提供文本路径时,`get_events_dataframe` 会自动将文本转换为语音(TTS),并转写成词级时间戳,以便与音频/视频模态对齐。这确保了多模态刺激的事件时间轴一致,便于模型联合编码。