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社區為蘋果硅芯片打造 🍎