add some explanation in the module test project

This commit is contained in:
2026-04-14 15:16:06 +09:00
parent 3100c40421
commit 19a707d227
3 changed files with 25 additions and 8 deletions

View File

@@ -29,17 +29,23 @@ A Node.js environment is required to run the back-end middleware.
*(After installation, you must restart your terminal to apply the environment variables.)* *(After installation, you must restart your terminal to apply the environment variables.)*
#### **2.4. AI Model Download & Characteristics** #### **2.4. AI Model Download & Characteristics**
Open your terminal and run the following commands sequentially to download the two AI models used in this project. (Verify the installation using the `ollama list` command). Open your terminal and run the following commands sequentially to download the two AI models used in this project.
* **Download Text Processing Model:** `ollama pull phi3` * **Download Text Processing Model:** `ollama pull phi3`
* **[Model Characteristics]:** A Small Language Model (SLM) developed by Microsoft. It is lightweight and fast, possessing excellent text generation and logical reasoning capabilities, making it ideal for writing city introductions. * **[Model Characteristics]:** A Small Language Model (SLM) developed by Microsoft. It is lightweight and fast, possessing excellent text generation and logical reasoning capabilities, making it ideal for writing city introductions.
* **Download Vision (Image) Processing Model:** `ollama pull llava` * **Download Vision (Image) Processing Model:** `ollama pull llava`
* **[Model Characteristics]:** A Multimodal AI equipped with 'Vision' capabilities alongside text. It analyzes uploaded landmark images to describe objects or scenery and extracts core keywords. * **[Model Characteristics]:** A Multimodal AI equipped with 'Vision' capabilities alongside text. It analyzes uploaded landmark images to describe objects or scenery and extracts core keywords.
**🚨 IMPORTANT: Verify Model Names via `ollama list`**
Depending on the installation environment or timing, the exact names and tags of the downloaded models may vary (e.g., `phi3:latest`, `phi3:pb3`, `llava:latest`, or just `llava`). After downloading, you **MUST** run the `ollama list` command in your terminal to check the exact "NAME" of the models successfully installed on your PC. You will need these exact names for the next step.
--- ---
### **3. AI Middleware Server Setup & Execution** ### **3. AI Middleware Server Setup & Execution**
The provided Starter Kit contains an `ai-api` folder created by the AI engineering team. Inside, you will find `server.js` and `package.json`. **(🚨 NOTICE: Do NOT modify the code in this server under any circumstances.)** The provided Starter Kit contains an `ai-api` folder created by the AI engineering team. Inside, you will find `server.js` and `package.json`.
**🚨 NOTICE regarding `server.js` modification:**
You must open `server.js` and update the model names to match your local environment. Locate the `model: 'phi3'` and `model: 'llava'` properties inside the API routes and change them to the exact names you verified using the `ollama list` command (e.g., change to `model: 'phi3:pb3'`). **Other than updating these two model names, do NOT modify the core logic of this server under any circumstances.**
1. Open a terminal and navigate to the provided `ai-api` folder directory. 1. Open a terminal and navigate to the provided `ai-api` folder directory.
2. Enter the following command to install the required packages: 2. Enter the following command to install the required packages:
@@ -48,7 +54,6 @@ The provided Starter Kit contains an `ai-api` folder created by the AI engineeri
`npm start` `npm start`
4. If the message `🚀 AI Middleware Server running on http://localhost:3000` appears in the terminal, the server is running correctly. Do not close this terminal until the competition module ends. 4. If the message `🚀 AI Middleware Server running on http://localhost:3000` appears in the terminal, the server is running correctly. Do not close this terminal until the competition module ends.
---
### **4. API Testing via HOPPSCOTCH** ### **4. API Testing via HOPPSCOTCH**
Before starting your development, you must use Hoppscotch (or Postman) to test the two provided APIs and understand the format of the data they return. Before starting your development, you must use Hoppscotch (or Postman) to test the two provided APIs and understand the format of the data they return.

View File

