SemanticCachePopulate 정책

개요

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

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

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

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

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

시작하기 전에

SemanticCachePopulate 정책을 사용하기 전에 다음 작업을 완료해야 합니다.

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

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

역할 및 권한

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

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

API 사용 설정

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

Enable the APIs

<SemanticCachePopulate> 요소

SemanticCachePopulate 정책을 정의합니다.

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

<SemanticCachePopulate async="false" continueOnError="false"enabled="true" name="SCP-populate">
  <DisplayName>SCP-populate</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
    </VertexAI>
  </SimilaritySearch>
  <TTLInSeconds>{EXPIRATION_TIME_IN_SECONDS}</TTLInSeconds>
</SemanticCachePopulate>

<SemanticCachePopulate async="false" continueOnError="false"enabled="true" name="SCP-populate">
  <DisplayName>SCP-populate</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
    </VertexAI>
  </SimilaritySearch>
  <TTLInSeconds>60</TTLInSeconds>
</SemanticCachePopulate>

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

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

예

이 섹션에서는 <SemanticCachePopulate>를 사용하는 예시를 제공합니다.

<SemanticCachePopulate async="false" continueOnError="false"enabled="true" name="SCP-populate">
  <DisplayName>SCP-populate</DisplayName>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
    </VertexAI>
  </SimilaritySearch>
  <TTLInSeconds>60</TTLInSeconds>
</SemanticCachePopulate>

하위 요소 참조

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

<DisplayName>

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

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

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

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

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

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

<IgnoreUnresolvedVariables>

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

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

<SimilaritySearch>

벡터 색인을 업데이트하는 데 필요한 정보가 포함된 요소입니다.

자세한 내용은 데이터 포인트 upsert를 참고하세요.

데이터 포인트의 만료 시간은 입력 시간으로부터 <TTLInSeconds>입니다.

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

<SimilaritySearch>
  <VertexAI>
    <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
  </VertexAI>
</SimilaritySearch>

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

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

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

<VertexAI>
  <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>
</VertexAI>

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

벡터 색인에 데이터 포인트를 업서트하는 데 사용되는 URL입니다.

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

<URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexes/{INDEX_ID}:upsertDatapoints</URL>

<TTLInSeconds>

캐시된 응답의 TTL (수명)을 초 단위로 지정하는 요소입니다. 기본값은 60입니다.

자세한 내용은 활성 색인 업데이트 및 다시 빌드를 참고하세요.

흐름 변수

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

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

오류 참조

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

런타임 오류

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

배포 오류

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

오류 변수

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

오류 응답 예시

{
"fault": {
  "faultstring": "SemanticCacheLookup[SC-populate]: unable to resolve variable [variable_name]",
  "detail": {
    "errorcode": "steps.semanticcachepopulate.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에서 정책 스키마를 사용할 수 있습니다.