README.et.md
7,346 bytes
| 1 | # CountrySense |
|---|---|
| 2 | |
| 3 | Mudel, mis arvab ühe tänavapildi järgi ära riigi. Peenhäälestatud CLIP-i nägemistransformer (ViT-B/16) klassifitseerib pildi umbes saja riigi vahel. Ainult riigi tase: ei mingeid koordinaate ega linnade äraarvamist. |
| 4 | |
| 5 | Põhjalik arhitektuuri selgitus (kihthaaval, koos andmete valiku ja puhastamisega) on failis [docs/mudel.html](docs/mudel.html). Ava see brauseris. |
| 6 | |
| 7 | ## Miks riigi tase, mitte koordinaadid |
| 8 | |
| 9 | Täpne geolokatsioon (laius- ja pikkuskraadi ennustamine) on teadusartikli tasemel ülesanne: vaja on miljoneid pilte, suuri mudeleid ja arvutusressurssi, mida sel projektil ei ole. Riigi klassifitseerimine umbes saja riigi vahel on seevastu tavaline juhendatud õppe ülesanne: eeltreenitud nägemismudeli peenhäälestus mahub tasuta Colabi või Kaggle'i GPU peale ja annab demos üllatavalt hea täpsuse. |
| 10 | |
| 11 | Aus teekaart on selline: kõigepealt riik, hiljem regioon riigi sees (näiteks "Eesti, Lõuna-Eesti"). Koordinaadid ei ole plaanis. |
| 12 | |
| 13 | ## Andmestik ja valikukriteeriumid |
| 14 | |
| 15 | Vaikimisi andmestik on Kaggle'i [GeoLocation, Geoguessr Images 50K](https://www.kaggle.com/datasets/ubitquitin/geolocation-geoguessr-images-50k): umbes 50 000 Street View pilti, kaustad riikide kaupa. |
| 16 | |
| 17 | Valikukriteeriumid olid: |
| 18 | |
| 19 | - Sildid on kaustastruktuuris olemas, käsitsi märgendamist pole vaja. |
| 20 | - Umbes 150 riiki, millest pärast puhastust jääb alles 100 ringis. Piisavalt, et ülesanne oleks huvitav, ja piisavalt vähe, et tasuta GPU-ga hakkama saada. |
| 21 | - Suurus (mõni GB) mahub Colabi kettale ja laadimisaeg on talutav. |
| 22 | - Vaba juurdepääs kagglehub kaudu, API võtit pole vaja. |
| 23 | |
| 24 | Kood ei sõltu konkreetsest andmestikust: sobib iga kaust paigutusega `root/<riik>/<pilt>`. Suuremaks skaleerimiseks on hea kandidaat OpenStreetView-5M alamhulk. |
| 25 | |
| 26 | Oluline ausus: Street View kaamera katvus on kaldu rikaste riikide poole ja mudel õpib paratamatult ka kaamera artefakte (põlvkond, resolutsioon), mitte ainult maastikku. See on osa sellest, miks demo tundub "maagiline", ja see on dokumenteeritud, mitte maha vaikitud. |
| 27 | |
| 28 | ## Andmete puhastamine |
| 29 | |
| 30 | `countrysense/clean.py` käib kõik pildid läbi ja kirjutab manifesti (`data/manifest.csv`) ning raporti (`data/cleaning_report.csv`), kus iga välja jäetud pildi juures on põhjus. |
| 31 | |
| 32 | | Samm | Reegel | Miks | |
| 33 | |---|---|---| |
| 34 | | Rikutud failid | PIL ei suuda avada | Katkine allalaadimine kukutaks treeningu | |
| 35 | | Suurus | lühem külg < 128 px | Liiga vähe infot, ViT sisend on 224 px | |
| 36 | | Heledus | keskmine < 20 või > 235 | Praktiliselt mustad või läbipõlenud kaadrid | |
| 37 | | Teravus | gradiendi energia < 25 | Udused kaadrid (liikumine, vihm objektiivil) | |
| 38 | | Duplikaadid | sama phash (perceptual hash) | Street View annab kattuvaid kaadreid; duplikaat train- ja testihulgas oleks leke | |
| 39 | | Väikesed klassid | riigil < 100 pilti | Liiga vähe, et õppida ja usaldusväärselt mõõta | |
| 40 | | Suured klassid | lagi 2000 pilti riigi kohta | Vähendab tasakaalustamatust juba andmete tasemel | |
| 41 | |
| 42 | Läved on käsurea argumendid, vaikeväärtused on tabelis. |
| 43 | |
| 44 | ## Mudel ja valikukriteeriumid |
| 45 | |
| 46 | Backbone on OpenAI CLIP-i eeltreenitud ViT-B/16 (`vit_base_patch16_clip_224.openai` timm-i kaudu), 86 miljonit parameetrit. Pea on `Dropout(0.2)` pluss üks `Linear(768 -> riikide arv)` kiht. |
| 47 | |
| 48 | Kaalutud variandid: |
| 49 | |
| 50 | | Variant | Hinnang | |
| 51 | |---|---| |
| 52 | | CLIP ViT-B/16 (valitud) | Eeltreenitud 400M pilt-tekst paari peal, tunnused kodeerivad juba silte, taimestikku, arhitektuuri ja teemärgistust. Lineaarne pea CLIP-i tunnuste peal on tugev geolokatsiooni baastase. Mahub T4 peale. | |
| 53 | | ImageNet ViT/ConvNeXt | Töötab, aga ImageNeti klassid (koeratõud, esemed) on geograafiast kaugemal, transfer on nõrgem. | |
| 54 | | StreetCLIP (ViT-L/14) | Geolokatsiooniks juba häälestatud, aga kolm korda suurem, peenhäälestus tasuta T4 peal on kitsas. Hea järgmine samm, kui riistvara lubab. | |
| 55 | | Nullist treenitud CNN | Selle andmemahuga lootusetu, eeltreening on kogu projekti võimaldaja. | |
| 56 | |
| 57 | Miks ainult üks lineaarne kiht peas: CLIP-i tunnused on juba suures osas lineaarselt eraldatavad ja sügavam pea kipub selle andmemahuga üle sobituma. Detailne selgitus, mida transformeri sees olevad dense-kihid teevad, on failis [docs/mudel.html](docs/mudel.html). |
| 58 | |
| 59 | ## Treening |
| 60 | |
| 61 | Kaks faasi, kokku umbes 1 kuni 2 tundi tasuta T4 GPU peal: |
| 62 | |
| 63 | 1. **Faas 1, lineaarne sondeerimine (3 epohhi, lr 1e-3).** Backbone on külmutatud, treenime ainult pead. Juhuslikult initsialiseeritud pea gradiendid on alguses suured ja rikuksid eeltreenitud kaalud, seega laseme peal enne stabiliseeruda. |
| 64 | 2. **Faas 2, osaline peenhäälestus (8 epohhi, lr 2e-5 backbone / 1e-4 pea, koosinusgraafik).** Avame ainult viimased 4 transformeri plokki ja lõpu normi. Alumised kihid õpivad üldisi servi ja tekstuure, mis on niigi head; ülemised kihid kannavad semantikat, mida tasub geograafiale kohandada. Vähem avatud kihte tähendab ka vähem mälu ja väiksemat katastroofilise unustamise riski. |
| 65 | |
| 66 | Muud valikud: cross-entropy koos label smoothing 0.1 (piirialade sildid on loomupäraselt mürarikkad), AdamW, AMP (poolttäpsus), gradientide kärpimine, `WeightedRandomSampler` klasside tasakaalustamiseks (muidu domineeriksid suurte piltide arvuga riigid nagu USA). |
| 67 | |
| 68 | Augmentatsioonid: `RandomResizedCrop` (kaugus ja kadreering varieeruvad päriselt), kerge `ColorJitter` (valgustus ja kaamera). Teadlikult **ei kasuta** horisontaalset peegeldust: vasak- või parempoolne liiklus on päris geograafiline tunnus, mille peegeldamine õpetaks mudelile valet. Samal põhjusel ei pöörata pilti: horisondi asend on info. |
| 69 | |
| 70 | ## Mõõtmine |
| 71 | |
| 72 | `evaluate.py` raporteerib top-1, top-5 ja makro-F1, kirjutab riigipõhise täpsuse tabeli ja confusion matrix'i. Top-5 on geograafias aus mõõdik: Eesti ja Läti segiajamine on palju väiksem viga kui Eesti ja Brasiilia oma, ja vigade seas domineerivadki naabrid (Balti riigid omavahel, Skandinaavia, hispaaniakeelne Ladina-Ameerika). |
| 73 | |
| 74 | ## Käivitamine |
| 75 | |
| 76 | Colab (soovitatav): ava `notebooks/train_colab.ipynb`, vali T4 GPU ja käivita kõik lahtrid. |
| 77 | |
| 78 | Kohalikult: |
| 79 | |
| 80 | ```bash |
| 81 | pip install -r requirements.txt |
| 82 | python -m countrysense.clean --raw-dir data/raw |
| 83 | python -m countrysense.train --config configs/default.yaml |
| 84 | python -m countrysense.evaluate --checkpoint runs/clip_vit_b16/best.pt |
| 85 | python -m countrysense.predict --image minu_pilt.jpg |
| 86 | ``` |
| 87 | |
| 88 | Gradio demo: `pip install gradio` ja `python app.py`. |
| 89 | |
| 90 | ## Tulemused |
| 91 | |
| 92 | Täida pärast esimest treeningut (`runs/clip_vit_b16/metrics.json`): |
| 93 | |
| 94 | | Mõõdik | Väärtus | |
| 95 | |---|---| |
| 96 | | Top-1 | ... | |
| 97 | | Top-5 | ... | |
| 98 | | Makro-F1 | ... | |
| 99 | |
| 100 | Tüüpiline ootus selle retseptiga ja ~100 riigiga: top-1 vahemikus 50 kuni 70 protsenti ja top-5 üle 80 protsendi, sõltuvalt puhastusest ja epohhide arvust. Juhuslik pakkumine oleks 1 protsent. |
| 101 | |
| 102 | ## Piirangud |
| 103 | |
| 104 | - Street View katvus ja kaamera bias: mudel õpib osalt kaamerat, mitte maastikku. |
| 105 | - Riigid, mida andmestikus pole, ennustatakse paratamatult valesti mõneks naabriks. |
| 106 | - Sisetingimustes, dokumentidel ja inimestel pole mudelil mõtet, see on tänavavaadete klassifitseerija. |
| 107 | |
| 108 | ## Teekaart |
| 109 | |
| 110 | - [ ] Regioonitase riigi sees (hierarhiline pea: enne riik, siis regioon) |
| 111 | - [ ] Suurem treeningandmestik (OpenStreetView-5M alamhulk) |
| 112 | - [ ] Kalibratsioon ja keeldumine ("pole piisavalt kindel, et pakkuda") |
| 113 | - Plaanis ei ole: täpsed koordinaadid. See on teadustöö territoorium (PIGEON, GeoCLIP) ja nõuab arvutusmahtu, mida see projekt teadlikult väldib. |
| 114 | |