PointLLM：赋能大语言模型理解点云

Runsen Xu  Xiaolong Wang  Tai Wang  Yilun Chen  Jiangmiao Pang*  Dahua Lin 
香港中文大学 上海人工智能实验室 浙江大学

🏠 简介

我们提出了 PointLLM，一个能够理解物体彩色点云的多模态大语言模型。 它能够感知物体类型、几何结构和外观，而无需担心深度模糊、遮挡或视角依赖性问题。我们收集了一个包含 66 万条简单指令对和 7 万条复杂指令对的新数据集，以支持两阶段训练策略。为了严格评估我们模型的感知能力及其泛化能力，我们建立了两个基准测试：生成式 3D 物体分类和 3D 物体描述生成，并通过三种不同的评估方法进行评估。

🔥 新闻

• [2026-03-17] PointLLM-V2 的训练标注已发布在此处。
• [2025-07-06] PointLLM 的改进版本 PointLLM-V2 已被 TPAMI 2025 接收！模型、代码和数据即将发布！🎉
• [2025-04-21] 由于需要将服务器用于其他用途，我们已关闭在线演示。
• [2024-09-06] 我们已上传 PointLLM 用于 ECCV 2024 的最终版本，该版本包含更清晰的表述和额外的实验结果。请查看论文此处。
• [2024-07-01] PointLLM 已被 ECCV 2024 接收，并获得所有“强烈推荐”的评价。🎉 我们正在寻找有自我驱动力的学生进行 PointLLM 相关研究。如果您有兴趣，请将您的简历发送至 runsxu@gmail.com！
• [2023-12-29] 我们发布了在线 Gradio 演示的代码。
• [2023-12-26] 我们发布了模型评估代码，包括 ChatGPT/GPT-4 评估和传统指标评估。
• [2023-12-08] 我们发布了训练代码和 PointLLM-v1.2 模型。在线演示也已升级到 v1.2 版本。请享用！🎉
• [2023-12-01] 我们发布了论文的更新版本（v2），其中包含了额外的基线比较、增强的人工评估指标、改进的模型性能（PointLLM-v1.2）以及其他优化。请查看更新版本此处。
• [2023-10-18] 我们发布了我们的指令跟随数据，包括简单描述指令和复杂指令。下载此处。
• [2023-09-26] 我们发布了推理代码及检查点，以及我们使用的 Objaverse 彩色点云文件。您可以在自己的机器上与 PointLLM 进行对话。
• [2023-08-31] 我们发布了 PointLLM 的论文和一个在线 Gradio 演示。试试看！🎉

📋 目录

• 🤖 在线演示
• 💬 对话示例
• 🔍 概述
• 📦 训练与评估
• 📝 待办事项
• 🔗 引用
• 📄 许可证
• 📚 相关工作
• 👏 致谢

💬 对话示例

对话 1	对话 2	对话 3	对话 4

🔍 概述

模型

点云编码器从输入点云中提取特征，并将其投影到 LLM 骨干网络的潜在空间中。LLM 骨干网络处理点云标记和文本标记序列，并生成预测标记作为输出。

实验结果

与基线的定量比较。

更多结果请参阅我们的论文。

!!!注意：传统指标如 BLEU-1、ROUGE-L 和 METEOR 倾向于偏好较短的回复，可能无法有效捕捉语义准确性。有关此问题的详细讨论，请参阅我们的论文。我们建议社区不要仅依赖这些指标进行评估。

与基线的定性比较。

更多结果请参阅我们的论文。

📦 训练与评估

安装

我们在以下环境中测试了我们的代码：

• Ubuntu 20.04
• NVIDIA 驱动程序：515.65.01
• CUDA 11.7
• Python 3.10.13
• PyTorch 2.0.1
• Transformers 4.28.0.dev(transformers.git@cae78c46)

开始步骤：

1. 克隆此仓库。

git clone git@github.com:OpenRobotLab/PointLLM.git
cd PointLLM

2. 安装包

