Magma — 轻量级多模态模型研究与实验框架

通往多模态智能体之路

:sparkles: 亮点

• 数字与物理世界： Magma 是首个面向多模态智能体的基础模型，旨在处理虚拟和现实环境中的复杂交互！
• 多功能能力： Magma 作为单一模型，不仅具备通用的图像和视频理解能力，还能生成目标驱动的视觉规划和动作，使其适用于多种智能体任务！
• 最先进的性能： Magma 在各种多模态任务上实现了最先进的性能，包括 UI 导航、机器人操作，以及通用的图像和视频理解，特别是在空间理解和推理方面！
• 可扩展的预训练策略： Magma 的设计使其能够从海量无标签视频中可扩展地学习，并结合现有的智能体数据，从而具备强大的泛化能力，适用于现实世界的应用！

:fire: 新闻

• [2025.04.29] 带有 SoM 提示标注的 Mind2Web 和 AITW 已在 Hugging Face 发布！我们将其用于 Magma 的下游微调，并在论文表格中报告了结果。
• [2025.04.12] 🔥 我们在 Hugging Face 发布了带有视觉轨迹的预训练视频 Magma-Video-ToM。
• [2025.04.06] 带有视觉轨迹的 Open X-Embodiment 预训练数据可从 Magma-OXE-ToM 下载。
• [2025.03.16] 我们发布了为教学视频生成 SoM 和 ToM 的演示代码（即论文中的算法 2），位于 SoM/ToM 生成。
• [2025.03.09] 🔥 我们发布了 Magma 训练代码，以及一个在 Magma-820K 数据集上训练 Magma-8B 的示例。请查看 模型训练。
• [2025.03.06] 我们发布了一个展示机器人规划能力的新演示。运行 python agents/robot_traj/app.py 启动演示！
• [2025.02.28] 我们在 Hugging Face 发布了两个演示：Magma-UI 和 Magma-Gaming。请查看我们模型的动作定位和规划能力！
• [2025.02.26] ⭐ 激动人心的消息！Magma 被 CVPR 2025 接收！
• [2025.02.25] 🎉 重大新闻！我们正在 Hugging Face 和 Azure AI Foundry 上发布 Magma 模型！
• [2025.02.23] 我们发布了 Magma 推理代码！
• [2025.02.20] Magma 登顶 Hacker News！
• [2025.02.19] 我们将通过 MSR Forum 在下周二 02.25 发布我们的代码、模型和 UI 导航演示！
• [2025.02.18] 我们在 MSR 的旗舰项目 Magma 已在 arXiv 发布！

:bookmark_tabs: 待办事项

我们将发布以下所有内容：
- [x] 模型推理代码
- [x] 添加 UI 和游戏智能体演示
- [x] 模型检查点
- [x] 训练代码
- [x] 带有轨迹的 Open-XE 预训练数据
- [x] 带有轨迹的视频预训练数据
- [ ] 带有 SoM 的 SeeClick 和 Vision2UI 预训练数据
- [ ] UI/Libero 微调脚本
- [ ] 视频微调脚本

:clipboard: 目录

• 什么是 Magma？
• 我们如何预训练 Magma？
• 安装
• 数据预处理
• SoM 和 ToM 生成
• 模型训练
• 在 Open-X 上无 SoM/ToM 预训练
• 在 Magma-820K 上微调
• 模型使用
• 推理
  • 使用 Huggingface Transformers 推理
  • 使用本仓库本地代码推理
  • 使用 bitsandbytes 推理
  • 基准测试
• 使用 lmms-eval 评估
• 使用 SimplerEnv 评估
• 多图像或视频
• API 服务器
• 智能体演示
  • UI 智能体
  • 游戏智能体
  • 机器人视觉规划
• 引用
• 致谢

什么是 Magma？

Magma 是一个面向多模态智能体的基础模型。作为多模态智能体模型的基石，它应具备强大的多模态世界感知能力，并能精确执行目标驱动的动作（见上图）。基于此，我们致力于实现以下目标：

• 语言与时空智能： Magma 应同时具备强大的语言和时空智能，以理解图像和视频，将其动作基于观察结果进行定位，并进一步将外部目标转化为动作计划和执行。
• 数字与物理世界： Magma 不应局限于数字世界（例如，网页导航）或物理世界（例如，机器人操作），而应能跨越两个世界工作，就像人类一样。

为此，我们开发了新的预训练数据（主要由海量无标签视频和现有的标注智能体数据组成）以及新的预训练框架（统一了文本、图像和动作三种模态的训练），从而训练出一个名为 Magma 的面向多模态智能体的新基础模型。

我们如何预训练 Magma？

我们通过两个维度追求这一目标：

• 大规模异构训练数据：我们整理了海量数据，包括现有的多模态理解数据、UI 导航数据、机器人操作数据以及海量无标签视频。我们还提出了一种新的数据收集流程，用于收集海量无标签视频，该流程可扩展且成本效益高。为了从原始视频和机器人轨迹中获得有用的动作监督，我们精心去除了视频中的相机运动，然后将运动转化为模型训练的“动作”监督。这为模型学习跨模态连接以及长时程动作预测和规划提供了独特的信号。