@@ -29,17 +29,23 @@
*(설치가 완료되면 터미널을 재시작해야 환경변수가 적용됩니다.)* *(설치가 완료되면 터미널을 재시작해야 환경변수가 적용됩니다.)*
#### **2.4. AI 모델 다운로드 및 특징** #### **2.4. AI 모델 다운로드 및 특징**
터미널을 열고 아래 명령어를 순차적으로 실행하여 본 과제에 사용할 2개의 AI 모델을 다운로드합니다. (`ollama list` 명령어로 설치 완료 확인) 터미널을 열고 아래 명령어를 순차적으로 실행하여 본 과제에 사용할 2개의 AI 모델을 다운로드합니다.
* **텍스트 처리 모델 다운로드:** `ollama pull phi3` * **텍스트 처리 모델 다운로드:** `ollama pull phi3`
* **[모델 특징]:** Microsoft에서 개발한 초경량 언어 모델(SLM)입니다. 가볍고 빠르면서도 훌륭한 문장 생성 및 논리적 추론 능력을 갖추고 있어 도시의 소개글을 작성하는 데 사용됩니다. * **[모델 특징]:** Microsoft에서 개발한 초경량 언어 모델(SLM)입니다. 가볍고 빠르면서도 훌륭한 문장 생성 및 논리적 추론 능력을 갖추고 있어 도시의 소개글을 작성하는 데 사용됩니다.
* **비전(이미지) 처리 모델 다운로드:** `ollama pull llava` * **비전(이미지) 처리 모델 다운로드:** `ollama pull llava`
* **[모델 특징]:** 텍스트뿐만 아니라 '눈(Vision)'을 가진 멀티모달(Multimodal) AI입니다. 사용자가 업로드한 명소 이미지를 분석하여 그 안의 객체나 풍경을 설명하고 핵심 키워드를 추출하는 역할을 합니다. * **[모델 특징]:** 텍스트뿐만 아니라 '눈(Vision)'을 가진 멀티모달(Multimodal) AI입니다. 사용자가 업로드한 명소 이미지를 분석하여 그 안의 객체나 풍경을 설명하고 핵심 키워드를 추출하는 역할을 합니다.
**🚨 중요: `ollama list`를 통한 모델명 확인**
설치 환경이나 다운로드 시점에 따라 설치된 모델의 정확한 이름과 태그가 다를 수 있습니다 (예: `phi3:latest`, `phi3:pb3`, `llava:latest` 또는 태그 없이 `llava`). 다운로드가 완료되면 터미널에서 반드시 `ollama list` 명령어를 실행하여 PC에 설치된 모델들의 정확한 "NAME"을 확인하십시오. 다음 단계의 서버 설정에서 이 정확한 이름이 필요합니다.
--- ---
### **3. AI Middleware Server 설치 및 실행** ### **3. AI Middleware Server 설치 및 실행**
제공된 Starter Kit 안에는 AI 엔지니어링 팀이 작성한 `ai-api` 폴더가 있습니다. 이 폴더 안에는 `server.js``package.json`이 포함되어 있습니다. **(🚨 주의: 이 서버의 코드는 절대 수정하지 마십시오.)** 제공된 Starter Kit 안에는 AI 엔지니어링 팀이 작성한 `ai-api` 폴더가 있습니다. 이 폴더 안에는 `server.js``package.json`이 포함되어 있습니다.
**🚨 `server.js` 모델명 수정 안내 및 주의사항:**
선수들은 `server.js` 파일을 열고 본인의 로컬 환경에 맞게 모델명을 업데이트해야 합니다. 파일 내 API 라우트 코드에 작성된 `model: 'phi3'``model: 'llava'` 속성을 찾아, 앞서 `ollama list` 명령어로 확인한 정확한 이름으로 변경하십시오 (예: `model: 'phi3:pb3'`로 변경). **이 두 개의 모델명을 수정하는 것 외에, 서버의 다른 핵심 로직 코드는 절대 수정하지 마십시오.**
1. 터미널을 열고 제공된 `ai-api` 폴더 경로로 이동합니다. 1. 터미널을 열고 제공된 `ai-api` 폴더 경로로 이동합니다.
2. 아래 명령어를 입력하여 필수 패키지를 설치합니다. 2. 아래 명령어를 입력하여 필수 패키지를 설치합니다.
@@ -47,7 +53,7 @@
3. 설치가 완료되면 서버를 실행합니다. 3. 설치가 완료되면 서버를 실행합니다.
`npm start` `npm start`
4. 터미널에 `🚀 AI Middleware Server running on http://localhost:3000` 메시지가 출력되면 서버가 정상 작동 중인 것입니다. 이 터미널은 과제가 끝날 때까지 닫지 마십시오. 4. 터미널에 `🚀 AI Middleware Server running on http://localhost:3000` 메시지가 출력되면 서버가 정상 작동 중인 것입니다. 이 터미널은 과제가 끝날 때까지 닫지 마십시오.
--- ---
### **4. HOPPSCOTCH를 활용한 API 테스트** ### **4. HOPPSCOTCH를 활용한 API 테스트**

View File

@@ -29,17 +29,23 @@ Back-end oraliq dasturini (middleware) ishga tushirish uchun Node.js muhiti tala
*(O'rnatish tugagandan so'ng, muhit o'zgaruvchilari (environment variables) qo'llanilishi uchun terminalni qayta ishga tushirishingiz kerak.)* *(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** #### **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. (O'rnatish muvaffaqiyatli bo'lganini `ollama list` buyrug'i orqali tekshiring). 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` * **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. * **[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` * **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. * **[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** ### **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. **(🚨 DIQQAT: Hech qanday holatda ushbu server kodini o'zgartirmang.)** 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. 1. Terminalni oching va taqdim etilgan `ai-api` papkasi katalogiga o'ting.
2. Kerakli paketlarni o'rnatish uchun quyidagi buyruqni kiriting: 2. Kerakli paketlarni o'rnatish uchun quyidagi buyruqni kiriting: