用Shap-E生成3D模型时，很多人发现输出结果在Blender或Windows 3D查看器里打开后是一团没有颜色的灰模，纹理完全丢失。这个问题非常典型，而且大概率不是模型权重的问题，而是调用方式和解码参数没配对。Shap-E的架构决定了纹理和几何是两条latent通道，只要其中一条没处理对，最终导出的GLB就会缺贴图。下面从texture_latents的原理讲起，逐层拆解纹理丢失的原因和修复方法。
理解texture_latents：纹理为什么会丢
Shap-E内部有两套latent表示：一套描述几何形状（latent），另一套描述纹理外观（texture_latents）。在调用sample_latents或encode_latents时，如果纹理编码流程没有被正确触发，或者你在扩散采样阶段只保留了形状分支的latent，解码出来的模型自然没有颜色信息。很多人照着官方示例跑没问题，但一旦改成自己的prompt处理逻辑，就顺手把texture相关参数丢掉了。
另一个常见坑是显存不足时的自动降级。部分社区版本在guidance_scale调高后显存吃紧，会在采样时悄悄跳过纹理latent的联合优化，控制台没有任何警告，结果就是形状质量不错但贴图全丢。判断方法很简单：解码后检查模型对象的材质槽，如果base_color_texture字段为空或者是一张纯色图，说明纹理latent在采样阶段就没生成，后面怎么调UV都没用。
正确的做法是确保采样时同时拿到两组latent，并在解码时一起传入。下面是标准流程的代码：
import torch
from shap_e.diffusion.sample import sample_latents
from shap_e.diffusion.gaussian_diffusion import diffusion_from_config
from shap_e.models.download import load_model, load_config
from shap_e.util.notebooks import decode_latent_images
device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
model = load_model('transmitter', device=device)
diffusion = diffusion_from_config(load_config('diffusion'))
# 关键点：xmModel 必须是支持纹理的 transmitter
latents = sample_latents(
batch_size=1,
model=model,
diffusion=diffusion,
guidance_scale=15.0, # 过高可能触发纹理降级，建议 9~15
model_kwargs=dict(texts=['一个红色的皮质沙发']),
progress=True,
)
# 解码时同时处理 texture_latents
for latent in latents:
t = latent if not hasattr(latent, 'texture_latents') else latent
images = decode_latent_images(model, latent, rendering_mode='stf')
注意decode_latent_images内部会自动读取latent对象中包含的texture_latents张量，前提是采样阶段生成了它。如果你用的是encode_latents从已有3D资产编码，也要确认编码器输出包含纹理通道，否则需要在编码时传入带UV和贴图的原始网格。
UV展开与导出GLB的参数设置
即便texture_latents正常，导出环节的UV处理不当同样会让贴图看起来丢失或错乱。Shap-E的decode_latent_mesh返回的网格默认带有UV坐标，但拓扑是通过SDF/MIPNeRF场提取的，UV接缝位置可能在模型导出后与材质贴图对不齐，表现为模型整体着色但花纹被拉伸、镜像或完全糊成一团。
导出GLB时建议显式指定贴图尺寸和材质模式，代码如下：
from shap_e.util.notebooks import decode_latent_mesh
mesh = decode_latent_mesh(model, latents[0])
# 导出 GLB，保留顶点色与贴图
with open('output.glb', 'wb') as f:
mesh.write_glb(f)
# 如果需要 obj + mtl + png，导出前检查贴图通道
with open('output.obj', 'w') as f:
mesh.write_obj(f)
如果你的下游管线要求自己重做UV展开，在Blender中操作时注意三点。第一，展开算法选Smart UV Project而不是Angle Based，因为Shap-E生成的网格三角面很多、面片极小，Angle Based容易产生大量碎片岛，烘焙后贴图利用率极低，远看就像纹理丢了。第二， Island Margin至少设为0.02，否则烘焙时相邻UV岛互相渗透，出现色块串色。第三，纹理烘焙的目标分辨率建议不低于1024，Shap-E默认输出的隐式纹理场分辨率有限，低分辨率烘焙会把本就模糊的纹理进一步压垮。
另外，导出GLB前务必确认材质是PBR的Base Color通道而非Vertex Color通道。有些查看器不支持顶点色，只认贴图，如果模型用了顶点色存储颜色，在这些查看器里就表现为灰模。可以在导出脚本里做一次材质转换：
# 伪代码：将顶点色烘焙为贴图的思路 # 1. 读取 mesh.vertex_colors # 2. 新建 1024x1024 的空白贴图 # 3. 按 UV 坐标把顶点色写入对应像素 # 4. 将贴图挂到材质的 baseColorTexture 上 # 5. 清空 vertex_colors，避免查看器二义性
纹理偏色、模糊等衍生问题排查
修好纹理丢失后，还可能遇到贴图整体偏灰、颜色饱和度不足的情况。这通常和guidance_scale有关：数值偏低时模型对文本的颜色描述响应弱，生成的texture latent本身就偏中性色。可以尝试把guidance_scale从9提到15区间，同时把采样步数保持在64以上，纹理的颜色会明显更贴近prompt描述。反之guidance过高又会导致纹理过饱和甚至出现噪点，需要平衡。
纹理模糊则是另一类问题。Shap-E的纹理场分辨率受transmitter模型结构限制，天生不如专业贴图精细。如果业务上需要更清晰的贴图，可行的路径是先用Shap-E生成带纹理的基础模型，再导出到Blender中用高分辨率重烘焙，或者将模型送入Stable Diffusion类的纹理重绘工具做refine。直接在Shap-E侧调参提升纹理清晰度的空间非常有限，这一点要有心理预期。
最后提供一个快速排查清单：解码后打印mesh对象，确认材质槽非空且贴图字段有效；用decode_latent_images渲染几帧2D图片，如果图片有颜色而GLB没有，问题百分百在导出和UV环节；如果图片本身也没颜色，问题在采样阶段的texture_latents。按这个顺序定位，基本能在十分钟内锁定纹理丢失的真正原因。
Shap-Etexture_latentsUV展开修改时间：2026-09-10 22:04:45