엔드포인트 만들기 및 관리

프리뷰

이 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. GA 이전 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

이 페이지에서는 Google Distributed Cloud 연결 API 엔드포인트에서 Gemini를 만들고 관리하는 방법을 설명합니다.

설치 요구사항에 설명된 대로 Google 인증 하드웨어를 성공적으로 배포했다고 가정합니다.

기본 요건

이 섹션에서는 GDC 연결 API 엔드포인트에 Gemini를 배포하기 전에 완료해야 하는 일회성 단계를 설명합니다.

필요한 API 사용 설정

타겟 Google Cloud 프로젝트에서 다음 API를 사용 설정해야 합니다.

• aiplatform.googleapis.com
• anthos.googleapis.com
• anthosaudit.googleapis.com
• anthosgke.googleapis.com
• cloudresourcemanager.googleapis.com
• connectgateway.googleapis.com
• compute.googleapis.com
• container.googleapis.com
• edgecontainer.googleapis.com
• gdchardwaremanagement.googleapis.com
• gkeconnect.googleapis.com
• gkehub.googleapis.com
• gkeonprem.googleapis.com
• iam.googleapis.com
• iamcredentials.googleapis.com
• kubernetesmetadata.googleapis.com
• logging.googleapis.com
• monitoring.googleapis.com
• multiclustermetering.googleapis.com
• opsconfigmonitoring.googleapis.com
• oslogin.googleapis.com
• serviceusage.googleapis.com
• stackdriver.googleapis.com
• storage.googleapis.com
• sts.googleapis.com

API 사용 설정에 대한 자세한 내용은 서비스 사용 설정을 참고하세요.

필수 역할 부여

다음 필수 역할을 구성해야 합니다.

• GDC 연결 API 배포에서 Gemini를 관리하는 데 사용되는 계정의 경우 Distributed Cloud Edge Container API 역할 및 권한에 나열된 역할을 부여합니다.

• GDC 연결 API 엔드포인트에서 Gemini와 상호작용하는 데 사용되는 계정에는 Vertex AI API 역할 및 권한에 나열된 역할을 부여합니다.

타겟 Distributed Cloud 연결 영역에 관한 정보 가져오기

타겟 분산 클라우드 연결 영역의 이름을 가져오려면 다음 단계를 따르세요.

1. 영역 목록에 설명된 대로 Google Cloud 프로젝트에서 Distributed Cloud 연결 영역을 나열합니다.

2. 영역에 관한 정보 가져오기에 설명된 대로 타겟 영역에 관한 자세한 정보를 가져옵니다.

분산 클라우드 연결 영역의 인증된 머신에 관한 정보 가져오기

분산 클라우드 연결 영역에서 타겟 인증 머신의 이름을 가져오려면 다음을 실행하세요.

1. 영역의 머신 나열에 설명된 대로 타겟 분산 클라우드 연결 영역에서 분산 클라우드 연결 머신을 나열합니다.

2. 머신에 관한 정보 가져오기에 설명된 대로 타겟 머신에 관한 자세한 정보를 가져옵니다.

로컬 AI Platform API 및 Vertex AI API 서비스 사용 설정

1. 대상 Distributed Cloud 연결 영역에서 대상 Google Cloud 프로젝트를 사용 설정합니다.

   gcloud zone-management projects enable PROJECT_ID \
      --organization ORGANIZATION_ID \
      --location REGION \
      --zones ZONE
   

   다음을 바꿉니다.

   • PROJECT_ID: 대상 Google Cloud 프로젝트의 ID입니다.
   • ORGANIZATION_ID: 대상 Google Cloud 조직의 ID입니다.
   • REGION: 타겟 Distributed Cloud(연결형) 영역이 생성된 Google Cloud 리전입니다.
   • ZONE: 대상 Distributed Cloud connected 영역입니다.

2. 타겟 Google Cloud 프로젝트에서 AI Platform 서비스를 사용 설정합니다.

   gcloud services enable aiplatform.googleapis.com --project PROJECT_ID
   

   PROJECT_ID를 타겟 Google Cloud 프로젝트의 ID로 바꿉니다.

3. Distributed Cloud 연결된 영역에서 Vertex AI API 서비스를 사용 설정합니다.

   gcloud zone-management services enable vertex --project PROJECT_ID \
      --location REGION \
      --zones ZONE
   

   다음을 바꿉니다.

   • PROJECT_ID: 대상 Google Cloud 프로젝트의 ID입니다.
   • REGION: 타겟 Distributed Cloud(연결형) 영역이 생성된 Google Cloud 리전입니다.
   • ZONE: 대상 Distributed Cloud connected 영역입니다.

DNS 변환을 위한 엔드포인트 구성

