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

> 本地图生 3D：微软的 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-hans/packages/aigd.model3d-trellis2-4b

## 安装

使用 gamedev CLI，在项目文件夹中运行：

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

在桌面应用中：打开 Packages 窗口（状态栏中的包图标），选择 **Browse**，搜索 `aigd.model3d-trellis2-4b`，然后点击 **Add to Project**。更多：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 是微软的 [TRELLIS.2](https://huggingface.co/microsoft/TRELLIS.2-4B) 图生 3D 模型。它能把一张图像变成带纹理的 3D 模型：一个带 UV 图集和 PBR 材质（基础色、金属度、粗糙度）的 GLB，在 1024 分辨率下约 30 万个面。在 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)**：腾讯 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 只在贴图时简化网格，因此不带纹理时会写出原始解码网格（实测 1567 万个面），超出了应用的 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 步生成，得到以下端到端耗时和设备级显存峰值。起始显存占用为 3,676–4,819 MiB。

| 后端 | 分辨率 | 耗时 | 显存峰值 |
|---|---:|---:|---:|
| 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 流变换器（形状和纹理各有两个分辨率） | [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 不托管这些文件。你下载模型即表示接受这些许可。
````
