TRELLIS.2-4B

TRELLIS.2-4B

微软的 4B 图片转 3D 模型，把一张图片变成带 PBR 材质的有纹理 3D 网格，分辨率最高到 1536，适合有大显存 NVIDIA GPU 的人。

由 microsoft 在 Hugging Face 上制作。这些说明是 Mindket 根据它的模型页面和模型卡写的，模型自己的文件和许可证在 Hugging Face 上。

简介

它是什么：TRELLIS.2-4B 是微软把单张图片变成 3D 资产的模型。输出是带 PBR 材质的网格，材质涵盖颜色、不透明度和光线如何反应。模型是一个 40 亿参数的流匹配 Transformer。它在一种叫 O-Voxel 的稀疏体素结构上工作。

O-Voxel 同时存储形状和外观。它能处理开放表面、非流形几何和封闭形状，不需要有损的转换步骤。

适合谁：它适合有强大 NVIDIA GPU、想从图片得到 3D 草稿的 3D 美术师、游戏开发者和研究者。模型卡要求至少 24 GB 的 GPU 显存。

行业 | 谁在用 | 怎么用 | 例子
游戏和媒体 | 3D 美术师 | 把概念图变成起始网格 | 用一张图做出一个道具
产品设计 | 设计师 | 从产品照片起草 3D 模型 | 一个小设备的粗略模型
研究 | 图形学研究者 | 研究稀疏体素生成 | 在几种分辨率下测试
软件 | 开发者 | 把图片转 3D 加入流程 | 工具里的资产生成器

如果你没有 24 GB 的 NVIDIA GPU，或者需要 Windows 环境，可以跳过它，因为模型卡只在 Linux 上测试。

用在哪里：

• 带 NVIDIA GPU 的 Linux，这是测试过的环境
• 装有项目自带 trellis2 库的 Python
• 官方代码仓库，里面有安装步骤
• Windows、macOS 或 Linux，仅用 Python 下载文件

用例 | 谁用 | 得到什么
图片转 3D | 美术师和开发者 | 由一张图片生成的带 PBR 材质的网格
形状约束的纹理生成 | 3D 美术师 | 为输入网格和参考图片生成纹理
网格与 O-Voxel 转换 | 研究者 | 两种形式之间的快速转换

如何设置：先准备好下面这些东西。

• Linux，模型卡称这是唯一测试过的系统
• 至少 24 GB 的 NVIDIA GPU，A100 和 H100 已验证
• 用来编译部分包的 CUDA Toolkit，推荐 12.4 版本
• 用来管理依赖的 Conda，以及 Python 3.8 或更新版本

1. 按官方代码仓库的说明安装并配置依赖。
2. 下载模型文件，或让管线按名称自动获取。
3. 运行下一节的 Python 脚本。

pip install -U huggingface_hub
hf download microsoft/TRELLIS.2-4B

如何使用：你配置好环境，按模型名称加载管线，打开一张图片并运行管线。结果是一个网格，由于渲染器有限制，渲染前可以先简化它。

import os
os.environ['OPENCV_IO_ENABLE_OPENEXR'] = '1'
os.environ["PYTORCH_CUDA_ALLOC_CONF"] = "expandable_segments:True"  # Can save GPU memory
import cv2
import imageio
from PIL import Image
import torch
from trellis2.utils import render_utils
from trellis2.renderers import EnvMap
import o_voxel

# 1. Setup Environment Map
envmap = EnvMap(torch.tensor(
    cv2.cvtColor(cv2.imread('assets/hdri/forest.exr', cv2.IMREAD_UNCHANGED), cv2.COLOR_BGR2RGB),
    dtype=torch.float32, device='cuda'
))

# 2. Load Pipeline
pipeline.cuda()

# 3. Load Image & Run
image = Image.open("assets/example_image/T.png")
mesh = pipeline.run(image)[0]
mesh.simplify(16777216) # nvdiffrast limit

先在 它的密钥设置 里填上你自己的值。

分辨率 | 在 H100 上的时间
512 | 约 3 秒
1024 | 约 17 秒
1536 | 约 60 秒

示例：你对仓库里的示例图片运行脚本。管线返回一个网格，随后的调用会简化它。在 H100 上，512 分辨率运行约需 3 秒，1536 约需 60 秒。

新手与专家：先从最低分辨率开始，它最快，并用一张清楚的单个物体图片。使用结果之前，先检查有没有小孔。

稀疏 3D VAE 把空间下采样 16 倍。一个 1024 立方的资产只被编码成约 9.6K 个潜在词元。模型卡称这样带来的感知质量损失可以忽略。模型是没有偏好对齐的预训练基础模型，所以风格会有变化，你可能需要多试几张输入。

Title: 模型卡中在 H100 上的推理时间
分辨率 512: 3 seconds
分辨率 1024: 17 seconds
分辨率 1536: 60 seconds

配置环境并加载管线
打开一张图片
运行管线
得到带 PBR 材质的网格

注意事项：

• License: MIT
• Cost to run: 来源没有提到费用，但你需要至少 24 GB 的 NVIDIA GPU
• Data it reaches: 它把文件从 Hugging Face 下载到你的机器上，并读取你给它的图片
• Not for: 不经后处理就要求严格防水的几何体，因为原始网格可能有小孔，模型卡提到了填补它们的脚本

Hugging Face 上的数据（2026年11月13日）

• 任务：image to 3d
• 框架：trellis2
• 最近 30 天下载：2,566,439
• 点赞：1,481
• 许可证：mit
• 语言：en
• Quantized versions: 3
• Fine-tunes: 7
• 标签：trellis2, image-to-3d

链接

• 模型：https://huggingface.co/microsoft/TRELLIS.2-4B
• 文件：https://huggingface.co/microsoft/TRELLIS.2-4B/tree/main

获取模型

用 Hugging Face 的命令行下载它的文件：

pip install -U huggingface_hub
hf download microsoft/TRELLIS.2-4B

然后按它的模型卡使用它。这个工具包里没有会自己运行的东西。