PromptTokenLimit 정책

이 페이지는 Apigee에 적용되지만 Apigee Hybrid에는 적용되지 않습니다.

Apigee Edge 문서 보기

개요

PromptTokenLimit 정책은 사용자 프롬프트의 토큰 수를 제한하여 대규모 언어 모델 (LLM) 백엔드를 트래픽 급증으로부터 보호합니다.

PromptTokenLimit 정책은 SpikeArrest 정책과 유사하지만 SpikeArrest 정책은 요청 수를 제한하는 반면 PromptTokenLimit 정책은 이러한 요청 내의 토큰 수를 제한합니다. 이 정책은 비용과 성능이 처리된 토큰 수와 직접적으로 관련된 LLM 애플리케이션에 맞게 특별히 조정되었습니다.

이 정책은 확장 가능한 정책이며, 이 정책을 사용하면 Apigee 라이선스에 따라 비용 또는 사용률이 영향을 받을 수 있습니다. 정책 유형 및 사용 영향에 대한 자세한 내용은 정책 유형을 참조하세요.

PromptTokenLimit와 LLMTokenQuota의 차이점

PromptTokenLimit 정책은 토큰 사용량이 갑자기 급증하는 것을 방지하기 위해 운영 트래픽 관리에 사용됩니다. 반면 LLMTokenQuota 정책은 비용을 관리하고 비즈니스 계약을 시행하기 위해 더 긴 기간 (예: 시간, 일, 월)에 걸쳐 클라이언트 앱의 소비 한도를 적용하는 데 사용됩니다.

PromptTokenLimit 요소

PromptTokenLimit 정책을 정의합니다.

기본값 아래의 기본 정책 탭을 참고하세요.
필수 여부 선택사항
유형 복합 객체
상위 요소 해당 사항 없음
하위 요소 <Identifier>
<Rate> (필수)
<UseEffectiveCount>
<UserPromptSource>
<IgnoreUnresolvedVariables>

구문

PromptTokenLimit 요소는 다음 구문을 사용합니다.

<PromptTokenLimit continueOnError="false" enabled="true" name="POLICY_NAME">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Identifier ref=""/>
  <Rate ref="">[pm|ps]</Rate>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
  <IgnoreUnresolvedVariables>[false|true]</IgnoreUnresolvedVariables>
</PromptTokenLimit>
      

기본 정책

다음 예시는 UI에서 흐름에 PromptTokenLimit 정책을 추가할 때의 기본 설정을 보여줍니다.

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Identifier ref=""/>
  <Rate ref="">[pm|ps]</Rate>
  <UseEffectiveCount>[false|true]</UseEffectiveCount>
  <IgnoreUnresolvedVariables>[false|true]</IgnoreUnresolvedVariables>
</PromptTokenLimit>
      

이 요소에는 다음과 같이 모든 정책에 공통된 속성이 있습니다.

속성 기본값 필수 여부 설명
name 해당 사항 없음 필수

정책의 내부 이름입니다. name 속성의 값에는 문자, 숫자, 공백, 하이픈, 밑줄, 마침표가 포함될 수 있습니다. 이 값은 255자(영문 기준)를 초과할 수 없습니다.

원하는 경우 <DisplayName> 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름을 사용하여 정책에 라벨을 지정합니다.

continueOnError 거짓 선택사항 정책이 실패할 경우 오류가 반환되도록 하려면 false로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다. 정책이 실패해도 흐름 실행이 계속되도록 하려면 true로 설정합니다. 참조:
enabled 선택사항 정책을 시행하려면 true로 설정합니다. 정책을 중지하려면 false로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.
async   거짓 지원 중단됨 이 속성은 지원이 중단되었습니다.

예시

다음 예시에서는 PromptTokenLimit 정책을 사용할 수 있는 몇 가지 방법을 보여줍니다.

예 1

단일 복제본 내에서 프롬프트 토큰 제한

이 예에서는 프롬프트 토큰 제한이 단일 복제본 내에서 발생하며 한 리전의 여러 메시지 프로세서에 분산되지 않습니다.

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Identifier ref="request.url"/>
  <Rate>1pm</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

예 2

분산 토큰 제한

