147 lines
14 KiB
Markdown
147 lines
14 KiB
Markdown
# 🏆 WSC2026 Test Project - Veb Texnologiyalar
|
|
## **D Moduli: AI yordamida ishlaydigan Global City Explorer (Full-stack Integratsiya)**
|
|
|
|
### **1. Loyiha haqida umumiy ma'lumot (Project Overview)**
|
|
Siz 'Global City Explorer' platformasining full-stack dasturchisisiz. Ichki AI muhandislik jamoasi matnli ma'lumotlarni tahlil qilish va rasmlardan kalit so'zlarni ajratib olish uchun mahalliy AI modellaridan (Ollama) foydalanadigan **'AI Middleware Server'** ni (AI Oraliq Serveri) ishlab chiqdi. Bu sizga Starter Kit (Boshlang'ich to'plam) sifatida taqdim etilgan.
|
|
|
|
Sizning vazifangiz taqdim etilgan AI serverini ishga tushirish, uning API'larini tahlil qilish va administratorlar shahar ma'lumotlarini yaratishi, o'qishi, yangilashi va o'chirishi (CRUD) mumkin bo'lgan mukammal **Front-end (UI)** yaratishdir. Bundan tashqari, ma'lumotlarni faqat qat'iy server tekshiruvidan (server-side validation) o'tgandan keyingina qayta ishlaydigan va xavfsiz saqlaydigan kuchli **Back-end (DB Storage)** ni ishlab chiqishingiz kerak.
|
|
|
|
---
|
|
|
|
### **2. Infratuzilmani sozlash (Infrastructure Setup)**
|
|
Vazifani boshlashdan oldin, shaxsiy kompyuteringiz AI modellari va Node.js serverini ishga tushirish talablariga javob berishiga ishonch hosil qilishingiz va atrof-muhitni shunga mos ravishda sozlashingiz kerak.
|
|
|
|
#### **2.1. Uskuna talablari (Hardware Requirements)**
|
|
Mahalliy muhitda ikkita AI modelini uzluksiz ishga tushirish uchun quyidagi xususiyatlar tavsiya etiladi:
|
|
* **Xotira (RAM):** Kamida 8GB / Tavsiya etiladi 16GB+ (Ikkala model ham xotiraga yuklanishi kerak).
|
|
* **GPU:** 6GB+ VRAM'ga ega NVIDIA GPU tavsiya etiladi (CPU orqali ishlash ham mumkin, lekin tasvirni tahlil qilish vaqti kechikishi mumkin).
|
|
* **Disk hajmi (Storage):** Kamida 10GB bo'sh joy (HDD dan ko'ra SSD dan foydalanish qat'iy tavsiya etiladi).
|
|
|
|
#### **2.2. Node.js'ni tekshirish va o'rnatish**
|
|
Back-end oraliq dasturini (middleware) ishga tushirish uchun Node.js muhiti talab qilinadi.
|
|
1. Terminalni (yoki Command Prompt) oching va o'rnatilganligini tekshirish uchun `node -v` deb yozing. (`v18.x.x` yoki undan yuqori versiya chiqishi kutiladi).
|
|
2. **Agar o'rnatilmagan bo'lsa:** [Node.js rasmiy veb-saytiga (nodejs.org)](https://nodejs.org/) kiring, LTS (Long Term Support) versiyasini yuklab oling va o'rnating.
|
|
|
|
#### **2.3. Ollama (AI Dvigateli) ni tekshirish va o'rnatish**
|
|
1. Terminalni oching va versiyani tekshirish uchun `ollama -v` deb yozing.
|
|
2. **Agar o'rnatilmagan bo'lsa:** Windows tizimida **PowerShell**'ni Administrator sifatida ishga tushiring va o'rnatish uchun quyidagi buyruqni kiriting:
|
|
`irm https://ollama.com/install.ps1 | iex`
|
|
*(O'rnatish tugagandan so'ng, muhit o'zgaruvchilari (environment variables) qo'llanilishi uchun terminalni qayta ishga tushirishingiz kerak.)*
|
|
|
|
#### **2.4. AI modellarini yuklab olish va ularning xususiyatlari**
|
|
Ushbu loyihada foydalaniladigan ikkita AI modelini yuklab olish uchun terminalni oching va quyidagi buyruqlarni ketma-ket bajaring.
|
|
|
|
* **Matnni qayta ishlash modelini yuklab olish:** `ollama pull phi3`
|
|
* **[Model xususiyatlari]:** Microsoft tomonidan ishlab chiqilgan Kichik Til Modeli (SLM - Small Language Model). U yengil va tez bo'lib, mukammal matn yaratish va mantiqiy fikrlash qobiliyatiga ega. Bu uni shahar haqida qisqacha ma'lumot yozish uchun ideal qiladi.
|
|
* **Ko'rish (Tasvir) ni qayta ishlash modelini yuklab olish:** `ollama pull llava`
|
|
* **[Model xususiyatlari]:** Matn bilan bir qatorda 'Ko'rish' (Vision) imkoniyatlari bilan jihozlangan Multimodal AI. U foydalanuvchi tomonidan yuklangan diqqatga sazovor joylar tasvirlarini tahlil qilib, ob'ektlar yoki manzaralarni tasvirlaydi va asosiy kalit so'zlarni (keywords) ajratib oladi.
|
|
|
|
**🚨 MUHIM: Model nomlarini `ollama list` orqali tekshiring**
|
|
O'rnatish muhiti yoki vaqtiga qarab, yuklab olingan modellarning aniq nomlari va teglari farq qilishi mumkin (masalan, `phi3:latest`, `phi3:pb3`, `llava:latest` yoki shunchaki `llava`). Yuklab olgandan so'ng, kompyuteringizda muvaffaqiyatli o'rnatilgan modellarning aniq "NAME" (Nomi) ni tekshirish uchun terminalingizda albatta `ollama list` buyrug'ini ishga tushirishingiz SHART. Keyingi qadamdagi server sozlamalari uchun sizga ushbu aniq nomlar kerak bo'ladi.
|
|
|
|
---
|
|
|
|
### **3. AI Middleware Serverni o'rnatish va ishga tushirish**
|
|
Taqdim etilgan Starter Kit ichida AI muhandislik jamoasi tomonidan yaratilgan `ai-api` papkasi mavjud. Uning ichida `server.js` va `package.json` fayllarini topasiz.
|
|
|
|
**🚨 `server.js` faylini o'zgartirish bo'yicha DIQQAT va eslatma:**
|
|
Ishtirokchilar `server.js` faylini ochishi va model nomlarini o'zlarining mahalliy muhitiga moslashtirishi kerak. API marshrutlari (routes) kodidagi `model: 'phi3'` va `model: 'llava'` qatorlarini toping va ularni oldingi qadamda `ollama list` buyrug'i yordamida tekshirgan aniq nomlarga o'zgartiring (masalan, `model: 'phi3:pb3'` ga o'zgartiring). **Ushbu ikkita model nomini o'zgartirishdan tashqari, hech qanday holatda ushbu serverning asosiy mantiqiy kodlarini o'zgartirmang.**
|
|
|
|
1. Terminalni oching va taqdim etilgan `ai-api` papkasi katalogiga o'ting.
|
|
2. Kerakli paketlarni o'rnatish uchun quyidagi buyruqni kiriting:
|
|
`npm install`
|
|
3. O'rnatish tugagach, serverni ishga tushiring:
|
|
`npm start`
|
|
4. Agar terminalda `🚀 AI Middleware Server running on http://localhost:3000` xabari paydo bo'lsa, server to'g'ri ishlamoqda. Musobaqa moduli tugamaguncha bu terminalni yopmang.
|
|
|
|
---
|
|
|
|
### **4. HOPPSCOTCH orqali API test qilish**
|
|
Dasturlashni boshlashdan oldin, taqdim etilgan ikkita API qanday formatdagi ma'lumotlarni qaytarishini tushunish va test qilish uchun Hoppscotch (yoki Postman) dan foydalanishingiz SHART.
|
|
|
|
* **1-API: Matn ma'lumotlarini yaratish (`POST /api/generate-text`)**
|
|
* Body (`application/json`): `{"city_name": "Paris", "country": "France"}`
|
|
|
|
|
|
* **2-API: Tasvirni kompleks tahlil qilish (`POST /api/analyze-image`)**
|
|
* Body (`multipart/form-data`): `city_name` (Text), `country` (Text), `image` (Rasm yuklash uchun File formati)
|
|
|
|
|
|
---
|
|
|
|
### **5. Bajarilishi kerak bo'lgan vazifalar (Tasks to Complete)**
|
|
|
|
#### **5.1. Front-end talablari (Kengaytirilgan UI/UX)**
|
|
Administratorlar uchun `index.html` (yoki SPA framework) interfeysini yarating. Ekran asosan **'Ma'lumotlarni ro'yxatdan o'tkazish/Tahrirlash hududi'** va **'Ro'yxatga olinganlarni ko'rish hududi'** ga bo'linishi kerak.
|
|
|
|
* **[Ma'lumotlarni ro'yxatdan o'tkazish va tahrirlash hududi (Form Area)]**
|
|
* **Tasvirni oldindan ko'rish (Image Preview):** `<input type="file">` orqali rasm tanlanganda, u serverga yuborilishidan oldin ekranda rasm eskizi (thumbnail) darhol paydo bo'lishi kerak.
|
|
* **AI ma'lumotlar integratsiyasi:** Shahar/davlat nomini kiritgandan so'ng AI matn yaratish API'sini chaqiring va rasm yuklangandan so'ng AI vizual tahlil API'sini chaqiring. Qaytarilgan ma'lumotlar bilan formani to'ldiring.
|
|
* **Formani qulflash va yuklanish (Asynchronous State Management):** Og'ir AI tahlili biroz vaqt (10~30 soniya) talab qilganligi sababli, jarayon davomida foydalanuvchi qayta-qayta bosishining va xatoliklarning oldini olish uchun barcha kiritish maydonlari (input fields) va tugmalarni **qulflashingiz (disabled)** kerak. Bundan tashqari, foydalanuvchi tajribasini (UX) optimallashtirish uchun aniq yuklanish UI elementini (spinner, progress bar va hk.) ko'rsating.
|
|
* **Ma'lumotlarni tahrirlash va AI'dan qayta yuklash (Re-fetch):**
|
|
* Ro'yxatdagi ma'lum bir shahar uchun 'Tahrirlash' (Edit) tugmachasini bosish, formani o'sha shaharning ma'lumotlari bilan to'ldirishi kerak.
|
|
* Tahrirlash formasi **'Barcha ma'lumotlarni AI'dan qayta yuklash'** tugmasini o'z ichiga olishi kerak. Ushbu tugmani bosish formadagi joriy shahar, davlat va rasmga asoslanib, ikkala AI API'sini ham qayta ishga tushirishi va matn qiymatlarini (tavsif, kalit so'zlar) butunlay yangi AI javobi bilan almashtirishi kerak. Foydalanuvchi 'Yakuniy saqlash' ni bosganidagina ma'lumotlar DB'da yangilanadi.
|
|
|
|
* **[Ro'yxatni ko'rish va filtrlash hududi (List & Interactive Filtering)]**
|
|
* Butun dunyo bo'ylab saqlangan shahar ma'lumotlarini DB'dan oling va uni vizual ravishda Ro'yxat (List) yoki Kartalar Galereyasi (Card Gallery) formatida ko'rsating. Har bir elementda **'Tahrirlash' (Edit)** va **'O'chirish' (Delete)** tugmalari bo'lishi kerak.
|
|
* **Ma'lumotlarni o'chirish (Delete):** 'O'chirish' tugmasi bosilganda, tasodifan o'chirib yuborishning oldini olish uchun brauzerning standart `confirm` oynasi yoki maxsus Modal orqali foydalanuvchidan tasdiqlashni so'rang. Tasdiqlangandan so'ng, ma'lumotlarni DB'dan o'chiring va ro'yxatni darhol yangilang.
|
|
* **Heshteg orqali filtrlash:** Ro'yxatda ko'rsatilgan ma'lum bir kalit so'zni (masalan, `#EiffelTower`) bosish orqali darhol butun ro'yxat filtrlari ishga tushishi va faqat o'sha kalit so'zni o'z ichiga olgan shahar kartalarigina ko'rsatilishi kerak.
|
|
|
|
#### **5.2. Back-end talablari (DB va Server tomonida tekshirish)**
|
|
Ma'lumotlaringizni Yaratish, O'qish, Yangilash va O'chirish (CRUD - Create, Read, Update, Delete) operatsiyalarini mukammal bajarish uchun shaxsiy back-end serveringiz va ma'lumotlar bazasini yarating.
|
|
|
|
* **DB Sxemasi:** MySQL/MariaDB da `city_contents` jadvalini loyihalashtiring va yarating.
|
|
* **API ilovasi (CRUD):**
|
|
1. **GET (O'qish):** DB'da saqlangan barcha ma'lumotlarni JSON formatida qaytaradi.
|
|
2. **POST (Yaratish):** DB'ga yangi ma'lumotlarni `INSERT` qiladi va yuklangan rasmni jismoniy jihatdan yuklash (uploads) papkasiga saqlaydi.
|
|
3. **PUT yoki PATCH (Yangilash):** Muayyan ID uchun ma'lumotlarni yangilaydi. (Agar yangi rasm yuborilsa, eski rasm faylini almashtirishingiz yoki yangi fayl yo'lini yangilashingiz kerak).
|
|
4. **DELETE (O'chirish):** Muayyan ID uchun ma'lumotlarni DB'dan o'chiradi.
|
|
* **Server tomonida tekshirish (Xavfsizlikni tekshirish):** POST va PUT/PATCH so'rovlari uchun FAQAT quyidagi tekshiruvlardan o'tgan ma'lumotlargina serverga saqlanishi kerak:
|
|
1. **Fayl hajmi chegarasi:** Agar yuklangan rasm **5MB** dan oshsa, server so'rovni rad etishi va 400 HTTP status kodi (Bad Request) bilan birga xatolik xabarini qaytarishi kerak.
|
|
2. **Kengaytmani tekshirish:** Agar rasm ruxsat etilgan formatda bo'lmasa (`.jpg`, `.jpeg`, `.png`, `.webp`), server yuklashni rad etishi kerak.
|
|
|
|
#### **5.3. Qo'shimcha talablar (Xatolar va baholash mezonlari)**
|
|
* **Ma'lumotlarni tahlil qilish (Data Parsing):** Vision API javobida `keywords` toza massiv (array) sifatida emas, balki **JSON formatida o'ralgan matnli massiv (Stringified Array)** sifatida qaytariladi. Ularni toza va alohida teg UI sifatida ko'rsatish uchun front-end albatta to'g'ri tahlil qilish (parsing - `JSON.parse`) ni amalga oshirishi SHART.
|
|
* **Istisnolarni ko'rib chiqish (Exception Handling):** Agar back-end tekshiruvi muvaffaqiyatsiz bo'lsa (masalan, Fayl hajmi oshib ketdi), front-end ilovasi buzilmasligi (crash) kerak. U xatoni ushlab olishi (catch) va foydalanuvchini `alert` yoki Modal oyna orqali aniq xabardor qilishi kerak.
|
|
|
|
---
|
|
|
|
### **6. Ishtirokchi ish stoli bo'yicha qo'llanma (Competitor Workspace Guide)**
|
|
|
|
* **AI Middleware ishga tushirish joyi:** Taqdim etilgan `ai-api` papkasi. (1-Terminalda ishga tushiring va uni ochiq qoldiring).
|
|
* **Ishtirokchi ish stoli:** Sizning veb-serveringizning asosiy(root) papkasi (masalan, `http://localhost/module-d/`).
|
|
* **Baholashga tayyorgarlik:** Modul oxirida AI Middleware terminali ham, siz yaratgan veb-server ham ishlab turgan bo'lishi kerak. Ekspertlar brauzer orqali ulanadi va quyidagi siklni ketma-ket sinab ko'radi:
|
|
1. 5MB dan katta hajmdagi rasmni yuklashga urinish (Xatoni ushlab qolishni tekshirish)
|
|
2. Oddiy ma'lumotlarni yaratish (Create)
|
|
3. Ro'yxatni ko'rish va heshtegni bosish orqali filtrlash (Read & Filter)
|
|
4. **'Tahrirlash' tugmasini bosish, 'AI'dan qayta yuklash' orqali tarkibni yangilash va Saqlash (Update)**
|
|
5. **Ma'lumotni butunlay yo'q qilish uchun 'O'chirish' tugmasini bosish (Delete)**
|
|
|
|
---
|
|
|
|
### **7. Ilova: Namuna ma'lumotlar (Sample Data)**
|
|
Test qilish va yakuniy namoyish uchun quyidagi shahar/davlat ro'yxatidan foydalaning. **Test qilish uchun tavsiya etilgan diqqatga sazovor joylarning rasmlari Starter Kit ichidagi `sample-images` papkasida taqdim etilgan.** (Back-end himoya mantiqini sinab ko'rish uchun kamida bitta 5MB dan katta yuqori aniqlikdagi rasmni tayyorlab qo'ying).
|
|
|
|
| Shahar nomi | Davlat nomi | Diqqatga sazovor joy (Landmark) |
|
|
| :--- | :--- | :--- |
|
|
| **Paris** | France | Eyfel minorasi, Luvr muzeyi |
|
|
| **Seoul** | South Korea | Kyonbokkun saroyi, N Seul minorasi |
|
|
| **Tokyo** | Japan | Tokio minorasi, Shibuya chorrahasi |
|
|
| **New York** | USA | Ozodlik haykali, Tayms maydoni |
|
|
| **Rome** | Italy | Kolizey, Trevi favvorasi |
|
|
| **Sydney** | Australia | Opera teatri, Harbor ko'prigi |
|
|
| **Cairo** | Egypt | Giza piramidalari, Sfinks |
|
|
| **London** | UK | Big Ben, London ko'zi |
|
|
|
|
---
|
|
|
|
### **8. Baholash xulosasi (Mark Summary - Jami 25 ball)**
|
|
Ushbu jadval baholash toifalari bo'yicha ajratilgan ballar xulosasini beradi. Batafsil baholash sxemasi (Marking Scheme) alohida taqdim etiladi.
|
|
|
|
| Toifa (Category) | Tavsif (Description) | Maksimal Ball |
|
|
| :--- | :--- | :---: |
|
|
| **A. Front-end UI & UX** | UI tuzilishi, Asinxron holatni boshqarish (Yuklash/Qulflash), Ma'lumotlarni ulash (Binding) va Tahlil qilish (Parsing) | 7 |
|
|
| **B. Data Interaction** | Ma'lumotlar ro'yxatini ko'rsatish (rendering) va Heshtegga asoslangan filtrlash funksiyasi | 5 |
|
|
| **C. Back-end CRUD API** | DB va Fayl tizimida Yaratish, O'qish, Yangilash (AI'dan qayta yuklash bilan birga) va O'chirish amallari | 8 |
|
|
| **D. Security & Validation**| Server tomonida fayl hajmi/kengaytmani tekshirish, Mijoz tomonida istisnolarni (xatolarni) ko'rib chiqish | 5 |
|
|
| **Jami Ballar** | | **25** | |