From 12e3ee041631f1b167328d31e28bbcd45162c804 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EC=9E=84=ED=98=9C=EC=A0=95?= Date: Mon, 25 Aug 2025 04:47:00 +0900 Subject: [PATCH 1/2] =?UTF-8?q?:memo:=20docs:=20=EB=A6=AC=EB=93=9C?= =?UTF-8?q?=EB=AF=B8=20=EC=88=98=EC=A0=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 155 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 87 insertions(+), 68 deletions(-) diff --git a/README.md b/README.md index 3e20804..03b777c 100644 --- a/README.md +++ b/README.md @@ -1,99 +1,118 @@ -# ✨Project Convention✨ ---- +# πŸ€– μž”λ°˜ν”ŒλŸ¬νŒ… AI -
- -## βœ‰οΈ Commit Convention +FastAPI 기반의 **AI μΆ”μ²œ μ„œλ²„**둜, μ‹μ•½μ²˜ μ˜μ–‘μ„±λΆ„ν‘œ 데이터λ₯Ό 기반으둜 +**λ§žμΆ€ν˜• 반찬 μΆ”μ²œ**κ³Ό **μ„­μ·¨ 팁 제곡**을 λ‹΄λ‹Ήν•©λ‹ˆλ‹€. -컀밋 λ©”μ‹œμ§€λŠ” **Udacity μŠ€νƒ€μΌ**을 μ‚¬μš©ν•˜λ©°, λ‹€μŒκ³Ό 같은 ꡬ쑰둜 μž‘μ„± +### πŸ”Ή AI κΈ°λŠ₯ -``` -type: Subject (제λͺ©) +* **메뉴 μΆ”μ²œ** -body (λ³Έλ¬Έ) (κΈ΄ μ„€λͺ…이 ν•„μš”ν•œ κ²½μš°μ— μž‘μ„±) + * 5가지 μ½˜μ…‰νŠΈ 기반: + `diet(λ‹€μ΄μ–΄νŠΈ)`, `keto(저탄고지)`, `low_sodium(μ €μ—Ό)`, `glycemic(ν˜ˆλ‹Ή)`, `bulking(λ²Œν¬μ—…)` + * μž…λ ₯ 메뉴λͺ… -> μœ μ‚¬λ„ 맀칭 -> μ˜μ–‘ μ„±λΆ„ ν”Όμ²˜ν™” -> μ½˜μ…‰νŠΈλ³„ μ μˆ˜ν™”(0\~100) -footer (꼬리말) (issue tracker IDλ₯Ό λͺ…μ‹œν•˜κ³  싢은 κ²½μš°μ— μž‘μ„±) -``` -
+* **Tip 생성** + + * OpenAI API 연동을 ν†΅ν•œ **μ‹μŠ΅κ΄€ κ°€μ΄λ“œ / λ ˆμ‹œν”Ό μ œμ•ˆ** + +--- +## πŸš€ Tech Stack -### πŸ›  **type**: μ»€λ°‹μ˜ μœ ν˜• +### πŸ”Ή Framework & Language +- **Python 3.11** +- **FastAPI : κ²½λŸ‰ μ›Ή ν”„λ ˆμž„μ›Œν¬** +- **Uvicorn : ASGI μ„œλ²„** -| νƒ€μž… | μ„€λͺ… | -|------------|------------------------------------------------| -| `feat` | ✨ μƒˆλ‘œμš΄ κΈ°λŠ₯ μΆ”κ°€ | -| `fix` | πŸ› 버그 μˆ˜μ • | -| `docs` | πŸ“ λ¬Έμ„œ μˆ˜μ • (README, 주석 λ“±) | -| `style` | πŸ’„ μ½”λ“œ ν¬λ§·νŒ…, μ„Έλ―Έμ½œλ‘  λˆ„λ½ λ“± κΈ°λŠ₯ 영ν–₯ μ—†λŠ” λ³€κ²½ | -| `refactor` | ♻️ μ½”λ“œ λ¦¬νŒ©ν† λ§ (κΈ°λŠ₯ λ³€ν™” μ—†μŒ) | -| `test` | βœ… ν…ŒμŠ€νŠΈ μ½”λ“œ μΆ”κ°€ λ˜λŠ” μˆ˜μ • | -| `chore` | πŸ”§ λΉŒλ“œ μ„€μ •, νŒ¨ν‚€μ§€ λ§€λ‹ˆμ € μ„€μ • λ“± 기타 μž‘μ—… | -| `perf` | ⚑ μ„±λŠ₯ κ°œμ„  | -| `ci` | πŸ”„ CI κ΄€λ ¨ μ„€μ • 및 슀크립트 μˆ˜μ • | -| `revert` | βš™οΈ 이전 컀밋 되돌리기 | + -
-### πŸ–ŠοΈ **Subject**: 제λͺ© -- 50자 μ΄λ‚΄λ‘œ κ°„κ²°ν•˜κ²Œ μž‘μ„± -- λ§ˆμΉ¨ν‘œ(`.`) κΈˆμ§€ -- κ³Όκ±° μ‹œμ œ X, λͺ…λ Ήμ–΄ μ‚¬μš© +### πŸ”Ή Data / ML +- **scikit-learn : 벑터화, 차원 μΆ•μ†Œ, μŠ€μΌ€μΌλ§, 결츑치 보정** +- **hnswlib : κ·Όμ ‘ 탐색 (메뉴λͺ… μœ μ‚¬λ„ 맀칭)** +- **numpy / joblib : 수치 μ—°μ‚° 및 λͺ¨λΈ 직렬화** +-**μ‹μ•½μ²˜ μ˜μ–‘μ„±λΆ„ν‘œ 데이터 (Excel/CSV) : μ˜μ–‘ 정보 기반 ν•™μŠ΅/μΆ”μ²œ** + + -
-### πŸ“ **Body**: λ³Έλ¬Έ +--- -- **선택 사항** -- 제λͺ©μ—μ„œ μ„€λͺ…ν•  수 μ—†λŠ” μΆ”κ°€ 정보λ₯Ό 제곡 -- "무엇을"κ³Ό "μ™œ"λ₯Ό μ€‘μ‹¬μœΌλ‘œ μƒμ„Ένžˆ 기술 -- ν•œ 쀄당 72자 μ΄λ‚΄λ‘œ μž‘μ„± -- ν•„μš”μ‹œ Markdown μ‚¬μš© κ°€λŠ₯ +## πŸ“‚ Project Structure +```text +πŸ“¦ menu-ai +β”œβ”€β”€ Dockerfile +β”œβ”€β”€ main.py # FastAPI μ‹€ν–‰ μ—”νŠΈλ¦¬ν¬μΈνŠΈ +β”œβ”€β”€ requirements.txt +β”œβ”€β”€ leftovers +β”‚ β”œβ”€β”€ core # μ„€μ •, μ—λŸ¬ ν•Έλ“€λŸ¬, 곡톡 응닡, μ™ΈλΆ€ ν΄λΌμ΄μ–ΈνŠΈ +β”‚ └── domain +β”‚ β”œβ”€β”€ recommend # 메뉴 μΆ”μ²œ 도메인 +β”‚ β”‚ β”œβ”€β”€ api/ # μΆ”μ²œ API +β”‚ β”‚ β”œβ”€β”€ data/ # 원본 μ˜μ–‘ 데이터 (μ‹μ•½μ²˜ μ—‘μ…€) +β”‚ β”‚ β”œβ”€β”€ model_store # ν•™μŠ΅λœ λͺ¨λΈ 및 μ „μ²˜λ¦¬ μ•„ν‹°νŒ©νŠΈ +β”‚ β”‚ β”œβ”€β”€ schemas/ # μš”μ²­/응닡 μŠ€ν‚€λ§ˆ +β”‚ β”‚ └── service/ # μΆ”μ²œ 둜직 (맀칭, μŠ€μ½”μ–΄λ§, μ „μ²˜λ¦¬, ν•™μŠ΅) +β”‚ └── tip # 팁/λ ˆμ‹œν”Ό 도메인 +β”‚ β”œβ”€β”€ api/ # Tip API +β”‚ β”œβ”€β”€ schemas/ # μš”μ²­/응닡 μŠ€ν‚€λ§ˆ +β”‚ └── service/ # ν”„λ‘¬ν”„νŠΈ/LLM 호좜 +``` --- -
+## πŸ”¬ 데이터 νŒŒμ΄ν”„λΌμΈ & μ•Œκ³ λ¦¬μ¦˜ -## 🌿 Git Flow 브랜치 μ „λž΅ (with `main`) 🌿 +1. **데이터 λ‘œλ”©** + * μ‹μ•½μ²˜ μ˜μ–‘ 데이터(`.xlsx`) λ‘œλ“œ -> 결츑치 보정(Imputer) -> μ •κ·œν™”(Scaler) -### 🌴 κΈ°λ³Έ 브랜치 -| 브랜치 | μ—­ν•  | -|--------|------| -| `main` | μ΅œμ’… 배포용 브랜치 (stable) | -| `develop` | λ‹€μŒ 배포λ₯Ό μœ„ν•œ 톡합 개발 브랜치 | +2. **메뉴λͺ… 맀칭** -
+ * TF-IDF 벑터화 -> TruncatedSVD 차원 μΆ•μ†Œ -> hnswlib κ·Όμ ‘ νƒμƒ‰μœΌλ‘œ μœ μ‚¬ 메뉴 검색 -### 🌱 **μž‘μ—… 브랜치 넀이밍 κ·œμΉ™** +3. **μ˜μ–‘ ν”Όμ²˜ν™”** -``` -type/#issue번호 (μž‘μ—… λ‹¨μœ„λŠ” κΈ°λŠ₯/μˆ˜μ •/λ¦¬νŒ©ν† λ§ λ“±μœΌλ‘œ ꡬ뢄) -``` + * `kcal, protein, fat, carbs, sugar, sodium` λ“± μ£Όμš” μ˜μ–‘μ†Œλ₯Ό 벑터화 +4. **μŠ€μ½”μ–΄λ§ (Concept Scoring)** -| prefix | μ„€λͺ… | μ˜ˆμ‹œ | -|--------------|------------------------------|-----------------------------------| -| `feature/` | ✨ μƒˆλ‘œμš΄ κΈ°λŠ₯ 개발 | `feature/#15` | -| `fix/` | πŸ› 버그 μˆ˜μ • | `fix/#42` | -| `refactor/` | ♻️ μ½”λ“œ λ¦¬νŒ©ν† λ§ | `refactor/#23` | -| `chore/` | πŸ”§ μ„€μ • λ³€κ²½, 작일 | `chore/#25` | -| `perf/` | ⚑ μ„±λŠ₯ κ°œμ„  | `perf/#94` | -| `hotfix/` | πŸš‘ κΈ‰ν•œ μˆ˜μ • (mainμ—μ„œ λ°”λ‘œ λΆ„κΈ°) | `hotfix/#102` | -| `test/` | πŸ§ͺ ν…ŒμŠ€νŠΈ μ½”λ“œ μΆ”κ°€/μˆ˜μ • | `test/#55` | + * λ‹€μ΄μ–΄νŠΈ: μ—΄λŸ‰Β·λ‹Ήλ₯˜Β·νƒ„μˆ˜ν™”λ¬Ό μ œν•œ + * μ €μ—Ό: λ‚˜νŠΈλ₯¨ 엄격 μ œν•œ + * ν˜ˆλ‹Ή: λ‹Ήλ₯˜Β·νƒ„μˆ˜ν™”λ¬Ό λ™μ‹œ μ œν•œ + * 저탄고지/λ²Œν¬μ—…: κΈ°μ‘΄ λΉ„μœ¨ μœ μ§€ -
+5. **μΆ”μ²œ κ²°κ³Ό λ°˜ν™˜** -### πŸš€ 브랜치 흐름 μš”μ•½ + * 점수(0\~100) 기반 λž­ν‚Ή β†’ μƒμœ„ N개 λ°˜ν™˜ + * 응닡 ꡬ쑰: `isSuccess`, `httpStatus`, `data`, `timeStamp` -```text -1. main ← 배포 -2. develop ← 톡합 개발 (PR λŒ€μƒ) -3. developμ—μ„œ feature/fix/... 브랜치 λΆ„κΈ° -4. κΈ°λŠ₯ μ™„λ£Œ ν›„ develop으둜 PR & 머지 -5. 배포 μ‹œ develop β†’ main 머지 -6. κΈ‰ν•œ μˆ˜μ •μ€ hotfixμ—μ„œ main β†’ develop 병합 +--- + +## βš™οΈ μ‹€ν–‰ 방법 + +### 1. μ˜μ‘΄μ„± μ„€μΉ˜ + +```bash +python3.11 -m venv .venv +source .venv/bin/activate +pip install --no-cache-dir -r requirements.txt ``` ---- +### 2. ν•™μŠ΅ (λͺ¨λΈ 생성) + +졜초 μ‹€ν–‰ μ‹œ, `model_store/`κ°€ λΉ„μ–΄ μžˆλ‹€λ©΄ ν•™μŠ΅ 과정이 ν•„μš”ν•©λ‹ˆλ‹€. + +```bash +python -m leftovers.domain.recommend.service.train +``` + +β†’ `nutrition_imputer.joblib`, `nutrition_scaler.joblib`, `concept_model_*.joblib` 등이 μƒμ„±λ©λ‹ˆλ‹€. + +### 3. μ„œλ²„ μ‹€ν–‰ + +```bash +uvicorn main:app --host 0.0.0.0 --port 8000 +``` From dc7a764d2833c8da6a3732b86384ac833f2b1073 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EC=9E=84=ED=98=9C=EC=A0=95?= Date: Mon, 25 Aug 2025 05:55:41 +0900 Subject: [PATCH 2/2] =?UTF-8?q?:memo:=20docs:=20=EB=A6=AC=EB=93=9C?= =?UTF-8?q?=EB=AF=B8=20=EA=B0=9C=EB=B0=9C=20=EA=B5=AC=EC=A1=B0=EB=8F=84=20?= =?UTF-8?q?=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 03b777c..0d94a0c 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ FastAPI 기반의 **AI μΆ”μ²œ μ„œλ²„**둜, μ‹μ•½μ²˜ μ˜μ–‘μ„±λΆ„ν‘œ 데이터 --- ## πŸš€ Tech Stack +struct-be ### πŸ”Ή Framework & Language - **Python 3.11** @@ -86,7 +87,7 @@ FastAPI 기반의 **AI μΆ”μ²œ μ„œλ²„**둜, μ‹μ•½μ²˜ μ˜μ–‘μ„±λΆ„ν‘œ 데이터 5. **μΆ”μ²œ κ²°κ³Ό λ°˜ν™˜** - * 점수(0\~100) 기반 λž­ν‚Ή β†’ μƒμœ„ N개 λ°˜ν™˜ + * 점수(0\~100) 기반 λž­ν‚Ή -> μƒμœ„ N개 λ°˜ν™˜ * 응닡 ꡬ쑰: `isSuccess`, `httpStatus`, `data`, `timeStamp` ---