시맨틱 캐싱 정책 시작하기

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

Apigee Edge 문서 보기

이 페이지에서는 Apigee 시맨틱 캐싱 정책을 구성하고 사용하여 시맨틱 유사성을 기반으로 지능형 응답 재사용을 사용 설정하는 방법을 설명합니다. Apigee API 프록시에서 이러한 정책을 사용하면 중복 백엔드 API 호출을 최소화하고 지연 시간을 줄이며 운영 비용을 절감할 수 있습니다.

시작하기 전에

시작하기 전에 다음 작업을 완료해야 합니다.

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Compute Engine, AI Platform, and Cloud Storage APIs.

   Enable the APIs

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the Compute Engine, AI Platform, and Cloud Storage APIs.

   Enable the APIs

8. Google Cloud 프로젝트 내에서 Vertex AI 텍스트 임베딩 API 및 벡터 검색을 설정하고 구성합니다.
9. Apigee 인스턴스에서 포괄적 환경을 사용할 수 있는지 확인합니다. 시맨틱 캐싱 정책은 포괄적 환경에만 배포할 수 있습니다.

필요한 역할

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

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

환경 변수 설정하기

Apigee 인스턴스가 포함된 Google Cloud 프로젝트에서 다음 명령어를 사용하여 환경 변수를 설정합니다.

export PROJECT_ID=PROJECT_ID
export REGION=REGION
export RUNTIME_HOSTNAME=RUNTIME_HOSTNAME

각 항목의 의미는 다음과 같습니다.

• PROJECT_ID는 Apigee 인스턴스가 있는 프로젝트의 ID입니다.
• REGION은 Apigee 인스턴스의 Google Cloud 리전입니다.
• RUNTIME_HOSTNAME은 Apigee 런타임의 호스트 이름입니다.

환경 변수가 올바르게 설정되었는지 확인하려면 다음 명령어를 실행하고 출력을 검토합니다.

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

프로젝트 설정

개발 환경에서 Google Cloud 프로젝트를 설정합니다.

    gcloud auth login
    gcloud config set project $PROJECT_ID

개요

시맨틱 캐싱 정책은 LLM 모델을 사용하는 Apigee 사용자가 동일하거나 의미적으로 유사한 프롬프트를 효율적으로 제공하여 백엔드 API 호출을 최소화하고 리소스 소비를 줄일 수 있도록 설계되었습니다.

SemanticCacheLookup 및 SemanticCachePopulate 정책은 Apigee API 프록시의 요청 흐름과 응답 흐름에 각각 연결됩니다. 프록시가 요청을 수신하면 SemanticCacheLookup 정책이 요청에서 사용자 프롬프트를 추출하고 Text embeddings API를 사용하여 프롬프트를 숫자로 변환합니다. 벡터 검색을 사용하여 유사한 프롬프트를 찾는 시맨틱 유사성 검색이 실행됩니다. 유사한 프롬프트 데이터 포인트가 발견되면 캐시 조회가 실행됩니다. 캐시된 데이터가 있으면 캐시된 응답이 클라이언트로 반환됩니다.

유사성 검색에서 유사한 이전 프롬프트를 반환하지 않으면 LLM 모델이 사용자 프롬프트에 대한 응답으로 콘텐츠를 생성하고 Apigee 캐시가 응답으로 채워집니다. 향후 요청에 대비하여 벡터 검색 색인 항목을 업데이트하기 위한 피드백 루프가 생성됩니다.

다음 섹션에서는 시맨틱 캐싱 정책을 만들고 구성하는 데 필요한 단계를 설명합니다.

1. 벡터 검색 색인의 서비스 계정을 구성합니다.
2. 벡터 검색 색인을 만들고 배포합니다.
3. API 프록시를 만들어 시맨틱 캐싱을 사용 설정합니다.
4. 시맨틱 캐싱 정책을 구성합니다.
5. 시맨틱 캐싱 정책을 테스트합니다.

벡터 검색 색인의 서비스 계정 구성

벡터 검색 색인의 서비스 계정을 구성하려면 다음 단계를 완료하세요.

