sam-docs/sam/docs/guides/ai-model-update-workflow.md

AI 모델 업데이트 워크플로우

작성일: 2026-03-03 상태: 확정 대상: Google Gemini, Claude, OpenAI 등 AI 모델 버전 업데이트 시 적용

---

1. 개요

1.1 목적

AI 제공사(Google, Anthropic, OpenAI)가 모델을 업데이트하거나 기존 모델을 종료(deprecate)할 때, SAM 시스템 전체를 안전하게 마이그레이션하기 위한 표준 절차를 정의한다.

1.2 핵심 원칙

SAM의 AI 설정은 환경변수 기반 아키텍처로 설계되어 있어, 모델 변경 시 코드 수정이 최소화된다.

.env (GEMINI_MODEL=gemini-2.5-flash)         ← ① 여기만 바꾸면 동작
  ↓
config/services.php (env() + fallback 기본값)  ← ② fallback도 업데이트 권장
  ↓
AiConfig 모델 (DEFAULT_MODELS 상수)            ← ③ 관리 화면 기본값
  ↓
서비스 클래스 (config 또는 AiConfig 참조)       ← 코드 수정 불필요

---

2. 수정 대상 전체 매핑

2.1 환경변수 (.env) — 🔴 필수

환경	파일 위치	변수명
로컬 API	/home/aweso/sam/api/.env	GEMINI_MODEL
로컬 MNG	/home/aweso/sam/mng/.env	GEMINI_MODEL
개발서버 API	/home/webservice/api/.env	GEMINI_MODEL
개발서버 MNG	/home/webservice/mng/.env	GEMINI_MODEL
운영서버 API	/home/webservice/api/.env	GEMINI_MODEL
운영서버 MNG	/home/webservice/mng/.env	GEMINI_MODEL

참고: API와 MNG가 같은 .env 값을 사용하므로 둘 다 동일하게 변경해야 한다. 참고: GEMINI_API_KEY와 GEMINI_BASE_URL은 모델 변경 시 대부분 그대로 유지된다.

2.2 코드 Fallback 기본값 — 🟡 권장

코드에 하드코딩된 fallback 기본값. .env가 정상 설정되어 있으면 동작에 영향 없지만, 유지보수를 위해 함께 업데이트한다.

파일	줄	현재 값
api/config/services.php	46	env('GEMINI_MODEL', 'gemini-2.0-flash')
mng/config/services.php	40	env('GEMINI_MODEL', 'gemini-2.0-flash')
mng/app/Models/System/AiConfig.php	62	DEFAULT_MODELS['gemini'] = 'gemini-2.0-flash'
mng/app/Models/System/AiConfig.php	97	config('services.gemini.model', 'gemini-2.0-flash')
api/app/Services/AiReportService.php	326	config('services.gemini.model', 'gemini-2.0-flash')

2.3 데이터베이스 — 🟢 필요 시

테이블	변경 내용	변경 방법
ai_configs	모델명 변경	MNG 관리 화면 (/system/ai-config)
ai_pricing_configs	새 모델 단가 추가	MNG 관리 화면 (/system/ai-token-usage → 단가 설정)

ai_token_usages 테이블은 과거 기록이므로 수정 불필요. 새 호출부터 새 모델명으로 기록된다.

2.4 Google API Base URL — 보통 변경 불필요

변수	현재 값	비고
GEMINI_BASE_URL	https://generativelanguage.googleapis.com/v1beta	v1beta → v1 변경 시에만 수정

Google이 API 버전을 올릴 때(v1beta → v1) Base URL도 변경 필요. 모델명만 바뀔 때는 그대로 유지.

---

3. 실행 절차 (Step-by-Step)

Step 1: 사전 확인 (10분)

# 1. 새 모델명 확인 (Google AI Studio 또는 공식 문서)
# 예: gemini-2.0-flash → gemini-2.5-flash

# 2. API 호환성 확인
# - Base URL 변경 여부 (v1beta → v1 등)
# - 요청/응답 스키마 변경 여부
# - 가격 변경 여부

# 3. 현재 사용 중인 모델 확인
grep -r "GEMINI_MODEL" /home/aweso/sam/api/.env /home/aweso/sam/mng/.env

---

Step 2: 로컬 환경 테스트 (15분)

# 1. 로컬 .env 수정
# api/.env
GEMINI_MODEL=gemini-2.5-flash

# mng/.env
GEMINI_MODEL=gemini-2.5-flash

# 2. 캐시 클리어 (config가 캐시되어 있을 수 있음)
docker exec sam-api-1 php artisan config:clear
docker exec sam-mng-1 php artisan config:clear

# 3. MNG 관리 화면에서 테스트
# http://mng.sam.kr/system/ai-config → "연결 테스트" 버튼

# 4. 실제 기능 테스트
# - 명함 OCR 테스트 (BusinessCardOcrService)
# - 사업자등록증 OCR 테스트 (TradingPartnerOcrService)
# - AI 리포트 생성 테스트 (AiReportService)

---

Step 3: 코드 Fallback 업데이트 (5분)

# Claude Code에게 요청:
# "Gemini 모델 fallback 기본값을 gemini-2.5-flash로 업데이트해줘"

# 수정 대상 (5개 파일):
# 1. api/config/services.php
# 2. mng/config/services.php
# 3. mng/app/Models/System/AiConfig.php (DEFAULT_MODELS + getActiveGemini)
# 4. api/app/Services/AiReportService.php

---

Step 4: 개발서버 배포 + 테스트 (10분)