이 예에서는 프롬프트 토큰 제한이 한 리전의 여러 복제본에 분산되고 '슬라이딩 창' 비율 제한 알고리즘이 적용됩니다.

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
  <Identifier ref="request.url"/>
  <Rate>1pm</Rate>
  <UseEffectiveCount>true</UseEffectiveCount>
</PromptTokenLimit>

예시 3

요청당 컨텍스트 윈도우 크기 토큰 제한

이 예에서는 프롬프트 토큰 제한이 단일 복제본 내에서 발생하며 한 리전의 여러 메시지 프로세서에 분산되지 않습니다. 이 특정 구성은 요청당 컨텍스트 윈도우 크기 토큰 제한에 사용됩니다.

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <UserPromptSource>{jsonPath('$.messages',request.content,true)}</UserPromptSource>
  <Identifier ref="messageid"/>
  <Rate>1pm</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

예 4

기본값을 사용하여 토큰 제한을 분산했습니다.

이 예에서는 프롬프트 토큰 제한이 단일 복제본 내에서 발생하며 한 리전의 여러 메시지 프로세서에 분산되지 않습니다. 사용자 프롬프트 소스 기본값이 사용됩니다. {jsonPath('$.messages',request.content,true)}

<PromptTokenLimit continueOnError="false" enabled="true" name="PTL-limitTokens-1">
  <DisplayName></DisplayName>
  <Properties/>
  <Identifier ref="messageid"/>
  <Rate>1pm</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

하위 요소 참조

이 섹션에서는 <PromptTokenLimit>의 하위 요소를 설명합니다.

<DisplayName>

name 속성 외에 이 요소를 사용하여 관리 UI 프록시 편집기에서 자연스러운 다른 이름으로 정책의 라벨을 지정합니다.

<DisplayName> 요소는 모든 정책에 공통으로 적용됩니다.

기본값 해당 사항 없음
필수 여부 선택사항. <DisplayName>을 생략하면 정책의 name 속성 값이 사용됩니다.
유형 문자열
상위 요소 <PolicyElement>
하위 요소 없음

<DisplayName> 요소는 다음 문법을 사용합니다.

구문

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

<DisplayName> 요소에 속성 또는 하위 요소가 없습니다.

<Identifier>

클라이언트에 따라 PromptTokenLimit 정책을 적용할 수 있도록 요청을 그룹화하는 방법을 선택할 수 있습니다. 예를 들어 개발자 ID별로 요청을 그룹화할 수 있으며, 이 경우 각 개발자의 요청은 해당 프록시의 모든 요청이 아닌 자체 PromptTokenLimit 비율로 계산됩니다.

<Identifier> 요소를 비워 두면 해당 API 프록시에 대한 모든 요청에 한 개의 비율 제한이 적용됩니다.

기본값 해당 사항 없음
필수 여부 선택사항
유형 문자열
상위 요소 <PromptTokenLimit>
하위 요소 없음

구문

<PromptTokenLimit
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="POLICY_NAME"
>
  <Identifier ref="FLOW_VARIABLE"/>
</PromptTokenLimit>

예 1

다음 예에서는 개발자 ID별로 PromptTokenLimit 정책을 적용합니다.

<PromptTokenLimit name="PTL-limitTokens-1">
  <Identifier ref="developer.id"/>
  <Rate>42pm</Rate/>
  <UseEffectiveCount>true</UseEffectiveCount>
</PromptTokenLimit>
      

다음 표는 <Identifier>의 속성을 설명합니다.

속성 설명 기본값 접속 상태
ref PromptTokenLimit 그룹이 요청을 수신하는 변수를 식별합니다. VerifyAPIKey 정책에 사용 가능한 고유한 클라이언트를 나타내는 모든 흐름 변수를 사용할 수 있습니다. JavaScript 정책 또는 AssignMessage 정책을 사용하여 커스텀 변수를 설정할 수도 있습니다. 해당 사항 없음 필수

<Rate>

분당 또는 초당 간격으로 허용되는 토큰 수를 설정하여 토큰 급증 (또는 버스트)을 제한하는 비율을 지정합니다. 이 요소를 <Identifier>와 함께 사용하여 클라이언트의 값을 허용해 런타임에 트래픽을 원활하게 조절할 수 있습니다. <UseEffectiveCount> 요소를 사용하여 정책에 사용되는 비율 제한 알고리즘을 설정합니다.

