Motivation

Support Hunyuan3D-2 (2.0)

Modifications

Serve

• Added mesh_api.py: exposes /v1/meshes create/list/retrieve/delete and mesh content download.

Pipeline Config

• Added Hunyuan3D2PipelineConfig (task_type=I2M): shape/paint/delight subfolders and related hyperparameters; DiT/VAE config references.
• Added configs/models/dits/hunyuan3d.py, configs/models/vaes/hunyuan3d.py, and configs/sample/hunyuan3d.py (Hunyuan3DSamplingParams).
• base.py: added ModelTaskType.I2M, data_type() returns DataType.MESH.

Model Architecture

• DiT: runtime/models/dits/hunyuan3d.py (Hunyuan3DShapeModel, Basic2p5DTransformerBlock, etc.).
• VAE: runtime/models/vaes/hunyuan3d_vae.py (Hunyuan3DShapeVAE).
• Encoder: runtime/models/encoders/hunyuan3d.py (Hunyuan3DShapeConditioner, Hunyuan3DShapeImageProcessor, etc.).
• Scheduler: runtime/models/schedulers/hunyuan3d_scheduler.py.
• Mesh utilities and rendering: runtime/models/mesh3d_utils.py; csrc/render/hunyuan3d_rasterizer, csrc/render/mesh_processor (C++/CUDA).

Pipeline Stages

• Shape: hunyuan3d_shape.py — BeforeDenoising → Denoising → Export → Save.
• Paint: hunyuan3d_paint.py — Preprocess → TexGen → Postprocess.
• Main pipeline: hunyuan3d_pipeline.py — Hunyuan3D2Pipeline composes the above stages and uses _resolve_class / resolve_hunyuan3d_tool to resolve non-diffusers components.

Model Loading Flow

• Replace the “multiple files + diffusers layout” flow with “single checkpoint + prefix-based splitting + YAML config”; the DiT is still built via meta instantiation and weight loading with load_model_from_full_model_state_dict and an optional param_names_mapping.

Attention Backend Adaptation

• Hunyuan3D DiT: DiT uses SGLang’s LocalAttention (with FA/TORCH_SDPA);
• UNet 2.5D replaces Diffusers’ attention with SGLangAttentionWrapper, which calls the same backends via get_attn_backend().

Accuracy Tests

Align with Hunyuan3D 2.0

How to Use

sglang generate   --model-path tencent/Hunyuan3D-2   --image-path demo.png --save-output --output-path outputs

TP

sglang generate   --model-path tencent/Hunyuan3D-2  --image-path demo.png  --save-output  --output-path outputs --tp-size 2 --num-gpus 2

Example

Open glb file in https://gltf-viewer.donmccurdy.com/

1

input

output

screenshot

1 gpu

https://github.com/Prozac614/Hunyuan3D-example/blob/main/1/1gpu.glb

tp 2

https://github.com/Prozac614/Hunyuan3D-example/blob/main/1/tp.glb

2

input

output

screenshot

1 gpu

https://github.com/Prozac614/Hunyuan3D-example/blob/main/2/1gpu.glb

tp 2

https://github.com/Prozac614/Hunyuan3D-example/blob/main/2/tp2.glb

3

input

output

screenshot

1gpu

https://github.com/Prozac614/Hunyuan3D-example/blob/main/3/1gpu.glb

tp 2

https://github.com/Prozac614/Hunyuan3D-example/blob/main/3/output_20260219-153808.glb

Checklist

• Format your code according to the Format code with pre-commit.
• Add unit tests according to the Run and add unit tests.
• Update documentation according to Write documentations.
• Provide accuracy and speed benchmark results according to Test the accuracy and Benchmark the speed.
• Follow the SGLang code style guidance.

Review Process

1. Ping Merge Oncalls to start the PR flow. See the PR Merge Process.
2. Get approvals from CODEOWNERS and other reviewers.
3. Trigger CI tests with comments or contact authorized users to do so.
   • /tag-run-ci-label, /rerun-failed-ci, /tag-and-rerun-ci
4. After green CI and required approvals, ask Merge Oncalls to merge.