# 1. 코드 커밋 & 푸시 (Jenkins 자동 배포)
# "개발서버 푸시"

# 2. 개발서버 .env 수정 (SSH 접속)
ssh pro@114.203.209.83

# API
cd /home/webservice/api
# .env 파일에서 GEMINI_MODEL 수정
php artisan config:clear

# MNG
cd /home/webservice/mng
# .env 파일에서 GEMINI_MODEL 수정
php artisan config:clear

# 3. 개발서버에서 기능 테스트
# https://admin.codebridge-x.com/system/ai-config → 연결 테스트

---

Step 5: 단가 설정 업데이트 (5분)

# MNG 관리 화면 접속
# /system/ai-token-usage → 단가 설정 탭

# 기존 모델 단가 비활성화 (삭제하지 않음 — 과거 기록 참조용)
# 새 모델 단가 추가:
# - provider: gemini
# - model_name: gemini-2.5-flash
# - input_price_per_million: (Google 공식 가격)
# - output_price_per_million: (Google 공식 가격)
# - exchange_rate: (현재 환율)
# - is_active: true

---

Step 6: 운영서버 배포 (10분)

# 1. 운영 코드 배포
# "운영서버 푸시"

# 2. 운영서버 .env 수정 (개발팀장이 직접)
# API: /home/webservice/api/.env → GEMINI_MODEL=gemini-2.5-flash
# MNG: /home/webservice/mng/.env → GEMINI_MODEL=gemini-2.5-flash
# php artisan config:clear (api, mng 각각)

# 3. 운영서버 기능 확인

---

Step 7: 사후 모니터링 (1일)

# 1. AI 토큰 사용량 모니터링
# /system/ai-token-usage → 새 모델명으로 로그 기록되는지 확인

# 2. 에러 로그 모니터링
# API: storage/logs/laravel.log
# MNG: storage/logs/laravel.log

# 3. 기존 모델 종료일 전까지 롤백 준비
# .env의 GEMINI_MODEL만 이전 값으로 되돌리면 즉시 롤백

---

4. 체크리스트 (모델 업데이트 시)

사전 준비

• 새 모델명 확인 (공식 문서)
• API 호환성 확인 (Base URL, 스키마 변경 여부)
• 새 모델 가격 확인

로컬 테스트

• api/.env 의 GEMINI_MODEL 수정
• mng/.env 의 GEMINI_MODEL 수정
• Docker config:clear 실행
• MNG AI 설정 화면에서 연결 테스트 성공
• 명함 OCR / 사업자등록증 OCR / AI 리포트 테스트

코드 업데이트

• api/config/services.php fallback 기본값 변경
• mng/config/services.php fallback 기본값 변경
• AiConfig.php DEFAULT_MODELS 상수 변경
• AiConfig::getActiveGemini() fallback 변경
• AiReportService.php fallback 변경
• Git 커밋

개발서버

• 코드 푸시 (Jenkins 배포)
• .env 수정 (api, mng)
• config:clear 실행
• 연결 테스트 + 기능 테스트

단가 설정

• 기존 모델 단가 비활성화
• 새 모델 단가 추가 (input/output 가격, 환율)

운영서버

• 코드 푸시 (cherry-pick → main)
• .env 수정 (개발팀장 직접)
• config:clear 실행
• 기능 확인

사후 관리

• 토큰 사용량 로그에 새 모델명 확인
• 에러 로그 모니터링 (1일)
• 구 모델 종료일 전 롤백 가능 상태 유지

---

5. 긴급 롤백 절차

모델 변경 후 문제 발생 시:

# 1. .env만 이전 모델로 변경 (코드 수정 불필요)
GEMINI_MODEL=gemini-2.0-flash

# 2. 캐시 클리어
php artisan config:clear

# 3. 즉시 이전 모델로 복구됨

.env 기반 아키텍처의 장점: 코드 배포 없이 환경변수만 변경하면 즉시 롤백 가능

---

6. FAQ

Q: Base URL도 바꿔야 하나?

A: 대부분 변경 불필요. Google이 API 버전을 올릴 때(예: v1beta → v1)에만 GEMINI_BASE_URL도 함께 변경한다. 모델명만 바뀔 때는 GEMINI_MODEL만 수정하면 된다.

Q: API 키도 바꿔야 하나?

A: 변경 불필요. 동일 프로젝트 내에서 모델이 바뀌어도 API 키는 유지된다.

Q: React 프로젝트도 수정해야 하나?

A: 불필요. React는 Google Maps API Key만 사용하며, Gemini AI 호출 코드가 없다.

Q: MNG 관리 화면에서만 바꾸면 안 되나?

A: 현재 구조상 AiConfig::getActiveGemini()는 DB가 아니라 .env 값을 읽는다. DB의 ai_configs 테이블은 관리 화면 표시/테스트용이며, 실제 API 호출은 .env → config() 경로를 따른다. 따라서 .env 수정이 필수다.

Q: 향후 DB 기반으로 전환하면 더 편해지나?

A: 맞다. AiConfig::getActiveGemini()가 DB에서 활성 설정을 읽도록 리팩토링하면, MNG 관리 화면에서만 모델을 바꿔도 전체 적용된다. 서버 SSH 접속 없이 웹에서 즉시 변경 가능해진다. 이는 향후 개선 과제로 검토할 수 있다.

---

관련 문서

• AI 설정 가이드
• 서버 환경 비교 — 실행 환경 섹션

---

최종 업데이트: 2026-03-03