wiki-vault/Sources/Homelab/hunyuan3d-sunnie-pipeline.md

created	path	project	status	tags	type	updated
2026-04-27	Sources/Homelab	hunyuan3d-sunnie-pipeline	active	homelab docker ai-ml gpu blender pbs sunnie	project-plan	2026-04-27

Hunyuan3D-2 + Sunnie Animation Pipeline

Self-hosted deployment of Tencent Hunyuan3D-2 on the Manjaro tower (RTX 3080), feeding into a Blender pipeline to produce a dancing 3D version of Sunnie for PBS content.

Why Hunyuan3D-2 over InstantMesh

For stylized characters, open-source models (Hunyuan, Trellis) preserve cartoon aesthetics better than commercial tools (Tripo, Meshy) that over-detail. Hunyuan3D-2 also outputs PBR textures (not just vertex colors), which matters once Sunnie hits Blender for re-lighting. InstantMesh stays in flight as a comparison data point.

Stack

• Host: Manjaro tower (i7 / 128GB / RTX 3080, 10GB VRAM)
• Runtime: Docker + NVIDIA Container Toolkit
• Model variant: Hunyuan3D-2mini with hunyuan3d-dit-v2-mini-turbo subfolder (10GB VRAM-friendly)
• Required flags: --low_vram_mode --enable_flashvdm
• UI: Gradio on :8080
• Downstream: Blender 4.x, Mixamo for auto-rig + dance animations

VRAM reality check

The full Hunyuan3D-2 model wants more than 10GB. The mini-turbo variant

• low-VRAM flags is the target config for the 3080. If quality is unacceptable, fallbacks: rent an A100/4090 hour on RunPod for final-quality renders, or move workload to a future GPU upgrade.

Known issues

• No official Tencent Docker image — community Dockerfiles only (referenced in repo issues #125, #122)
• First-run model download is large (multiple GB across HuggingFace repos) — persist to host volume
• Hunyuan3D-2.1 exists with better PBR but Docker support is rougher; deferring until 2.0 baseline works

Phase 1 — Deploy Hunyuan3D-2

• Verify NVIDIA Container Toolkit: docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi
• Clone repo: git clone https://github.com/Tencent-Hunyuan/Hunyuan3D-2.git ~/projects/hunyuan3d-2
• Write Dockerfile (community-style, base nvidia/cuda:12.4.0-devel-ubuntu22.04)
• Build image: docker compose build
• Create model cache dir: mkdir -p ~/hunyuan3d-models
• First run: docker compose up — weights download to mounted volume
• Verify Gradio UI at http://localhost:8080
• Smoke test with sample image, save .glb output

Phase 2 — Sunnie mesh generation

• Prepare Sunnie reference image (front-facing, transparent or white background, clean lines)
• Generate mesh via Gradio UI
• Export as .glb or .obj with PBR textures
• Iterate prompt/source image until mesh is acceptable

Phase 3 — Blender cleanup

• Import mesh into Blender 4.x
• Inspect topology — likely needs decimate or retopo for clean rig deformation
• Verify UV maps and PBR material assignment
• Pose into T-pose if not already (Mixamo requirement)
• Export as .fbx for Mixamo upload

Phase 4 — Rig + animate via Mixamo

• Upload .fbx to Mixamo, place rigging markers
• Verify auto-rig deformation
• Pick dance animation from Mixamo library
• Download rigged .fbx with skin + animation
• Re-import to Blender, verify playback

Phase 5 — Final render

• Set up Blender scene (lighting, camera, background)
• Render dance sequence (Cycles or Eevee depending on quality target)
• Export video for PBS use

docker-compose.yml (starting point)

yaml services: hunyuan3d: build: context: ./Hunyuan3D-2 dockerfile: Dockerfile image: hunyuan3d-2:local container_name: hunyuan3d ports: - "8080:8080" volumes: - ~/hunyuan3d-models:/root/.cache/hy3dgen - ./outputs:/workspace/outputs command: > python3 gradio_app.py --model_path tencent/Hunyuan3D-2mini --subfolder hunyuan3d-dit-v2-mini-turbo --texgen_model_path tencent/Hunyuan3D-2 --low_vram_mode --enable_flashvdm --host 0.0.0.0 --port 8080 deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] restart: unless-stopped

Open questions

• If mini-turbo quality is insufficient for Sunnie, escalate to Hunyuan3D-2.1 (more VRAM-hungry, rougher Docker) or RunPod cloud GPU?
• Reverse-proxy through Traefik on *.lab.herbylab.dev, or keep local-only?
• Worth integrating with InstantMesh deploy for side-by-side mesh comparison?
• Long-term: candidate tool for OpenClaw to call as a 3D-gen capability?

References

• Hunyuan3D-2 repo: https://github.com/Tencent-Hunyuan/Hunyuan3D-2
• Hunyuan3D-2.1 (newer, PBR-focused): https://github.com/Tencent-Hunyuan/Hunyuan3D-2.1
• Docker discussion: https://github.com/Tencent-Hunyuan/Hunyuan3D-2/issues/125
• Mixamo: https://www.mixamo.com
• Companion project: instantmesh-docker

...sent from Jenny & Travis