117f06c055
README + CLAUDE.md previously claimed Hunyuan3D-2/ and docker/outputs/ were "gitignored". The repo has no .gitignore at all; those paths are just untracked. Use "untracked" / "not committed" wording instead so the operator contract (clone upstream, don't add) is clear without implying a gitignore safety net. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
98 lines
3.6 KiB
Markdown
98 lines
3.6 KiB
Markdown
# Claude notes — hunyuan3d-sunnie
|
|
|
|
Agent context for this repo. Read before non-trivial changes.
|
|
|
|
## What this is
|
|
|
|
One-off pipeline to generate a 3D mesh of *Sunnie* from a reference
|
|
image using Tencent's [Hunyuan3D-2](https://github.com/Tencent-Hunyuan/Hunyuan3D-2)
|
|
(`mini-turbo` variant), then rig + animate in Blender via Mixamo. This
|
|
repo owns the **docker wrapper** around upstream Hunyuan3D-2 — it is
|
|
**not** a fork of the model code itself.
|
|
|
|
## Repo shape
|
|
|
|
```
|
|
hunyuan3d-sunnie/
|
|
Hunyuan3D-2/ # UNTRACKED — upstream clone. Cloned by the operator
|
|
# before `docker compose build`. Not a git submodule.
|
|
docker/
|
|
Dockerfile # community-derived (per repo issues #125, #122)
|
|
compose.yml # GPU compose; pins the mini-turbo model + flashvdm
|
|
outputs/ # generated .glb meshes land here (untracked)
|
|
README.md
|
|
CLAUDE.md
|
|
```
|
|
|
|
`Hunyuan3D-2/` is intentionally untracked. Operators run
|
|
`git clone https://github.com/Tencent-Hunyuan/Hunyuan3D-2.git` once;
|
|
the Dockerfile then COPYs it in via the build context. Don't add it
|
|
as a submodule or vendor it into source control — keep the upstream
|
|
boundary clean.
|
|
|
|
## Hardware contract
|
|
|
|
- **NVIDIA GPU required**, exposed through Docker via the nvidia
|
|
runtime (`deploy.resources.reservations.devices` with the `nvidia`
|
|
driver). The compose `command` is tuned for **RTX 3080 / 10 GB
|
|
VRAM** with `--low_vram_mode` + `--enable_flashvdm`. Move to a
|
|
bigger card → drop `--low_vram_mode`. Smaller card → expect OOMs.
|
|
- **CUDA 12.4**. The Dockerfile pulls `nvidia/cuda:12.4.0-devel-ubuntu22.04`
|
|
and installs PyTorch from the cu124 wheels index. Don't switch CUDA
|
|
versions without re-aligning the PyTorch index URL.
|
|
|
|
## Compose command — don't casually edit
|
|
|
|
```yaml
|
|
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
|
|
```
|
|
|
|
- `--model_path` + `--subfolder` together select the **mini-turbo**
|
|
variant. The full Hunyuan3D-2 model won't fit in 10 GB.
|
|
- `--texgen_model_path` uses the full Hunyuan3D-2 model **for PBR
|
|
texture generation only** (texture-gen has a lower VRAM ceiling
|
|
than mesh-gen).
|
|
- Removing `--low_vram_mode` or `--enable_flashvdm` will likely
|
|
produce OOM on a 3080.
|
|
|
|
## Model weights
|
|
|
|
First run downloads weights to the `hunyuan3d-models` named volume
|
|
(mounted at `/root/.cache/hy3dgen`). Both the mini-turbo mesh model
|
|
and the full texgen model need to come down — several GB total. Don't
|
|
prune that volume between sessions unless you're ready to wait through
|
|
the re-download.
|
|
|
|
## Where outputs land
|
|
|
|
`./docker/outputs/` is bind-mounted into the container at
|
|
`/workspace/outputs/`. The Gradio app drops `.glb` files there with
|
|
PBR textures embedded — ready for Blender import → Mixamo rigging.
|
|
The dir is untracked; nothing in it is meant to be committed.
|
|
|
|
## Don't-touch zones
|
|
|
|
- The untracked `Hunyuan3D-2/` directory — let operators reclone if
|
|
they need to update.
|
|
- The `--low_vram_mode` + `--enable_flashvdm` flags — load-bearing for
|
|
the 3080.
|
|
- The Dockerfile's PyTorch index URL — pinned to cu124 to match the
|
|
base image.
|
|
- `pip install -e .` and `flash-attn` are wrapped in `|| true` because
|
|
they're known-flaky on this base image; that's intentional. Don't
|
|
"fix" by making them required.
|
|
|
|
## Bigger picture
|
|
|
|
This is a personal/one-off project, not part of the homelab production
|
|
stack. It only runs on the dev tower (which has the GPU) — never on
|
|
the herbydev Proxmox host or the NAS.
|