Vggt Mps

🚀 VGGT-MPS：适用于苹果硅芯片的3D视觉代理

🍎 VGGT（视觉几何基础变换器）借助金属性能着色器（MPS）为苹果硅芯片进行了优化

利用Facebook Research的VGGT模型，将单视图或多视图图像转换为丰富的3D重建结果，现在该模型在M1/M2/M3 Mac上得到了加速。

🚀 快速开始

安装选项

选项A：从PyPI安装（即将推出）

# 从PyPI安装（发布后）
pip install vggt-mps

# 下载模型权重（5GB）
vggt download

选项B：使用UV从源代码安装（推荐用于开发）

git clone https://github.com/jmanhype/vggt-mps.git
cd vggt-mps

# 使用uv安装（比pip快10 - 100倍！）
make install

# 或者手动使用uv安装
uv pip install -e .

选项C：使用传统pip从源代码安装

git clone https://github.com/jmanhype/vggt-mps.git
cd vggt-mps

# 创建虚拟环境
python -m venv vggt-env
source vggt-env/bin/activate

# 安装依赖项
pip install -r requirements.txt

2. 下载模型权重

# 下载5GB的VGGT模型
vggt download

# 或者如果从源代码运行：
python main.py download

或者手动从 Hugging Face 下载。

3. 测试MPS支持

# 测试MPS加速
vggt test --suite mps

# 或者从源代码运行：
python main.py test --suite mps

预期输出：

✅ MPS（金属性能着色器）可用！
   在苹果硅芯片GPU上运行
✅ 模型权重已加载到mps
✅ MPS操作正常工作！

4. 设置环境（可选）

# 复制环境配置
cp .env.example .env

# 使用您的设置编辑.env
nano .env

✨ 主要特性

v2.0.0版本新特性

🎯 重大更改

• 统一的CLI：新增vggt命令，包含用于所有操作的子命令。
• 专业打包：通过pyproject.toml实现可用于PyPI的打包，具有正确的src布局。
• Web界面：使用Gradio UI进行交互式3D重建（vggt web）。
• 增强测试：全面的测试套件，包含MPS和稀疏注意力测试。
• 现代工具：支持UV，使用Makefile自动化，具备GitHub Actions CI/CD。

🚀 核心特性

• MPS加速：使用金属性能着色器在苹果硅芯片上实现全GPU加速。
• ⚡ 稀疏注意力：实现O(n)内存扩展，适用于城市规模的重建（节省100倍内存！）。
• 🎥 多视图3D重建：从图像生成深度图、点云和相机位姿。
• 🔧 MCP集成：模型上下文协议服务器，用于与Claude Desktop集成。
• 📦 5GB模型：高效的10亿参数模型，在苹果硅芯片上运行流畅。
• 🛠️ 多种导出格式：支持PLY、OBJ、GLB格式的3D点云导出。

VGGT的功能

VGGT通过预测以下内容从图像中重建3D场景：

• 深度图：逐像素深度估计。
• 相机位姿：6自由度相机参数。
• 3D点云：密集的3D重建。
• 置信度图：预测的可靠性得分。

📦 安装指南

安装选项

选项A：从PyPI安装（即将推出）

# 从PyPI安装（发布后）
pip install vggt-mps

# 下载模型权重（5GB）
vggt download

选项B：使用UV从源代码安装（推荐用于开发）

git clone https://github.com/jmanhype/vggt-mps.git
cd vggt-mps

# 使用uv安装（比pip快10 - 100倍！）
make install

# 或者手动使用uv安装
uv pip install -e .

选项C：使用传统pip从源代码安装

git clone https://github.com/jmanhype/vggt-mps.git
cd vggt-mps

# 创建虚拟环境
python -m venv vggt-env
source vggt-env/bin/activate

# 安装依赖项
pip install -r requirements.txt

下载模型权重

# 下载5GB的VGGT模型
vggt download

# 或者如果从源代码运行：
python main.py download

或者手动从 Hugging Face 下载。

测试MPS支持

# 测试MPS加速
vggt test --suite mps

# 或者从源代码运行：
python main.py test --suite mps

预期输出：

✅ MPS（金属性能着色器）可用！
   在苹果硅芯片GPU上运行
✅ 模型权重已加载到mps
✅ MPS操作正常工作！

设置环境（可选）

# 复制环境配置
cp .env.example .env

# 使用您的设置编辑.env
nano .env

💻 使用示例

基础用法

处理图像

from src.tools.readme import vggt_quick_start_inference

result = vggt_quick_start_inference(
    image_directory="./tmp/inputs",
    device="mps",  # 使用苹果硅芯片GPU
    max_images=4,
    save_outputs=True
)

提取视频帧

