# TRELLIS.2 4B（3D 模型）

> 本機影像轉 3D：Microsoft 的 TRELLIS.2 4B 能把單張影像變成貼圖完整的 3D 模型（含 UV 貼圖集與 PBR 材質的 GLB），可用於遊戲素材，解析度為 512、1024 或 1536。透過 trellis.cpp 在具備 16 GB 顯示記憶體的 NVIDIA 或 Vulkan GPU 上執行。授權為 MIT，影像編碼器另採 Meta 的 DINOv3 授權。

- ID: `aigd.model3d-trellis2-4b`
- 來源: 官方 (第一方 `aigd.*`)
- 分類: 3D
- 發佈者: AI Game Dev (`aigd`), 已驗證
- 最新版本: 1.0.5 (發佈於 2026-11-22)
- 授權條款: SEE LICENSE IN README.md
- 需要 AI Game Dev 應用程式: `>=0.32.0-beta.6`
- 原生程式碼: 否
- 評分: 尚無評分
- HTML 頁面: https://ai-game.dev/zh-hant/packages/aigd.model3d-trellis2-4b

## 安裝

在專案資料夾中，使用 gamedev CLI：

```bash
gamedev pkg add aigd.model3d-trellis2-4b
```

在桌面應用程式中：開啟「套件」視窗（狀態列上的套件圖示），選擇 **瀏覽**，搜尋 `aigd.model3d-trellis2-4b`，然後點 **加入專案**。更多資訊：https://ai-game.dev/docs/wiki/app/packages

## 版本

| 版本 | 發佈日期 | 需要應用程式 | 備註 |
|---|---|---|---|
| 1.0.5 | 2026-11-22 | `>=0.32.0-beta.6` | 最新 |
| 1.0.4 | 2026-11-21 | `>=0.32.0-beta.6` | - |

## 說明

````markdown
# TRELLIS.2 4B (`aigd.model3d-trellis2-4b`)