기본값 해당 사항 없음
필수 여부 필수
유형 정수
상위 요소 <PromptTokenLimit>
하위 요소 없음

구문

다음 방법 중 하나로 비율을 지정할 수 있습니다.

  • <Rate> 요소의 본문으로 지정하는 정적 비율
  • 클라이언트가 전달할 수 있는 변수 값입니다. ref 속성을 사용하여 흐름 변수의 이름을 식별합니다.
<PromptTokenLimit
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME"
>
  <Rate ref="FLOW_VARIABLE">RATE[pm|ps]</Rate>
</PromptTokenLimit>

유효한 비율 값(변수 값 또는 요소의 본문에 정의됨)은 다음 형식을 따라야 합니다.

  • intps (초당 토큰 수, 밀리초 간격으로 평활화)
  • intpm (분당 토큰 수, 초 간격으로 평활화)

int 값은 0이 아닌 양의 정수여야 합니다.

예 1

다음 예에서는 비율을 초당 토큰 5개로 설정합니다.

<PromptTokenLimit name="PTL-Static-5ps">
  <Rate>5ps</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>
        

이 정책은 200밀리초마다 허용되는 토큰 1개(1000/5)로 비율을 평활화합니다.

예 2

다음 예에서는 비율을 분당 토큰 12개로 설정합니다.

<PromptTokenLimit name="PTL-Static-12pm">
  <Rate>12pm</Rate>
  <UseEffectiveCount>false</UseEffectiveCount>
</PromptTokenLimit>

이 정책 예시는 5마다 허용되는 토큰 1개 (60/12)로 비율을 평활화합니다.

다음 표는 <Rate>의 속성을 설명합니다.

속성 설명 존재 여부 기본값
ref 비율을 지정하는 흐름 변수를 식별합니다. HTTP 쿼리 파라미터, 헤더 또는 메시지 본문 콘텐츠와 같은 흐름 변수 또는 KVM과 같은 값이 될 수 있습니다. 자세한 내용은 흐름 변수 참조를 확인하세요.

JavaScript 정책 또는 AssignMessage 정책을 사용하여 커스텀 변수를 사용할 수도 있습니다.

ref 이 요소의 본문을 모두 정의하면 ref 값이 적용되고 요청에서 흐름 변수가 설정될 때 우선 적용됩니다. (ref에서 식별된 변수가 요청에 설정되지 않은 반대의 경우에도 마찬가지입니다.)

예를 들면 다음과 같습니다.

<Rate ref="request.header.custom_rate">1pm</Rate>

이 예시에서 클라이언트가 custom_rate 헤더를 전달하지 않는 경우 API 프록시 비율은 모든 클라이언트에 대해 분당 토큰 1개입니다. 클라이언트가 값이 10ps인 custom_rate 헤더를 전달하면 custom_rate 헤더가 없는 요청이 전송될 때까지 프록시의 모든 클라이언트에 대해 비율 제한은 초당 요청 10개로 됩니다.

<Identifier>를 사용하여 요청을 그룹화하면 다양한 유형의 클라이언트에 커스텀 비율을 적용할 수 있습니다.

ref에 값을 지정하지만 <Rate> 요소의 본문에 비율을 설정하지 않고 클라이언트가 값을 전달하지 않는 경우 PromptTokenLimit 정책이 오류를 일으킵니다.

선택사항 해당 사항 없음
다음 표에서는 트래픽 제한 동작을 정의하는 Rate의 속성에 대해 설명합니다.
속성 설명
messagesPerPeriod 정의된 기간 내에 허용되는 토큰 수를 지정합니다. 예를 들어 정책이 '10ps' (초당 토큰 10개)로 구성된 경우 messagesPerPeriod 값은 10이 됩니다.
periodInMicroseconds messagesPerPeriod가 계산되는 기간(마이크로초)을 정의합니다. '10ps' 구성의 경우 이 값은 1,000,000이 되며 이는 1초에 해당합니다.
maxBurstMessageCount 새 간격 시작 시 즉시 또는 짧은 시간 동안 허용될 수 있는 최대 토큰 수를 나타냅니다.

<UseEffectiveCount>

