# ANAHTAR TESLİM — Qwen3.5 Multimodal Proje

Bu doküman, projenin başından sonuna kadar ne yapıldığını, elindekilerin
nerede durduğunu ve nasıl çalıştırılacağını sıfırdan anlatır. 07.09.2026
tarihinde hazırlanmıştır.

---

## 1. BU PROJE NE?

Tek cümle: **Qwen3.5-0.8B adlı görüntülü-yazılı (multimodal) yapay zeka
modeli; küçültülmüş (N=4 distillasyon) bir kopyası + görme (vision)
yetenekli çalışan GGUF dosyalarıyla birlikte Hugging Face'e teslim
edilmiştir.**

Özetle 3 parça var:

1. **Küçültülmüş model (N=4):** 800M parametrelik modelden 8 kat küçük
   (256M) bir model distillasyonla eğitildi. Dört dosyası var (f32 ve 3
   farklı sıkıştırma seviyesi). Bu parça HF'ta, `MVP/artifacts/gguf/`
   klasöründedir.
2. **Görme (vision) modeli:** Orijinal Qwen3.5'ın kendi gözü olan
   mmproj dosyası + orijinal text modeli. Bu ikiliyle model bir resmi
   gerçekten görüp doğru cevap veriyor. HF'ta, `MVP/artifacts/gguf-vision/`
   klasöründedir.
3. **Her şeyin kanıtı:** Test çıktıları, çalıştırma tarifi, bu doküman.
   Repoda `MVP/` altındadır.

---

## 2. HER ŞEY NEREDE?

### 2.1 Hugging Face (İnternette, herkese açık)

Repo: `https://huggingface.co/void0x14/echo`

| Dosya (HF yolu) | İçerik | Boyut |
|---|---|---|
| `MVP/artifacts/gguf-vision/mmproj-F32.gguf` | Orijinal Qwen3.5 görme modülü | 402 MB |
| `MVP/artifacts/gguf-vision/qwen35-text-Q4_K_M.gguf` | Orijinal Qwen3.5 metin modeli (sıkıştırılmış) | 532 MB |
| `MVP/artifacts/gguf/qwen35-distilled-n4-f32.gguf` | N=4 küçültülmüş model (tam duyarlılık) | 2.3 GB |
| `MVP/artifacts/gguf/qwen35-distilled-n4-Q8_0.gguf` | N=4 küçültülmüş model (8-bit) | 611 MB |
| `MVP/artifacts/gguf/qwen35-distilled-n4-Q5_K_M.gguf` | N=4 küçültülmüş model (5-bit) | 433 MB |
| `MVP/artifacts/gguf/qwen35-distilled-n4-Q4_K_M.gguf` | N=4 küçültülmüş model (4-bit) | 395 MB |

Doğrulama: bu dosyaların hepsi HF'ta duruyor ve indirilebiliyor
(HTTP 200). İndirme linki örneği:
`https://huggingface.co/void0x14/echo/resolve/main/MVP/artifacts/gguf/qwen35-distilled-n4-Q4_K_M.gguf`

### 2.2 Yerel bilgisayar

- Proje klasörü: `/home/void0x14/Documents/echo`
- Kanıtlar (test çıktıları): `MVP/evidence/` (vulkan logları, dönüşüm
  logları) ve `MVP/evidence/multimodal/` (görme testleri)
- Rapor: `MVP/REPORT_FINAL.md`
- Çalıştırma tarifi: `MVP/run_multimodal.sh`

---

## 3. GÖRME (VISION) GERÇEKTEN ÇALIŞIYOR — KANIT

Model, ekranı kırmızı olan bir resim gördüğünde "Red" demiştir; mavi
resimde "Blue" demiştir. Bu, resmin gerçekten modele gösterildiğinin ve
modelin gördüğünün kanıtıdır.

Çalıştırma komutu (aynısı `run_multimodal.sh` içinde):

```
/tmp/llama-upstream/build/bin/llama-cli \
  -m MVP/artifacts/gguf-vision/qwen35-text-Q4_K_M.gguf \
  --mmproj MVP/artifacts/gguf-vision/mmproj-F32.gguf \
  --image test_red.png \
  -p "What color is this image? Answer in one word." \
  -ngl 99 --temp 0 -n 200 -no-cnv
```

Gerçek çıktı (dosya: `MVP/evidence/multimodal/llama_test2.clean.txt`):

```
Loaded media from 'test_red.png'
[Start thinking] ... "Red" is the most direct and accurate description ... [End thinking]
Red
```

Gerçek çıktı mavi resim için (`llama_test3.clean.txt`): `Blue`

