# Hunyuan3D 2.1 ile görselden 3D model üretimi: kurulum ve kullanım rehberi

Kaynak: https://3dsinifi.com/haber/hunyuan3d-2-1-ile-gorselden-3d-model-uretimi-kurulum-ve · Kategori: Eğitimler · Yayın: 3 Ekim 2026

> Tencent'in açık kaynaklı Hunyuan3D 2.1 modeli, tek bir görselden PBR dokulu 3D mesh üretebiliyor. Bu rehberde kurulumdan Gradio arayüzüne kadar kullanım adımları Türkçe anlatılıyor.

## Kısaca
- Hunyuan3D 2.1, görüntüden şekil (Hunyuan3D-Shape) ve doku (Hunyuan3D-Paint) üreten iki ayrı modülden oluşuyor.
- Sisteme göre şekil üretimi 10 GB, doku üretimi 21 GB, ikisi birlikte ise 29 GB VRAM gerektiriyor.
- Model, Python 3.10 ve PyTorch 2.5.1+cu124 ile test edilmiş olup macOS, Windows ve Linux'u destekliyor.
- Çıktılar glb/obj gibi standart mesh formatlarında kaydedilebiliyor ve Gradio tabanlı yerel bir arayüzle de kullanılabiliyor.

Tencent'in geliştirdiği Hunyuan3D, tek bir referans görselden üç boyutlu, dokulu bir mesh üreten açık kaynaklı bir görüntüden-3D'ye (image-to-3D) sistemdir. Bu rehberde, modelin 2.1 sürümünü kurup kod üzerinden veya Gradio arayüzüyle nasıl çalıştırabileceğiniz adım adım anlatılıyor. Archviz ve iç mekan görselleştirme süreçlerinde hızlı konsept mobilya, obje veya aksesuar mesh'i üretmek isteyenler için pratik bir başlangıç rehberidir.

## Ne öğreneceksiniz

Bu rehberin sonunda, bir görselden mesh (şekil) üretmeyi, bu mesh'e doku (texture) uygulamayı ve sonucu glb/obj formatında dışa aktarmayı öğrenmiş olacaksınız. Ayrıca kendi bilgisayarınızda Gradio tabanlı yerel bir arayüz başlatmayı da görmüş olacaksınız.

## Gereksinimler

- Python 3.10 ve PyTorch 2.5.1 (CUDA 12.4 ile test edilmiştir).
- NVIDIA GPU: yalnızca şekil üretimi için en az 10 GB VRAM, yalnızca doku üretimi için 21 GB, ikisini birlikte çalıştırmak için 29 GB VRAM önerilir.
- Hunyuan3D-Shape-v2-1 (3,3 milyar parametre) ve Hunyuan3D-Paint-v2-1 (2 milyar parametre) model ağırlıkları Hugging Face üzerinden indirilir.
- Sistem macOS, Windows ve Linux üzerinde çalışabilmektedir.

## Kurulum adımları

1. PyTorch'u CUDA 12.4 destekli sürümle kurun:

```bash
pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt
```

2. Doku üretimi için gereken özel rasterizer ve fark edilebilir render modülünü derleyin:

```bash
cd hy3dpaint/custom_rasterizer
pip install -e .
cd ../..
cd hy3dpaint/DifferentiableRenderer
bash compile_mesh_painter.sh
cd ../..
```

3. Doku yükseltme için kullanılan hazır ağırlığı indirin:

```bash
wget https://github.com/xinntao/Real-ESRGAN/releases/download/v0.1.0/RealESRGAN_x4plus.pth -P hy3dpaint/ckpt
```

4. Bir görselden önce dokusuz mesh üretin, ardından aynı görseli kullanarak doku uygulayın:

```python
import sys
sys.path.insert(0, './hy3dshape')
sys.path.insert(0, './hy3dpaint')
from textureGenPipeline import Hunyuan3DPaintPipeline, Hunyuan3DPaintConfig
from hy3dshape.pipelines import Hunyuan3DDiTFlowMatchingPipeline

shape_pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2.1')
mesh_untextured = shape_pipeline(image='assets/demo.png')[0]

paint_pipeline = Hunyuan3DPaintPipeline(Hunyuan3DPaintConfig(max_num_view=6, resolution=512))
mesh_textured = paint_pipeline(mesh_path, image_path='assets/demo.png')
```

Bu kod bloğu, önce şekil üretim hattını çalıştırıp dokusuz bir mesh elde ediyor, ardından doku üretim hattına aynı referans görseli vererek fiziksel tabanlı (PBR) bir doku uyguluyor. Üretilen mesh bir trimesh nesnesi olarak döner ve glb/obj gibi formatlara kaydedilebilir.

5. Komut satırı yerine arayüz tercih ederseniz, Gradio uygulamasını yerel olarak başlatabilirsiniz:

```bash
python3 gradio_app.py --model_path tencent/Hunyuan3D-2.1 --subfolder hunyuan3d-dit-v2-1 --texgen_model_path tencent/Hunyuan3D-2.1 --low_vram_mode
```