1. 다음 명령어를 사용하여 서비스 계정을 만듭니다.

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --description="DESCRIPTION" \
     --display-name="SERVICE_ACCOUNT_DISPLAY_NAME"

   각 항목의 의미는 다음과 같습니다.

   • SERVICE_ACCOUNT_NAME은 서비스 계정의 이름입니다.
   • DESCRIPTION은 서비스 계정에 대한 설명입니다.
   • SERVICE_ACCOUNT_DISPLAY_NAME은 서비스 계정의 표시 이름입니다.

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

   gcloud iam service-accounts create ai-client \
     --description="semantic cache client" \
     --display-name="ai-client"

2. 다음 명령어를 사용하여 서비스 계정에 AI Platform User 역할을 부여합니다.

   gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" \
     --role="roles/aiplatform.user"

   여기서 SERVICE_ACCOUNT_NAME은 이전 단계에서 만든 서비스 계정의 이름입니다.

3. 다음 명령어를 사용하여 서비스 계정에 IAM Service Account User 역할을 할당합니다.

   gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" \
     --role="roles/iam.serviceAccountUser"

   여기서 SERVICE_ACCOUNT_NAME은 이전 단계에서 만든 서비스 계정의 이름입니다.

벡터 검색 색인 만들기 및 배포

벡터 검색 색인을 만들고 배포하려면 다음 단계를 따르세요.

1. 스트리밍 업데이트를 허용하는 벡터 검색 색인을 만듭니다.

   ACCESS_TOKEN=$(gcloud auth print-access-token) && curl --location --request POST \
     "https://$REGION-aiplatform.googleapis.com/v1/projects/$PROJECT_ID/locations/$REGION/indexes" \
       --header "Authorization: Bearer $ACCESS_TOKEN" \
       --header 'Content-Type: application/json' \
       --data-raw \
       '{
         "displayName": "semantic-cache-index",
         "description": "semantic-cache-index",
         "metadata": {
           "config": {
             "dimensions": "768",
             "approximateNeighborsCount": 150,
             "distanceMeasureType": "DOT_PRODUCT_DISTANCE",
             "featureNormType": "NONE",
             "algorithmConfig": {
               "treeAhConfig": {
                 "leafNodeEmbeddingCount": "10000",
                 "fractionLeafNodesToSearch": 0.05
                 }
               },
             "shardSize": "SHARD_SIZE_MEDIUM"
             },
           },
         "indexUpdateMethod": "STREAM_UPDATE"
       }'

   $REGION은 벡터 검색 색인이 배포되는 리전을 정의합니다. Apigee 인스턴스와 동일한 리전을 사용하는 것이 좋습니다. 이 환경 변수는 이전 단계에서 설정되었습니다.

   이 작업이 완료되면 다음과 유사한 응답이 표시됩니다.

   {
     "name": "projects/976063410430/locations/us-west1/indexes/5695338290484346880/operations/9084564741162008576",
     "metadata": {
       "@type": "type.googleapis.com/google.cloud.aiplatform.v1.CreateIndexOperationMetadata",
       "genericMetadata": {
         "createTime": "2025-04-25T18:45:27.996136Z",
         "updateTime": "2025-04-25T18:45:27.996136Z"
       }
     }
   }

   벡터 검색 색인 만들기에 관한 자세한 내용은 색인 만들기를 참고하세요.

2. 다음 명령어를 사용하여 IndexEndpoint를 만듭니다.

   gcloud ai index-endpoints create \
     --display-name=semantic-cache-index-endpoint \
     --public-endpoint-enabled \
     --region=$REGION \
     --project=$PROJECT_ID

   이 단계를 완료하는 데 몇 분 정도 걸릴 수 있습니다. 완료되면 다음과 유사한 응답이 표시됩니다.

   Waiting for operation [8278420407862689792]...done.
     Created Vertex AI index endpoint: projects/976063410430/locations/us-west1/indexEndpoints/7953875911424606208.

   IndexEndpoint 만들기에 관한 자세한 내용은 IndexEndpoint 만들기를 참고하세요.

