Hunyuan3D auf Apple Silicon
Wie ein State-of-the-Art-Bildgenerierungsmodell für 3D-Geometrie den Sprung von CUDA auf Apple Silicon schafft — und wie man beweist, dass der Port wirklich dasselbe rechnet
PROJEKT
Hunyuan3D auf Apple Silicon
TECHNOLOGIEN
Herausforderung
Die Geschichte beginnt mit einem Geburtstagsgeschenk: ein 3D-Drucker. Was schnell fehlte, war Nachschub an Modellen — ein 3D-Scanner war finanziell nicht drin, und Dienste wie Meshy.ai, die aus Fotos 3D-Modelle generieren, kosten im Abo auf Dauer mehr als der Drucker selbst. Die Entwickler-Antwort lag nahe: selbst bauen.
Die Grundlage gibt es als Open Source: Tencents Hunyuan3D-2.1 erzeugt aus einem einzigen Foto ein vollständiges 3D-Mesh — ist aber wie praktisch alle Image-to-3D-Modelle auf CUDA und damit auf NVIDIA-Hardware festgenagelt. Wer auf einem Mac entwickelt, schaut zu.
Das Ziel: die komplette Shape-Pipeline — Diffusion-Transformer, VAE-Decoder, Vision-Conditioner — nativ auf dem eigenen MacBook (M5 Max, 64 GB) zum Laufen bringen. Mit Apples MLX-Framework direkt auf der Metal-GPU, ohne CUDA und ohne PyTorch zur Laufzeit.
Die eigentliche Schwierigkeit ist dabei nicht das Übersetzen von Code, sondern der Beweis der Korrektheit: Ein Diffusionsmodell produziert aus jedem noch so subtilen Portierungsfehler weiterhin hübsche Ergebnisse — nur eben falsche. „Sieht gut aus“ ist kein Test. Drei Anforderungen standen deshalb fest:
- Numerische Parität — jede portierte Komponente muss nachweislich dasselbe rechnen wie die PyTorch-Referenz, nicht nur ähnlich aussehen
- Komplett lokal — vom Bild-Upload bis zum fertigen GLB-Mesh läuft alles auf dem eigenen Rechner
- Benutzbar — nicht nur ein CLI-Skript, sondern eine echte Web-Oberfläche mit 3D-Viewer, Fortschrittsanzeige und Download
Lösung
Entstanden ist ein Monorepo aus drei Teilen: der MLX-Port der Pipeline (Python), ein API-Server mit asynchronen Generierungs-Jobs und eine Next.js-Webapp mit react-three-fiber-Viewer. Vier Aspekte waren entscheidend.
Der Port: Diffusion-Transformer bis Volume-Decode
Portiert wurde die gesamte Kette: der MMDiT-Diffusion-Transformer inklusive Mixture-of-Experts-Routing, der Flow-Matching-Scheduler mit Classifier-Free Guidance, der DINOv2-Vision-Conditioner und der ShapeVAE-Decoder mit FlashVDM — einem hierarchischen Volume-Decode, der das 3D-Feld erst grob abtastet und nur dort verfeinert, wo die Oberfläche tatsächlich verläuft. Dazu ein Weight-Konverter, der die originalen Checkpoints in MLX-safetensors überführt. Neben der Single-View-Pipeline läuft auch die Multiview-Variante, die vier Ansichten (vorn, links, hinten, rechts) zu einem konsistenteren Mesh kombiniert.
Parität als Methodik, nicht als Stichprobe
Jede Komponente wird gegen die originale PyTorch-Implementierung getestet: identische Gewichte, identischer Input, dann Vergleich der Ausgaben auf Bit-Ebene (Toleranz ~1e-5 auf CPU). Die Lektion des Projekts: Random-Weight-Tests reichen nicht. Ein Bug im Mixture-of-Experts-Gate — die Experten-Auswahl wählte bei nahezu gleichauf liegenden Scores mehr als k Experten — blieb mit Zufallsgewichten unsichtbar und flog erst mit echten Modellgewichten auf. Datenabhängige Pfade wie Top-k-Routing brauchen Tests mit realen Daten.
End-to-End-Beweis statt Bauchgefühl
Der finale Test führt echte Sampling-Steps mit identischem Rauschen und Conditioning auf beiden Implementierungen aus und vergleicht die Latents: relative Abweichung ~1,3e-3 — reine float16/GPU-Rundung. Da VAE-Decode und Marching Cubes deterministisch und einzeln verifiziert sind, folgt aus Latent-Gleichheit Mesh-Gleichheit. Der Port ist damit kein „Nachbau“, sondern eine belegbar äquivalente Implementierung.
Eine Oberfläche, die die Wartezeit erzählt
Die Webapp macht aus der Pipeline ein Produkt: Bild per Drag-and-drop hochladen, Qualitätsparameter über Slider einstellen, generieren. Während das Backend rechnet, zeigt ein GLSL-Partikel-Preloader eine wabernde Punktwolke, die beim Fertigwerden per Crossfade in das echte Mesh übergeht — gerendert als Clay-Material mit Orbit-Steuerung, robust gegen WebGL-Context-Verlust. Der API-Server verarbeitet Jobs asynchron; das Frontend pollt den Fortschritt und liefert am Ende das GLB zum Download.
Code-Beispiele
Ergebnisse
Ein State-of-the-Art-Image-to-3D-Modell läuft vollständig lokal auf dem MacBook — vom Foto zum herunterladbaren 3D-Mesh, ohne dass ein Byte den Rechner verlässt:
- Komplette Shape-Pipeline nativ auf der Metal-GPU — kein CUDA, kein PyTorch zur Laufzeit
- Numerisch verifiziert: Denoiser rel. Fehler 5,6e-6, End-to-End-Latents ~1,3e-3 (reine fp16-Rundung) gegen die PyTorch-Referenz
- Zwei Pipeline-Varianten: Single-View und Multiview (vier Ansichten für konsistentere Geometrie)
- Drei Zugänge: CLI, JSON-API mit asynchronen Jobs, Webapp mit 3D-Viewer
- Testsuite mit Parität-Harness und Mutationstests als dauerhaftes Sicherheitsnetz
Der ehrliche Vergleich gehört dazu: An die Auflösung von Meshy.ai kommt der Port nicht heran — dort rechnen Rechenzentrums-GPUs, hier ein Laptop. Dafür läuft alles lokal, kostet kein Abo, und der 3D-Drucker hat Nachschub. Über den konkreten Anlass hinaus ist eine übertragbare Methodik entstanden: Wie verifiziert man ML-Portierungen so, dass „läuft auf meiner Hardware“ auch „rechnet dasselbe“ bedeutet. Die Modellgewichte unterliegen der Tencent-Non-Commercial-Lizenz, der Port ist ein reines Forschungs- und Lernprojekt — deshalb ist der Code aktuell nicht veröffentlicht: Die Lizenz-Klärung für die EU läuft derzeit direkt mit Tencent.
Visuelle Eindrücke
Aus einem PNG-Logo wird ein 3D-Mesh: Einzelbild-Upload, Qualitäts-Regler, 345.000 Faces im react-three-fiber-Viewer — Export als GLB, STL, OBJ oder PLY, z.B. für den 3D-Druck.