1. 관리형 DNS 주소, 최상위 도메인 (TLD), 대상 Distributed Cloud 연결 영역의 인증 기관 (CA) 인증서를 가져옵니다.

   gcloud alpha zone-management zones describe ZONE \
     --organization ORGANIZATION_ID \
     --location REGION
   

   다음을 바꿉니다.

   • ORGANIZATION_ID: 대상 Google Cloud 조직의 ID입니다.
   • REGION: 타겟 Distributed Cloud(연결형) 영역이 생성된 Google Cloud 리전입니다.
   • ZONE: 대상 Distributed Cloud connected 영역입니다.

   다음 예는 이 명령어의 출력을 보여줍니다.

   -----BEGIN CERTIFICATE-----
   MIIDATCCAemgAwIBAgIRAOsIG15loHwPBpjQe9FZYUAwDQYJKoZIhvcNAQELBQAw
   GjEYMBYGA1UEAxMPZ2RjZS1jbHVzdGVyLWNhMB4XDTI1MDcyOTEyMTAwNloXDTQ5
   MDcyMzEyMTAwNlowGjEYMBYGA1UEAxMPZ2RjZS1jbHVzdGVyLWNhMIIBIjANBgkq
   hkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3YdoASubyzHdgZ0vIU5g1dxdFRT1T4wc
   o9FaRXftSTDfiNVNKj/vC+De9EZokpyLZkdZNep6p0TLJAsPZYq+yiTCiaJ6Ihwy
   3LBn8j2PessSIte2LUhkft1yCQqfkgpYfKcjM3IauIXETS961m0uJb4sntgLJ4nM
   Scb5vpW1f70D1V27bqnEsE7+rbxzeFTosHC+DGBcLqIE0ptdionm/4xoltH7yv2O
   qKfcc/46TyPwGRzxifEdNzjKZ1kRdTThESfW+L7TQNv6VF5TC4FPksYX/ID/X7Fz
   G9BRey0mikvc4J7qQIeyMRlpIKqRh/1FCdRDC9vVEQipT2Ls0MwwTwIDAQABo0Iw
   QDAOBgNVHQ8BAf8EBAMCAYYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUmES2
   pyMLOnnsKug8amFmenOaTr8wDQYJKoZIhvcNAQELBQADggEBADn71zo7cNFZ0kQE
   C2lS6b0DLz4Nd1yCz5fGDvxzcTRdOT60wyq/TAx1YlYse33cGk/cQ7RkVsM56UX1
   T8RMvi09UcEQG3wFrYuU62ZjXF1a3RrOnHxyvVdyvbUYAO5gvzBQrj4tMZYX9kL3
   6H/9FwXuHVyqWAm0xpWvZfszwJjY4C1VxoDwmRiZPYzTrWI6/rY0QmORgcZXLnPL
   OVufbAX30aRGdTRnVXxE0fKmXwzbtbSHilU5hJT7EQWMvV5hJfyNqdXG0gbrhrsk
   sB0yRjk5PHQd9pOMcXcYIgfNnUEcQl4qeSll3g5cZ+cRrcTO1USFLRo8dcbQpJ6Y
   6ykzvKs=
   -----END CERTIFICATE-----
   createTime: '2025-08-25T20:46:50.269384028Z'
   dnsServers:
   - ipAddress: 10.200.1.10
   tld: my-tld.google.private.goog
   name: organizations/my-organization/locations/my-region/zones/my-zone
   state: STATE_RUNNING
   

   인증서를 파일에 저장합니다. 다음 단계에서 이 파일을 사용합니다.

2. 다음과 같이 엔드포인트의 DNS 구성을 만듭니다.

   mkdir /etc/systemd/resolved.conf.d
   echo '[Resolve]
   DNS=DNS_SERVER_ADDRESS
   Domains=~TOP_LEVEL_DOMAIN' > /etc/systemd/resolved.conf.d/dns.conf
   sudo systemctl restart systemd-resolved
   

   다음을 바꿉니다.

   • DNS_SERVER_ADDRESS: DNS 서버의 IP 주소입니다.
   • TOP_LEVEL_DOMAIN: 엔드포인트의 최상위 도메인

GDC 연결 API 엔드포인트에 Gemini 배포

GDC 연결 API 엔드포인트에 Gemini를 배포하려면 다음 단계를 따르세요.

1. 엔드포인트를 만듭니다.

   gcloud ai endpoints create \
      --project=PROJECT_ID \
      --region=REGION \
      --gdc-zone=ZONE \
      --display_name=ENDPOINT_NAME
   

   다음을 바꿉니다.

   • PROJECT_ID: 대상 Google Cloud 프로젝트의 ID입니다.
   • REGION: 타겟 Distributed Cloud(연결형) 영역이 생성된 Google Cloud 리전입니다.
   • ZONE: 대상 Distributed Cloud connected 영역입니다.
   • ENDPOINT_NAME: 이 엔드포인트를 고유하게 식별하는 의미 있는 이름입니다.

