🤖 Magma：多模态AI智能体的基础模型

Jianwei Yang^*1†  Reuben Tan^1†  Qianhui Wu^1†  Ruijie Zheng^2‡  Baolin Peng^1‡  Yongyuan Liang^2‡

Yu Gu¹  Mu Cai³  Seonghyeon Ye⁴  Joel Jang⁵  Yuquan Deng⁵  Lars Liden¹  Jianfeng Gao^1▽

¹ 微软研究院；² 马里兰大学；³ 威斯康星大学麦迪逊分校
⁴ KAIST；⁵ 华盛顿大学

^* 项目负责人 ^† 第一作者 ^‡ 第二作者 ^▽ 领导层

CVPR 2025

📄 arXiv论文   🌐 项目主页   🤗 Hugging Face模型 ☁️ Azure AI Foundry 📺 视频

迈向多模态AI智能体之路

:sparkles: 亮点

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

:fire: 最新消息

• [2025.04.29] Mind2Web 和 AITW 数据集，附带SoM提示标注，已在Hugging Face上发布！我们使用这些数据对Magma进行了下游微调，并在表格中报告了结果。
• [2025.04.12] 🔥 我们在Hugging Face上发布了带有视觉轨迹的预训练视频 Magma-Video-ToM。
• [2025.04.06] 可以从 Magma-OXE-ToM 下载带有视觉轨迹的Open X-Embodiment预训练数据。
• [2025.03.16] 我们在 SoM/ToM Generation 中发布了用于生成教学视频的SoM和ToM的示例代码（即我们论文中的算法2）。
• [2025.03.09] 🔥 我们发布了Magma的训练代码，并提供了一个在Magma-820K数据集上训练Magma-8B的示例。请查看 Model Training。
• [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 on 02.25 上发布我们的代码、模型以及UI导航演示！
• [2025.02.18] 我们在微软研究院的旗舰项目Magma已在 arXiv 上发布！

:bookmark_tabs: 待办事项

我们将陆续发布以下内容：

• 模型推理代码
• 添加UI和游戏代理演示
• 模型检查点
• 训练代码
• 带有轨迹的Open-XE预训练数据
• 带有轨迹的视频预训练数据
• SeeClick和Vision2UI预训练数据，附带SoM
• UI/Libero微调脚本
• 视频微调脚本

:clipboard: 目录

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

什么是Magma？

Magma 是一个多模态 AI 代理的基础模型。作为多模态代理模型的基石，它应当具备强大的多模态感知能力，并能精确地执行目标驱动的行为（见上图）。基于这一理念，我们致力于实现以下目标：

• 语言与时空智能： Magma 应当同时具备强大的语言理解和时空感知能力，以理解图像和视频、根据观察结果采取行动，并进一步将外部目标转化为行动计划并加以执行。
• 数字世界与物理世界： Magma 不应局限于数字世界（如网页导航）或物理世界（如机器人操作），而应能够在两个世界之间无缝切换，正如人类自身一样。

为此，我们开发了一种新的预训练数据集，主要由大量未标注的野外视频以及现有的标注好的代理数据组成；同时，我们还设计了一个全新的预训练框架，能够统一训练文本、图像和动作这三种模态的数据，从而训练出一种面向多模态 AI 代理的新基础模型——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

模型使用

推理

使用 Hugging Face Transformers 进行推理

我们已将模型上传至 Hugging Face Hub。您可以通过以下代码轻松加载模型和处理器。

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": "你是一个能看、能说、能行动的智能体。"},            
    {"role": "user", "content": "<image_start><image><image_end>\n机器人上是什么字母？"},
]
prompt = processor.tokenizer.apply_chat_template(convs, tokenize=False, add_generation_prompt=True)
inputs = processor(images=[image], texts=prompt, return_tensors="pt")
inputs['pixel_values'] = inputs['pixel_values'].unsqueeze(0)
inputs['image_sizes'] = inputs['image_sizes'].unsqueeze(0)
inputs = inputs.to("cuda").to(dtype)

generation_args = { 
    "max_new_tokens": 500, 
    "temperature": 0.0, 
    "do_sample": False, 
    "use_cache": True,
    "num_beams": 1,
} 

with torch.inference_mode():
    generate_ids = model.generate(**inputs, **generation_args)

generate_ids = generate_ids[:, inputs["input_ids"].shape[-1] :]
response = processor.decode(generate_ids[0], skip_special_tokens=True).strip()

print(response)

使用本仓库中的本地 Transformers 代码进行推理

如果您想调试我们的模型，我们也提供了本地推理代码。您可以运行以下代码来加载模型。

from magma.processing_magma import MagmaProcessor
from magma.modeling_magma import MagmaForCausalLM

dtype = torch.bfloat16
model = MagmaForCausalLM.from_pretrained("microsoft/Magma-8B", trust_remote_code=True, torch_dtype=dtype)
processor = MagmaProcessor.from_pretrained("microsoft/Magma-8B", trust_remote_code=True)
model.to("cuda")

使用 bitsandbytes 进行推理