3. 다음 명령어를 사용하여 색인을 엔드포인트에 배포합니다.

   INDEX_ENDPOINT_ID=$(gcloud ai index-endpoints list \
     --project=$PROJECT_ID \
     --region=$REGION \
     --format="json" | jq -c -r \
     '.[] | select(.displayName=="semantic-cache-index-endpoint") | .name | split("/") | .[5]' \
     ) && INDEX_ID=$(gcloud ai indexes list \
     --project=$PROJECT_ID \
     --region=$REGION \
     --format="json" | jq -c -r \
     '.[] | select(.displayName=="semantic-cache-index") | .name | split("/") | .[5]' \
     ) && gcloud ai index-endpoints deploy-index \
     $INDEX_ENDPOINT_ID \
     --deployed-index-id=semantic_cache \
     --display-name=semantic-cache \
     --index=$INDEX_ID \
     --region=$REGION \
     --project=$PROJECT_ID

색인을 엔드포인트에 처음 배포하는 데 20~30분 정도 걸릴 수 있습니다. 작업 상태를 확인하려면 다음 명령어를 사용합니다.

gcloud ai operations describe OPERATION_ID \
  --project=$PROJECT_ID \
  --region=$REGION

색인이 배포되었는지 확인합니다.

gcloud ai operations describe OPERATION_ID \
  --index-endpoint=$INDEX_ENDPOINT_ID --region=$REGION --project=$PROJECT_ID

이 명령어는 $ done: true를 반환해야 합니다.

API 프록시를 만들어 시맨틱 캐싱 사용 설정

이 단계에서는 아직 만들지 않은 경우 Proxy with Semantic Cache 템플릿을 사용하여 새 API 프록시를 만듭니다.

API 프록시를 만들기 전에 다음 환경 변수를 설정합니다.

export PUBLIC_DOMAIN_NAME=$(gcloud ai index-endpoints describe $INDEX_ENDPOINT_ID --region=$REGION --project=$PROJECT_ID | grep "publicEndpointDomainName" | awk '{print $2}')

시맨틱 캐싱과 함께 사용할 프록시를 만들려면 다음 단계를 따르세요.

1. Google Cloud Console에서 API 프록시 페이지로 이동합니다.

   API 프록시로 이동

2. + 만들기를 클릭하여 API 프록시 만들기 창을 엽니다.
3. 프록시 템플릿 상자에서 시맨틱 캐시가 있는 프록시를 선택합니다.
4. 다음 세부정보를 입력합니다.
   • 프록시 이름: 프록시 이름을 입력합니다.
   • 설명: (선택사항) 프록시에 대한 설명을 입력합니다.
   • 타겟 (기존 API): 프록시가 호출하는 백엔드 서비스의 URL을 입력합니다. 콘텐츠를 생성하는 데 사용되는 LLM 모델 엔드포인트입니다.

     이 튜토리얼에서는 타겟 (기존 API)을 다음과 같이 설정할 수 있습니다.

     REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.0-flash-001:generateContent

5. 다음 시맨틱 캐시 URL을 입력합니다.
   • Generate Embeddings URL: 이 Vertex AI 서비스는 시맨틱 분석을 위해 텍스트 입력을 숫자 형식으로 변환합니다.

     이 튜토리얼에서는 이 URL을 다음과 같이 설정할 수 있습니다.

     REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/text-embedding-004:predict

   • 최근접 이웃 쿼리 URL: 이 Vertex AI 서비스는 벡터 검색 색인에서 이전 요청의 유사한 텍스트 입력을 검색하여 재처리를 방지합니다.

     이 튜토리얼에서는 이 URL을 다음과 같이 설정할 수 있습니다.

     PUBLIC_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/REGION/indexEndpoints/INDEX_ENDPOINT_ID:findNeighbors

     PUBLIC_DOMAIN_NAME 및 INDEX_ENDPOINT_ID 값은 이전 단계에서 설정했습니다. 이러한 값을 가져오려면 다음 명령어를 사용하면 됩니다.

       echo $PUBLIC_DOMAIN_NAME
       echo $INDEX_ENDPOINT_ID

   • 업서트 색인 URL: 이 Vertex AI 서비스는 색인을 새 항목 또는 수정된 항목으로 업데이트합니다.

     이 튜토리얼에서는 이 URL을 다음과 같이 설정할 수 있습니다.

     REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/indexes/INDEX_ID:upsertDatapoints

6. 다음을 클릭합니다.
7. 만들기를 클릭합니다.

API 프록시의 XML 구성은 Develop 탭에서 확인할 수 있습니다. 기본값이 포함된 SemanticCacheLookup 및 SemanticCachePopulate 정책은 이미 프록시 요청 및 응답 흐름에 연결되어 있습니다.

시맨틱 캐싱 정책 구성

API 프록시의 Develop 탭에 있는 Detail 보기에서 정책 이름을 클릭하면 각 정책의 XML 구성을 볼 수 있습니다. 정책 XML은 개발 탭의 코드 보기에서 직접 수정할 수 있습니다.

정책을 수정합니다.

• SemanticCacheLookup 정책:
  • 기본값을 사용하려면 <UserPromptSource> 요소를 삭제합니다.
  • semantic_cache 값을 사용하도록 <DeployedIndexId> 요소를 업데이트합니다.
  • 두 프롬프트가 일치하는 것으로 간주되는 시점을 결정하기 위해 의미론적 유사도 <Threshold> 값을 구성합니다. 기본값은 0.9이지만 애플리케이션의 민감도에 따라 이 값을 조정할 수 있습니다. 숫자가 클수록 캐시 적중으로 간주되려면 프롬프트가 더 밀접하게 관련되어야 합니다. 이 튜토리얼에서는 이 값을 0.95로 설정하는 것이 좋습니다.
  • 저장을 클릭합니다.
• SemanticCachePopulate 정책:
  • <TTLInSeconds> 요소를 설정하여 캐시가 만료될 때까지의 시간(초)을 지정합니다. 기본값은 60초입니다. Apigee는 LLM 모델에서 수신하는 모든 cache-control 헤더를 무시합니다.
  • 저장을 클릭합니다.

API 프록시에 Google 인증 추가

또한 대상에 대한 프록시 호출을 사용 설정하려면 API 프록시의 대상 엔드포인트에 Google 인증을 추가해야 합니다.

Google 액세스 토큰을 추가하려면 다음 단계를 따르세요.

1. 개발 탭의 대상 엔드포인트 폴더에서 기본값을 클릭합니다. 코드 뷰에는 <TargetEndpoint> 요소의 XML 구성이 표시됩니다.
2. XML을 수정하여 <HTTPTargetConnection> 아래에 다음 구성을 추가합니다.

   <Authentication>
     <GoogleAccessToken>
       <Scopes>
         <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
       </Scopes>
     </GoogleAccessToken>
   </Authentication>

3. 저장을 클릭합니다.

API 프록시 배포

API 프록시를 배포하려면 다음 안내를 따르세요.

1. 배포를 클릭하여 API 프록시 배포 창을 엽니다.
2. 버전 필드는 1로 설정해야 합니다. 선택되어 있지 않으면 1을 클릭하여 선택합니다.
3. 환경 목록에서 프록시를 배포할 환경을 선택합니다. 환경은 포괄적 환경이어야 합니다.
4. 이전 단계에서 만든 서비스 계정을 입력합니다.
5. 배포를 클릭합니다.

시맨틱 캐싱 정책 테스트

시맨틱 캐싱 정책을 테스트하려면 다음 단계를 따르세요.

1. 다음 명령어를 사용하여 프록시에 요청을 전송합니다.

   curl https://$RUNTIME_HOSTNAME/PROXY_NAME -H 'Content-Type: application/json' --data '{
     "contents": [
         {
             "role": "user",
             "parts": [
                 {
                     "text": "Why is the sky blue?"
                 }
             ]
         }
     ]
   }'

   여기서 PROXY_NAME은 이전 단계에서 배포한 API 프록시의 기본 경로입니다.

