Google 서비스를 호출하도록 확장 프로그램 구성

서비스 확장 프로그램을 사용하면 지원되는 애플리케이션 부하 분산기가 Google 서비스에 대한 콜아웃을 사용하여 확장 프로그램을 구성할 수 있습니다. 이 페이지에서는 이러한 확장 프로그램을 구성하는 방법을 보여줍니다.

개요는 Google 서비스와의 통합을 참고하세요.

트래픽 확장 프로그램을 구성하여 Model Armor 서비스 호출

트래픽 확장 프로그램을 구성하여 Model Armor를 호출하여 GKE Inference Gateway를 비롯한 애플리케이션 부하 분산기로 향하는 생성형 AI 추론 트래픽에 보안 정책을 균일하게 적용할 수 있습니다.

트래픽 확장 프로그램은 관련 확장 프로그램 서비스를 하나 이상의 체인으로 그룹화합니다. 동일한 확장 프로그램 체인에서 플러그인과 콜아웃을 모두 구성할 수 있습니다. 각 확장 프로그램 체인은 Common Expression Language (CEL) 일치 조건을 사용하여 처리할 트래픽을 선택합니다. 부하 분산기는 각 체인의 일치 조건에 대해 요청을 순차적으로 평가합니다. 요청이 체인에서 정의한 조건과 일치하면 체인의 모든 확장 프로그램이 요청에 대해 작동합니다. 하나의 체인만 지정된 요청과 일치합니다.

체인의 각 확장 프로그램에는 지원되는 자체 이벤트 세트가 있을 수 있습니다. 확장 프로그램이 요청 및 응답 콘텐츠에 적용한 수정사항은 체인의 나머지 확장 프로그램에 표시됩니다. 응답 이벤트를 지원하도록 구성된 확장 프로그램의 경우 확장 프로그램 시퀀스가 응답 경로에서 반전됩니다.

트래픽 확장 프로그램은 추론 게이트웨이를 사용하여 생성된 부하 분산기 전달 규칙에 연결됩니다. 리소스를 구성하면 일치하는 요청이 Model Armor 서비스로 전송됩니다.

시작하기 전에

  1. 프로젝트 소유자 또는 편집자 역할이 있거나 다음 Compute Engine IAM 역할이 있는 적절한 프로젝트를 식별합니다.

  2. 필요한 API를 사용 설정합니다.

    콘솔

    1. Google Cloud 콘솔에서 API 액세스 사용 설정 페이지로 이동합니다.

      API 액세스 사용 설정으로 이동

    2. Compute Engine API, Model Armor API, Network Services API를 비롯한 필수 API를 사용 설정하는 안내를 따릅니다.

    gcloud

    gcloud services enable 명령어를 사용합니다.

    gcloud services enable compute.googleapis.com modelarmor.googleapis.com networkservices.googleapis.com

  3. 필요한 Model Armor 템플릿을 만듭니다.

  4. 추론 게이트웨이를 배포하여 Google Kubernetes Engine 인프라를 설정합니다. 추론 요청을 전송하여 테스트합니다.

    몇 가지 제한사항이 적용되지만 다음 OpenAI API 엔드포인트가 지원됩니다. Assistants, Chat Completions, Completions (레거시), Messages, Threads

OpenAI API 엔드포인트 구성 시 제한사항