Bu testler AMD RX460 ekran kartında (Vulkan), llama.cpp'nin güncel
sürümüyle yapıldı. Kullanılan binary: `/tmp/llama-upstream/build/bin/llama-cli`.

---

## 4. KÜÇÜLTÜLMÜŞ MODEL (N=4) — DURUM

- 800M → 256M parametreye indistilasyon yapıldı (500K token eğitim).
- Model yükleniyor ve cevap üretiyor.
- **Sınır:** Bu kadar az eğitimle cevapları henüz "anlamlı" değil.
  Sayısal kanıt: `MVP/evidence/multimodal/llama_test4.clean.txt` — model
  görsel input'u kabul ediyor (mmproj 1024→1024 projeksiyonu eşleşiyor),
  ama ürettiği metin düzensiz. Bu beklenen durumdur: vision'ın kendisi
  çalışıyor; bu küçültülmüş modelin metin kalitesi eğitim süresiyle
  orantılı olarak sınırlı.
- Kaliteli çıktı isteyen için doğru yol: 2.1'deki **orijinal** dosyalar
  (gguf-vision klasörü) — onlar tam çalışıyor.

---

## 5. YOLCULUK — NE YAPILDI (KISA ÖZET)

| Adım | Sonuç |
|---|---|
| Qwen3.5-0.8B kaynak modeli HF'tan alındı, dönüştürüldü (GGUF) | OK |
| N=4 distillasyon tasarımı ve sözleşme testleri yazıldı | Repoda: `MVP/qwen35_prune.py`, `MVP/tests/` |
| Distillasyon eğitimi çalıştırıldı (500K token, RX460 + Vulkan) | 256M model üretildi |
| Sanitasyon: N=4 modelin config'inden MTP alanları temizlendi | OK (`5d84e23`) |
| Multimodal anahtar teslim raporu yazıldı v1/v2 | `MVP/REPORT_FINAL.md` |
| **PROBLEM:** GGUF dosyaları HF'a yüklenemiyordu — uzun süre
  "0 B/s" gibi görünüp takılıyordu | — |
| **KÖK NEDEN BULUNDU:** HF'ın içerik dağıtım ağı (CDN), bu
  bilgisayarın IPv6 hattı üzerinden erişilemiyordu. Bağlantı isteği
  atılıyor, yanıt gelmiyordu. Not: bu bir "HF limiti" DEĞİLDİR —
  daha önce rapora öyle yazılmıştı, o bilgi YANLIŞTI ve düzeltildi. | — |
| Çözüm: `/etc/hosts` ile IPv4 üzerinden erişim zorlandı, dosyalar
  HF'ın resmi aracı (`hf upload`) ile yüklendi | 6/6 dosya yüklendi,
  200 döndü |
| Git tarihi düzeltildi; GGUF'lar LFS pointer olarak repoya işlendi;
  hf upload'ın commit'leriyle birleştirildi (rebase) | Push OK |
| **Nihai durum:** remote main = `c209fdf`, HF dosyaları erişilebilir,
  vision çalışıyor | ANAHTAR TESLİM |

---

## 6. NASIL KULLANACAKSIN? (3 ADIM)

1. **Modeli indir:** HF linklerinden (2.1) GGUF dosyalarını al.
   En pratik: `git clone https://huggingface.co/void0x14/echo`
2. **llama.cpp kur:** https://github.com/ggml-org/llama.cpp (veya bu
   makinede hazır: `/tmp/llama-upstream/build/bin/llama-cli`)
3. **Çalıştır:**
   ```
   ./run_multimodal.sh resim.png "soru metni"
   ```
   veya vision yoksa, N=4 text için:
   ```
   llama-cli -m MVP/artifacts/gguf/qwen35-distilled-n4-Q4_K_M.gguf -p "Merhaba" -ngl 99
   ```

---

## 7. DOSYA HARİTASI

```
echo/ (repo kökü, git)
├── MVP/
│   ├── ANAHTAR_TESLIM.md        ← bu doküman
│   ├── REPORT_FINAL.md          ← detaylı rapor (v3)
│   ├── run_multimodal.sh        ← tek tuşla görme testi
│   ├── qwen35_prune.py          ← distillasyon kodu
│   ├── validate_checkpoint.py   ← kontrol noktası doğrulayıcı
│   ├── tests/                   ← sözleşme testleri
│   ├── evidence/                ← tüm kanıt logları
│   ├── evidence/multimodal/     ← görme test kanıtları
│   └── artifacts/
│       ├── gguf/                ← N=4 küçültülmüş model (4 dosya)
│       ├── gguf-vision/         ← orijinal görme modeli (2 dosya)
│       └── ... (safetensors checkpoint'ler)
└── docs/superpowers/            ← plan ve tasarım dokümanları
```