프롬프트 문자열을 의미상 유사한 다음 프롬프트 문자열로 대체하여 API 호출을 반복합니다.
• 하늘은 왜 파랗지?
• 하늘은 왜 파란색인가요?
• 하늘은 왜 파란색인가요?
• 하늘이 파란 이유를 설명해 줄 수 있어?
• 하늘은 왜 파란색인가요?
2. 유사한 메시지가 캐시된 후 각 호출의 응답 시간을 비교합니다.

호출이 캐시에서 제공되고 있는지 확인하려면 응답 헤더를 확인하세요. Cached-Content: true 헤더가 첨부되어야 합니다.

권장사항

시맨틱 캐싱 정책을 사용할 때는 API 관리 프로그램에 다음 권장사항을 통합하는 것이 좋습니다.

• Model Armor로 민감한 정보의 캐싱을 방지합니다.

  민감한 정보가 캐시되지 않도록 하려면 콘텐츠 필터링에 Model Armor를 사용하는 것이 좋습니다. Model Armor는 민감한 정보를 감지하면 응답을 캐시 불가능한 것으로 표시할 수 있습니다. 자세한 내용은 Model Armor 개요를 참고하세요.

• Vertex AI 데이터 포인트 무효화 및 TTL (수명)로 데이터 업데이트 상태를 관리합니다.

  캐시된 응답이 최신 상태이고 백엔드 시스템의 최신 정보를 반영하도록 적절한 데이터 포인트 무효화 전략을 구현하는 것이 좋습니다. 자세한 내용은 활성 색인 업데이트 및 재빌드를 참고하세요.

  데이터의 변동성과 업데이트 빈도에 따라 캐시된 응답의 TTL을 조정할 수도 있습니다. SemanticCachePopulate 정책에서 TTL을 사용하는 방법에 관한 자세한 내용은 <TTLInSeconds>를 참고하세요.

• 사전 정의된 캐싱 전략을 사용하여 가장 정확한 응답 데이터를 보장합니다.

  다음과 유사한 사전 정의된 캐싱 전략을 구현하는 것이 좋습니다.

  • 일반 AI 응답: 사용자별 응답이 아닌 경우 긴 TTL (예: 1시간)을 구성합니다.
  • 사용자별 응답: 캐싱을 구현하지 않거나 사용자별 정보가 포함된 응답에 짧은 TTL (예: 5분)을 설정합니다.
  • 시간에 민감한 응답: 실시간 또는 빈번한 업데이트가 필요한 응답에는 짧은 TTL (예: 5분)을 구성합니다.

제한사항

시맨틱 캐싱 정책에는 다음과 같은 제한사항이 적용됩니다.

• 캐시 가능한 최대 텍스트 크기는 256KB입니다. 자세한 내용은 Apigee 제한사항 페이지의 캐시 값 크기를 참고하세요.
• Apigee는 LLM 모델에서 수신하는 모든 cache-control 헤더를 무시합니다.
• 캐시가 제대로 무효화되지 않거나 의미 유사 알고리즘이 매우 유사한 의미의 입력을 구분하기에 충분히 정확하지 않으면 응답이 오래되었거나 잘못된 정보를 반환할 수 있습니다.
• 일부 지역에서는 벡터 검색 기능이 지원되지 않습니다. 지원되는 리전 목록은 Vertex AI 위치 페이지의 기능 가용성 섹션을 참고하세요. Apigee 조직이 지원되지 않는 지역에 있는 경우 Apigee 조직과 다른 리전에 색인 엔드포인트를 만들어야 합니다.
• 서버 전송 이벤트 (SSE)의 연속 응답 스트리밍을 위해 EventFlows를 사용하는 API 프록시에는 시맨틱 캐싱 정책이 지원되지 않습니다.
• <UserPromptSource> 내의 JsonPath 함수가 ignoreUnresolvedVariables 기능을 지원하지 않습니다. 기본적으로 null 또는 빈 값은 메시지 템플릿 적용 중에 무시됩니다.

다음 단계

Model Armor 정책을 시작하는 방법을 알아보세요.