• 通用预训练目标：文本和动作本质不同，因此存在巨大鸿沟，而视觉标记是连续的。我们提出了一个通用的预训练框架，统一了所有三种模态的训练，并证明这对于模型学习跨模态连接至关重要。更具体地说，我们提出了 Set-of-Mark 和 Trace-of-Mark 作为模型预训练的辅助任务，作为不同输出模态之间的桥梁。通过这种方式，我们在文本与动作模态之间，以及图像与动作模态之间建立了良好的对齐。

安装

1. 将本仓库克隆到本地机器：

git clone https://github.com/microsoft/Magma
cd Magma

2. 安装依赖：

conda create -n magma python=3.10 -y
conda activate magma
pip install --upgrade pip
pip install -e .

3. 安装训练所需的包：

pip install -e ".[train]"

4. 安装智能体所需的包：

pip install -e ".[agent]"

5. 其他可能需要的包：

• Co-tracker

# 安装 co-tracker
git clone https://github.com/facebookresearch/co-tracker
cd co-tracker
pip install -e .
pip install imageio[ffmpeg]
cd ../

• Kmeans

# 安装 kmeans_pytorch，注意：使用 pip 安装会导致错误
git clone https://github.com/subhadarship/kmeans_pytorch
cd kmeans_pytorch
pip install -e .
cd ../

• 其他

# 安装其他包
pip install ipython
pip install faiss-cpu
pip install decord

⚠️ 请确保已安装正确版本的 transformers（>=4.49.0）。如果看到异常行为，请检查 transformers 的版本，并可能查看下面的定制化 transformers。

if "gamma" in key and "clip_vision_model" not in key:
    key = key.replace("gamma", "weight")

pip install git+https://github.com/jwyang/transformers.git@dev/jwyang-v4.44.1

pip install git+https://github.com/jwyang/transformers.git@dev/jwyang-v4.48.2

数据预处理

SoM 和 ToM 生成

如论文表 1 所示，我们将 SoM 和 ToM 应用于机器人数据和教学视频。为确保可复现性，我们提供了为教学视频生成 SoM 和 ToM 的代码。代码位于 tools/som_tom/demo.py。您可以运行以下命令为机器人数据生成 SoM 和 ToM：

python tools/som_tom/demo.py

然后您可以在 tools/som_tom/videos 文件夹中找到两个视频。从 CoTracker 提取的原始轨迹显示在 orig_trace.mp4 中，而 SoM-ToM 视频名为 som_tom.mp4。

模型训练

我们提供了在 Open-X-Embodiment 上预训练 LLama-3-8B-Instruct 以及在不同下游任务上微调 Magma-8B 的说明。

在 Open-X 上无 SoM/ToM 预训练

• 数据准备

从官方网站下载 Open-X-Embodiment。然后相应地编辑数据配置文件 openx.yaml。数据配置文件应如下所示：

# 所有数据路径的列表
DATA_PATH:
  - "/path/to/open-x"
IMAGE_FOLDER:
  - "siglip-224px+mx-oxe-magic-soup"
LANGUAGE_PATH:
  - ""

• 在 OpenX 上预训练

设置好数据集和配置后，您可以运行以下命令来微调模型：

sh scripts/pretrain/pretrain_openx.sh

• 优势：我们付出了巨大努力，将 Open-X 数据加载器从 OpenVLA 中解耦出来，并使其与我们实验中使用的其他数据集兼容。*

在 Magma-820K 上微调

• 数据准备

从 MagmaAI/Magma-820K 下载标注文件。请根据数据集页面中的数据集列表准备图像数据。完成后，请相应地编辑 magma_820k.yaml 文件。

# 所有数据路径的列表
DATA_PATH:
  - "/path/to/magma_820k.json"
IMAGE_FOLDER:
  - "/root/to/magma_820k/images"

• 从 Magma-8B 微调

设置好数据集和配置后，您可以运行以下命令来微调模型：

sh scripts/finetune/finetune_magma_820k.sh

模型使用

推理

使用 Huggingface Transformers 推理

我们已将模型上传至 Huggingface Hub。您可以使用以下代码轻松加载模型和处理器。

点击展开

```python from PIL import Image import torch from transformers import AutoModelForCausalLM from transformers import AutoProcessor dtype = torch.bfloat16 model = AutoModelForCausalLM.from_pretrained("microsoft/Magma-8B", trust_remote_code=True, torch_dtype=dtype) processor = AutoProcessor.from_pretrained("microsoft/Magma-8B", trust_remote_code=True) model.to("cuda") # 推理 image = Image.open("./assets/images/magma_logo.jpg").convert("RGB") convs = [ {"role": "system", "content": "You are agent that can see, talk and act."}, {"role": "user", "content": "\nWhat is the letter on the robot?"}, ] prompt = processor.tokenizer.apply