# 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분)

```bash
# 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분)

```bash
# 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분)

```bash
# 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분)

```bash
# 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분)

```bash
# 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. 긴급 롤백 절차

모델 변경 후 문제 발생 시:

```bash
# 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 설정 가이드](/home/aweso/sam/docs/guides/ai-config-settings.md)
- [서버 환경 비교](/home/aweso/sam/CLAUDE.md) — 실행 환경 섹션

---

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