TRELLIS-text-large-voxhammer 快速开始教程:10分钟跑通你的第一个文本生成3D模型
TRELLIS-text-large-voxhammer 快速开始教程:10分钟跑通你的第一个文本生成3D模型
TRELLIS-text-large-voxhammer 是微软 TRELLIS 的文本生成3D模型(text-to-3d)权重仓库:只需输入一句文字提示词,就能自动生成带完整几何与材质的大型 3D 资产。本文为面向新手的快速开始教程,带你 10 分钟跑通你的第一个文本生成3D模型。
一、这是什么项目?🧩
TRELLIS-text-large-voxhammer 对应论文《Structured 3D Latents for Scalable and Versatile 3D Generation》中的 TRELLIS Text(L 尺寸)——即文本条件版的大型 3D 生成模型,采用 MIT 许可(详见 README.md)。
和图像版 TRELLIS 相比,它的核心区别在于「条件输入」:
- 文本编码器:
openai/clip-vit-large-patch14,把提示词变成模型可理解的语义向量 - 两段式生成:先生成稀疏结构(Sparse Structure),再生成结构化潜码(SLat),最后解码为 3D 资产
- 三种输出:网格 Mesh(可导出 GLB)、辐射场(PBR 材质)、高斯泼溅(Gaussian Splatting)
- 权重共享:解码器等组件复用图像版
microsoft/TRELLIS-image-large的权重,本仓库只存放两个「文本条件 Flow 模型」
二、仓库目录结构:先看有哪些文件 📦
TRELLIS-text-large-voxhammer/
├── ckpts/ # 文本条件版权重(本仓库核心)
│ ├── ss_flow_txt_dit_L_16l8_fp16.safetensors # 稀疏结构 Flow 模型
│ ├── ss_flow_txt_dit_L_16l8_fp16.json # 对应结构配置
│ ├── slat_flow_txt_dit_L_64l8p2_fp16.safetensors # 结构化潜码 Flow 模型(L 尺寸)
│ └── slat_flow_txt_dit_L_64l8p2_fp16.json # 对应结构配置
├── pipeline.json # 流水线装配配置
└── README.md # 项目说明
两个 Flow 模型各司其职:
| 文件 | 作用 | 对应参数 |
|---|---|---|
| ckpts/ss_flow_txt_dit_L_16l8_fp16.json | 根据文本生成 16³ 稀疏结构 | 粗粒度「形体骨架」 |
| ckpts/slat_flow_txt_dit_L_64l8p2_fp16.json | 根据文本生成 64 分辨率结构化潜码 | model_channels: 1024、num_blocks: 24,L 尺寸主力模型 |
三、核心配置解读:pipeline.json 里藏了什么 🔍
pipeline.json 声明了整个生成流水线 TrellisTextTo3DPipeline,新手只需看懂三块:
1. 本地权重(本仓库提供)
"sparse_structure_flow_model": "ckpts/ss_flow_txt_dit_L_16l8_fp16",
"slat_flow_model": "ckpts/slat_flow_txt_dit_L_64l8p2_fp16"
2. 采样参数(决定生成速度与质量)
- 采样器:
FlowEulerGuidanceIntervalSampler(两级采样共用) steps: 25:每级 25 步 Euler 采样cfg_strength: 7.5:引导强度,越高越贴合提示词cfg_interval: [0.5, 0.95]、rescale_t: 3.0:精细化的引导调度参数
3. 文本条件
text_cond_model: openai/clip-vit-large-patch14
四、快速开始:4 步跑通你的第一个文本生成3D模型 🚀
第 1 步:克隆仓库(含 LFS 权重)
git clone https://gitcode.com/hf_mirrors/FishWoWater/TRELLIS-text-large-voxhammer
cd TRELLIS-text-large-voxhammer
git lfs install && git lfs pull
💡
ckpts/下的.safetensors通过 Git-LFS 存储,务必执行git lfs pull,否则拿到的是指针文件而非真实权重。
第 2 步:准备运行环境
- Python 3.10+,推荐 NVIDIA GPU(L 尺寸模型建议显存 16GB 起步)
- 安装 PyTorch 与 TRELLIS 推理依赖:
pip install torch
pip install diffusers
第 3 步:加载流水线并输入提示词
from diffusers import TrellisTextTo3DPipeline
# 指向本地克隆的仓库,自动读取 pipeline.json 与 ckpts/ 权重
pipeline = TrellisTextTo3DPipeline.from_pretrained(
"./TRELLIS-text-large-voxhammer"
)
# 输入提示词,两段式 Flow 采样自动生成 3D 模型
result = pipeline(prompt="a cute cartoon robot, highly detailed")
# 导出为 GLB 网格文件
result.export_glb("robot.glb")
具体 API 以你所安装版本的官方文档为准;提示词建议用英文,效果更稳定。
第 4 步:查看与使用你的 3D 模型
打开生成的 robot.glb:可用 Blender、Windows 3D Viewer 或任意 glTF 在线预览工具查看,也可以直接用于 Unity、Three.js 等渲染管线。
五、新手常见问题 FAQ ❓
Q1:.safetensors 文件只有几百字节?
是 Git-LFS 指针。执行 git lfs install && git lfs pull 下载真实权重即可。
Q2:生成速度有多快?
两级采样各 25 步,L 尺寸模型在消费级显卡上通常以分钟计;可适当调低 num_inference_steps 换取速度。
Q3:显存不够怎么办? 权重已使用 fp16;仍不足时可换用更小的 TRELLIS 模型,或降低输出分辨率。
Q4:输出除了 Mesh 还能要什么?
pipeline.json 中同时配置了辐射场解码器(slat_decoder_rf,可渲染 PBR 材质)与高斯泼溅解码器(slat_decoder_gs),可按需选择导出格式。
六、小结 ✨
- TRELLIS-text-large-voxhammer = 文本生成3D模型:一句提示词 → 完整 3D 资产(GLB/PBR/高斯泼溅)
- 仓库核心是两个文本条件 Flow 模型(ckpts/)+ 一份流水线配置(pipeline.json)
- 跑通四步:克隆 → 拉取 LFS 权重 → 加载
TrellisTextTo3DPipeline→ 输入提示词导出 GLB
试着换一句更有想象力的提示词,做出属于你的第一个 3D 作品吧!