Bu komut, hem şekil hem doku modelini yükleyip tarayıcı üzerinden görsel yükleyip mesh üretebileceğiniz bir arayüz açar; `--low_vram_mode` seçeneği sınırlı VRAM'li sistemlerde yardımcı olabilir.

## Bu, mimari görselleştirme için ne anlama geliyor

Hunyuan3D, tek bir fotoğraf veya render görselinden hızlıca konsept düzeyinde mobilya, aksesuar veya heykel benzeri objeler üretmek isteyen 3D sanatçılar ve iç mimarlar için kullanılabilir bir araçtır. Üretilen mesh'ler glb/obj formatında olduğundan Blender, 3ds Max gibi yazılımlara aktarılıp sahneye yerleştirilebilir. Tencent'in yayınladığı karşılaştırmalı ölçümlere göre Hunyuan3D, geometri detayı, koşul görseline uyum ve doku kalitesi bakımından diğer açık ve kapalı kaynaklı modelleri geride bırakıyor; ancak bu sonuçlar üreticinin kendi testlerine dayandığından bağımsız doğrulama yapılmadığı unutulmamalıdır. Ayrıca 29 GB VRAM gerektiren tam hat (şekil+doku), çoğu ofis bilgisayarının üzerinde bir donanım talebi olduğundan, güçlü bir iş istasyonu veya bulut GPU erişimi gerekir.

## Yaygın hatalar

- Yetersiz VRAM'li bir GPU'da hem şekil hem doku hattını aynı anda çalıştırmaya çalışmak hata veya çökmeye yol açabilir; gerekirse `--low_vram_mode` kullanın.
- Karmaşık arka planlı veya birden fazla nesne içeren referans görseller, modelin yanlış geometri çıkarmasına neden olabilir; tek nesneli, sade arka planlı görseller tercih edilmelidir.
- CUDA sürümünü PyTorch kurulum komutundaki sürümle (cu124) eşleştirmemek kurulum hatalarına yol açar.

## Sonraki adımlar

Üretilen glb/obj dosyasını Blender veya 3ds Max'e aktararak ölçeklendirme, malzeme düzeltmesi ve sahneye yerleştirme yapabilirsiniz. Daha önceki sürüm olan Hunyuan3D 2.0 ile karşılaştırma yaparak hangi sürümün donanımınıza uygun olduğunu test etmeniz de faydalı olacaktır.

## Kaynak ve lisans

Bu rehber, Tencent tarafından Hugging Face üzerinde yayınlanan Hunyuan3D-2 ve Hunyuan3D-2.1 model kartlarındaki resmi kurulum ve kullanım talimatlarından Türkçeye uyarlanmıştır. Hunyuan3D-2.1 model kartında lisans "tencent-hunyuan-community" (özel topluluk lisansı) olarak belirtilmiştir; kod örnekleri bu kaynaklardan orijinal haliyle alınmıştır.

## Pro ipucu
Tam hattı (şekil+doku) çalıştırmadan önce GPU'nuzun en az 29 GB VRAM'e sahip olduğundan emin olun; yetersizse `--low_vram_mode` seçeneğiyle Gradio uygulamasını başlatın.

## 3dsınıfı yorumu
Hunyuan3D 2.1, açık kaynaklı olması sayesinde Türkiye'deki ofisler ve öğrenciler için ücretsiz bir deneme imkânı sunuyor; özellikle hızlı konsept mobilya veya aksesuar mesh'i üretmek isteyenler için ilgi çekici. Ancak 29 GB VRAM gereksinimi, çoğu dizüstü veya standart masaüstü iş istasyonunun kapasitesini aşıyor; bu nedenle güçlü bir yerel GPU ya da bulut GPU kirası gerekebilir.

Tencent'in paylaştığı kıyaslama tablolarının üreticinin kendi testlerine dayandığını hatırlamakta fayda var; bağımsız karşılaştırma yapılmadan sonuçları doğrudan kabul etmek yerine kendi proje görselleriyle deneme yapmak daha sağlıklı olur. Ticari kullanımda lisans koşullarının (Tencent Hunyuan community license) dikkatle incelenmesi, özellikle proje teslimlerinde kullanılacaksa önemlidir.

## Kaynaklar
- [huggingface.co (Apache-2.0)](https://huggingface.co/tencent/Hunyuan3D-2.1/blob/refs%2Fpr%2F6/README.md) (özet)
- [huggingface.co (Apache-2.0)](https://huggingface.co/tencent/Hunyuan3D-2) (alıntı)
- [huggingface.co (Apache-2.0)](https://huggingface.co/tencent/Hunyuan3D-2/blob/fb35d48b9ceca5439d03a2b8345fd6fbffe02119/README.md) (özet)

_Yapay zekâ ile yazıldı, kaynaklarla doğrulandı. © 3dsınıfı_