我们还提供了一个使用 bitsandbytes 进行推理的示例代码。您可以运行以下代码来加载模型。

from PIL import Image
import torch
from transformers import AutoModelForCausalLM
from transformers import AutoProcessor 
from transformers import BitsAndBytesConfig

# 定义量化配置
quantization_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_compute_dtype=torch.float16,
    bnb_4bit_use_double_quant=True,
    bnb_4bit_quant_type="nf4"
)

# 加载带有量化配置的模型
model = AutoModelForCausalLM.from_pretrained(
    "microsoft/Magma-8B", 
    trust_remote_code=True,
    device_map={"": 0},  # 强制所有内容加载到 GPU 0
    quantization_config=quantization_config
)
processor = AutoProcessor.from_pretrained("microsoft/Magma-8B", trust_remote_code=True)

# 推理
image = Image.open("assets/images/magma_logo.jpg").convert("RGB")

convs = [
    {"role": "system", "content": "你是一个能看、能说、能行动的智能体。"},            
    {"role": "user", "content": "<image_start><image><image_end>\n机器人上是什么字母？"},
]
prompt = processor.tokenizer.apply_chat_template(convs, tokenize=False, add_generation_prompt=True)
inputs = processor(images=[image], texts=prompt, return_tensors="pt")
inputs['pixel_values'] = inputs['pixel_values'].unsqueeze(0)
inputs['image_sizes'] = inputs['image_sizes'].unsqueeze(0)

# 将输入转换为正确的设备和数据类型
inputs = {k: v.to(device=model.device, dtype=torch.float16 if v.dtype == torch.float32 else v.dtype) 
          for k, v in inputs.items()}

generation_args = { 
    "max_new_tokens": 500, 
    "temperature": 0.0, 
    "do_sample": False, 
    "use_cache": True,
    "num_beams": 1,
} 

with torch.inference_mode():
    generate_ids = model.generate(**inputs, **generation_args)

generate_ids = generate_ids[:, inputs["input_ids"].shape[-1] :]
response = processor.decode(generate_ids[0], skip_special_tokens=True).strip()
print(response)

基准测试

我们对模型在使用和不使用 bitsandbytes 情况下的推理时间和内存占用进行了基准测试。

使用 lmms-eval 进行评估

请参阅 lmms-eval-instruction 以获取使用 lmms-eval 工具包进行评估的详细说明。

一切准备就绪后，您可以在根目录下运行以下代码来评估我们的模型。

sh scripts/evaluation/lmms-eval/lmms_eval_magma.sh

您可以通过修改变量 eval_tasks 来评估其他基准。运行以下代码可以查看 eval_tasks 的列表：

# lmms-eval --tasks {list_groups,list_subtasks,list_tags,list}
lmms-eval --tasks list_groups

使用 SimplerEnv 进行评估

请参阅 SimplerEnv-instruction 以获取使用 SimplerEnv 工具包进行评估的详细说明。

一切准备就绪后，您可以通过运行以下代码来评估我们的模型。

sh scripts/evaluation/simplerenv/bridge.sh

多张图片或视频支持

对于我们的模型来说，处理多张图片非常简单。您只需在文本提示中重复占位符，并相应地将所有图片添加到列表中即可。一个示例代码如下：

convs = [
    {"role": "system", "content": "你是一个能看、能说、能行动的智能体。"},            
    {"role": "user", "content": "<image_start><image><image_end>\n<image_start><image><image_end>\n<image_start><image><image_end>\n机器人上是什么字母？"},
]
prompt = processor.tokenizer.apply_chat_template(convs, tokenize=False, add_generation_prompt=True)
inputs = processor(images=[image1,image2,image3], texts=prompt, return_tensors="pt")

我们的模型会自动为您完成视觉标记的填充！

API 服务器

我们提供一个基于 FastAPI 的服务器，用于将 Magma 部署为 REST API 服务，从而实现以下功能：

• 通过 REST 端点进行视觉和语言处理
• 为机器人应用提供动作预测
• 支持 base64 编码的图片以及文件上传

该服务器可以通过三种方式部署：

1. 直接运行：最简单的开发方式
2. Docker 容器：推荐用于生产环境
3. 原生系统服务：适用于系统集成场景

快速入门

cd server
./magma-server.sh run

这将设置一个 conda 环境、安装依赖项，并在端口 8080 上启动服务器。

Docker 部署

cd server
./magma-server.sh docker up

API 端点

API 提供以下端点：

• GET /health - 检查服务器是否运行及模型是否已加载
• POST /predict - 使用 base64 编码的图片进行预测
• POST /predict_from_file - 使用上传的图片文件进行预测

更多详细信息，请参阅 Server README。

代理演示

UI 代理

我们为自己的模型构建了代理模型。首个构建的是 UI 代理演示。由于我们的模型使用 Set-of-Mark 和 Trace-of-Mark 进行预训练，因此与 OmniParser 天然具有协同效应。将两者结合，您即可立即获得一个 UI 代理，运行命令如下：

python agents/ui_agent/app.py

