본문으로 건너뛰기

학습 데이터셋 스토리지 쿼터 — 워크스페이스 용량 한도 (v1.2+)

운영자/관리자가 워크스페이스별로 학습 데이터셋 스토리지 한도(bytes)를 등록하고 사용량을 점검할 때 사용합니다 (#2989 M0). prod SeaweedFS 는 볼륨 슬롯 구조상 용량 고갈을 사후 알람으로 잡을 수 없어, 선제 쿼터가 유일한 방어선입니다.

누가 사용할 수 있나요​

사용자가능한 작업
admin realm role 보유자모든 워크스페이스의 한도 등록·수정·해제, 전체 매트릭스 조회
워크스페이스 멤버 (viewer 이상)GET /api/v1/datasets/usage 로 자기 워크스페이스의 사용량/한도/사용자별 breakdown 조회

동작 방식​

  • Soft 한도 — 넘어도 업로드는 허용되지만, 응답의 quota_warning 필드·경고 로그·Prometheus 메트릭이 발생합니다.
  • Hard 한도 — 넘는 업로드는 즉시 HTTP 413 으로 거부됩니다 (detail 에 "쿼터" 문구 — 파일 크기 상한 413 과 구분).
  • 값 0 = "없음". 두 값 모두 양수면 soft ≤ hard 가 강제됩니다.
  • 쿼터 행이 없는 워크스페이스는 GEND_DATASET_DEFAULT_QUOTA_BYTES (기본 0=무제한) 가 hard 로 적용됩니다 — 기존 워크스페이스를 깨지 않는 안전 롤아웃 기본입니다.

사용량 산정 — 적재 원장(training_dataset_ingests.bytes_added) 합계:

경로계상 바이트
이미지 파일/zip 업로드실제 S3 에 저장된 blob + 썸네일 합 (중복·거부 파일 제외)
JSONL / Parquet 업로드Bronze 원본(raw) 바이트 — dedup 결과와 무관하게 항상 저장되므로
데이터셋 삭제원장이 함께 삭제되어 사용량이 즉시 감소 (실제 S3 는 GC 유예 후 정리 — 기본 7일)
행 삭제 (DELETE /rows)변화 없음 — S3 blob 은 지워지지 않음

알려진 한계 (M0 후속): export 산출물은 사용량에 잡히지 않습니다. 중복만 있는 JSONL/Parquet 업로드의 raw 도 원장에 잡히지 않지만, raw 키가 content-hash 결정적이라 같은 파일 재업로드는 같은 객체를 덮어써 파일당 1회 사본으로 유계입니다. 원장 컬럼 도입(v1.2) 이전의 기존 데이터는 0 으로 계상됩니다.

단계별 사용법​

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

v1.2+ 는 관리자 UI(사이드바 → 데이터셋 쿼터, /admin/dataset-quotas)에서 등록/수정/해제할 수 있습니다.

관리자 데이터셋 쿼터 화면

# workspace_id 확인 후 soft 4GB / hard 5GB 등록
curl -sS -X PUT "https://gend.genon.ai/api/v1/admin/dataset-quotas/${WS_ID}" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" -H "Content-Type: application/json" \
  -d '{"soft_limit_bytes": 4294967296, "hard_limit_bytes": 5368709120}'

시나리오 2 — 사용량 확인 (멤버, v1.2+ 는 UI/CLI 가능)​

  • UI: 데이터셋 페이지 상단 사용량 카드 — 게이지(사용/hard)·soft 마커·사용자별 표. "증설 신청" 버튼으로 시나리오 4 를 화면에서 수행.

    데이터셋 페이지 사용량 카드

  • CLI: gend dataset usage / 증설 신청은 gend dataset request-quota --hard-gb N --reason "...".

  • REST:

curl -sS "https://gend.genon.ai/api/v1/datasets/usage" \
  -H "Authorization: Bearer ${TOKEN}" -H "X-Workspace-Slug: ${SLUG}"
# → used_bytes / soft·hard_limit_bytes / remaining_bytes / per_user[]

시나리오 3 — 한도 해제​

curl -sS -X DELETE "https://gend.genon.ai/api/v1/admin/dataset-quotas/${WS_ID}" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}"   # 204 — 이후 기본값(무제한) 적용

시나리오 4 — 증설 신청 → 관리자 승인 (v1.2+)​

한도가 부족한 워크스페이스 멤버(analyst 이상)가 직접 신청하고, 관리자가 승인하면 쿼터가 자동 반영됩니다.

# 1) 멤버 — 증설 신청 (요청 한도는 절대값, 승인 시 그대로 적용)
curl -sS -X POST "https://gend.genon.ai/api/v1/datasets/quota-increase" \
  -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  -d '{"soft_limit_bytes": 8000000000, "hard_limit_bytes": 10000000000,
       "reason": "Physical AI 이미지 셋 적재 (약 8GB)"}'
# → 201 + 승인 요청 ID. 같은 워크스페이스에 대기 중 신청이 있으면 409.

# 2) 관리자 — 승인 (기존 Approvals 화면 또는 API)
curl -sS -X POST "https://gend.genon.ai/api/v1/approvals/${REQUEST_ID}/decide" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" -H "Content-Type: application/json" \
  -d '{"action": "approve", "comment": "승인"}'
# → 승인과 동시에 쿼터가 신청 값으로 갱신됩니다 (원자적 — 실패 시 승인도 롤백).
#    거부(reject) 시 쿼터는 변하지 않습니다. 본인 신청은 본인이 승인할 수 없습니다.
  • 신청 목록은 GET /api/v1/approvals?request_type=dataset_storage_quota_increase 로 필터합니다.
  • 결정 시 approval_decided 이벤트가 발생합니다 — 알림을 받으려면 알림 채널 의 events 목록에 approval_decided 를 추가하세요.

모니터링​

메트릭의미
gend_dataset_quota_block_total{level="hard"}413 거부 발생 — rate > 0 이면 사용자가 막히는 중 (알림 후보)
gend_dataset_quota_block_total{level="soft"}soft 경고 발생
gend_dataset_storage_usage_bytes전사 사용량 합계 (라벨 없음 — 레플리카별 값이므로 Grafana 집계는 max())

관련 문서​