SemanticCacheLookup 정책

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

Apigee Edge 문서 보기

개요

SemanticCacheLookup 정책은 AI 워크로드, 특히 대규모 언어 모델(LLM)과 관련된 워크로드의 성능을 최적화하도록 설계된 고급 캐싱 정책입니다.

이 정책은 Vertex AI Text Embeds API를 사용하여 텍스트용 임베딩을 생성하고 벡터 검색을 사용하여 정확한 일치가 아닌 시맨틱 유사성을 기반으로 유사한 프롬프트를 찾습니다.

SemanticCacheLookup 정책을 사용하면 반복 쿼리의 응답 시간을 줄이고 LLM에 대한 통화 볼륨을 줄여 비용을 최적화할 수 있습니다.

이 정책은 SemanticCachePopulate 정책과 함께 사용됩니다.

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

시작하기 전에

SemanticCacheLookup 정책을 사용하려면 먼저 다음 작업을 완료해야 합니다.

• Vertex AI 프로젝트를 만듭니다.
• 벡터 검색 색인을 만듭니다.
• 색인의 Vertex AI 엔드포인트를 만듭니다.
• SemanticCachePopulate 정책을 만듭니다.

이러한 작업을 완료하는 방법에 대한 자세한 내용은 시맨틱 캐싱 정책 시작하기를 참고하세요.

필요한 역할

SemanticCacheLookup 정책을 적용하고 사용하는 데 필요한 권한을 얻으려면 관리자에게 Apigee 프록시를 배포하는 데 사용하는 서비스 계정에 대한 AI Platform 사용자(roles/aiplatform.user) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

API 사용 설정

Enable the Compute Engine, Vertex AI, and Cloud Storage APIs.

Enable the APIs

<SemanticCacheLookup> 요소

SemanticCacheLookup 정책을 정의합니다.

<SemanticCacheLookup> 요소는 다음 구문을 사용합니다.

<SemanticCacheLookup async="false" continueOnError="false" enabled="true" name="SCL-lookup">
  <DisplayName>SCL-lookup</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UserPromptSource>{jsonPath($.contents[-1].parts[-1].text,request.content,true)}</UserPromptSource>
  <Embeddings>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
    </VertexAI>
  </Embeddings>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
      <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
      <Threshold>0.95</Threshold>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

<SemanticCacheLookup async="false" continueOnError="false"enabled="true" name="SCL-lookup">
  <DisplayName>SCL-lookup</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UserPromptSource>{jsonPath($.contents[-1].parts[-1].text,request.content,true)}</UserPromptSource>
  <Embeddings>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict
      </URL>
    </VertexAI>
  </Embeddings>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
      <Threshold>0.9</Threshold>
      <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

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

다음 표에서는 <SemanticCacheLookup>의 하위 요소에 대한 대략적인 설명을 제공합니다.

{jsonPath($.contents[-1].parts[-1].text,request.content,true)}

하위 요소 참조

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

<DisplayName>

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

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

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

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

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

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

<IgnoreUnresolvedVariables>

변수가 확인되지 않은 경우 처리를 중지할지 여부를 결정합니다. 확인되지 않은 변수를 무시하고 계속 처리하려면 true로 설정합니다.

<DefaultValue>가 제공된 경우 IgnoreUnresolvedVariables를 적용할 수 없습니다.

<UserPromptSource>

추출할 사용자 메시지 텍스트의 페이로드 위치입니다. 문자열 텍스트 값만 지원됩니다.

이 필드는 변수 또는 JSON 경로 함수 사용을 비롯한 Apigee 메시지 템플릿 구문을 지원합니다.

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

{jsonPath($.contents[-1].parts[-1].text,request.content,true)}

<Embeddings>

이 요소는 텍스트 임베딩을 생성하는 데 필요한 정보를 포함합니다.

<Embeddings> 요소는 다음 구문을 사용합니다.

<Embeddings>
  <VertexAI>
    <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
  </VertexAI>
</Embeddings>

<VertexAI>(<Embeddings>의 하위 요소)

Vertex AI 관련 속성의 <URL> 요소를 포함합니다.

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

<VertexAI>
  <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
</VertexAI>

<URL>(<VertexAI>의 하위 요소)

텍스트 임베딩을 생성하는 데 사용되는 URL입니다. SemanticCacheLookup 정책에 텍스트 임베딩을 제공할 수 있는 모델 목록은 지원되는 모델을 참고하세요.

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

<URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>

<SimilaritySearch>

이 요소에는 유사성 검색을 실행하는 데 필요한 정보가 포함되어 있습니다.

자세한 내용은 공개 색인을 쿼리하여 최근접 이웃 가져오기를 참고하세요.

<SimilaritySearch> 요소는 다음 구문을 사용합니다.

<SimilaritySearch>
  <VertexAI>
    <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors
    </URL>
    <Threshold>0.9</Threshold>
    <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
  </VertexAI>
</SimilaritySearch>

<VertexAI>(<SimilaritySearch>의 하위 요소)

Vertex AI 관련 속성의 <URL> 요소를 포함합니다.

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

<VertexAI>
  <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
  <Threshold>0.9</Threshold>
  <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
</VertexAI>

다음 표에서는 <VertexAI>의 하위 요소에 대한 대략적인 설명을 제공합니다.

흐름 변수

흐름 변수를 사용하면 HTTP 헤더, 메시지 콘텐츠 또는 흐름에서 사용 가능한 컨텍스트를 기준으로 정책 및 흐름의 동적 런타임 동작을 구성할 수 있습니다. 흐름 변수에 대한 자세한 내용은 흐름 변수 참조를 확인하세요.

정책은 실행 중에 이러한 읽기 전용 변수를 설정할 수 있습니다.

오류 참조

이 섹션에서는 반환되는 오류 코드 및 오류 메시지와 <SemanticCacheLookup> 정책과 관련해서 Apigee에서 설정된 오류 변수에 대해 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.

런타임 오류

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

배포 오류

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

오류 변수

이러한 변수는 이 정책이 런타임 시 오류를 트리거할 때 설정됩니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항을 참조하세요.

오류 응답 예시

{
  "fault": {
    "faultstring": "SemanticCacheLookup[SC-lookup]: unable to resolve variable [variable_name]",
    "detail": {
      "errorcode": "steps.semanticcachelookup.UnresolvedVariable"
    }
  }
}

오류 규칙 예시

<FaultRule name="SemanticCacheLookup Faults">
    <Step>
        <Name>SCL-CustomSetVariableErrorResponse</Name>
        <Condition>(fault.name = "SetVariableFailed")</Condition>
    </Step>
    <Condition>(semanticcachelookup.failed = true)</Condition>
</FaultRule>

스키마

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