Hi3D v1.0 是一个基于 Sparc3D 构建的开源高分辨率 3D 几何细化模型：只需一张参考图片和一个粗网格，就能把"粗糙的 3D 模型"逐级细化打磨，最高支持1536³ 有效稀疏提取分辨率，让 3D 网格表面细节大幅升级。本文面向新手，用最少的代码带你完成 Hi3D v1.0 的安装、运行与产物验收。

1. Hi3D v1.0 是什么：给"低模"做精雕细琢的 AI 模型

很多图片转 3D（image-to-3D）工具都能生成一个大致形状，但表面往往是"低模"——浮雕、线脚、鳞片这类细节全部丢失。Hi3D v1.0 解决的正是 3D 生成流程的下一步：粗网格细化👇

• 输入：同一物体的参考图片 + 一个粗网格（来自任意 3D 生成工具）
• 输出：高分辨率、纯几何的 3D 网格（不含纹理、材质）
• 核心原理：以图像特征为条件，逐级采样稀疏潜变量，通过自剪枝稀疏 VAE 解码并提取网格
• 训练规模：约 200 万个精选 3D 资产

2. 三级渐进式细化：1536³ 高分辨率 3D 生成是怎么做到的

Hi3D v1.0 不是"一步到位"，而是逐轮放大：每一轮解码、提取网格后重新体素化，作为下一轮的稀疏支撑。请求 512³ 只跑一轮，1024³ 跑两轮，1536³ 跑全部三轮（详见 README.md 中的流程表格）：

💡 注意：1536³ 指的是标称稀疏坐标与提取网格，并不是一个稠密的 1536³ 张量，也不代表固定的三角面数。稀疏表示是它能做到高分辨率的关键。

3. 效果一览：局部细节与多视角对比

下图将 9 种方法放在一起对比局部几何，Hi3D v1.0 为最右列（青绿色标出），在层叠浮雕、建筑线脚、鳞片、牙齿、同心凹槽等结构上优势明显：

多视角对比则验证了全局形状质量：车辆、装甲角色、扶手椅与手提包分别从正面、背面、底部展示。隐藏视角属于合理补全，而非对不可见表面的精确重建：

更多示例（人形半身像、机械机器人、风格化角色）可参阅官方文档中同一张图的后续对比图：

4. Hi3D v1.0 安装指南：环境要求与一键部署

硬件与系统要求（不支持 CPU 推理）⚠️：

• Linux + Python 3.10
• 计算能力 ≥ 8.0 的 NVIDIA GPU
• CUDA 12.0–12.5 工具链（需与 PyTorch 构建匹配）
• 已验证的完整环境：Python 3.10.12、PyTorch 2.5.0+cu124、96 GB NVIDIA H20（1536³ 完整流程仅在该 GPU 上验证过）

克隆仓库并按顺序安装：

git clone https://gitcode.com/hf_mirrors/hi3d-official/Hi3Dv1.0.git cd Hi3Dv1.0 pip install torch==2.5.0+cu124 torchvision==0.20.0+cu124 \ --extra-index-url https://download.pytorch.org/whl/cu124 pip install packaging ninja psutil pip install --no-build-isolation flash-attn==2.7.4.post1 pip install -c docker/constraints.txt -e ".[inference]"

安装要点：flash-attn必须在 PyTorch 之后单独源码安装（关闭构建隔离）；docker/constraints.txt锁定已验证的内核组合（含spconv-cu120与flash-attn）；Triton 网格内核在首次调用时自动编译。需要演示脚本的去背景功能时，再装.[demo]依赖组即可。

5. 第一次运行：命令行与 Python 两种 3D 几何细化调用方式

方式一：命令行细化已有粗网格（无需额外依赖）：

python demo/refine_mesh.py \ --model hi3d-official/Hi3Dv1.0 \ --image input.png --coarse-mesh coarse.glb --output refined.glb \ --resolution 1024 --num-inference-steps 25 --seed 0

显存紧张时可加--sequential-cpu-offload启用模型卸载；图片有背景时可加--remove-background（需先装 demo 依赖组）。

方式二：Python API（完整示例见 README.md）：

from sparc3d import Sparc3DPipeline pipeline = Sparc3DPipeline.from_pretrained("hi3d-official/Hi3Dv1.0").to("cuda") result = pipeline(image, coarse_mesh, resolution=1024, num_inference_steps=25, seed=0) result.mesh.export("refined.glb")

支持512 / 1024 / 1536三档分辨率，默认每轮 25 步调度更新（配置见 scheduler/scheduler_config.json）；seed与 CPUtorch.Generator二选一，不能同时提供。

6. 仓库文件导读：模型权重与配置都在哪里

本仓库根目录即完整的模型文件集，加载器只读 JSON 与 safetensors，不执行任何仓库内 Python。核心文件一览：

另有中英双语说明文档 README.zh-CN.md 与 README.md，以及条件编码器（DINOv2 / CLIP）等外部依赖的加载说明。

7. 实用注意事项：跑 3D 几何细化前必知的 5 件事

1. 仅几何输出：不生成纹理、材质；结果会重新居中并将最大半径归一为 1，不保留输入的世界坐标与绝对尺度。
2. 粗结构很重要：粗网格中的严重结构错误可能被保留；图片中看不到的区域属于合理补全，不是精确重建。
3. 强依赖 GPU 内核：flash-attn无替代注意力路径；复杂输入的自适应体素化可能降档并发出警告，无法达到目标分辨率时会直接报错。
4. 相同种子 ≠ 相同网格：GPU 稀疏卷积与注意力并非逐位确定，比较结果应在相同输入、模型版本与环境下进行。
5. 许可条款：协议允许商用，但商业集成需展示Powered by Hi3D 1.0；月活超过 20 万或月收入达 100 万美元时，须 60 日内申请单独书面许可（详见 LICENSE 与 THIRD_PARTY_LICENSES.md）。

Hi3D v1.0 基于 Sparc3D（Sparse Representation and Construction for High-Resolution 3D Shapes Modeling）构建。至此，你已掌握从环境搭建到 1536³ 高分辨率 3D 几何细化的完整路径——准备一张图片和一个粗网格，就可以开始打磨你的 3D 模型了 🚀