conda create -n pointllm python=3.10 -y
conda activate pointllm
pip install --upgrade pip  # 启用 PEP 660 支持
pip install -e .

# * 用于训练
pip install ninja
pip install flash-attn

数据准备

Objaverse 训练数据

1. 从此处下载 660K 个 Objaverse 彩色点云的两个压缩文件。它们大约需要 77GB 的存储空间。
2. 运行以下命令将两个文件合并为一个并解压缩。这将生成一个名为 8192_npy 的文件夹，其中包含 660K 个名为 {Objaverse_ID}_8192.npy 的点云文件。每个文件都是一个维度为 (8192, 6) 的 numpy 数组，其中前三个维度是 xyz，后三个维度是 rgb，范围在 [0, 1] 内。

cat Objaverse_660K_8192_npy_split_a* > Objaverse_660K_8192_npy.tar.gz
tar -xvf Objaverse_660K_8192_npy.tar.gz

3. 在 PointLLM 文件夹中，创建一个 data 文件夹，并在该目录中创建指向解压文件的软链接。

cd PointLLM
mkdir data
ln -s /path/to/8192_npy data/objaverse_data

指令遵循数据

1. 在 PointLLM/data 文件夹中，创建一个名为 anno_data 的目录。
2. 我们的指令遵循数据，包括简单描述和复杂指令，可以从此处下载。如果您下载数据有困难（例如网络问题），请通过电子邮件联系作者。

• 简单描述数据有 660K 个样本，复杂指令有 70K 个样本。
• 两种训练数据都基于 Objaverse 数据集。
• 复杂指令是使用 GPT-4 生成的。

3. 将数据文件放入 anno_data 目录。目录结构应如下所示：

PointLLM/data/anno_data
├── PointLLM_brief_description_660K_filtered.json
├── PointLLM_brief_description_660K.json
└── PointLLM_complex_instruction_70K.json

4. 请注意，PointLLM_brief_description_660K_filtered.json 是从 PointLLM_brief_description_660K.json 过滤而来，移除了我们保留的 3000 个对象作为验证集。如果您想复现我们论文中的结果，应使用 PointLLM_brief_description_660K_filtered.json 进行训练。PointLLM_complex_instruction_70K.json 包含来自训练集的对象。
5. 如果您想自己生成复杂指令，请参考我们的论文了解其他细节。系统提示位于 pointllm/data/data_generation/system_prompt_gpt4_0613.txt。
6. [可选] PointLLM-V2 的标注可在 PointLLM_V2_Stage1_1M_filtered.json 和 PointLLM_V2_Stage2_700k_filtered.json 获取。您需要从 Objaverse-XL 此处 下载额外的点云。

评估数据

1. 从此处下载我们用于 Objaverse 数据集基准测试的参考真值 PointLLM_brief_description_val_200_GT.json，并将其放入 PointLLM/data/anno_data。我们还提供了训练期间过滤的 3000 个对象 ID 此处 及其对应的参考真值 此处，可用于对所有 3000 个对象进行评估。
2. 在 PointLLM/data 中创建一个名为 modelnet40_data 的目录。从此处下载 ModelNet40 点云的测试分割 modelnet40_test_8192pts_fps.dat，并将其放入 PointLLM/data/modelnet40_data。

训练

下载初始 LLM 和点编码器权重

1. 在 PointLLM 文件夹中，创建一个名为 checkpoints 的目录。
2. 下载预训练的 LLM 和点编码器：PointLLM_7B_v1.1_init 或 PointLLM_13B_v1.1_init。将它们放入 checkpoints 目录。
3. 请注意，上述 "v1.1" 表示我们使用 Vicuna-v1.1 检查点，您无需再次下载原始的 LLaMA 权重。

开始训练

1. 对于第一阶段训练，只需运行：

cd PointLLM
scripts/PointLLM_train_stage1.sh

2. 第一阶段训练完成后，开始第二阶段训练：

scripts/PointLLM_train_stage2.sh

PointLLM-v1.1 与 PointLLM-v1.2