更重要的是，我们的 Magma 模型不仅具备动作接地能力，还拥有多模态理解与推理能力。您不仅可以使用文本让模型预测点击位置：

前往排名第一的帖子

还可以随时提出自由问题！只需在文本提示前加上前缀“Q:”，例如：

Q: 这篇帖子的标题是什么？

游戏代理

我们还构建了一个游戏代理演示。您可以运行以下命令来启动演示：

python agents/gaming_agent/app.py

演示运行后，您将看到一个机器人主动收集绿色方块。

机器人视觉规划

我们也构建了机器人视觉规划演示。您可以运行以下命令来启动演示：

python agents/robot_traj/app.py

在此演示中，您可能会遇到此 issue 中讨论的问题，快速解决方法是运行以下命令：

pip install imageio[ffmpeg]

如果仍然无效，请安装较旧版本的 transformers：

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

用户指南

直接使用

该模型旨在以英语为基础，广泛应用于研究领域。模型接受图像和文本作为输入，并生成文本输出，可用于以下用途：

• 基于图像/视频的文本生成： 模型可以根据输入的文本和图像生成文本（如描述、答案）。
• 视觉规划能力： 模型还可以生成视觉轨迹，作为完成任务的未来规划（如将物体从一处移动到另一处）。
• 智能体能力： 模型还能生成 UI 接地指令（如点击“搜索”按钮）以及机器人操作指令（如机器人夹爪的 7 自由度控制）。

我们的模型仅用于研究目的，旨在促进多模态人工智能领域的知识共享与研究加速，尤其是多模态智能体 AI 方面的研究。

下游应用

该模型可进一步微调以适应不同的下游任务，例如：

• 图像字幕与问答： 我们可以在此模型的基础上，结合多模态大语言模型的流水线，进一步微调用于图像字幕和问答任务。根据我们的实验，该模型在这些任务上表现出色，同时在空间理解与推理方面更具优势。
• 视频字幕与问答： 同样地，我们也可以将其微调用于视频字幕和问答任务。实验表明，该模型在时间理解与推理方面表现优异，性能可与现有最佳模型媲美。
• UI 导航： 该模型还可针对特定的 UI 导航任务进行微调，例如网页导航或移动应用导航。在这些任务上，模型的表现尤为突出。
• 机器人操控： 由于该模型具备视觉-语言-行动一体化的通用智能体能力，因此非常适合进一步微调以应用于机器人任务。微调后，该模型在机器人操控任务上的表现显著优于当前最先进的模型，如 OpenVLA。

偏见、风险与局限性

请注意，该模型并非专门为所有下游用途而设计或评估。开发者在选择具体应用场景时，应充分考虑语言模型的常见局限性，并在实际使用前对准确性、安全性及公平性进行评估与缓解，尤其是在高风险场景下。此外，开发者还需了解并遵守与其应用场景相关的适用法律或法规（包括隐私保护、贸易合规等）。

引用

如果您在研究中使用本模型，请考虑引用以下文献：

@misc{yang2025magmafoundationmodelmultimodal,
      title={Magma: 多模态智能体的基础模型}, 
      author={Jianwei Yang、Reuben Tan、Qianhui Wu、Ruijie Zheng、Baolin Peng、Yongyuan Liang、Yu Gu、Mu Cai、Seonghyeon Ye、Joel Jang、Yuquan Deng、Lars Liden、Jianfeng Gao},
      year={2025},
      eprint={2502.13130},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2502.13130}, 
}

致谢

我们的工作得到了微软研究院的支持。我们感谢所有为构建该项目付出努力的贡献者。

我们的工作建立在一些令人惊叹的开源项目之上，包括 Transformers、LLaVA、OpenVLA、SeeClick、Mind2Web，以及多个优秀的开源数据集，如 Ego4d、Epic-Kitchen、Something-Somethingv2、Open-X-Embodiment。此外，我们还使用了若干评估基准，例如 SimplerEnv 和 Libero。

许可证

本项目采用 MIT 许可证授权。详情请参阅 LICENSE 文件。

贡献

本项目欢迎各类贡献和建议。大多数贡献都需要您签署贡献者许可协议（CLA），以声明您有权并将您的贡献权利授予我们使用。有关详细信息，请访问 https://cla.opensource.microsoft.com。

当您提交拉取请求时，CLA 机器人会自动判断您是否需要提供 CLA，并相应地标记您的 PR（例如添加状态检查或评论）。您只需按照机器人提供的指示操作即可。对于使用我们 CLA 的所有仓库，您只需完成一次此步骤。

本项目已采纳 微软开源行为准则。更多信息请参阅 行为准则常见问题解答 或发送邮件至 opencode@microsoft.com 咨询更多问题或意见。

商标

本项目可能包含与项目、产品或服务相关的商标或标识。未经授权使用微软商标或标识须遵守并遵循 微软商标与品牌指南。在本项目的修改版本中使用微软商标或标识时，不得造成混淆或暗示微软的赞助关系。任何第三方商标或标识的使用均应遵守该第三方的相关政策。