sam-docs/sam/docs/guides/ai-management.md

SAM AI 관리 종합 가이드

작성일: 2026-03-03 상태: 확정 대상 독자: SAM 프로젝트에 투입되는 모든 개발자

---

1. 개요

1.1 목적

SAM 시스템에서 사용하는 AI 서비스(Google Gemini, Anthropic Claude, OpenAI)의 설정 구조, 호출 흐름, 모델 관리, 비용 추적을 한눈에 파악할 수 있는 종합 가이드다.

1.2 현재 상태 (2026-03-03)

Provider	모델	용도	상태
Google Gemini	gemini-2.5-flash	명함 OCR, 사업자등록증 OCR, 재무 리포트, 회의 요약, 동영상 스크립트	✅ 운영 중
Anthropic Claude	claude-sonnet-4-20250514	AI 재무 분석 (예비)	🟡 코드 준비
OpenAI	gpt-4o	범용 AI (예비)	🟡 코드 준비
Google Cloud STT	Chirp 2	음성 녹음 → 텍스트 변환	✅ 운영 중
Google Cloud Storage	Standard	음성 파일 백업	✅ 운영 중

---

2. 아키텍처

2.1 설정 흐름도

┌─────────────────────────────────────────────────────────────┐
│  .env 파일 (환경별 4곳)                                      │
│  ┌───────────────────────────────────────────┐              │
│  │ GEMINI_API_KEY=AIzaSy...                  │              │
│  │ GEMINI_MODEL=gemini-2.5-flash             │ ← ① 핵심    │
│  │ GEMINI_BASE_URL=https://...googleapis...  │              │
│  └───────────────────────────────────────────┘              │
└────────────────────────┬────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│  config/services.php                                         │
│  ┌───────────────────────────────────────────┐              │
│  │ 'gemini' => [                             │              │
│  │   'model' => env('GEMINI_MODEL',          │              │
│  │              'gemini-2.5-flash'),          │ ← ② fallback│
│  │ ]                                         │              │
│  └───────────────────────────────────────────┘              │
└────────────────────────┬────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│  AiConfig::getActiveGemini()                                 │
│  ┌───────────────────────────────────────────┐              │
│  │ config('services.gemini.model',           │              │
│  │        'gemini-2.5-flash')                │ ← ③ fallback│
│  └───────────────────────────────────────────┘              │
└────────────────────────┬────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│  서비스 클래스 (실제 API 호출)                                 │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ BusinessCardOcrService    → AiConfig::getActiveGemini│    │
│  │ TradingPartnerOcrService  → AiConfig::getActiveGemini│    │
│  │ AiReportService (API)     → config('services.gemini')│    │
│  │ GeminiScriptService       → AiConfig::getActiveGemini│    │
│  │ NotionService             → AiConfig::getActiveGemini│    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

핵심: .env의 GEMINI_MODEL 값만 바꾸면 전체 서비스가 새 모델을 사용한다.

2.2 프로젝트별 역할

프로젝트	AI 관련 역할
MNG	명함 OCR, 사업자등록증 OCR, 동영상 스크립트, AI 설정 관리 UI, 토큰 사용량 조회
API	재무 AI 리포트 생성, 토큰 사용량 저장, AI 가격 설정
React	AI 기능 없음 (Google Maps만 사용)

---

3. 환경변수 설정

3.1 Gemini AI 설정

# ─── Google Gemini AI ───
GEMINI_API_KEY=AIzaSy...               # Google AI Studio에서 발급
GEMINI_MODEL=gemini-2.5-flash          # 사용할 모델명
GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta
GEMINI_PROJECT_ID=codebridge-chatbot   # GCP 프로젝트 ID

3.2 환경별 .env 위치

환경	API 경로	MNG 경로
로컬 (Docker)	/home/aweso/sam/api/.env	/home/aweso/sam/mng/.env
개발서버	/home/webservice/api/.env	/home/webservice/mng/.env
운영서버	/home/webservice/api/.env	/home/webservice/mng/.env

API와 MNG는 같은 GEMINI_MODEL 값을 사용해야 한다.

---

4. 서비스별 AI 호출 매핑

4.1 MNG 프로젝트

서비스	파일	용도	설정 소스
명함 OCR	app/Services/BusinessCardOcrService.php	명함 이미지 → 연락처 정보 추출	AiConfig::getActiveGemini()
사업자등록증 OCR	app/Services/TradingPartnerOcrService.php	사업자등록증 → 거래처 정보 추출	AiConfig::getActiveGemini()
동영상 스크립트	app/Services/Video/GeminiScriptService.php	영상 자막/스크립트 생성	AiConfig::getActiveGemini()
Notion 연동	app/Services/NotionService.php	Notion 콘텐츠 AI 분석	AiConfig::getActiveGemini()

4.2 API 프로젝트

서비스	파일	용도	설정 소스
재무 AI 리포트	app/Services/AiReportService.php	지출/매출/매입 데이터 AI 분석	config('services.gemini')

4.3 공통 유틸

파일	역할
mng/app/Helpers/AiTokenHelper.php	토큰 사용량 저장 (Gemini, Claude, GCS, STT)
mng/app/Models/System/AiConfig.php	AI 설정 모델 (Provider별 활성 설정 조회)
mng/app/Models/System/AiPricingConfig.php	토큰 단가 설정 (비용 계산)
mng/app/Models/System/AiTokenUsage.php	토큰 사용 이력

---

5. 관리 화면

5.1 AI 설정 관리

• URL: /system/ai-config
• 기능: Provider별 API 키, 모델명, Base URL 관리 / 연결 테스트 / 활성화 토글
• 컨트롤러: app/Http/Controllers/System/AiConfigController.php