이 요소를 사용하면 아래 설명된 대로 값을 true 또는 false로 설정하여 개별 PromptTokenLimit 알고리즘 간에 선택할 수 있습니다.

true

true로 설정하면 PromptTokenLimit가 리전에 배포됩니다. 즉, 요청 수가 한 리전의 메시지 프로세서(MP) 간에 동기화됩니다. 또한 '슬라이딩 창' 비율 제한 알고리즘이 적용됩니다. 이 알고리즘은 일관적인 비율 제한 동작을 제공하며 백엔드로 전송될 수 있는 수신 요청 수를 '평활화'하지 않습니다. 요청 급증이 짧은 간격으로 전송되면 <Rate> 요소에 설정된 대로 구성된 비율 제한을 초과하지 않는 한 허용됩니다. 예를 들면 다음과 같습니다.

<PromptTokenLimit name="Prompt-Token-Limit-1">
  <Rate>12pm</Rate>
  <Identifier ref="client_id" />
  <UseEffectiveCount>true</UseEffectiveCount>
</PromptTokenLimit>

false(기본값)

false (기본값)로 설정된 경우 PromptTokenLimit 정책은 지정된 비율 제한을 더 작은 간격으로 나눠서 토큰 급증을 평활화하는 '토큰 버킷' 알고리즘을 사용합니다. 이 접근 방식의 단점은 짧은 기간 동안 수신되는 여러 적법한 토큰이 잠재적으로 거부될 수 있다는 것입니다.

예를 들어, 30pm (분당 토큰 30개)의 비율을 입력한다고 가정하겠습니다. 테스트에서 토큰이 1분 내에 들어오는 한 1초에 30개의 토큰을 보낼 수 있다고 생각할 수 있습니다. 하지만 정책은 다른 방식으로 설정을 적용합니다. 생각해보면 1초 내 토큰 30개는 일부 환경에서 작은 급증으로 간주될 수 있습니다.

  • 분당 비율은 간격으로 허용되는 전체 요청으로 평활화됩니다.

    예를 들어 30pm은 다음과 같이 평활화됩니다.
    60초 (1분)/30pm = 2초 간격, 또는 2초마다 허용되는 토큰 1개. 2초 이내의 두 번째 토큰은 실패합니다. 또한 1분 이내의 31번째 토큰도 실패합니다.

  • 초당 비율은 밀리초 간격으로 허용되는 전체 요청으로 평활화됩니다.

    예를 들어 10ps는 다음과 같이 평활화됩니다.
    1000밀리초 (1초) / 10ps = 100밀리초 간격, 100밀리초마다 허용되는 토큰 1개. 100밀리초 이내의 두 번째 토큰은 실패합니다. 또한 1초 이내의 11번째 토큰도 실패합니다.

기본값 거짓
필수 여부 선택사항
유형 불리언
상위 요소 <PromptTokenLimit>
하위 요소 없음

다음 표에서는 <UseEffectiveCount> 요소의 속성을 설명합니다.

속성 설명 기본값 존재 여부
ref <UseEffectiveCount> 값이 포함된 변수를 식별합니다. HTTP 쿼리 파라미터, 헤더, 메시지 본문 콘텐츠와 같은 흐름 변수가 될 수 있습니다. 자세한 내용은 흐름 변수 참조를 확인하세요. JavaScript 정책 또는 AssignMessage 정책을 사용하여 커스텀 변수를 설정할 수도 있습니다. 해당 사항 없음 선택사항

<UserPromptSource>

사용자 프롬프트 텍스트를 가져오는 소스를 제공합니다. 메시지 템플릿을 사용합니다.

메시지 템플릿은 사용자 프롬프트 텍스트의 단일 값을 제공해야 합니다.

예를 들면 {jsonPath('$.contents[-1].parts[-1].text',request.content,true)}입니다.

기본값 해당 사항 없음
필수 여부 선택사항
유형 문자열
상위 요소 <PromptTokenLimit>
하위 요소 없음

구문

<PromptTokenLimit
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME">
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
</PromptTokenLimit>

예 1

<PromptTokenLimit name="Prompt-Token-Limit-1">
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
</PromptTokenLimit>

<IgnoreUnresolvedVariables>

해결되지 않은 변수가 발생하면 처리를 중지할지 여부를 결정합니다.