GKE 인프라에 대해 OpenAI API 엔드포인트를 구성할 때 프롬프트 및 응답 정리와 관련된 다음 제한사항을 고려하세요.

  • 스트리밍 API 응답은 어떤 API에서도 지원되지 않습니다. 스트리밍 API와 비 스트리밍 API를 혼합하여 사용하는 경우 트래픽 확장 프로그램을 구성할 때 failOpen를 true로 설정합니다. Model Armor는 비스트리밍 응답을 정리하고 스트리밍 응답은 무시합니다.

  • 프롬프트와 대답을 삭제할 때는 다음 작업만 지원됩니다.

    • Assistants API: Create, Delete, List, Modify, Retrieve
    • Chat Completions API: Create, Delete, Get Chat Completion, Get Chat Message, List, Update
    • Completions (기존) API: Create
    • Messages API: Create, Delete, List, Modify, Retrieve
    • 스레드 API: Create, Delete, Modify, Retrieve

  • 대답에 여러 선택사항을 반환하는 API 호출 (예: POST https://api.openai.com/v1/chat/completions)의 경우 선택사항 목록의 첫 번째 항목만 정리됩니다.

트래픽 확장 프로그램 구성

  1. 부하 분산기로 추론 요청을 전송하고 부하 분산기의 노출된 IP 주소를 지정하여 확장 프로그램을 구성하기 전의 동작을 확인합니다.

    curl -v http://${IP}/v1/chat/completions
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer $(gcloud auth print-access-token)' \
  -d '{"model": "meta-llama/Llama-3.1-8B-Instruct",
       "messages": [
          {
            "role": "user",
            "content": "Can you remember my ITIN: 123-45-6789"
          }
        ],
       "max_tokens": 250,
       "temperature": 0.1}'

    민감한 데이터가 LLM에 전송되었지만 요청에서 HTTP 200 OK 상태 코드가 생성됩니다.

  2. Model Armor가 민감한 정보가 포함된 프롬프트를 차단하도록 트래픽 확장 프로그램을 구성합니다.

    콘솔

    1. Google Cloud 콘솔에서 서비스 확장 프로그램 페이지로 이동합니다.

      서비스 확장 프로그램으로 이동

    2. 확장 프로그램 만들기를 클릭합니다. 마법사가 열려 초기 단계를 안내합니다.

    3. 제품에서 부하 분산을 선택합니다. 그런 다음 계속을 클릭합니다. 지원되는 애플리케이션 부하 분산기 목록이 표시됩니다.

    4. 부하 분산기 유형을 선택합니다.

    5. 리전을 us-central1로 지정합니다. 계속을 클릭합니다.

    6. 확장 프로그램 유형으로 트래픽 확장 프로그램을 선택한 다음 계속을 클릭합니다.

    7. 확장 프로그램 만들기 양식을 열려면 계속을 클릭합니다. 확장 프로그램 만들기 양식에서 앞서 선택한 항목은 수정할 수 없습니다.

    8. 기본사항 섹션에서 다음을 수행합니다.

      1. 확장 프로그램의 고유한 이름을 지정합니다.

        이름은 소문자로 시작해야 합니다. 이어서 최대 62자의 소문자, 숫자 또는 하이픈이 와야 하며 하이픈으로 끝나면 안 됩니다.

      2. 선택사항: 최대 1,024자를 사용하여 확장 프로그램에 대한 간략한 설명을 입력합니다.

      3. 선택사항: 라벨 섹션에서 라벨 추가를 클릭합니다. 그런 다음 표시되는 행에서 다음을 실행합니다.

        • 키에 키 이름을 입력합니다.
        • 값에 키 값을 입력합니다.

        키-값 쌍을 더 추가하려면 라벨 추가를 클릭합니다. 최대 64개의 키-값 쌍을 추가할 수 있습니다.

        라벨에 대한 자세한 내용은 프로젝트 라벨 만들기 및 업데이트를 참고하세요.

    9. 전달 규칙에서 확장 프로그램과 연결할 전달 규칙을 하나 이상 선택합니다. 추론 게이트웨이 배포의 일부로 생성된 전달 규칙을 선택합니다. 이미 다른 확장 프로그램과 연결된 전달 규칙은 선택할 수 없으며 사용할 수 없는 것으로 표시됩니다.

    10. 확장 프로그램 체인의 경우 일치하는 요청에 실행할 확장 프로그램 체인을 하나 이상 추가합니다.

      확장 프로그램 체인을 추가하려면 다음 단계를 따른 후 완료를 클릭하세요.

      • 새 확장 프로그램 체인 이름에 고유한 이름을 지정합니다.

        이름은 RFC-1034를 준수해야 하며 소문자, 숫자, 하이픈만 사용해야 하고 최대 길이는 63자(영문 기준)입니다. 또한 첫 번째 문자는 문자여야 하고 마지막 문자는 문자나 숫자여야 합니다.

      • 확장 프로그램 체인이 실행되는 요청을 일치시키려면 일치 조건에 Common Expression Language(CEL) 표현식(예: request.path == "/v1/chat/completions")을 지정합니다.

        CEL 표현식에 대한 자세한 내용은 구문 도움말 보기를 클릭하거나 CEL 일치자 언어 참조를 참고하세요.

      • 일치하는 요청에 실행할 확장 프로그램을 하나 이상 추가합니다.

        각 확장 프로그램의 확장 프로그램에서 다음을 수행한 후 완료를 클릭합니다.

        • 확장 프로그램 이름에 고유한 이름을 지정합니다.

          이름은 RFC-1034를 준수해야 하며 소문자, 숫자, 하이픈만 사용해야 하고 최대 길이는 63자(영문 기준)입니다. 또한 첫 번째 문자는 문자여야 하고 마지막 문자는 문자나 숫자여야 합니다.

        • 프로그래밍 가능 유형에서 Google 서비스를 선택한 다음 모델 아머 서비스 엔드포인트를 선택합니다(예: modelarmor.us-central1.rep.googleapis.com).

        • 제한 시간의 경우 스트림의 메시지가 제한 시간 초과되는 10~1, 000밀리초 사이의 값을 지정합니다. Model Armor의 지연 시간은 약 250밀리초입니다.

        • 이벤트에서 모든 HTTP 이벤트 유형을 선택합니다.

        • 헤더 전달에서 헤더 추가를 클릭한 다음 클라이언트 또는 백엔드에서 확장 프로그램으로 전달할 HTTP 헤더를 추가합니다. 헤더를 지정하지 않으면 모든 헤더가 전송됩니다.

        • 선택사항: 확장 프로그램이 시간 초과되거나 실패하고 요청 또는 응답 처리를 계속하려면 Fail open에 대해 Enabled를 선택합니다. 체인의 후속 확장 프로그램도 실행됩니다.

          기본적으로 Fail open 옵션은 선택되어 있지 않습니다. 이 경우 오류가 발생하면 요청 또는 응답 처리가 중지됩니다. 응답 헤더가 다운스트림 클라이언트에 전송되지 않으면 클라이언트에 일반 HTTP 500 상태 코드가 반환됩니다. 응답 헤더가 전송되면 클라이언트에 대한 HTTP 스트림이 재설정됩니다.

          보안 또는 무결성을 우선시하는 경우 장애 허용을 선택하지 않은 기본 옵션이 선호됩니다. 특히 중요하지 않은 작업에 대해 Fail open을 사용 설정하면 가용성의 우선순위를 지정할 때 도움이 됩니다.

        • 메타데이터에서 메타데이터 추가를 클릭하여 특정 모델에 해당하는 프롬프트와 응답을 검사하는 데 사용할 Model Armor 템플릿을 지정합니다.

          키에 model_armor_settings을 지정합니다. 값의 경우 템플릿을 다음과 같은 JSON 문자열로 지정합니다.

          [{ "model": "MODEL_NAME", "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE", "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE" }]

          다음을 바꿉니다.

          • MODEL_NAME: InferenceModel 리소스로 구성된 모델의 이름(예: meta-llama/Llama-3.1-8B-Instruct)
          • TEMPLATE_PROJECT_ID: Model Armor 템플릿의 프로젝트 ID
          • LOCATION: Model Armor 템플릿의 위치(예: us-central1)
          • RESPONSE_TEMPLATE: 모델이 사용할 응답 템플릿
          • PROMPT_TEMPLATE: 모델에서 사용할 프롬프트 템플릿

          요청이 모델과 정확히 일치하지 않는 경우 사용할 기본 템플릿을 추가로 지정할 수 있습니다. 기본 템플릿을 구성하려면 MODEL_NAME을 default로 지정합니다.

          프롬프트 또는 응답 트래픽을 스크리닝하지 않으려면 빈 필터 템플릿을 만들어 포함하세요.

          metadata의 총 크기는 1KiB보다 작아야 합니다. 메타데이터의 총 키 수는 20개 미만이어야 합니다. 각 키의 길이는 64자(영문 기준) 미만이어야 합니다. 각 값의 길이는 1,024자(영문 기준) 미만이어야 합니다. 모든 값은 문자열이어야 합니다.

          요청이 차단되면 Model Armor는 표준 403 Forbidden 상태 코드를 반환합니다. Model Armor 템플릿의 보안 정책에서 맞춤 응답 설정 (맞춤 상태 코드 및 메시지 포함)을 정의하여 상태를 재정의할 수 있습니다. 자세한 내용은 TemplateMetadata를 참고하세요.

    11. 확장 프로그램 만들기를 클릭합니다.

    gcloud

    1. YAML 파일에서 콜아웃을 정의하고 추론 게이트웨이를 배포할 때 생성되는 전달 규칙과 연결합니다. 제공된 샘플 값을 사용합니다.

      cat >traffic_callout_service.yaml <<EOF
    name: traffic-ext
    forwardingRules:
    - https://www.googleapis.com/compute/v1/projects/LB_PROJECT_ID/regions/us-central1/forwardingRules/FORWARDING_RULE
    loadBalancingScheme: INTERNAL_MANAGED
    extensionChains:
    - name: "chain1-model-armor"
      matchCondition:
        celExpression: 'request.path == "/v1/chat/completions"'
      extensions:
      - name: extension-chain-1-model-armor
        service: modelarmor.us-central1.rep.googleapis.com
        failOpen: true
        supportedEvents:
        - REQUEST_HEADERS
        - REQUEST_BODY
        - REQUEST_TRAILERS
        - RESPONSE_HEADERS
        - RESPONSE_BODY
        - RESPONSE_TRAILERS
        timeout: 1s
        metadata:
          model_armor_settings: '[
            {
              "model": "MODEL_NAME",
              "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE",
              "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE"
            }
          ]'
