시맨틱 캐싱 정책 시작하기

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

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

시작하기 전에

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

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.

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

Go to project selector

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

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

Enable the APIs

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

Go to project selector

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

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

Enable the APIs

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

필요한 역할

시맨틱 캐싱 정책을 만들고 사용하는 데 필요한 권한을 얻으려면 Apigee 프록시 배포에 사용하는 서비스 계정에 대한 AI 플랫폼 사용자 (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

개요

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

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

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

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

벡터 검색 색인의 서비스 계정 구성하기
벡터 검색 색인 만들기 및 배포
시맨틱 캐싱을 사용 설정하는 API 프록시 만들기
시맨틱 캐싱 정책 구성하기
시맨틱 캐싱 정책 테스트

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

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

다음 명령어를 사용하여 서비스 계정을 만듭니다.
```
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"
```
다음 명령어를 사용하여 서비스 계정에 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은 이전 단계에서 만든 서비스 계정의 이름입니다.
다음 명령어를 사용하여 서비스 계정에 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은 이전 단계에서 만든 서비스 계정의 이름입니다.

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

벡터 검색 색인을 만들어 배포하려면

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

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"
    }
  }
}

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

다음 명령어를 사용하여 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 만들기를 참고하세요.

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

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

참고: 색인을 엔드포인트에 배포하는 명령어에는 jq가 필요합니다. 이 JSON 처리 유틸리티가 개발 환경에 아직 설치되어 있지 않은 경우 다음 명령어를 사용하여 설치할 수 있습니다. $ sudo apt install jq.

색인을 엔드포인트에 처음 배포하는 데 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 프록시 만들기

이 단계에서는 (아직 만들지 않은 경우) 시맨틱 캐시가 있는 프록시 템플릿을 사용하여 새 API 프록시를 만듭니다.

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

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

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

Google Cloud 콘솔의 API 프록시 페이지로 이동합니다.
API 프록시로 이동
+ 만들기를 클릭하여 API 프록시 만들기 창을 엽니다.
프록시 템플릿 상자에서 시맨틱 캐시가 있는 프록시를 선택합니다.
다음 세부정보를 입력합니다.
- 프록시 이름: 프록시 이름을 입력합니다.
- 설명: (선택사항) 프록시에 대한 설명을 입력합니다.
- 대상(기존 API): 프록시가 호출하는 백엔드 서비스의 URL을 입력합니다. 콘텐츠를 생성하는 데 사용되는 LLM 모델 엔드포인트입니다.
  이 튜토리얼에서는 대상(기존 API)을 다음과 같이 설정할 수 있습니다.
```
REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.0-flash-001:generateContent
```
다음 시맨틱 캐시 URL을 입력합니다.
참고: 이러한 URL은 개발 탭의 프록시 편집기에 있는 XML 구성에 추가할 수도 있습니다.
- 임베딩 생성 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
```
다음을 클릭합니다.
만들기를 클릭합니다.

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

시맨틱 캐싱 정책 구성하기

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

정책 수정:

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

API 프록시에 Google 인증 추가

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

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

개발 탭의 대상 엔드포인트 폴더에서 기본값을 클릭합니다. 코드 뷰에 <TargetEndpoint> 요소의 XML 구성이 표시됩니다.

XML을 수정하여 <HTTPTargetConnection> 아래에 다음 구성을 추가합니다.

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

저장을 클릭합니다.

API 프록시 배포

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

배포를 클릭하여 API 프록시 배포 창을 엽니다.
버전 필드가 1로 설정되어 있어야 합니다. 그렇지 않은 경우 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 프록시의 기본 경로입니다.

하늘은 왜 파란가요?
하늘이 파란 이유는 무엇인가요?
하늘은 왜 파란색인가요?
하늘이 파란 이유를 설명해 줄 수 있어?
왜 하늘은 파란색인가요?

유사한 프롬프트가 캐시된 후 각 호출의 응답 시간을 비교합니다.

호출이 캐시에서 제공되는지 확인하려면 응답 헤더를 확인하세요. 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)의 연속 응답 스트리밍을 위해 EventFlow를 사용하는 API 프록시에는 시맨틱 캐싱 정책이 지원되지 않습니다.
<UserPromptSource> 내의 JsonPath 함수는 ignoreUnresolvedVariables 기능을 지원하지 않습니다. 기본적으로 null 또는 빈 값은 메시지 템플릿 적용 중에 무시됩니다.

다음 단계

Model Armor 정책을 시작하는 방법 알아보기