from src.tools.demo_gradio import vggt_extract_video_frames

result = vggt_extract_video_frames(
    video_path="input_video.mp4",
    frame_interval_seconds=1.0
)

创建3D场景

from src.tools.demo_viser import vggt_reconstruct_3d_scene

result = vggt_reconstruct_3d_scene(
    images_dir="./tmp/inputs",
    device_type="mps",
    confidence_threshold=0.5
)

高级用法

稀疏注意力的使用

from src.vggt_sparse_attention import make_vggt_sparse

# 一行代码将任何VGGT转换为稀疏版本
sparse_vggt = make_vggt_sparse(regular_vggt, device="mps")

# 相同的用法，内存复杂度从O(n²)变为O(n)
output = sparse_vggt(images)  # 可处理1000张以上的图像！

📚 详细文档

CLI命令（v2.0.0）

所有功能都可以通过统一的vggt命令访问：

# 使用示例图像进行快速演示
vggt demo

# 使用厨房数据集进行演示（4张图像）
vggt demo --kitchen --images 4

# 处理您自己的图像
vggt reconstruct data/*.jpg

# 对大场景使用稀疏注意力
vggt reconstruct --sparse data/*.jpg

# 导出为特定格式
vggt reconstruct --export ply data/*.jpg

# 启动交互式Web界面
vggt web

# 在特定端口上打开并提供公共链接
vggt web --port 8080 --share

# 运行全面测试
vggt test --suite all

# 专门测试稀疏注意力
vggt test --suite sparse

# 进行性能基准测试
vggt benchmark --compare

# 下载模型权重
vggt download

从源代码运行（开发）

如果不进行安装直接从源代码运行：

python main.py demo
python main.py reconstruct data/*.jpg
python main.py web
python main.py test --suite mps
python main.py benchmark --compare

MCP服务器集成

添加到Claude Desktop

1. 编辑~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "vggt-agent": {
      "command": "uv",
      "args": [
        "run",
        "--python",
        "/path/to/vggt-mps/vggt-env/bin/python",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "/path/to/vggt-mps/src/vggt_mps_mcp.py"
      ]
    }
  }
}

2. 重启Claude Desktop

可用的MCP工具

• vggt_quick_start_inference - 从图像进行快速3D重建。
• vggt_extract_video_frames - 从视频中提取帧。
• vggt_process_images - 完整的VGGT处理流程。
• vggt_create_3d_scene - 生成GLB格式的3D文件。
• vggt_reconstruct_3d_scene - 多视图重建。
• vggt_visualize_reconstruction - 创建可视化结果。

🔧 技术细节

MPS优化

• 设备检测：自动检测MPS可用性。
• 数据类型选择：使用float32以实现最佳MPS性能。
• 自动混合精度处理：针对MPS禁用CUDA自动混合精度。
• 内存管理：在Metal上进行高效的张量操作。

模型架构

📄 许可证

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

🐛 故障排除

MPS不可用

# 检查PyTorch MPS支持
python -c "import torch; print(torch.backends.mps.is_available())"

模型加载问题

# 验证模型文件
ls -lh repo/vggt/vggt_model.pt
# 应显示约5GB的文件

内存问题

• 减小批量大小。
• 降低分辨率。
• 使用CPU作为后备方案。

📚 参考文献

• VGGT论文
• Facebook Research VGGT
• Hugging Face模型

📚 文档

• 开发指南 - 设置您的开发环境。
• 发布指南 - PyPI发布流程。
• 贡献指南 - 如何进行贡献。
• API文档 - 详细的API参考。
• 示例 - 代码示例和演示。

🚀 发布说明

v2.0.0（最新版本）

• ✨ 统一的CLI，使用vggt命令。
• 📦 专业的Python打包（可用于PyPI）。
• 🌐 Gradio Web界面。
• 🧪 全面的测试套件。
• 🛠️ 现代工具（UV、Makefile、GitHub Actions）。
• 📝 完整的文档更新。

查看 完整更新日志

🤝 贡献

我们遵循轻量级的Git Flow：

• main分支保存最新的稳定版本，并且受到保护。
• develop分支是日常工作的默认集成分支。

贡献时：

1. 从develop分支创建您的功能分支（git switch develop && git switch -c feature/my-change）。
2. 保持提交内容聚焦，并在相关时包含测试或文档更新。
3. 针对develop分支打开拉取请求；维护人员将在发布时将更改合并到main分支。

请在进行大型开发工作之前，针对bug或功能请求创建问题。完整细节、测试期望和发布流程请参阅。

🙏 致谢

• Facebook Research提供VGGT模型。
• 苹果公司提供金属性能着色器。
• PyTorch团队提供MPS后端。

由AI社区为苹果硅芯片打造 🍎