4c581ad7f5
- AI 관리 종합 가이드 신규 (ai-management.md) - 모델 업데이트 워크플로우 신규 (ai-model-update-workflow.md) - 변경 이력 기록 (20260303_gemini_model_upgrade.md) - AI 설정 기술문서 모델명 업데이트 - INDEX.md에 AI 문서 3건 등록
120 lines
4.2 KiB
Markdown
120 lines
4.2 KiB
Markdown
# Gemini 모델 업그레이드: 2.0-flash → 2.5-flash
|
|
|
|
**날짜:** 2026-03-03
|
|
**작업자:** Claude Code
|
|
|
|
---
|
|
|
|
## 변경 개요
|
|
|
|
Google이 2026년 6월 1일부로 Gemini 2.0 Flash 모델 서비스를 종료한다는 통보를 받아, SAM 시스템 전체의 Gemini 모델을 `gemini-2.0-flash` → `gemini-2.5-flash`로 마이그레이션했다.
|
|
|
|
---
|
|
|
|
## 변경 사유
|
|
|
|
- Google의 공식 메일 통보: Gemini 2.0 Flash / 2.0 Flash-Lite → 2026-06-01 강제 종료
|
|
- 마이그레이션 경로: `gemini-2.0-flash` → `gemini-2.5-flash`
|
|
- API 키, Base URL 변경 없음 (모델명만 변경)
|
|
|
|
---
|
|
|
|
## 수정된 파일
|
|
|
|
### API 프로젝트 (`/home/aweso/sam/api`)
|
|
|
|
| 파일 | 변경 내용 |
|
|
|------|----------|
|
|
| `.env` | `GEMINI_MODEL=gemini-2.0-flash` → `gemini-2.5-flash` |
|
|
| `config/services.php` | fallback 기본값 `gemini-2.0-flash` → `gemini-2.5-flash` |
|
|
| `app/Services/AiReportService.php` | fallback 기본값 변경 |
|
|
|
|
### MNG 프로젝트 (`/home/aweso/sam/mng`)
|
|
|
|
| 파일 | 변경 내용 |
|
|
|------|----------|
|
|
| `.env` | `GEMINI_MODEL=gemini-2.0-flash` → `gemini-2.5-flash` |
|
|
| `config/services.php` | fallback 기본값 변경 |
|
|
| `app/Models/System/AiConfig.php` | `DEFAULT_MODELS['gemini']` 상수 + `getActiveGemini()` fallback 변경 |
|
|
| `app/Services/NotionService.php` | fallback 기본값 변경 |
|
|
| `resources/views/system/ai-config/index.blade.php` | UI placeholder, 기본값, JS defaultModels 변경 |
|
|
| `resources/views/google-cloud/ai-guide/index.blade.php` | 서비스 현황 테이블 모델명 7곳 변경 |
|
|
| `resources/views/academy/env-management.blade.php` | 환경변수 예시 테이블 변경 |
|
|
|
|
### 문서 (`/home/aweso/sam/docs`)
|
|
|
|
| 파일 | 변경 내용 |
|
|
|------|----------|
|
|
| `guides/ai-config-settings.md` | 기본 모델명 업데이트, 최종 업데이트 날짜 변경 |
|
|
| `guides/ai-management.md` | **신규** — AI 관리 종합 가이드 (아키텍처, 버전 이력, 온보딩) |
|
|
| `guides/ai-model-update-workflow.md` | **신규** — 모델 업데이트 표준 절차 (7단계 워크플로우) |
|
|
| `changes/20260303_gemini_model_upgrade.md` | **신규** — 이 변경 이력 문서 |
|
|
|
|
### 수정하지 않은 파일 (의도적)
|
|
|
|
| 파일 | 이유 |
|
|
|------|------|
|
|
| `api/database/migrations/2026_01_27_*.php` | 이미 실행된 마이그레이션 — 변경 시 DB 무결성 문제 |
|
|
| `api/database/migrations/2026_02_07_*.php` | 동일 |
|
|
| `api/database/migrations/2026_02_09_*.php` | 동일 |
|
|
| `mng/views/google-cloud/cloud-api-pricing/index.blade.php` | `2.0 → 2.5` 마이그레이션 안내 UI — 이전 모델명이 의도적 잔존 |
|
|
|
|
---
|
|
|
|
## 서버 .env 수정 필요 (배포 후)
|
|
|
|
| 환경 | 파일 | 변수 | 담당 |
|
|
|------|------|------|------|
|
|
| 개발서버 | `/home/webservice/api/.env` | `GEMINI_MODEL=gemini-2.5-flash` | SSH 접속 수정 |
|
|
| 개발서버 | `/home/webservice/mng/.env` | `GEMINI_MODEL=gemini-2.5-flash` | SSH 접속 수정 |
|
|
| 운영서버 | `/home/webservice/api/.env` | `GEMINI_MODEL=gemini-2.5-flash` | 개발팀장 직접 |
|
|
| 운영서버 | `/home/webservice/mng/.env` | `GEMINI_MODEL=gemini-2.5-flash` | 개발팀장 직접 |
|
|
|
|
수정 후 반드시 실행:
|
|
```bash
|
|
php artisan config:clear
|
|
```
|
|
|
|
---
|
|
|
|
## DB 단가 설정 필요
|
|
|
|
MNG `/system/ai-token-usage` → 단가 설정에서:
|
|
- 기존 `gemini-2.0-flash` 단가 → 비활성화
|
|
- 신규 `gemini-2.5-flash` 단가 추가:
|
|
- `input_price_per_million`: 0.15
|
|
- `output_price_per_million`: 0.60
|
|
- `exchange_rate`: 현재 환율
|
|
|
|
---
|
|
|
|
## 테스트 체크리스트
|
|
|
|
- [x] 로컬 .env 수정 완료
|
|
- [x] 코드 fallback 전체 변경 완료
|
|
- [ ] 로컬 연결 테스트 (MNG `/system/ai-config`)
|
|
- [ ] 개발서버 .env 수정 + config:clear
|
|
- [ ] 개발서버 연결 테스트
|
|
- [ ] 운영서버 .env 수정 + config:clear
|
|
- [ ] DB 단가 설정 (gemini-2.5-flash)
|
|
- [ ] 토큰 사용량 로그 확인 (새 모델명)
|
|
|
|
---
|
|
|
|
## 롤백 절차
|
|
|
|
문제 발생 시 `.env`만 되돌리면 즉시 복구:
|
|
```bash
|
|
# 모든 환경의 .env에서
|
|
GEMINI_MODEL=gemini-2.0-flash
|
|
php artisan config:clear
|
|
```
|
|
|
|
---
|
|
|
|
## 관련 문서
|
|
|
|
- [AI 관리 종합 가이드](../guides/ai-management.md)
|
|
- [모델 업데이트 워크플로우](../guides/ai-model-update-workflow.md)
|
|
- [AI 설정 기술문서](../guides/ai-config-settings.md)
|