쿼터 거버넌스: Quota Protection + Smart Warmup의 조합 전술
Antigravity Tools로 프록시를 실행하는 것은 꽤 안정적이지만, 가장 두려운 것은 한 가지입니다: 주력 모델의 쿼터가 "몰래 다 먹혀", 진짜 사용할 때才发现이 이미 너무 낮아서 호출할 수 없는 것입니다.
이 수업은 쿼터 거버넌스만 전문으로 설명합니다: Quota Protection을 사용하여 핵심 모델을 확보하고, Smart Warmup을 사용하여 쿼터가 다시 차면 "가벼운 워밍업"을 한 번 수행하여, 임시 실패를 줄입니다.
쿼터 거버넌스란 무엇인가요?
쿼터 거버넌스는 Antigravity Tools에서 두 세트 연동 메커니즘을 사용하여 "쿼터를 어떻게 쓸 것인가"를 제어하는 것을 말합니다: 어떤 모델의 남은 쿼터가 임계값 아래로 떨어지면, Quota Protection은 해당 모델을 계정의 protected_models에 넣고, 해당 모델을 요청할 때 우선적으로 회피합니다. 쿼터가 100%로 돌아오면, Smart Warmup은 극히 작은 트래픽으로 한 번 워밍업 요청을 트리거하고, 로컬 역사 파일로 4시간 쿨링을 수행합니다.
이 수업을 마치면 할 수 있는 것
- Quota Protection을 활성화하여, 낮은 쿼터 계정이 자동으로 "비켜가게" 하고, 고가치 모델을 핵심 요청에 남겨둘 수 있습니다
- Smart Warmup을 활성화하여, 쿼터가 다시 차면 자동으로 워밍업하고(4시간 쿨링이 트리거 주파수에 어떻게 영향을 주는지 알 수 있습니다), 4시간 쿨링이 트리거 주파수에 어떻게 영향을 주는지 알 수 있습니다
quota_protection/scheduled_warmup/protected_models세 필드가 각각 어디서 작동하는지 명확히 할 수 있습니다- 어떤 모델 이름이 "보호 그룹"으로 정규화되는지(어떤 것은 아님) 알 수 있습니다
현재의 문제점
- "계정 로테이션"을 한다고 생각하지만, 실제로는 계속 동일한 종류의 고가치 모델을 소비하고 있습니다
- 쿼터가 낮아서才发现이고, 심지어 Claude Code/클라이언트가 백그라운드에서 warmup하여 할당량을 갉아먹을 수도 있습니다
- 워밍업을 켰지만, 정확히 언제 트리거되는지, 쿨링이 있는지, 쿼터에 영향을 주는지 모릅니다
언제 이 방법을 사용해야 할까요?
- 여러 계정 풀이 있고, 핵심 모델이 "중요한 순간"에 여전히 남아 있기를 원합니다
- 쿼터가 다시 차는 시간을 수동으로 계속 보고 싶지 않고, 시스템이 자동으로 "다 찼을 때의 가벼운 검증"을 하게 하고 싶습니다
🎒 시작 전 준비
전제 조건
이 수업은 기본적으로 다음을 할 수 있다고 가정합니다:
- Accounts 페이지에서 계정 목록을 보고, 쿼터를 수동으로 새로고침할 수 있습니다
- 이미 로컬 리버스 프록시를 시작했고(최소
/healthz에 접근 가능)
아직 실행하지 않았다면, 먼저 **로컬 리버스 프록시 시작 및 첫 번째 클라이언트 연결**를 보세요.
또한, Smart Warmup은 로컬 역사 파일 warmup_history.json을 씁니다. 이것은 데이터 디렉터리에 있으며, 데이터 디렉터리 위치와 백업 방법은 먼저 **최초 실행 필독: 데이터 디렉터리, 로그, 트레이 및 자동 시작**을 보세요.
핵심 아이디어
이 "조합 전술"은 실제로 매우 간단합니다:
- Quota Protection은 "더 이상 낭비하지 마세요"를 담당합니다: 어떤 모델이 임계값 아래로 떨어지면, 보호 모델로 표시하고, 해당 모델을 요청할 때 우선적으로 회피합니다(모델 레벨, 계정을 일괄 금지하지 않음).
- Smart Warmup은 "다 찼으면 한 번 검증하세요"를 담당합니다: 모델이 100%로 돌아오면, 가벼운 요청을 한 번 트리거하여 링크가 사용 가능한지 확인하고, 4시간 쿨링으로 반복 방해를 피합니다.
이들은 모두 프론트엔드의 AppConfig에 있는 구성 필드에 해당합니다:
quota_protection.enabled / threshold_percentage / monitored_models(src/types/config.ts참조)scheduled_warmup.enabled / monitored_models(src/types/config.ts참조)
그리고 실제로 "해당 모델을 요청할 때 이 계정을 건너뛸지 결정하는" 논리는 백엔드 TokenManager에 있습니다:
- 계정 파일의
protected_models는get_token(..., target_model)에서 필터링에 참여합니다(src-tauri/src/proxy/token_manager.rs참조) target_model은 먼저 한 번 정규화(normalize_to_standard_id)하므로,claude-sonnet-4-5-thinking같은 변형은 동일한 "보호 그룹"으로 접힙니다(src-tauri/src/proxy/common/model_mapping.rs참조)
다음 수업 예고
다음 수업에서는 **Proxy Monitor: 요청 로그, 필터링, 상세 복원 및 내보내기**를 학습하여, 호출 블랙박스를 복습 가능한 증거 체인으로 만듭니다.
따라해 보세요
1단계: 먼저 쿼터를 "숫자가 있게" 새로고침
왜 필요한가요? Quota Protection은 계정의 quota.models[].percentage를 기준으로 판단합니다. 쿼터가 새로고침되지 않았으면, 보호 논리가 당신에게 아무것도 할 수 없습니다.
작업 경로: Accounts 페이지를 열고, 도구 모음의 새로고침 버튼을 클릭합니다(단일 계정 또는 전체 가능).
보아야 할 것: 계정 행에 각 모델의 쿼터 퍼센트(예: 0-100)와 reset time이 나타납니다.
2단계: Settings에서 Smart Warmup 열기(선택사항이지만 추천)
왜 필요한가요? Smart Warmup의 목표는 "쿼터 절약"이 아니라 "쿼터가 다 찼을 때 한 번 링크 자체 검증"입니다. 이것은 모델 쿼터가 100%일 때만 트리거되며, 4시간 쿨링이 있습니다.
작업 경로: Settings에 들어가서, 계정 관련 설정 영역으로 전환하고, Smart Warmup 스위치를 켜고, 모니터링할 모델을 체크합니다.
설정 저장을 잊지 마세요.
보아야 할 것: Smart Warmup이 펼쳐지고 모델 목록이 나타납니다. 최소 1개 모델이 체크되어 있어야 합니다.
3단계: Quota Protection 열기 및 임계값과 모니터링 모델 설정
왜 필요한가요? Quota Protection은 "여유 남기기"의 핵심입니다: 모니터링 모델의 쿼터 퍼센트 <= threshold_percentage일 때, 해당 모델을 계정 파일의 protected_models에 쓰고, 이후 해당 모델을 요청할 때 이러한 계정을 우선적으로 회피합니다.
작업 경로: Settings에서 Quota Protection을 엽니다.
- 임계값 설정(
1-99) - 모니터링할 모델 체크(최소 1개)
매우 좋은 기본 구성
너무 고민하지 않으려면, 기본 threshold_percentage=10부터 시작하면 됩니다(src/pages/Settings.tsx 참조).
보아야 할 것: Quota Protection의 모델 체크가 최소 1개 유지됩니다(UI가 마지막 하나도 취소하는 것을 방지합니다).
4단계: "보호 그룹 정규화"가 함정에 빠지게 하지 않는지 확인
왜 필요한가요? TokenManager는 쿼터 보호 판단을 할 때, 먼저 target_model을 표준 ID(normalize_to_standard_id)로 정규화합니다. 예를 들어 claude-sonnet-4-5-thinking은 claude-sonnet-4-5로 정규화됩니다.
이것은 의미합니다:
- Quota Protection에서
claude-sonnet-4-5를 체크합니다 - 실제로
claude-sonnet-4-5-thinking을 요청합니다
여전히 보호에 적중합니다(왜냐하면 이들은 동일한 그룹에 속하기 때문입니다).
보아야 할 것: 어떤 계정의 protected_models에 claude-sonnet-4-5가 포함될 때, claude-sonnet-4-5-thinking에 대한 요청은 해당 계정을 우선적으로 회피합니다.
5단계: 즉시 검증이 필요할 때, "수동 워밍업"으로 한 번 warmup 트리거
왜 필요한가요? 정기 Smart Warmup의 스캔 주기는 10분에 한 번입니다(src-tauri/src/modules/scheduler.rs 참조). 즉시 링크를 검증하고 싶으면, 수동 워밍업이 더 직접적입니다.
작업 경로: Accounts 페이지를 열고, 도구 모음의 "워밍업" 버튼을 클릭합니다:
- 계정을 선택하지 않음: 전량 워밍업 트리거(
warm_up_all_accounts호출) - 계정 선택: 선택한 계정에 대해 각각 워밍업 트리거(
warm_up_account호출)
보아야 할 것: toast가 나타나고, 내용은 백엔드가 반환한 문자열에서 옵니다(예: "Warmup task triggered ...").
체크포인트 ✅
- Accounts 페이지에서 각 계정의 모델 쿼터 퍼센트를 볼 수 있습니다(쿼터 데이터 체인 OK 증명)
- Settings에서 Quota Protection / Smart Warmup을 열고, 구성을 성공적으로 저장할 수 있습니다
protected_models는 "모델 레벨" 제한임을 이해합니다: 한 계정은 특정 모델에 대해서만 회피될 수 있습니다- warmup에 4시간 쿨링이 있다는 것을 알고 있습니다: 짧은 시간 내에 반복해서 워밍업을 클릭하면, "skipped/cooldown" 관련 프롬프트를 볼 수 있습니다
일반적인 실수
1) Quota Protection을 켰지만 계속 적용되지 않음
가장 일반적인 원인은: 계정에 quota 데이터가 없습니다. 보호 논리는 백엔드에서 먼저 quota.models[]를 읽어야만 임계값을 판단할 수 있습니다(src-tauri/src/proxy/token_manager.rs 참조).
1단계로 돌아가서, 먼저 쿼터를 새로고침하세요.
2) 왜 소수의 모델만 "보호 그룹"으로 간주되는가요?
TokenManager의 target_model 정규화는 "화이트리스트식"입니다: 명확하게 나열된 모델 이름만 표준 ID로 매핑됩니다(src-tauri/src/proxy/common/model_mapping.rs 참조).
정규화 후의 논리는: 정규화된 이름(표준 ID 또는 원래 모델 이름)으로 계정의 protected_models 필드를 일치시킵니다. 일치에 성공하면, 해당 계정은 건너뜁니다(src-tauri/src/proxy/token_manager.rs:555-560, 716-719 참조). 이것은 의미합니다:
- 화이트리스트 내의 모델(예:
claude-sonnet-4-5-thinking)은 표준 ID(claude-sonnet-4-5)로 정규화되고, 다음protected_models에 있는지 판단합니다 - 화이트리스트 외의 모델은 정규화 실패 시 원래 모델 이름으로 돌아가고, 여전히
protected_models를 일치시킵니다
즉, 쿼터 보호 판단은 "모든 모델 이름"에 대해 유효하며, 화이트리스트 내의 모델은 먼저 정규화될 뿐입니다.
3) 수동/정기 워밍업은 왜 프록시가 실행 중이어야 하는가요?
워밍업 요청은 최종적으로 로컬 프록시의 내부 엔드포인트에 닿습니다: POST /internal/warmup(src-tauri/src/proxy/server.rs의 라우트 및 src-tauri/src/proxy/handlers/warmup.rs의 구현 참조). 프록시 서비스를 시작하지 않으면, warmup은 실패합니다.
또한, 워밍업 호출하는 포트는 구성에서 옵니다: proxy.port(구성 읽기 실패 시 8045로 롤백, src-tauri/src/modules/quota.rs 참조).
이 수업 요약
- Quota Protection은 "손실 멈추기"를 담당합니다: 임계값 아래에서 모델을
protected_models에 넣고, 해당 모델을 요청할 때 우선적으로 회피합니다 - Smart Warmup은 "다 찼으면 자체 검증"을 담당합니다. 100%에서만 트리거하고, 10분에 한 번 스캔하고, 4시간 쿨링합니다
- 두 가지는 모두 "쿼터 새로고침" 체인에 의존합니다: 먼저
quota.models[]가 있어야, 거버넌스에 기반이 있습니다
다음 수업 예고
쿼터 거버넌스는 "더 안정적으로 쓰기"를 해결합니다. 다음 수업에서는 Proxy Monitor를 계속 보아, 요청 로그, 계정 적중, 모델 매핑을 모두 복습 가능한 증거 체인으로 만드는 것을 추천합니다.
부록: 소스 코드 참조
클릭하여 소스 코드 위치 확인
업데이트 시간: 2026-01-23
| 기능 | 파일 경로 | 라인 |
|---|---|---|
| Quota Protection UI(임계값, 모델 체크, 최소 1개 유지) | src/components/settings/QuotaProtection.tsx | 13-168 |
| Smart Warmup UI(활성화 후 기본 체크, 최소 1개 유지) | src/components/settings/SmartWarmup.tsx | 14-120 |
쿼터 거버넌스 구성 필드(quota_protection / scheduled_warmup) | src/types/config.ts | 54-94 |
기본 임계값 및 기본 구성(threshold_percentage: 10) | src/pages/Settings.tsx | 20-51 |
protected_models 쓰기/복원(임계값 판단 및 디스크 저장) | src-tauri/src/proxy/token_manager.rs | 254-467 |
요청 측 쿼터 보호 필터링(get_token(..., target_model)) | src-tauri/src/proxy/token_manager.rs | 470-674 |
보호 그룹 정규화(normalize_to_standard_id) | src-tauri/src/proxy/common/model_mapping.rs | 230-254 |
Smart Warmup 정기 스캔(10분마다 한 번 + 4시간 쿨링 + warmup_history.json) | src-tauri/src/modules/scheduler.rs | 11-221 |
수동 워밍업 명령(warm_up_all_accounts / warm_up_account) | src-tauri/src/commands/mod.rs | 167-212 |
워밍업 구현(내부 엔드포인트 /internal/warmup 호출) | src-tauri/src/modules/quota.rs | 271-512 |
| 내부 워밍업 엔드포인트 구현(요청 구성 + 업스트림 호출) | src-tauri/src/proxy/handlers/warmup.rs | 3-220 |