sam-docs/sam/docs/changes/20260303_gemini_model_upgrade.md

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	개발팀장 직접

수정 후 반드시 실행:

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: 현재 환율

---

테스트 체크리스트

• 로컬 .env 수정 완료
• 코드 fallback 전체 변경 완료
• 로컬 연결 테스트 (MNG /system/ai-config)
• 개발서버 .env 수정 + config:clear
• 개발서버 연결 테스트
• 운영서버 .env 수정 + config:clear
• DB 단가 설정 (gemini-2.5-flash)
• 토큰 사용량 로그 확인 (새 모델명)

---

롤백 절차

문제 발생 시 .env만 되돌리면 즉시 복구:

# 모든 환경의 .env에서
GEMINI_MODEL=gemini-2.0-flash
php artisan config:clear

---

관련 문서

• AI 관리 종합 가이드
• 모델 업데이트 워크플로우
• AI 설정 기술문서