sam-manage/docs/GCC토큰정책비교자료.md

AI 토큰 사용량 추적 방식 비교 분석

작성일: 2026-02-07 프로젝트: SAM (Smart Automation Management) 목적: AI API 토큰 사용량 추적 방식 선택에 대한 기술적 근거 문서

---

1. 배경

SAM 프로젝트는 Google Gemini API와 Anthropic Claude API를 여러 기능에서 활용하고 있다. AI API 비용 관리 및 테넌트별 사용량 분석을 위해 토큰 사용량 추적이 필요하며, 이를 구현하는 두 가지 방식을 비교 분석한다.

SAM 프로젝트 AI API 호출 현황

기능	AI 서비스	모델	프로젝트
AI 리포트 생성	Google Gemini	gemini-2.0-flash	API
사업자등록증 OCR	Anthropic Claude	claude-3-haiku	MNG
명함 OCR	Google Gemini	gemini-2.0-flash	MNG
회의록 AI 요약	Anthropic Claude	claude-3-haiku	MNG
음성 인식 (STT)	Google Cloud	Speech-to-Text	MNG

---

2. 방식 A: API 응답에서 직접 추출하여 DB 저장 (채택)

동작 원리

[SAM 서버] → [AI API 호출] → [응답 수신]
                                   ↓
                          usageMetadata / usage 필드 추출
                                   ↓
                          ai_token_usages 테이블에 저장
                                   ↓
                          MNG 관리 화면에서 조회

Gemini API 응답 예시

{
  "candidates": [{ "content": { "parts": [{ "text": "..." }] } }],
  "usageMetadata": {
    "promptTokenCount": 1250,
    "candidatesTokenCount": 523,
    "totalTokenCount": 1773
  }
}

Claude API 응답 예시

{
  "content": [{ "type": "text", "text": "..." }],
  "usage": {
    "input_tokens": 1100,
    "output_tokens": 480
  }
}

장점

• 비즈니스 컨텍스트 연결: 테넌트, 기능(메뉴), 사용자 단위로 추적 가능
• 추가 인증 불필요: 기존 API Key만으로 동작 (Google Cloud 서비스 계정 불필요)
• 실시간 기록: API 호출 즉시 저장
• 다중 AI 서비스 통합: Gemini, Claude 등 서로 다른 AI 서비스를 하나의 테이블에서 통합 관리
• 구현 난이도 낮음: 응답에 이미 포함된 데이터를 추출하기만 하면 됨
• 멀티테넌트 지원: tenant_id 기반으로 테넌트별 비용 분리 가능

단점

• 코드 수정 필요: 새 AI 기능 추가 시 토큰 저장 코드를 명시적으로 추가해야 함
• 누락 가능성: try-catch 내부에서 저장 실패 시 데이터 누락 가능 (단, 비즈니스 로직에 영향 없음)
• 외부 호출 미추적: SAM 외부에서 동일 API Key로 호출한 사용량은 추적 불가
• 비용 계산은 추정치: 모델별 단가를 코드에 하드코딩하므로 가격 변동 시 업데이트 필요

---

3. 방식 B: Google Cloud Monitoring API로 조회

동작 원리

[Google Cloud Console]
     ↓
[Cloud Monitoring API]  ←  SAM 서버에서 주기적 조회
     ↓
  프로젝트 전체 사용량 집계 반환
     ↓
  SAM DB에 저장 또는 직접 표시

관련 Google Cloud API

API	용도	제공 데이터
monitoring.googleapis.com	메트릭 조회	API 호출 수, 토큰 수 (프로젝트 단위)
serviceusage.googleapis.com	할당량 관리	API 사용량 및 할당량
billing.googleapis.com	결제 데이터	프로젝트 전체 과금 정보

요구 사항

1. Google Cloud 프로젝트 필요 (API Key만으로는 불가)
2. 서비스 계정 생성 및 IAM 역할 부여 필요
   • roles/monitoring.viewer (Monitoring 읽기)
   • roles/billing.viewer (결제 읽기)
3. OAuth2 인증 또는 서비스 계정 JSON 키 파일
4. Cloud Monitoring API 활성화

장점

• 자동 집계: 모든 API 호출이 자동으로 집계됨 (코드 수정 불필요)
• 누락 없음: Google 인프라에서 직접 집계하므로 데이터 손실 없음
• 정확한 과금 데이터: Google이 산정한 실제 비용 조회 가능
• 외부 호출 포함: API Key를 사용하는 모든 호출이 포함됨

단점