通常，您无需关心以下内容。它们仅用于复现我们 v1 论文（PointLLM-v1.1）中的结果。如果您想与我们的模型进行比较或将我们的模型用于下游任务，请使用性能更好的 PointLLM-v1.2（参考我们的 v2 论文）。

以下步骤用于复现 PointLLM-v1.1（点击展开）

1. PointLLM v1.1 和 v1.2 使用略有不同的预训练点编码器和投影器。如果您想复现 PointLLM v1.1，请编辑初始 LLM 和点编码器权重目录中的 config.json 文件，例如 vim checkpoints/PointLLM_7B_v1.1_init/config.json。

2. 更改键 "point_backbone_config_name" 以指定另一个点编码器配置：

   # 从
   "point_backbone_config_name": "PointTransformer_8192point_2layer" # v1.2
   # 改为
   "point_backbone_config_name": "PointTransformer_base_8192point", # v1.1
   

3. 编辑 scripts/train_stage1.sh 中点编码器的检查点路径：

   # 从
   point_backbone_ckpt=$model_name_or_path/point_bert_v1.2.pt # v1.2
   # 改为
   point_backbone_ckpt=$model_name_or_path/point_bert_v1.1.pt # v1.1
   

聊天

1. 训练好的模型检查点可在此处获取（包括不同版本的 PointLLM）。
2. 运行以下命令，使用 torch.float32 数据类型启动聊天机器人，以讨论 Objaverse 的 3D 模型。模型检查点将自动下载。您也可以手动下载模型检查点并指定其路径。示例如下：

cd PointLLM
PYTHONPATH=$PWD python pointllm/eval/PointLLM_chat.py --model_name RunsenXu/PointLLM_7B_v1.2 --data_name data/objaverse_data --torch_dtype float32

3. 您也可以轻松修改代码以使用 Objaverse 以外的点云，只要输入模型的点云维度为 (N, 6)，其中前三个维度是 xyz，后三个维度是 rgb（范围在 [0, 1] 内）。您可以将点云采样为 8192 个点，因为我们的模型是在此类点云上训练的。

4. 下表显示了不同模型和数据类型的 GPU 要求。如果适用，我们推荐使用 torch.bfloat16，这也是我们论文实验中使用的数据类型。

   模型	数据类型	GPU 内存
   PointLLM-7B	torch.float16	14GB
   PointLLM-7B	torch.float32	28GB
   PointLLM-13B	torch.float16	26GB
   PointLLM-13B	torch.float32	52GB

Gradio 演示

1. 我们提供了在线 Gradio 演示的代码。您可以运行以下命令在本地启动演示，进行聊天和可视化。

cd PointLLM
PYTHONPATH=$PWD python pointllm/eval/chat_gradio.py --model_name RunsenXu/PointLLM_7B_v1.2 --data_path data/objaverse_data

2. 温馨提示：如果您想在公共环境中发布演示，请参考 https://www.gradio.app/guides/sharing-your-app#security-and-file-access。

评估

推理

1. 运行以下命令进行推理。
2. 在不同基准测试上进行推理的不同命令（以 PointLLM_7B_v1.2 为例）：

cd PointLLM
export PYTHONPATH=$PWD

# Objaverse 上的开放词汇分类
python pointllm/eval/eval_objaverse.py --model_name RunsenXu/PointLLM_7B_v1.2 --task_type classification --prompt_index 0 # 或 --prompt_index 1

# Objaverse 上的物体描述生成
python pointllm/eval/eval_objaverse.py --model_name RunsenXu/PointLLM_7B_v1.2 --task_type captioning --prompt_index 2

# ModelNet40 上的闭集零样本分类
python pointllm/eval/eval_modelnet_cls.py --model_name RunsenXu/PointLLM_7B_v1.2 --prompt_index 0 # 或 --prompt_index 1

3. 请检查这两个脚本的默认命令行参数。您可以指定不同的提示词、数据路径和其他参数。
4. 推理后，结果将以以下格式的字典形式保存在 {model_name}/evaluation 中：