EOF

      다음을 바꿉니다.

      • TEMPLATE_PROJECT_ID: Model Armor 템플릿의 프로젝트 ID
      • LB_PROJECT_ID: 부하 분산기 전달 규칙의 프로젝트 ID

      • FORWARDING_RULE: 확장 프로그램과 연결할 하나 이상의 전달 규칙입니다. 추론 게이트웨이 배포의 일환으로 생성된 전달 규칙을 선택합니다.

        이미 다른 확장 프로그램과 연결된 전달 규칙은 선택할 수 없으며 사용할 수 없는 것으로 표시됩니다.

      • MODEL_NAME: InferenceModel 리소스로 구성된 모델의 이름입니다(예: meta-llama/Llama-3.1-8B-Instruct).

      • LOCATION: Model Armor 템플릿의 위치(예: us-central1)

      • RESPONSE_TEMPLATE: 모델이 사용할 응답 템플릿

      • PROMPT_TEMPLATE: 모델에서 사용할 프롬프트 템플릿

      metadata 필드에서 특정 모델에 해당하는 프롬프트와 대답을 검사할 때 사용할 Model Armor 설정과 템플릿을 지정합니다.

      요청이 모델과 정확히 일치하지 않는 경우 사용할 기본 템플릿을 추가로 지정할 수 있습니다. 기본 템플릿을 구성하려면 MODEL_NAME을 default로 지정합니다.

      프롬프트 또는 응답 트래픽을 스크리닝하지 않으려면 빈 필터 템플릿을 만들어 포함하세요.

      metadata의 총 크기는 1KiB보다 작아야 합니다. 메타데이터의 총 키 수는 16개 미만이어야 합니다. 각 키의 길이는 64자(영문 기준) 미만이어야 합니다. 각 값의 길이는 1,024자(영문 기준) 미만이어야 합니다. 모든 값은 문자열이어야 합니다.

      요청이 차단되면 Model Armor는 표준 403 Forbidden 상태 코드를 반환합니다. Model Armor 템플릿의 보안 정책에서 맞춤 응답 설정 (맞춤 상태 코드 및 메시지 포함)을 정의하여 상태를 재정의할 수 있습니다. 자세한 내용은 TemplateMetadata를 참고하세요.

    2. 트래픽 확장 프로그램을 가져옵니다. 다음 샘플 값과 함께 gcloud service-extensions lb-traffic-extensions import 명령어를 사용합니다.

      gcloud service-extensions lb-traffic-extensions import traffic-ext \
    --source=traffic_callout_service.yaml \
    --location=us-central1

    kubectl

    1. v1.32.2-gke.1182001 이전 버전의 GKE를 사용하는 경우 트래픽 확장 프로그램 CRD를 설치합니다.

      kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/gke-gateway-api/refs/heads/main/config/crd/networking.gke.io_gcptrafficextensions.yaml

    2. YAML 파일에 확장 프로그램을 정의합니다. 이 맞춤 리소스는 추론 게이트웨이를 Model Armor 서비스에 연결합니다. 제공된 샘플 값을 사용합니다.

      cat >traffic_callout_service.yaml <<EOF