확인되지 않은 변수를 무시하고 계속 처리하려면 true로 설정합니다. 그렇지 않으면 false로 설정합니다. 기본값은 false입니다.

기본값 거짓
필수 여부 선택사항
유형 불리언
상위 요소 <PromptTokenLimit>
하위 요소 없음

구문

<PromptTokenLimit
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME">
  <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>
</PromptTokenLimit>

예시

<PromptTokenLimit name="Prompt-Token-Limit-1">
  <Rate>10ps</Rate>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</PromptTokenLimit>

흐름 변수

PromptTokenLimit 정책이 실행되면 다음과 같은 흐름 변수가 채워집니다.

변수 유형 권한 설명
ratelimit.POLICY_NAME.failed 불리언 읽기 전용 정책이 실패했는지 여부를 나타냅니다(true 또는 false).
ratelimit.POLICY_NAME.resolvedUserPrompt 문자열 읽기 전용 추출된 사용자 프롬프트를 반환합니다.
ratelimit.POLICY_NAME.userPromptSource 문자열 읽기 전용 정책에 지정된 사용자 프롬프트의 메시지 템플릿을 반환합니다.
ratelimit.POLICY_NAME.userPromptTokenCount 문자열 읽기 전용 추출된 사용자 프롬프트의 토큰 수를 반환합니다.

자세한 내용은 흐름 변수 참조를 확인하세요.

오류 참조

이 섹션에서는 반환되는 오류 코드 및 오류 메시지와 이 정책이 오류를 트리거할 때 Apigee에서 설정한 오류 변수를 설명합니다. SpikeArrest 정책 오류가 표시될 수도 있습니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 오류 처리를 참고하세요.

런타임 오류

이러한 오류는 정책이 실행될 때 발생할 수 있습니다.

오류 코드 HTTP 상태 Apigee 오류 원인 수정
policies.prompttokenlimit.FailedToExtractUserPrompt 400 FALSE API 요청에서 사용자 프롬프트를 추출할 수 없습니다.
policies.prompttokenlimit.PromptTokenLimitViolation 429 FALSE PromptTokenLimit 위반입니다.
policies.prompttokenlimit.FailedToCalculateUserPromptTokens 500 TRUE 사용자 프롬프트의 토큰은 계산할 수 없습니다.

배포 오류

이 오류는 이 정책이 포함된 프록시를 배포할 때 발생할 수 있습니다.

오류 코드 HTTP 상태 Apigee 오류 원인 수정
policies.prompttokenlimit.MessageWeightNotSupported 500 FALSE MessageWeight는 PromptTokenLimit 정책에서 지원되지 않습니다.

오류 변수

이러한 변수는 런타임 오류가 발생하면 설정됩니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항을 참고하세요.

변수 설명
ratelimit.policy_name.fault.name fault_name은 위의 런타임 오류 표에 나열된 오류 이름입니다. 오류 이름은 오류 코드의 마지막 부분입니다. fault.name Matches "PromptTokenLimitViolation"
ratelimit.policy_name.failed policy_name은 오류를 발생시킨 정책의 사용자 지정 이름입니다. ratelimit.PTL-PromptTokenLimitPolicy.failed = true

오류 응답 예시

다음은 오류 응답의 예시입니다.

{  
   "fault":{  
      "detail":{  
         "errorcode":"policies.prompttokenlimit.PromptTokenLimitViolation"
      },
      "faultstring":"Prompt Token Limit Violation. Allowed rate : MessageRate{capacity=10, period=Minutes}"
   }
}

오류 규칙 예시

다음은 PromptTokenLimitViolation 오류를 처리하기 위한 오류 규칙의 예시입니다.

<FaultRules>
    <FaultRule name="Prompt Token Limit Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "PromptTokenLimitViolation") </Condition>
        </Step>
        <Condition>ratelimit.PTL-1.failed=true</Condition>
    </FaultRule>
</FaultRules>

LLMTokenQuota 또는 PromptTokenLimit 정책이 설정한 비율 제한을 초과하는 현재 HTTP 상태 코드는 429 (너무 많은 요청)입니다.

스키마

각 정책 유형은 XML 스키마(.xsd)로 정의됩니다. 참고로 GitHub에서 정책 스키마를 사용할 수 있습니다.

관련 주제