docs: ANAHTAR TESLIM — sifirdan eksiksiz devir dokumani

MVP/ANAHTAR_TESLIM.md

@@ -0,0 +1,167 @@
+# 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ı
+```