Hunyuan3D auf Apple Silicon
Ein State-of-the-Art-Modell für Bild-zu-3D, nativ auf Apple Silicon portiert und numerisch gegen das Original verifiziert. Dazu ein eigenes Web-Tool, das aus der Pipeline ein benutzbares Produkt macht
Juni 2026
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 mit zwei Hälften: der MLX-Port als Rechen-Engine (Python) und ein eigenes Web-Tool als Produkt obendrauf (Next.js mit react-three-fiber), verbunden über einen asynchronen API-Server. Zuerst die Engine.
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.
Das Web-Tool: aus der Pipeline wird ein Produkt
Damit aus der Engine etwas Benutzbares wird, habe ich ein eigenes Web-Tool gebaut, das den ganzen Ablauf führt: Bild per Drag-and-drop hochladen (Einzelbild oder vier Ansichten für die Multiview-Variante), Qualität und Mesh-Auflösung über Slider einstellen, generieren, ansehen, herunterladen. Dahinter steuert eine Fünf-Zustands-Maschine den Flow von leer über bereit und generierend bis Erfolg oder Fehler. Weil eine Generierung 20 bis 120 Sekunden dauert, hält der API-Server bewusst keinen HTTP-Request offen (ein Dev-Proxy würde den Socket kappen): Die Arbeit läuft in einem Hintergrund-Thread, das Frontend pollt den Fortschritt und bekommt am Ende das fertige GLB.
Details, die die Wartezeit erzählen
Der Feinschliff steckt in der Choreografie. Während gerechnet wird, 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 und robust gegen WebGL-Context-Verlust. Und weil das Ganze für den 3D-Druck gedacht ist, gibt es eine Live-Vorschau der Dreiecks-Reduktion: Ein Slider dezimiert das Mesh in Echtzeit direkt im Viewer, bevor man es exportiert, für kleinere Dateien ohne böse Überraschung im Slicer.
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)
- Eigenes Web-Tool auf der Engine: Drag-and-drop, 3D-Viewer mit Partikel-Preloader, Live-Vorschau der Dreiecks-Reduktion und GLB-Export
- Drei Zugänge zur Pipeline: CLI, asynchrone JSON-API und die Webapp
- 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: ML-Portierungen so zu verifizieren, 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.