TRELLIS.2 4B 是 Microsoft 的 [TRELLIS.2](https://huggingface.co/microsoft/TRELLIS.2-4B) 影像轉 3D 模型。它能把單張影像變成貼圖完整的 3D 模型：一個含 UV 貼圖集與 PBR 材質（基礎色、金屬度、粗糙度）的 GLB，在解析度 1024 下約有 300,000 個面。在 AI Game Dev 中，它會透過 **[Local 3D generation](https://ai-game.dev/packages/aigd.trellis)**（`aigd.trellis`，trellis.cpp）在你的 GPU 上執行，需要具備 16 GB 顯示記憶體的 NVIDIA（CUDA）或 Vulkan GPU。它適合想從概念美術取得貼圖素材、又不想依賴雲端服務的開發者。

## 你可以製作的內容

- 從一張照片或概念圖，做出帶貼圖、可直接用於 PBR 的道具、武器、家具、載具與角色。
- 從一般照片生成模型：背景會自動去除（BiRefNet）。
- 解析度 512 的較輕量草稿，或 1536 的更精細模型。

## 範例指令

- 「用 TRELLIS.2 把 `Concepts/potion.png` 變成貼圖完整的 3D 模型。」
- 「先把我這台舊收音機的這張照片做成解析度 512 的貼圖 GLB，好讓我快速確認一下。」
- 「以 1536 解析度生成騎士概念的 3D 模型。」

## 重點特色

|  |  |
|---|---|
| 模型 ID | `aigd.model3d-trellis2-4b.f16` |
| 操作 | 影像轉 3D（單張 PNG 或 JPEG 影像） |
| 輸出 | 含 UV 貼圖集與 PBR 材質的貼圖 GLB（PNG 貼圖） |
| 解析度 | 512、1024（預設）、1536 |
| 步數 | 預設 12 |
| 執行環境 | 具備 16 GB 顯示記憶體的 NVIDIA（CUDA）或 Vulkan GPU |
| 下載 | 16.5 GB，10 個檔案 |
| 授權 | MIT；DINOv3 編碼器採用 Meta 的 DINOv3 License |

## TRELLIS.2 或 Pixal3D

兩者都在 [Local 3D generation](https://ai-game.dev/packages/aigd.trellis) 上執行，並產生貼圖 GLB。

- **TRELLIS.2 4B**（本套件）：基礎模型，另外提供較輕量的 512 解析度。
- **[Pixal3D](https://ai-game.dev/packages/aigd.model3d-pixal3d)**：Tencent ARC 以 TRELLIS.2 微調的版本，會更貼近照片的輪廓；僅支援 1024 與 1536 解析度。它與 TRELLIS.2 共用 3.5 GB 的檔案，因此兩者合計約 27 GB。

若要在 NVIDIA GPU 上取得無貼圖網格，請參閱 [TripoSG](https://ai-game.dev/packages/aigd.model3d-triposg)、[Hunyuan3D-2.1 Shape](https://ai-game.dev/packages/aigd.model3d-hunyuan3d-2-1-shape) 與 [Step1X-3D Geometry](https://ai-game.dev/packages/aigd.model3d-step1x-3d-geometry)。

## 限制與實測

- **輸入：** 一張 PNG 或 JPEG 影像，內容為單一物件。背景會自動去除（BiRefNet），因此一般照片也能用；本身已含透明度的影像會保留其透明度。
- **輸出：** 一個完整的獨立 GLB（PNG 貼圖）。
- **解析度：** 512（較輕量）、1024（預設，512→1024 串接流程）、1536。
- **一律貼圖：** 不提供僅產生幾何的執行模式。trellis.cpp v0.8.1 只在貼圖時簡化網格，因此若不貼圖，它會寫出原始解碼網格（實測 15.67 百萬個面），超出應用程式的 GLB 限制。沒有任何執行期旗標能在其他情況下簡化網格。
- **非位元一致：** 相同的影像、種子與設定不會產生位元一致的 GLB。兩次以種子 42 執行的 CUDA 執行都產生了有效的 GLB，但幾何與 SHA-256 雜湊不同；記錄下來的種子僅代表該次請求的設定。
- **硬體：** 具備 **16 GB** 顯示記憶體的 NVIDIA（CUDA）或 Vulkan GPU。上游指出 1024 串接流程可在 16 GB 顯示卡上執行，並在 RTX 5060 Ti 16 GB 上實測每個模型 3:16–7:23（Radeon 8060S iGPU 為 6:09–12:39），已包含模型載入時間。
- **下載：** 16.5 GB，10 個檔案。

在 Windows 上搭配 RTX 4090，以種子 42、12 步生成一張影像，得到以下端到端時間與整張裝置的 VRAM 峰值。起始 VRAM 用量為 3,676–4,819 MiB。

| 後端 | 解析度 | 時間 | VRAM 峰值 |
|---|---:|---:|---:|
| CUDA | 512 | 60.77 s | 7,321 MiB |
| CUDA | 1024 | 290.88 s | 10,166 MiB |
| CUDA | 1536 | 687.35 s | 14,857 MiB |
| Vulkan | 512 | 147.04 s | 7,558 MiB |
| Vulkan | 1024 | 710.54 s | 13,447 MiB |

## 下載內容

全部來自 [`ilintar/trellis2-gguf`](https://huggingface.co/ilintar/trellis2-gguf) 的修訂版 `a57397bd3d351599d9729fc144b3f87c3f87d65b`（F16 權重、F32 正規化參數），並以 sha256 校驗：

| 檔案 | 內容說明 | 來源模型 | 授權 |
|---|---|---|---|
| `ss_flow`, `shape_flow_512`, `shape_flow_1024`, `tex_flow_512`, `tex_flow_1024` | 三個階段的 1.3B flow transformer（形狀與貼圖各有兩種解析度） | [microsoft/TRELLIS.2-4B](https://huggingface.co/microsoft/TRELLIS.2-4B) | MIT |
| `shape_dec`, `tex_dec` | 形狀與貼圖解碼器 | microsoft/TRELLIS.2-4B | MIT |
| `ss_dec` | 稀疏結構解碼器 | [microsoft/TRELLIS-image-large](https://huggingface.co/microsoft/TRELLIS-image-large) | MIT |
| `dinov3` | DINOv3 ViT-L/16 影像編碼器 | [timm/vit_large_patch16_dinov3.lvd1689m](https://huggingface.co/timm/vit_large_patch16_dinov3.lvd1689m)（Meta 的 DINOv3） | [DINOv3 License](https://ai.meta.com/resources/models-and-libraries/dinov3-license/) |
| `birefnet` | 背景移除 | [ZhengPeng7/BiRefNet](https://huggingface.co/ZhengPeng7/BiRefNet) | MIT |

## 授權

TRELLIS.2 為 **MIT** 授權：允許商業使用，你產生的內容歸你所有（由於下方 DINOv3 編碼器的使用限制，應用程式會在下載前請你接受授權）。有一個元件不是 MIT：

- **DINOv3 影像編碼器**（`dinov3.gguf`）——Meta 的 [DINOv3 License](https://ai.meta.com/resources/models-and-libraries/dinov3-license/)（2025 年 8 月 14 日）。這是全球適用、免費且免權利金的授權，允許商業使用，但附帶以下條件：
  - 若你散布此編碼器或其衍生物，必須附上 DINOv3 License 的副本，並在相關網站、使用者介面、部落格文章、關於頁面或產品文件中**顯著展示 "Built with DINOv3"**。
  - 不得用於受 ITAR 規範的活動，或受貿易管制禁止的最終用途：軍事或戰爭、核子產業或應用、間諜活動，以及槍械與非法武器。你不得為貿易制裁的對象。
  - 不得對底層元件進行逆向工程。若你違反授權，或就這些素材對 Meta 提起訴訟，Meta 可終止授權。
- GGUF 儲存庫 `ilintar/trellis2-gguf` 宣告授權為「other」，並指向來源模型；它本身不附加任何條款。
- Meta 的授權頁面（2025 年 8 月 14 日，上方已連結）包含 "Built with DINOv3" 義務；隨 DINOv3 程式碼附上的副本（2025 年 8 月 19 日）則沒有。本套件遵循較嚴格的那一份。

必要的署名文字：

> TRELLIS.2 © Microsoft Corporation (MIT). Built with DINOv3 (DINOv3 License, © Meta Platforms).
> BiRefNet © ZhengPeng7 (MIT).

限制簡單來說：上述的 DINOv3 署名要求，以及其軍事／武器／貿易管制禁令。沒有營收上限、沒有地區限制、沒有浮水印。

所有檔案皆從 Hugging Face 下載。AI Game Dev 不代為託管。下載模型即表示你接受這些授權。
````
