SamProject/sam-manage
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs:GCC 토큰 정책 비교자료 기술문서 추가

Browse Source 
- API 응답 직접 추출 vs GCC Monitoring API 비교 분석
- SAM 프로젝트 적합성 근거 정리
- 기술 구현 명세 및 향후 개선 방안 포함

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
김보곤
2026-02-07 11:27:59 +09:00
parent bb81d07d61
commit ee9f9c128a
1 changed files with 238 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

238
docs/GCC토큰정책비교자료.md Normal file
View File

@@ -0,0 +1,238 @@
# 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 응답 예시
```json
{
"candidates": [{ "content": { "parts": [{ "text": "..." }] } }],
"usageMetadata": {
"promptTokenCount": 1250,
"candidatesTokenCount": 523,
"totalTokenCount": 1773
}
}
```
### Claude API 응답 예시
```json
{
"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를 월말 교차 검증 용도로 보조적으로 활용할 수 있다.