apiVersion: networking.gke.io/v1
kind: GCPTrafficExtension
metadata:
  name: traffic-ext
spec:
  targetRefs:
  - group: "gateway.networking.k8s.io"
    kind: Gateway
    name: inference-gateway
  extensionChains:
  - name: "chain1-model-armor"
    matchCondition:
      celExpressions:
      - celMatcher: 'request.path == "/v1/chat/completions"'
      extensions:
      - name: extension-chain-1-model-armor
        googleAPIServiceName: modelarmor.us-central1.rep.googleapis.com
        failOpen: true
        supportedEvents:
        - RequestHeaders
        - RequestBody
        - RequestTrailers
        - ResponseHeaders
        - ResponseBody
        - ResponseTrailers
        timeout: 1s
        metadata:
          model_armor_settings: '[
            {
              "model": "MODEL_NAME",
              "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE",
              "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE"
            }
          ]'
EOF

      다음을 바꿉니다.

      • MODEL_NAME: InferenceModel 리소스로 구성된 모델의 이름입니다(예: meta-llama/Llama-3.1-8B-Instruct).
      • TEMPLATE_PROJECT_ID: Model Armor 템플릿의 프로젝트 ID
      • LOCATION: Model Armor 템플릿의 위치(예: us-central1)
      • RESPONSE_TEMPLATE: 모델이 사용할 응답 템플릿
      • PROMPT_TEMPLATE: 모델에서 사용할 프롬프트 템플릿

      metadata 필드에서 특정 모델에 해당하는 프롬프트와 대답을 검사할 때 사용할 Model Armor 설정과 템플릿을 지정합니다.

      요청이 모델과 정확히 일치하지 않는 경우 사용할 기본 템플릿을 추가로 지정할 수 있습니다. 기본 템플릿을 구성하려면 MODEL_NAME을 default로 지정합니다.

      프롬프트 또는 응답 트래픽을 스크리닝하지 않으려면 빈 필터 템플릿을 만들어 포함하세요.

      metadata의 총 크기는 1KiB보다 작아야 합니다. 메타데이터의 총 키 수는 16개 미만이어야 합니다. 각 키의 길이는 64자(영문 기준) 미만이어야 합니다. 각 값의 길이는 1,024자(영문 기준) 미만이어야 합니다. 모든 값은 문자열이어야 합니다.

      요청이 차단되면 Model Armor는 표준 403 Forbidden 상태 코드를 반환합니다. Model Armor 템플릿의 보안 정책에서 맞춤 응답 설정 (맞춤 상태 코드 및 메시지 포함)을 정의하여 상태를 재정의할 수 있습니다. 자세한 내용은 TemplateMetadata를 참고하세요.

    3. traffic_callout_service.yaml 파일에 정의된 구성을 GKE 클러스터에 적용합니다. 이 명령어는 추론 게이트웨이를 Model Armor 서비스에 연결하는 GCPTrafficExtension 리소스를 만듭니다.

      kubectl apply -f traffic_callout_service.yaml

  3. 서비스 확장 프로그램 서비스 계정에 필요한 역할을 부여합니다. gcloud projects add-iam-policy-binding 명령어를 사용합니다.

    gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/container.admin
gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.user

    다음을 바꿉니다.

    • TEMPLATE_PROJECT_ID: Model Armor 템플릿의 프로젝트 ID
    • LB_PROJECT_NUMBER: 부하 분산기의 프로젝트 번호

    이 값은 프로젝트의 Google Cloud 콘솔의 프로젝트 정보 패널에 나열됩니다.

  4. 트래픽 확장 프로그램이 예상대로 작동하는지 확인하려면 동일한 curl 명령어를 실행합니다.

    curl -v http://${IP}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer $(gcloud auth print-access-token)' \
  -d '{"model": "meta-llama/Llama-3.1-8B-Instruct",
       "messages": [
          {
            "role": "user",
            "content": "Can you remember my ITIN: 123-45-6789"
          }
        ],
       "max_tokens": 250,
       "temperature": 0.1}'
  ```

서비스 확장 프로그램을 구성하면 민감한 데이터가 포함된 요청이 HTTP 403 Forbidden 상태 코드를 생성하고, 템플릿에 구성된 대로 오류 메시지를 로깅하고, 연결을 닫습니다.

요청이 안전하면 HTTP 200 OK 상태 코드를 생성하고 LLM 응답을 사용자에게 반환합니다.

확장 프로그램의 동작을 모니터링하려면 로그 탐색기를 사용하세요. 쿼리 창에서 추론 게이트웨이 구성에 따라 적절한 부하 분산기 리소스 유형으로 필터링합니다.

애플리케이션 부하 분산기 로그 항목에는 HTTP 또는 HTTPS 트래픽을 디버깅하는 데 도움이 되는 정보가 포함되어 있습니다.

보안 평가를 더 자세히 분석하려면 Model Armor 감사 로깅을 사용 설정하세요.

다음 단계