Workspace LLM Quota — 월별 USD 한도

이 문서는 운영자/관리자가 워크스페이스별로 LLM 호출 비용 한도(월 USD 캡)를 등록하고, 사용량을 점검하며, 한도를 넘었을 때 동작을 통제할 때 사용합니다.

누가 사용할 수 있나요

사용자	가능한 작업
admin realm role 보유자	모든 워크스페이스의 한도 등록·수정·삭제, 전체 매트릭스 조회
워크스페이스 멤버 (Keycloak group /tenants/{slug})	자기 워크스페이스의 현재 사용량 / 한도 조회
그 외 사용자	호출 거부 (HTTP 403)

접근 권한 부여 절차

1. Keycloak Console 접속 → 좌측 Groups 메뉴
2. /tenants/{slug} 그룹 선택 (예: /tenants/finance-invest)
3. Members 탭 → Add member → 사용자 검색·추가
4. 전사 관리자 권한이 필요하면 사용자 상세 → Role mapping → admin realm role 부여

권한 변경 후에는 사용자가 한 번 로그아웃했다가 다시 로그인해야 새 그룹/role 이 토큰에 반영됩니다.

무엇을 할 수 있나요

워크스페이스 단위로 두 종류의 월 USD 한도를 설정할 수 있습니다.

• Soft 한도 — 넘어도 호출은 그대로 허용되지만, 로그 경고와 Prometheus 메트릭이 발생합니다. "곧 한도에 도달함"을 알리는 용도입니다.
• Hard 한도 — 넘는 즉시 호출이 차단되고 HTTP 429 가 반환됩니다. 비용 사고를 막는 마지막 방어선입니다.

값을 0 으로 두면 해당 한도는 "없음"으로 간주됩니다. 두 값을 모두 양수로 등록하면 soft ≤ hard 가 강제됩니다.

그림: ⚙ 관리 콘솔 → AI & MCP 플랫폼 → AI 모델 사용량 대시보드에서 워크스페이스별 누적 비용을 확인합니다. 같은 합계가 ai-quota-status API 의 used_usd 값과 일치합니다.

화면 둘러보기

현재 한도/사용량은 두 가지 진입점으로 확인합니다.

위치	내용
⚙ 관리 콘솔 → AI & MCP 플랫폼 → AI 모델 사용량	모든 워크스페이스의 누적 비용 (Group by Workspace)
Workspace → AI Settings → Quota Status	본인 소속 워크스페이스의 한도와 이번 달 사용량

API 응답에는 다음 컬럼이 있습니다.

필드	의미
used_usd	이번 달 누적 호출 비용 (USD)
soft_limit / hard_limit	등록된 한도, 0 이면 미설정
soft_exceeded / hard_exceeded	한도 초과 여부 (true/false)

단계별 사용법

시나리오 1 — 새 워크스페이스에 한도 등록 (운영자)

finance-invest 워크스페이스에 월 $400 경고, $500 차단을 등록합니다.

1. Keycloak 로그인 후 admin 토큰 확보 (Authorization: Bearer ...)
2. 워크스페이스 ID 조회
3. PUT /api/v1/admin/llm-quotas/{workspace_id} 호출

WS_ID=$(curl -sS "https://gend.genon.ai/api/v1/workspaces?slug=finance-invest" \
  -H "Authorization: Bearer $TOKEN" | jq -r '.[0].id')

curl -sS -X PUT "https://gend.genon.ai/api/v1/admin/llm-quotas/$WS_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"monthly_usd_soft_limit": 400, "monthly_usd_hard_limit": 500}'

응답 200 이면 등록 완료입니다. 같은 엔드포인트를 다시 호출하면 값이 갱신됩니다.

시나리오 2 — 이번 달 사용량 확인 (워크스페이스 멤버)

자기 소속 워크스페이스의 현재 한도/사용량을 조회합니다.

curl -sS "https://gend.genon.ai/api/v1/workspaces/finance-invest/ai-quota-status" \
  -H "Authorization: Bearer $TOKEN"

응답 예시:

{
  "workspace_id": "9a1c...",
  "used_usd": 432.10,
  "soft_limit": 400.0,
  "hard_limit": 500.0,
  "soft_exceeded": true,
  "hard_exceeded": false
}

