CLOVA Studio 이용량 제어 정책

Prev Next

Classic/VPC 환경에서 이용 가능합니다.

CLOVA Studio는 사용자가 특정 시간 내에 이용할 수 있는 API 요청 횟수와 토큰 수에 상한선을 두고 있습니다. 이를 이용량 제어 정책이라 하며 서비스의 가용성을 유지하고 안정성을 확보하기 위해 필요한 정책입니다. 사용자는 정해진 범위 내에서 CLOVA Studio 서비스를 이용할 수 있고, 요청 가능한 최댓값을 초과할 경우에는 오류 메시지 및 오류 코드가 반환됩니다.
이용량 제어 정책을 적용함으로써 악의적으로 API를 다량 호출하여 공격하는 행위를 막을 수 있고 과도한 트래픽으로부터 서비스를 보호할 수 있습니다. 또한 특정 사용자가 리소스를 독점하는 것을 방지하여 모든 사용자가 리소스를 안정적으로 사용할 수 있는 환경을 구성할 수 있습니다. 모델, 도구, 목적에 따라 이용할 수 있는 최댓값이 달라지므로 이 가이드에서 안내하는 내용을 반드시 숙지해 주십시오.

참고
  • 본 가이드는 Basic 플랜을 기준으로 작성되었습니다. 일정 수준의 이용량이 보장되어야 하는 경우 별도의 Exclusive 플랜을 이용할 수 있습니다. 해당 플랜 및 정책과 관련하여 더 자세한 정보가 필요할 경우, 고객 지원으로 문의해 주십시오.
  • 이 가이드에서 안내하는 최대 이용량은 사용자가 CLOVA Studio 서비스 이용 시 요청할 수 있는 최댓값을 명시한 것으로, 해당 값만큼의 요청량을 반드시 보장한다는 의미는 아닙니다. 최대 이용량 이내로 서비스를 이용하더라도 인프라 상황 및 트래픽에 따라 처리 지연이 발생하거나 실패할 수 있습니다.
  • 최대 이용량은 추후 변경될 수 있습니다. 최대 이용량이 변경될 경우, 이용 고객에게 별도로 안내할 예정입니다.

최대 이용량 산정 시 기준이 되는 대상은 다음과 같습니다.