{
  "prompt": "",
  "results": [
    {
      "object_id": "",
      "ground_truth": "", 
      "model_output": "",
      "label_name": "" # 仅用于 modelnet40 分类
    }
  ]
}

ChatGPT/GPT-4 评估

1. 在 https://platform.openai.com/api-keys 获取您的 OpenAI API 密钥。
2. 运行以下命令，使用 ChatGPT/GPT-4 并行评估模型输出（大约花费 1.5 到 2.2 美元）。

cd PointLLM
export PYTHONPATH=$PWD
export OPENAI_API_KEY=sk-****

# Objaverse 上的开放词汇分类
python pointllm/eval/evaluator.py --results_path /path/to/model_output --model_type gpt-4-0613 --eval_type open-free-form-classification --parallel --num_workers 15

# Objaverse 上的物体描述生成
python pointllm/eval/evaluator.py --results_path /path/to/model_output --model_type gpt-4-0613 --eval_type object-captioning --parallel --num_workers 15

# ModelNet40 上的闭集零样本分类
python pointllm/eval/evaluator.py --results_path /path/to/model_output --model_type gpt-3.5-turbo-0613 --eval_type modelnet-close-set-classification --parallel --num_workers 15

3. 评估脚本支持中断和恢复。您可以在任何时候使用 Ctrl+C 中断评估过程。这将保存临时结果。如果评估过程中发生错误，脚本也会保存当前状态。您可以通过再次运行相同的命令从上次中断的地方恢复评估。
4. 评估结果将以另一个字典的形式保存在 {model_name}/evaluation 中。 部分指标解释如下：

"average_score": 我们在论文中报告的 GPT 评估的描述生成分数。
"accuracy": 我们在论文中报告的分类准确率，包括当模型输出模糊或模棱两可以及 ChatGPT 输出 "INVALID" 时，ChatGPT 所做的随机选择。
"clean_accuracy": 移除那些 "INVALID" 输出后的分类准确率。
"total_predictions": 预测总数。
"correct_predictions": 正确预测数。
"invalid_responses": ChatGPT 输出的 "INVALID" 数量。

# 调用 OpenAI API 的一些其他统计信息
"prompt_tokens": ChatGPT/GPT-4 提示词的总令牌数。
"completion_tokens": ChatGPT/GPT-4 完成结果的总令牌数。
"GPT_cost": 整个评估过程的 API 成本，以美元计 💵。

5. 一步式评估。 您也可以在推理后立即开始评估，通过传递 --start_eval 标志并指定 --gpt_type。例如：

python pointllm/eval/eval_objaverse.py --model_name RunsenXu/PointLLM_7B_v1.2 --task_type classification --prompt_index 0 --start_eval --gpt_type gpt-4-0613

传统指标评估

1. 对于物体描述生成任务，运行以下命令，使用传统指标评估模型输出，包括 BLEU、ROUGE、METEOR、Sentence-BERT 和 SimCSE。

python pointllm/eval/traditional_evaluator.py --results_path /path/to/model_captioning_output

2. 请注意，我们不建议使用 BLEU、ROUGE 和 METEOR 进行评估，因为它们偏向于短描述，并且在捕捉语义准确性和多样性方面存在不足。

📝 待办事项列表

• 添加带有检查点的推理代码。
• 发布指令遵循数据。
• 添加训练代码。
• 添加评估代码。
• 添加 gradio 演示代码。
• 发布具有更好模型和数据的 PointLLM-V2。

欢迎社区贡献！👇 如果您需要任何支持，请随时提出问题或联系我们。

• 支持 Phi-2 LLM，使 PointLLM 更易于社区使用。
• 支持 InternLM 等中文 LLM。

🔗 引用

如果您觉得我们的工作和此代码库有帮助，请考虑给这个仓库点个星 🌟 并引用：

@inproceedings{xu2024pointllm,
  title={PointLLM: Empowering Large Language Models to Understand Point Clouds},
  author={Xu, Runsen and Wang, Xiaolong and Wang, Tai and Chen, Yilun and Pang, Jiangmiao and Lin, Dahua},
  booktitle={ECCV},
  year={2024}
}

