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년 3월 27일 기준으로 지원 가능한 최대 이용량으로, 추후 변동될 수 있습니다.
CLOVA Studio 웹 및 테스트 앱
CLOVA Studio 플레이그라운드와 테스트 앱에서 이용 가능한 최대 QPM, TPM을 설명합니다.
모델별 최대 이용량
모델별로 이용 가능한 최대 QPM, TPM은 다음과 같습니다.
| 구분 | QPM | TPM |
|---|---|---|
| HCX-003 | 30 | 10,000 |
| HCX-DASH-001 | 100 | 20,000 |
| Exclusive 전용 모델 | 120 | 20,000 |
| 튜닝 모델 | 튜닝 시 사용된 모델에 대한 요청으로 간주 | |
| 스킬셋 학습 모델 | 10 | - |
도구별 최대 이용량
익스플로러 도구별로 이용 가능한 최대 QPM, TPM은 다음과 같습니다.
| 구분 | QPM | TPM | 비고 |
|---|---|---|---|
| 요약 | 10 | 30,000 | TPM 계산 시 입력값만 포함 |
| 문단 나누기 | 120 | - | |
| 임베딩 v2 | 60 | 40,000 | TPM 계산 시 입력값만 포함 |
서비스 앱
서비스 앱에서 모델별, 도구별로 이용 가능한 최대 QPM과 TPM을 설명합니다.
서비스 앱의 이용 가능한 최대 QPM, TPM 계산 시 웹 및 테스트 앱의 최대 이용량도 포함됩니다. 따라서 명시된 최댓값으로 이용하려면 서비스 앱과 테스트 앱을 동시에 운영해야 하며, 서비스 앱 단독 운영 시에는 테스트 앱의 최대 이용량을 뺀 값이 적용됩니다.
모델별 최대 이용량
모델별로 이용 가능한 최대 QPM, TPM은 다음과 같습니다.
| 모델 | QPM | TPM |
|---|---|---|
| HCX-003 | 별도 문의 요망 | |
| HCX-DASH-001 | 별도 문의 요망 | |
| Exclusive 전용 | 별도 문의 요망 | |
| 튜닝 모델 | 튜닝 시 사용한 모델에 대한 요청으로 간주 | |
| 스킬셋 튜닝 모델 | 별도 문의 요망 | |
도구별 최대 이용량
익스플로러 도구별로 이용 가능한 최대 QPM, TPM은 다음과 같습니다.
| 구분 | QPM | TPM | 비고 |
|---|---|---|---|
| 요약 | 40 | 90,000 | TPM 계산 시 입력값만 포함 |
| 문단 나누기 | 480 | - | |
| 임베딩 v2 | 600 | 1,000,000 | TPM 계산 시 입력값만 포함 |
최대 이용량 확인
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 관리 방법
- QPM 수치를 미리 확인한 후 최댓값 이내로 요청해 주십시오.
- 별도의 API 호출 제어 기능(rate limit)을 직접 구현 및 추가해 주십시오.
- 요청 사이에 일정 시간 지연 기능(time sleep)을 별도로 추가해 주십시오.
- HTTP 429 코드 반환 및 해당 오류 메시지 응답 시 예외 처리를 통해 일정 시간 지연 이후 재요청해 주십시오.
TPM 관리 방법
- TPM 수치를 미리 확인하여 작업을 위해 입력하는 토큰 수와 결괏값 생성 시 사용할 최대 토큰 수를 실제로 필요한 정도만 설정해 주십시오.
- API 호출 시 입력한 문자열의 토큰 수를 확인하려면 익스플로러 메뉴의 토큰 계산기 API를 활용해 주십시오.
- API 호출 시 결괏값에 사용할 최대 토큰 수를 조정하려면
maxTokens필드의 값을 수정해 주십시오. - 플레이그라운드 메뉴에서 입력된 문자열의 토큰 수를 확인하려면 플레이그라운드 화면 상단의 계산 아이콘을 클릭해 주십시오.
- 플레이그라운드 메뉴에서 결괏값 생성 시 사용할 최대 토큰 수를 조정하려면 플레이그라운드 화면 왼쪽에 있는 Maximum tokens 필드를 수정해 주십시오.