구분 설명
사용자의 계정 메인 계정을 기준으로 최대 이용량 산정
  • 서브 계정이 있는 경우, 서브 계정의 이용량도 메인 계정의 이용량에 포함
    		•
    모델 및 도구 이용하는 모델 및 도구에 따라 최대 이용량이 달라짐
  • 튜닝 모델로 작업할 경우, 튜닝 시 사용된 모델에 대한 요청으로 간주하여 최대 이용량 산정
    • 이용 목적 테스트 앱이냐 서비스 앱이냐에 따라 최대 이용량이 달라짐

    CLOVA Studio에서 이용량이 제한되는 수치는 분당 요청 횟수인 QPM과 분당 처리 토큰 수를 의미하는 TPM입니다. QPM과 TPM이 모두 적용되는 경우, 두 개의 값 중 하나라도 최댓값에 먼저 도달하면 오류 코드가 반환됩니다.
    QPM과 TPM에 대한 설명은 다음과 같습니다.

    구분 설명
    QPM (Queries per Minute) 1분 동안 모델 및 도구에 작업을 요청한 횟수
    TPM (Tokens per Minute) 1분 동안 처리할 토큰 수
  • 처리할 토큰 수=입력된 토큰 수+결괏값 생성 시 사용할 최대 토큰 수(maxTokens)
    		•
    참고

    2025년 5월 22일 기준으로 지원 가능한 최대 이용량으로, 추후 변동될 수 있습니다.

    CLOVA Studio 플레이그라운드와 테스트 앱에서 이용 가능한 최대 QPM, TPM을 설명합니다.

    모델별 최대 이용량

    모델별로 이용 가능한 최대 QPM, TPM은 다음과 같습니다.

    구분 QPM TPM
    HCX-005 60 30,000
    HCX-DASH-002 60 30,000
    HCX-003 30 10,000
    HCX-DASH-001 100 20,000
    Exclusive 전용 모델 120 20,000
    튜닝 모델 튜닝 시 사용된 모델에 대한 요청으로 간주

    도구별 최대 이용량

    익스플로러 도구별로 이용 가능한 최대 QPM, TPM은 다음과 같습니다.

    구분 QPM TPM 비고
    요약 10 30,000 TPM 계산 시 입력값만 포함
    문단 나누기 120 -
    임베딩 v2 60 40,000 TPM 계산 시 입력값만 포함

    스킬 트레이너 최대 이용량

    스킬 트레이너에서 이용 가능한 최대 QPM, TPM은 다음과 같습니다.

    구분 QPM 비고
    스킬셋 답변 생성 10 작업 및 버전 미구분
    라우터 30 작업 및 버전 미구분

    서비스 앱에서 모델별, 도구별로 이용 가능한 최대 QPM과 TPM을 설명합니다.
    서비스 앱의 이용 가능한 최대 QPM, TPM 계산 시 웹 및 테스트 앱의 최대 이용량도 포함됩니다. 따라서 명시된 최댓값으로 이용하려면 서비스 앱과 테스트 앱을 동시에 운영해야 하며, 서비스 앱 단독 운영 시에는 테스트 앱의 최대 이용량을 뺀 값이 적용됩니다.

    모델별 최대 이용량

    모델별로 이용 가능한 최대 QPM, TPM은 다음과 같습니다.

    모델 QPM TPM
    HCX 전체 (Exclusive 전용 포함) 별도 문의 요망
    튜닝 모델 튜닝 시 사용한 모델에 대한 요청으로 간주
    스킬셋 튜닝 모델 별도 문의 요망

    도구별 최대 이용량

    익스플로러 도구별로 이용 가능한 최대 QPM, TPM은 다음과 같습니다.

    구분 QPM TPM 테스트 앱 제외 시 (QPM | TPM) 비고
    요약 40 90,000 30 | 60,000 TPM 계산 시 입력값만 포함
    문단 나누기 480 - 360 | -
    임베딩 v2 600 1,000,000 540 | 960,000 TPM 계산 시 입력값만 포함

    스킬 트레이너 최대 이용량

    스킬 트레이너에서 이용 가능한 최대 QPM은 다음과 같습니다.

    구분 QPM 테스트 앱 제외 시 (QPM) 비고
    스킬셋 답변 생성 40 30 작업 및 버전 미구분
    라우터 90 60 작업 및 버전 미구분

    cURL, Python 등을 통해 API를 호출하여 CLOVA Studio 서비스를 이용하는 경우, API 응답 헤더를 통해 이용량 제어 관련 정보를 확인할 수 있습니다.

    확인 가능한 정보는 아래와 같습니다.

    Key Value (예시) 설명 비고
    x-ratelimit-limit-requests 60 이용중인 API에 설정된 최대 이용량 (QPM)
    x-ratelimit-limit-tokens 10000 이용중인 API에 설정된 최대 이용량 (TPM) TPM 이용량 제한이 있는 경우 포함
    x-ratelimit-remaining-requests 59 이용중인 API에 설정된 최대 이용량에 도달하기까지 남은 이용량 (요청 수)
    x-ratelimit-remaining-tokens 9462 이용중인 API에 설정된 최대 이용량에 도달하기까지 남은 이용량 (토큰 수) TPM 이용량 제한이 있는 경우 포함
    x-ratelimit-reset-requests 23s 이용중인 API에 설정된 최대 이용량 (요청 수) 초기 값 재설정까지 남은 시간
    x-ratelimit-reset-tokens 23s 이용중인 API에 설정된 최대 이용량 (토큰 수) 초기 값 재설정까지 남은 시간 TPM 이용량 제한이 있는 경우 포함

    CLOVA Studio 서비스 이용 시 요청할 수 있는 최댓값이 초과될 경우, HTTP 429 코드가 반환되거나 오류 메시지가 나타납니다. 최대 이용량을 초과하지 않기 위해 수행할 수 있는 작업을 설명합니다.

    참고

    CLOVA Studio는 안정적이고 원활한 서비스를 제공하기 위해 최선을 다하고 있으나 최대 요청량 이내로 서비스를 이용할 경우에도 일부 처리 지연이 발생하거나 실패할 수 있습니다.

    • QPM 수치를 미리 확인한 후 최댓값 이내로 요청해 주십시오.
    • 별도의 API 호출 제어 기능(rate limit)을 직접 구현 및 추가해 주십시오.
    • 요청 사이에 일정 시간 지연 기능(time sleep)을 별도로 추가해 주십시오.
    • HTTP 429 코드 반환 및 해당 오류 메시지 응답 시 예외 처리를 통해 일정 시간 지연 이후 재요청해 주십시오.
    • TPM 수치를 미리 확인하여 작업을 위해 입력하는 토큰 수와 결괏값 생성 시 사용할 최대 토큰 수를 실제로 필요한 정도만 설정해 주십시오.
    • API 호출 시 입력한 문자열의 토큰 수를 확인하려면 익스플로러 메뉴의 토큰 계산기 API를 활용해 주십시오.
    • API 호출 시 결괏값에 사용할 최대 토큰 수를 조정하려면 maxTokens 필드의 값을 수정해 주십시오.
    • 플레이그라운드 메뉴에서 입력된 문자열의 토큰 수를 확인하려면 플레이그라운드 화면 상단의 계산 아이콘을 클릭해 주십시오.
      clovastudio-ratelimiting_tpm-mitigation01_ko
    • 플레이그라운드 메뉴에서 결괏값 생성 시 사용할 최대 토큰 수를 조정하려면 플레이그라운드 화면 왼쪽에 있는 Maximum tokens 필드를 수정해 주십시오.
      clovastudio-ratelimiting_tpm-mitigation02_ko