📄 许可证

本作品遵循 知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议。

📚 相关工作

让我们携手，共同推动面向 3D 的大语言模型（LLM）发展！

• Point-Bind & Point-LLM：将点云与 Image-Bind 对齐，并利用 ImageBind-LLM 来推理多模态输入，而无需 3D 指令数据训练。
• 3D-LLM：使用 2D 基础模型来编码 3D 点云的多视图图像。

👏 致谢

• LLaVA：我们的代码库基于 LLaVA 构建。
• Vicuna：我们使用了 Vicuna-7B 和 Vicuna-13B 的检查点。
• Objaverse：我们使用 Objaverse 数据集的模型进行训练和评估。
• Cap3D：我们使用 Cap3D 的标注数据来生成我们的数据。
• ULIP-2：我们使用 ULIP-2 来预训练我们的点云编码器。

PointLLM 快速上手指南

PointLLM 是一个能够理解彩色物体点云的多模态大语言模型。本指南将帮助您快速完成环境配置、安装和基本使用。

环境准备

系统要求

• 操作系统: Ubuntu 20.04
• 显卡驱动: NVIDIA Driver 515.65.01 或更高版本
• CUDA: 11.7
• Python: 3.10.13

前置依赖

• PyTorch 2.0.1
• Transformers 4.28.0.dev (特定版本)

安装步骤

1. 克隆仓库

   git clone git@github.com:OpenRobotLab/PointLLM.git
   cd PointLLM
   

2. 创建并激活 Conda 环境

   conda create -n pointllm python=3.10 -y
   conda activate pointllm
   

3. 安装依赖包

   pip install --upgrade pip
   pip install -e .
   

   注：如需进行模型训练，还需额外安装以下包

   pip install ninja
   pip install flash-attn
   

数据准备

1. 下载点云数据

从 Hugging Face 下载两个压缩文件（共约 77GB），合并并解压：

cat Objaverse_660K_8192_npy_split_a* > Objaverse_660K_8192_npy.tar.gz
tar -xvf Objaverse_660K_8192_npy.tar.gz

解压后得到 8192_npy 文件夹，内含 66 万个点云文件（.npy 格式，形状为 (8192, 6)）。

2. 创建数据链接

在 PointLLM 目录下创建 data 文件夹，并建立软链接指向解压后的数据：

cd PointLLM
mkdir data
ln -s /path/to/8192_npy data/objaverse_data

请将 /path/to/8192_npy 替换为您的实际解压路径。

3. 下载指令数据

1. 在 PointLLM/data 下创建 anno_data 目录。
2. 从同一 Hugging Face 链接 下载以下三个 JSON 文件，并放入 anno_data 目录：
   • PointLLM_brief_description_660K_filtered.json
   • PointLLM_brief_description_660K.json
   • PointLLM_complex_instruction_70K.json

基本使用（推理）

1. 下载预训练模型

在 PointLLM 目录下创建 checkpoints 文件夹，并从以下链接下载模型权重（如 7B 版本）放入其中：

• PointLLM_7B_v1.1_init

2. 运行推理脚本

项目提供了与模型对话的示例代码。您可以参考 PointLLM 仓库中的推理脚本（例如 inference.py 或相关 demo 代码）来加载模型并与您的点云数据进行交互。基本流程如下：

1. 加载点云数据（.npy 文件）。
2. 使用 PointLLM 模型处理点云。
3. 输入文本指令，获取模型生成的描述或对话回复。

具体推理命令请参考项目 README 中 “Inference” 部分或相关脚本的说明。

模型训练（可选）

如果您需要从头训练或微调模型，请按以下步骤进行：

1. 阶段一训练

运行提供的脚本：

cd PointLLM
scripts/PointLLM_train_stage1.sh

2. 阶段二训练

在阶段一训练完成后，运行：

scripts/PointLLM_train_stage2.sh

注意：训练需要大量计算资源和时间，请确保您的硬件环境满足要求。