2. 모델을 배포합니다.

   gcloud ai endpoints deploy-model ENDPOINT_NAME \
     --region=REGION \
     --gdc-zone=ZONE \
     --model=MODEL_PUBLIC_ID
   

   다음을 바꿉니다.

   • ENDPOINT_NAME: 대상 엔드포인트의 이름입니다.
   • REGION: 타겟 Distributed Cloud(연결형) 영역이 생성된 Google Cloud 리전입니다.
   • ZONE: 대상 Distributed Cloud connected 영역입니다.
   • MODEL_PUBLIC_ID: 모델의 공개 ID입니다. 지원되는 모델 목록은 지원되는 모델을 참고하세요.

3. 엔드포인트 주소를 가져옵니다.

   gcloud ai endpoints describe ENDPOINT_NAME \
     --project=PROJECT_ID \
     --region=REGION
   

   다음을 바꿉니다.

   • ENDPOINT_NAME: 대상 엔드포인트의 이름입니다.
   • PROJECT_ID: 대상 Google Cloud 프로젝트의 ID입니다.
   • REGION: 타겟 Distributed Cloud(연결형) 영역이 생성된 Google Cloud 리전입니다.

4. 타겟 Distributed Cloud 연결 영역에서 엔드포인트의 서비스 계정을 만듭니다.

   gcloud alpha zone-management service-accounts create SERVICE_ACCOUNT \
     --project PROJECT_ID \ 
     --location REGION \
     --zone ZONE 
   

   다음을 바꿉니다.

   • SERVICE_ACCOUNT: 이 서비스 계정을 고유하게 식별하는 의미 있는 이름입니다.
   • PROJECT_ID: 대상 Google Cloud 프로젝트의 ID입니다.
   • REGION: 타겟 Distributed Cloud(연결형) 영역이 생성된 Google Cloud 리전입니다.
   • ZONE: 대상 Distributed Cloud connected 영역입니다.

5. 타겟 Distributed Cloud 연결 영역의 ID 및 액세스 관리 정책을 가져옵니다.

   gcloud alpha zone-management zones get-iam-policy ZONE \
     --project PROJECT_ID \ 
     --location REGION
   

   다음을 바꿉니다.

   • ZONE: 대상 Distributed Cloud connected 영역입니다.
   • PROJECT_ID: 대상 Google Cloud 프로젝트의 ID입니다.
   • REGION: 타겟 Distributed Cloud(연결형) 영역이 생성된 Google Cloud 리전입니다.

6. 서비스 계정에 AI Platform 개발자 역할을 할당합니다.

   gcloud alpha zone-management zones set-iam-policy  \
     --project PROJECT_ID \
     --location REGION \
     --zone ZONE
   

   다음을 바꿉니다.

   • POLICY_FILE: 역할 할당 정책이 포함된 JSON 또는 YAML 파일입니다.
   • PROJECT_ID: 대상 Google Cloud 프로젝트의 ID입니다.
   • REGION: 타겟 Distributed Cloud(연결형) 영역이 생성된 Google Cloud 리전입니다.
   • ZONE: 대상 Distributed Cloud connected 영역입니다.

   다음은 JSON 형식의 정책 예시입니다.

   "bindings": [
      {
         "role": "roles/aiplatform.geminiDeveloper",
         "members": [
         "serviceAccount": "projects/my-project/locations/my-region/serviceAccounts/my-service-account"
         ]
      }
   ],
   "etag": ""
   

   다음은 YAML 형식의 정책 예시입니다.

   bindings:
   - role: roles/aiplatform.geminiDeveloper
   members:
   - serviceAccount: projects/my-project/locations/my-region/serviceAccounts/my-service-account
   etag: ""
   

7. 서비스 계정의 키를 생성합니다.

   gcloud alpha zone-management service-accounts keys create  \
      --service-account  \
      --project  \
      --location  \
      --ca-cert-path 
   

   다음을 바꿉니다.

   • SA_KEY_FILE: 생성된 서비스 계정 키를 저장할 파일입니다.
   • PROJECT_ID: 대상 Google Cloud 프로젝트의 ID입니다.
   • REGION: 타겟 Distributed Cloud(연결형) 영역이 생성된 Google Cloud 리전입니다.
   • CA_CERTIFICATE_FILE: 이전에 만든 CA 인증서 파일입니다.

8. 서비스 계정의 ID 토큰을 출력합니다.

   gcloud alpha zone-management auth print-identity-token \
     --cred-file=SA_CREDENTIAL_FILE \
     --audience=ENDPOINT_URL
   

   다음을 바꿉니다.

   • SA_KEY_FILE: 이전에 만든 서비스 계정 키 파일입니다.
   • ENDPOINT_URL: TLD 접미사를 포함한 엔드포인트의 정규화된 URL입니다.

