Hi3D v1.0 是一款基于 Sparc3D 的高分辨率 3D 几何细化模型：它以同一物体的参考图 + 粗网格为输入，逐级采样稀疏潜变量，细化出最高1536³的高精度几何。能力很强，但新手上手时最容易踩坑。本文用「避坑」视角，把 Hi3D v1.0 的 5 大关键限制讲透——仅几何输出、依赖粗结构、必须 GPU 内核、种子不确定性、仅推理验证，帮你在落地前就绕开这些坑。

Hi3D v1.0 是什么：输入、流程与输出

一句话理解：Hi3D v1.0 把「一张图 + 一个粗模型」细化成一个高分辨率的干净几何体。它的三级细化节奏如下，请求 512³ 跑一轮、1024³ 两轮、1536³ 三轮：

⚠️ 注意：512³ / 1024³ / 1536³ 是「标称稀疏坐标 + 提取网格」，不是稠密的 1536³ 张量，也不代表固定的三角面数。

模型文件结构见 model_index.json，调度器采用FlowMatchHeunScheduler且默认每轮 25 步，配置在 scheduler/scheduler_config.json。下面进入正题：5 大限制逐条拆解。

限制一：仅几何单样本——只出几何，没有纹理材质颜色 🧊

核心限制：Hi3D v1.0不生成纹理、材质或顶点颜色，输出是「纯几何」。

• 输出会重新居中，并把最大半径归一为 1；
• 不保留输入的世界坐标和绝对尺度；
• 只输出单个样本（单样本）。

这意味着什么？如果你的下游需要贴图、材质球、或把模型放进既有场景并对齐坐标，Hi3D 本身解决不了——你得在下游自行补贴图、重新对齐坐标系、并按业务需求缩放。

上图红框是放大的参考区域，Hi3D v1.0（最右列，青绿色标出）在层叠浮雕、建筑线脚、曲线边界、鳞片、牙齿、同心凹槽等局部细节上表现突出——但请注意，它给的是几何细节，不是颜色。

限制二：依赖粗结构——上游粗网格的错误会被「原样保留」 🧱

核心限制：输出质量强依赖输入的粗网格质量。粗网格中的严重结构错误可能原样保留到结果里。

• 图像里看不见的区域属于「合理补全」，不是真实不可见表面的精确重建；
• 也就是说，Hi3D 负责「把形状细化得更精细」，不负责「替你纠正粗网格的硬伤」。

坑点 & 对策：把「上游粗网格要够准」当成第一原则。如果你用的是可选的 Hunyuan 粗网格生成示例，务必先肉眼检查粗网格结构是否站得住脚，再交给 Hi3D 细化。

多视角对比里，彩色部分是表面法线渲染（用于看清几何起伏），并非生成出来的纹理——再次提醒「仅几何」。隐藏视角的补全看着合理，但不要把它当成精确重建。

限制三：需要 GPU 内核——flash-attn 无替代，还不静默降级 ⚙️

核心限制：Hi3D v1.0 依赖 GPU 内核，且flash-attn没有替代注意力路径，不支持 CPU 推理。

已实测组合：Linux、Python 3.10、计算能力 ≥ 8.0 的 NVIDIA GPU，以及与所装 PyTorch 匹配的 CUDA 12.0–12.5 工具链；官方实测环境为96 GB 的 NVIDIA H20。1536³ 完整流程仅在该 GPU 上验证，更小显存的卡尚无峰值内存或可用性结论。

两个容易误会的点：

• 不静默降级：复杂输入的自适应体素化可能采用更粗的支撑网格并发出警告；如果无法达到请求分辨率，会直接报错，而不会悄悄返回一个较低分辨率的结果。这看似「不够智能」，其实是保护机制——避免你拿着一个被降质的结果当成功处理。
• 显存别想太多：启用--sequential-cpu-offload（或enable_sequential_cpu_offload）能减少常驻显存，但不构成最低显存承诺，也消不掉解码特征的内存开销。

限制四：种子不确定性——相同 seed 不保证相同网格哈希 🎲

核心限制：Hi3D v1.0相同种子不保证得到相同网格哈希。

原理：细化采样器用的是本地 CPU 随机数生成器，但GPU 上的稀疏卷积与注意力并不是逐位确定的。所以哪怕seed完全一样，两次跑出来的网格可能「几乎一样」但哈希不同。

复现结果的正确姿势：在相同输入、相同模型版本、相同调度器、相同环境下比较几何，而不是比较哈希值。调度器配置见 scheduler/scheduler_config.json，两个 Transformer 分别见 transformer_512/config.json 与 transformer_1024/config.json。

限制五：仅支持推理验证——没有训练与评测工具 🔒

核心限制：本仓库只提供推理验证，不包含训练代码、评测工具、基准划分与对比网格。

• 你不能仅凭本仓库复现论文里的对比表格；
• 几何细节与标称分辨率不保证满足你的特定下游应用。

模型文件本身（model_index.json、vae/config.json、transformer_512/config.json、transformer_1024/config.json）只是「加载所需」，跟训练流程无关。

5 大限制速查 + 落地建议清单 ✅

额外提醒（许可）：商业集成须展示Powered by Hi3D 1.0；相关产品或服务的月活用户超过 200,000或月收入达到 1,000,000 美元时，须在60 日内通知许可方并申请单独书面许可。完整范围与排除项见 THIRD_PARTY_LICENSES.md，许可正文见 LICENSE。

📌 总结：Hi3D v1.0 是「几何细化」的强力工具，但它是几何专家而非「全能建模器」。认清这 5 大限制、把上游粗网格质量管好、把显存与环境备齐，你就能把它的细节优势真正用起来。