• 비즈니스 컨텍스트 부재: 프로젝트 전체 합계만 제공 (테넌트별, 기능별, 사용자별 분리 불가)
• 추가 인프라 비용: Cloud Monitoring API 자체도 과금 대상
• 데이터 지연: 실시간이 아닌 수 분~수 시간 지연 (최대 24시간)
• 복잡한 인증: 서비스 계정 설정, IAM 역할, OAuth2 등 관리 부담
• Gemini만 해당: Claude API (Anthropic) 사용량은 Google Cloud에서 조회 불가
• API Key 방식 제한: 현재 SAM이 사용하는 API Key 인증으로는 일부 메트릭 접근 제한

---

4. 비교표

비교 항목	방식 A (API 응답 직접 추출)	방식 B (GCC Monitoring API)
테넌트별 분리	O	X
기능/메뉴별 분리	O	X
사용자별 추적	O	X
실시간 기록	O	X (지연 있음)
다중 AI 서비스 통합	O (Gemini + Claude)	X (Gemini만)
추가 인증/인프라 필요	X	O (서비스 계정, IAM)
누락 가능성	있음 (방어 코드 적용)	없음
코드 수정 필요성	새 기능마다 추가	불필요
구현 난이도	낮음	높음
운영 비용	없음	Cloud Monitoring 과금
비용 정확도	추정치 (모델별 단가 기반)	정확 (Google 산정)
외부 호출 추적	X	O

---

5. SAM 프로젝트 적합성 분석

방식 A를 채택한 핵심 이유

1. 멀티테넌트 환경 SAM은 여러 테넌트(회사)가 하나의 시스템을 공유하는 멀티테넌트 구조이다. "어떤 회사(테넌트)가 얼마나 사용했는지"를 추적해야 하며, GCC는 이 정보를 제공하지 않는다.

2. 기능별 비용 분석 AI 리포트, 명함 OCR, 회의록 요약 등 기능별 사용량을 별도로 집계해야 한다. GCC는 프로젝트 전체 합계만 제공하므로 기능별 분석이 불가능하다.

3. 다중 AI 서비스 SAM은 Gemini와 Claude를 함께 사용한다. GCC는 Google 서비스(Gemini)만 추적 가능하고, Anthropic Claude 사용량은 별도 관리해야 한다.

4. 인프라 단순성 추가 서비스 계정, IAM 설정, Cloud Monitoring API 활성화 등의 인프라 작업 없이 기존 API 응답에서 데이터를 추출하는 것만으로 충분하다.

---

6. 향후 개선 방안

6.1 월말 교차 검증 (권장)

• 방식 A의 DB 합계와 Google Cloud Console 대시보드의 사용량을 월 1회 대조
• 누락 여부를 확인하고 차이가 크면 원인 분석

6.2 단가 자동 업데이트

현재 모델별 단가가 코드에 하드코딩되어 있음. 향후 개선 가능:

• ai_configs 테이블에 모델별 단가 컬럼 추가
• 또는 별도 ai_pricing 설정 테이블 생성

6.3 알림 기능

• 월간 예산 임계치 초과 시 관리자 알림
• 테넌트별 사용량 한도 설정

---

7. 기술 구현 명세

저장 테이블: ai_token_usages

컬럼	타입	설명
id	bigint (PK)	자동 증가
tenant_id	bigint (FK)	테넌트 ID
model	varchar(100)	AI 모델명
menu_name	varchar(100)	호출 기능명
prompt_tokens	int unsigned	입력 토큰 수
completion_tokens	int unsigned	출력 토큰 수
total_tokens	int unsigned	전체 토큰 수
cost_usd	decimal(10,6)	예상 비용 (USD)
cost_krw	decimal(12,2)	예상 비용 (KRW)
request_id	varchar(100)	요청 추적 UUID
created_by	bigint (FK)	생성자 ID
created_at	timestamp	생성 시각
updated_at	timestamp	수정 시각

인덱스

• (tenant_id, created_at) - 테넌트별 기간 조회
• (tenant_id, menu_name) - 테넌트별 기능 조회

비용 단가 기준 (2026-02 기준)

모델	입력 단가	출력 단가
Gemini 2.0 Flash	$0.10 / 1M tokens	$0.40 / 1M tokens
Claude 3 Haiku	$0.25 / 1M tokens	$1.25 / 1M tokens

환율: 기본 1,400원/USD (config 설정 가능)

---

8. 결론

SAM 프로젝트의 멀티테넌트 아키텍처와 다중 AI 서비스 사용 환경에서, **API 응답 직접 추출 방식(방식 A)**이 비즈니스 요구사항을 충족하는 최적의 선택이다.

Google Cloud Monitoring API(방식 B)는 프로젝트 전체 사용량 확인에는 유용하나, 테넌트별/기능별 상세 추적이 불가능하여 SAM의 핵심 요구사항을 충족하지 못한다.

필요시 방식 B를 월말 교차 검증 용도로 보조적으로 활용할 수 있다.