배포된 Gemini on GDC 연결 API 엔드포인트 목록

배포된 Gemini on GDC 연결 API 엔드포인트를 나열하려면 다음 단계를 따르세요.

gcloud ai endpoints list \
    --project=PROJECT_ID \
    --region=REGION \
   --gdc-zone=ZONE
   

다음을 바꿉니다.

• PROJECT_ID: 대상 Google Cloud 프로젝트의 ID입니다.
• REGION: 타겟 Distributed Cloud(연결형) 영역이 생성된 Google Cloud 리전입니다.
• ZONE: 대상 Distributed Cloud connected 영역입니다.

GDC 연결 API 엔드포인트의 Gemini에 관한 정보 가져오기

배포된 Gemini on GDC 연결 API 엔드포인트에 관한 정보를 가져오려면 다음 단계를 따르세요.

gcloud ai endpoints describe ENDPOINT_NAME \
    --project=PROJECT_ID \
    --region=REGION
   

다음을 바꿉니다.

• ENDPOINT_NAME: 대상 엔드포인트의 이름입니다.
• PROJECT_ID: 대상 Google Cloud 프로젝트의 ID입니다.
• REGION: 타겟 Distributed Cloud(연결형) 영역이 생성된 Google Cloud 리전입니다.

Google Distributed Cloud Connected API 엔드포인트에서 Gemini와 상호작용

GDC의 Gemini에 연결된 API 엔드포인트는 ChatCompletions API와 ListAvailableModels API를 통한 상호작용을 지원합니다. 이러한 API를 사용하여 엔드포인트와 프로그래매틱 방식으로 상호작용합니다.

다음은 Chat Completions API를 통한 요청의 예입니다.

API_ENDPOINT="https://${IG_FQDN}/v1/projects/${PROJECT}/locations/${LOCATION}/chat/completions"

FLOW_ID="gemini-2.0-flash-001"

REQUEST_BODY='{
>   "model": "'${FLOW_ID}'",
>   "messages": [
>     {
>       "role": "system",
>       "content": "You are a helpful assistant."
>     },
>     {
>       "role": "user",
>       "content": "Hello!"
>     }
>   ],
}'

curl -X POST -vv -k \
  "${API_ENDPOINT}" \
  -d "${REQUEST_BODY}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${BEARER_TOKEN}" \
  -H "x-goog-user-project: projects/${PROJECT}"

다음은 문서를 입력으로 사용하는 멀티모달 Chat Completions API 요청의 예시입니다.

BASE64_IMAGE=$(base64 -w 0 sample-image.jpg)

{
    "model": "gemini-1.5-flash-002",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What is this image?"
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "data:image/jpeg;base64,'"${BASE64_IMAGE}"'"
                    }
                }
            ]
        }
    ]
}

다음은 ListAllAvailableModels API 요청의 예입니다.

# The request body -d parameter is intentionally omitted.
grpcurl -insecure \
  -H "Authorization: Bearer ${BEARER_TOKEN}" \
  -H "x-goog-user-project: projects/${PROJECT}" \
  "${IG_FQDN}:443" \
  cloud.gdc.ai.inference.inferencegateway.GeminiMetadataService.ListAvailableModels

Google Distributed Cloud 연결 API의 Gemini에 적합한 워크로드에 대한 자세한 내용은 Gemini 개요를 참고하세요.

연결된 Google Distributed Cloud API 엔드포인트에서 Gemini 삭제

GDC 연결 API 엔드포인트에서 Gemini를 삭제하려면 다음 단계를 따르세요.

1. 모델 배포를 취소합니다.

   gcloud ai endpoints undeploy-model ENDPOINT_NAME \
     --region=REGION \
     --gdc-zone=ZONE \
     --model=MODEL_PUBLIC_ID
   

   다음을 바꿉니다.

   • ENDPOINT_NAME: 대상 엔드포인트의 이름입니다.
   • REGION: 타겟 Distributed Cloud(연결형) 영역이 생성된 Google Cloud 리전입니다.
   • ZONE: 대상 Distributed Cloud connected 영역입니다.
   • MODEL_PUBLIC_ID: 모델의 공개 ID입니다. 지원되는 모델 목록은 지원되는 모델을 참고하세요.

2. 엔드포인트를 삭제합니다.

   gcloud ai endpoints delete ENDPOINT_NAME \
      --project=PROJECT_ID \
      --region=REGION
   

   다음을 바꿉니다.

   • PROJECT_ID: 대상 엔드포인트의 이름입니다.
   • REGION: 타겟 Distributed Cloud(연결형) 영역이 생성된 Google Cloud 리전입니다.