soft_exceeded: true 가 보이면 한도에 가까워졌다는 신호입니다. 이번 달 호출량을 조정하거나, 운영자에게 한도 상향을 요청하세요.

시나리오 3 — 한도 제거 (운영자)

해당 워크스페이스를 한도 적용 대상에서 제외하려면 DELETE 로 row 를 지웁니다.

curl -sS -X DELETE "https://gend.genon.ai/api/v1/admin/llm-quotas/$WS_ID" \
  -H "Authorization: Bearer $TOKEN"

이후 호출은 한도 검사 없이 통과합니다 (비용 캡 없음).

API 직접 호출 (선택)

Method	Path	권한	용도
GET	/api/v1/admin/llm-quotas	admin	전체 매트릭스
PUT	/api/v1/admin/llm-quotas/{workspace_id}	admin	한도 등록 또는 수정
DELETE	/api/v1/admin/llm-quotas/{workspace_id}	admin	한도 제거
GET	/api/v1/workspaces/{slug}/ai-quota-status	admin 또는 멤버	현재 한도와 사용량

전체 매트릭스 조회 예시:

curl -sS "https://gend.genon.ai/api/v1/admin/llm-quotas" \
  -H "Authorization: Bearer $TOKEN" | jq '.[] | {workspace_id, monthly_usd_soft_limit, monthly_usd_hard_limit}'

Prometheus 알림 (선택)

운영팀이 운영하는 Prometheus 가 있다면 다음 규칙을 추가하세요. 차단 발생 시 자동으로 알림이 발생합니다.

- alert: LLMWorkspaceQuotaHardExceeded
  expr: rate(gend_llm_quota_block_total{level="hard"}[5m]) > 0
  for: 1m
  annotations:
    summary: "워크스페이스 {{ $labels.workspace_id }} LLM 호출이 hard 한도로 차단됨"

- alert: LLMWorkspaceQuotaSoftWarning
  expr: rate(gend_llm_quota_block_total{level="soft"}[1h]) > 0
  for: 5m
  annotations:
    summary: "워크스페이스 {{ $labels.workspace_id }} LLM 비용이 soft 한도 초과"

자주 묻는 질문 / 문제 해결

Q. 사용자가 호출했더니 갑자기 HTTP 429 가 떨어집니다. A. hard 한도를 넘은 상태입니다. /api/v1/workspaces/{slug}/ai-quota-status 로 hard_exceeded 값을 확인하고, 필요하면 운영자가 한도를 상향하거나 DELETE 로 잠시 해제하세요. 월이 바뀌면 사용량은 자동으로 초기화됩니다.

Q. soft 한도만 등록해도 되나요? A. 가능합니다. monthly_usd_soft_limit 만 양수로 두고 monthly_usd_hard_limit 을 0 으로 보내면 경고만 발생하고 차단은 없습니다.

Q. soft 가 hard 보다 크면 어떻게 되나요? A. API 가 400 을 반환합니다. 반드시 soft ≤ hard (둘 다 양수일 때) 를 지켜야 합니다.

Q. 월 기준은 언제부터 언제까지인가요? A. UTC 기준 매월 1일 00:00 부터 다음 달 1일 00:00 까지 누적합니다. KST 기준으로 환산하면 매월 1일 09:00 KST 에 사용량이 0 으로 초기화됩니다.

Q. 등록된 LLM provider 가 여러 개여도 한도는 워크스페이스 단위로만 적용되나요? A. 네. 워크스페이스에서 호출한 모든 LLM provider (예: GenON Qwen 3.5 397B) 의 비용이 합산되어 한 한도에 누적됩니다. provider 별 분리 한도는 본 가이드 범위 밖입니다.

Q. 한도 등록 후에도 차단이 적용되지 않습니다. A. 호출자가 워크스페이스 컨텍스트 없이 호출 (예: admin token + 워크스페이스 헤더 미첨부) 하면 한도가 적용되지 않습니다. 호출 시 X-Workspace-Slug 헤더가 정상적으로 전달되는지 확인하세요.

참고: VLM(예: 비전 모델) 추가 등록도 가능합니다. 별도 Vault key 와 provider 등록이 필요하며, 본 가이드는 LLM 기본 예시(GenON Qwen 3.5 397B)만 다룹니다.