5.2 AI 토큰 사용량

• URL: /system/ai-token-usage
• 기능: 일별/메뉴별 토큰 사용량 조회 / 비용(USD, KRW) 통계 / 단가 설정
• 컨트롤러: app/Http/Controllers/System/AiTokenUsageController.php

5.3 Google Cloud AI 가이드

• URL: /google-cloud/ai-guide
• 기능: SAM에서 사용하는 Google AI 서비스 전체 현황 / 아키텍처 다이어그램

---

6. 모델 변경 이력 (버전 관리)

날짜	변경 내용	이유	영향 범위
2026-01-27	최초 설정: gemini-2.0-flash	SAM AI 기능 도입	전체
2026-03-03	gemini-2.0-flash → gemini-2.5-flash	Google 2026-06-01 서비스 종료 예고	전체

2026-03-03 변경 상세

배경: Google이 2026년 6월 1일부로 Gemini 2.0 Flash 모델 서비스를 종료한다는 통보를 함.

수정된 파일 (코드):

프로젝트	파일	변경 내용
API	config/services.php	fallback 기본값 변경
API	app/Services/AiReportService.php	fallback 기본값 변경
MNG	config/services.php	fallback 기본값 변경
MNG	app/Models/System/AiConfig.php	DEFAULT_MODELS 상수 + getActiveGemini() fallback 변경
MNG	app/Services/NotionService.php	fallback 기본값 변경
MNG	resources/views/system/ai-config/index.blade.php	UI placeholder/기본값 변경
MNG	resources/views/google-cloud/ai-guide/index.blade.php	서비스 현황 모델명 변경
MNG	resources/views/academy/env-management.blade.php	환경 변수 예시 변경

수정된 .env (환경별):

환경	수정 대상	담당
로컬 api/.env	GEMINI_MODEL=gemini-2.5-flash	✅ 완료
로컬 mng/.env	GEMINI_MODEL=gemini-2.5-flash	✅ 완료
개발서버 api, mng	GEMINI_MODEL=gemini-2.5-flash	배포 후 SSH 수정 필요
운영서버 api, mng	GEMINI_MODEL=gemini-2.5-flash	개발팀장 직접 수정

수정하지 않은 파일 (의도적):

파일	이유
api/database/migrations/ (3개)	이미 실행 완료된 마이그레이션 — 변경 금지
cloud-api-pricing/index.blade.php	2.0 → 2.5 마이그레이션 안내 UI — 이전 모델명이 의도적

---

7. 모델 업데이트 워크플로우

상세 절차: ai-model-update-workflow.md

7.1 요약 (7단계)

① 사전 확인     — 새 모델명, API 호환성, 가격 확인
② 로컬 테스트   — .env 수정 → config:clear → 연결 테스트
③ 코드 업데이트  — fallback 기본값 5곳 + 뷰 파일
④ 개발서버 배포  — 코드 push + .env 수정 + 기능 테스트
⑤ 단가 설정     — MNG 관리 화면에서 새 모델 단가 추가
⑥ 운영서버 배포  — cherry-pick + .env 수정 (개발팀장)
⑦ 사후 모니터링  — 토큰 로그 확인 + 에러 로그 감시 (1일)

7.2 긴급 롤백

# .env만 이전 모델로 변경 (코드 배포 불필요)
GEMINI_MODEL=gemini-2.0-flash
php artisan config:clear

---

8. 비용 관리

8.1 토큰 단가 (ai_pricing_configs)

모델	입력 ($/1M tokens)	출력 ($/1M tokens)	비고
gemini-2.5-flash	0.15	0.60	2026-03-03~
gemini-2.0-flash	0.10	0.40	~2026-06-01 종료 예정

단가는 MNG /system/ai-token-usage → 단가 설정에서 관리

8.2 비용 계산 흐름

API 호출 → 응답의 usageMetadata에서 토큰 수 추출
  ↓
AiTokenHelper::saveGeminiUsage()
  ↓
ai_pricing_configs에서 단가 조회 (캐시 60분)
  ↓
ai_token_usages 테이블에 기록 (토큰 수, USD, KRW)

---

9. 신규 개발자 온보딩 체크리스트

AI 관련 작업을 시작하기 전:

• 이 문서 전체 읽기
• 로컬 .env에 GEMINI_API_KEY, GEMINI_MODEL 설정 확인
• MNG /system/ai-config 화면에서 연결 테스트 성공 확인
• AI 호출 서비스 파일 위치 파악 (섹션 4 참조)
• AiConfig::getActiveGemini() 사용법 이해
• AiTokenHelper::saveGeminiUsage() 로 토큰 추적하는 패턴 이해

새 AI 기능 추가 시

// 1. AiConfig에서 활성 설정 가져오기
$config = AiConfig::getActiveGemini();
if (!$config) throw new \RuntimeException('Gemini API 설정이 없습니다.');

// 2. API 호출
$url = "{$config->base_url}/models/{$config->model}:generateContent?key={$config->api_key}";
$response = Http::timeout(30)->post($url, [ ... ]);

// 3. 토큰 사용량 기록
AiTokenHelper::saveGeminiUsage(
    $response->json()['usageMetadata'] ?? [],
    $config->model,
    '메뉴명'
);

---

관련 문서

문서	경로	설명
AI 설정 기술문서	docs/guides/ai-config-settings.md	DB 구조, 메서드, 코드 예시
모델 업데이트 워크플로우	docs/guides/ai-model-update-workflow.md	모델 변경 시 Step-by-Step 절차
변경 이력	docs/changes/20260303_gemini_model_upgrade.md	2.0→2.5 마이그레이션 상세 기록

---

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