이 페이지에서는 GKE 추론 게이트웨이를 배포하는 방법을 설명합니다.
이 페이지는 GKE 인프라를 관리하는 네트워킹 전문가와 AI 워크로드를 관리하는 플랫폼 관리자를 대상으로 합니다.
이 페이지를 읽기 전 다음 내용을 숙지해야 합니다.
- GKE Inference Gateway 정보
- GKE의 AI/ML 조정
- 생성형 AI 용어집
- Google Cloud의 부하 분산, 특히 부하 분산기가 GKE와 상호작용하는 방식
- GKE Service Extensions. 자세한 내용은 GKE Gateway 컨트롤러 문서를 참고하세요.
- Service Extensions를 사용하여 GKE 게이트웨이 트래픽 맞춤설정
GKE 추론 게이트웨이는 Google Kubernetes Engine (GKE) 게이트웨이를 개선하여 GKE에서 생성형 AI 애플리케이션과 워크로드의 제공을 최적화합니다. AI 워크로드의 효율적인 관리 및 확장, 지연 시간과 같은 워크로드별 성능 목표 지원, 리소스 활용률, 모니터링 가능성, AI 안전성을 향상합니다.
시작하기 전에
시작하기 전에 다음 태스크를 수행했는지 확인합니다.
- Google Kubernetes Engine API를 사용 설정합니다. Google Kubernetes Engine API 사용 설정
- 이 태스크에 Google Cloud CLI를 사용하려면 gcloud CLI를 설치한 후 초기화하세요. 이전에 gcloud CLI를 설치한 경우
gcloud components update를 실행하여 최신 버전을 가져옵니다.
필요한 경우 Compute Engine API, Network Services API, Model Armor API를 사용 설정합니다.
API 액세스 사용 설정으로 이동하여 안내를 따릅니다.
프로젝트에
roles/container.admin,roles/iam.serviceAccountAdmin역할이 있는지 확인합니다.프로젝트에 H100 GPU 할당량이 충분한지 확인합니다. 자세한 내용은 GPU 할당량 계획 및 배정 할당량을 참고하세요.
Hugging Face 계정이 없는 경우 만듭니다. 이 튜토리얼의 모델 리소스에 액세스하려면 이 권한이 필요합니다.
Llama 3.1 모델에 대한 액세스 권한을 요청하고 액세스 토큰을 생성합니다. 이 모델에 액세스하려면 Hugging Face에서 요청이 승인되어야 하며, 액세스 권한이 부여되지 않으면 배포가 실패합니다.
- 라이선스 동의 계약 서명: Llama 3.1 모델을 사용하려면 동의 계약에 서명해야 합니다. Hugging Face에서 모델 페이지로 이동하여 계정을 확인하고 약관에 동의합니다.
- 액세스 토큰 생성: 모델에 액세스하려면 Hugging Face 토큰이 필요합니다. Hugging Face 계정에서 내 프로필 > 설정 > 액세스 토큰으로 이동하여 읽기 권한이 있는 새 토큰을 만들고 클립보드에 복사합니다.
GKE Gateway Controller 요구사항
- GKE 버전 1.32.3 이상
- Google Cloud CLI 버전 407.0.0 이상
- Gateway API는 VPC 기반 클러스터에서만 지원됩니다.
- 프록시 전용 서브넷을 사용 설정해야 합니다.
- 클러스터에
HttpLoadBalancing부가기능이 사용 설정되어 있어야 합니다. - Istio를 사용하는 경우 Istio를 다음 버전 중 하나로 업그레이드해야 합니다.
- 1.15.2 이상
- 1.14.5 이상
- 1.13.9 이상
- 공유 VPC를 사용하는 경우 호스트 프로젝트에서 서비스 프로젝트에 대해 GKE 서비스 계정에
Compute Network User역할을 할당해야 합니다.
제한 및 한도
다음 제한사항이 적용됩니다.
- 멀티 클러스터 게이트웨이는 지원되지 않습니다.
- GKE 추론 게이트웨이는
gke-l7-regional-external-managed및gke-l7-rilbGatewayClass 리소스에서만 지원됩니다. - 교차 리전 내부 애플리케이션 부하 분산기는 지원되지 않습니다.
호환성 매트릭스
표에는 게이트웨이 API 추론 확장 프로그램 커스텀 리소스 정의 (CRD)의 호환성 및 지원 매트릭스가 간략하게 나와 있습니다. 여기에는 특정 버전 요구사항과 설치 메모를 비롯하여 오픈소스 (OSS) Gateway API 추론 확장 프로그램 프로젝트와 비교하여 GKE에서 지원하는 CRD 버전이 자세히 설명되어 있습니다.
| CRD 이름 | CRD API 버전 | GKE 관리형 지원 | OSS (게이트웨이 API 추론 확장 프로그램) 지원 |
|---|---|---|---|
| V1 InferencePool | inference.networking.k8s.io/v1 | GKE 1.32.3 이상에서 지원되며 GKE 1.34.0-gke.1626000 이상에서 기본적으로 CRD가 설치됨 | 게이트웨이 API 추론 확장 프로그램 v1.0.0부터 지원됨 |
| 알파 InferencePool(알파 InferencePool 버전이 지원 중단되었으므로 v1 InferencePool로 시작하는 것이 좋습니다) | inference.networking.x-k8s.io/v1alpha2 | GKE 1.32.3 이상에서 지원됩니다. 하지만 CRD는 GKE에 기본적으로 설치되지 않습니다. 사용자가 Gateway API 추론 확장 프로그램에서 CRD를 수동으로 설치해야 합니다. | 게이트웨이 API 추론 확장 프로그램 v0.2.0부터 지원됩니다. |
| Alpha InferenceObjective | inference.networking.x-k8s.io/v1alpha2 | GKE는 InferenceObjective를 관리하지 않습니다. | 게이트웨이 API 추론 확장 프로그램 v1.0.0부터 지원됨 |
| 알파 InferenceModel(InferenceModel이 지원 중단되었으므로 InferenceObjective로 시작하는 사용자에게 권장) | inference.networking.x-k8s.io/v1alpha2 | GKE는 InferenceModel을 관리하지 않습니다. | 게이트웨이 API 추론 확장 프로그램 v0.2.0부터 지원됩니다. |
GKE 추론 게이트웨이 구성
GKE 추론 게이트웨이를 구성하려면 다음 예시를 참고하세요. 한 팀이 vLLM 및 Llama3 모델을 실행하고 'food-review' 및 'cad-fabricator'라는 두 개의 개별 LoRA 미세 조정 어댑터를 사용하여 적극적으로 실험합니다.
GKE 추론 게이트웨이 구성의 개략적인 워크플로는 다음과 같습니다.
- 환경 준비: 필요한 인프라와 구성요소를 설정합니다.
- 추론 풀 만들기:
InferencePool커스텀 리소스를 사용하여 모델 서버 풀을 정의합니다. - 추론 목표 지정:
InferenceObjective커스텀 리소스를 사용하여 추론 목표를 지정합니다. - 게이트웨이 만들기: 게이트웨이 API를 사용하여 추론 서비스를 노출합니다.
HTTPRoute만들기: HTTP 트래픽이 추론 서비스로 라우팅되는 방식을 정의합니다.- 추론 요청 전송: 배포된 모델에 요청을 전송합니다.
개발 환경 준비
Helm을 설치합니다.
GKE 클러스터를 만듭니다.
- 버전 1.32.3 이상으로 GKE Autopilot 또는 Standard 클러스터를 만듭니다. 자세한 내용은 GKE 클러스터 만들기를 참고하세요.
- 원하는 컴퓨팅 제품군과 가속기로 노드를 구성합니다.
- 선택한 가속기, 모델, 성능 요구사항에 따라 사전 구성되고 테스트된 배포 매니페스트를 위해 GKE Inference Quickstart를 사용하세요.
GKE 클러스터에 필요한 커스텀 리소스 정의 (CRD)를 설치합니다.
1.34.0-gke.1626000이전 GKE 버전의 경우 다음 명령어를 실행하여 v1InferencePool및 알파InferenceObjectiveCRD를 모두 설치합니다.
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api-inference-extension/releases/download/v1.0.0/experimental-manifests.yaml- GKE 버전
1.34.0-gke.1626000이상의 경우 다음 명령어를 실행하여 알파InferenceObjectiveCRD만 설치합니다.
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api-inference-extension/raw/v1.0.0/config/crd/bases/inference.networking.x-k8s.io_inferenceobjectives.yamlv1.32.2-gke.1182001이전 버전의 GKE를 사용하고 GKE 추론 게이트웨이와 함께 모델 아머를 사용하려면 트래픽 및 라우팅 확장 프로그램 CRD를 설치해야 합니다.kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/gke-gateway-api/refs/heads/main/config/crd/networking.gke.io_gcptrafficextensions.yaml kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/gke-gateway-api/refs/heads/main/config/crd/networking.gke.io_gcproutingextensions.yaml측정항목을 스크래핑할 승인을 설정하려면
inference-gateway-sa-metrics-reader-secret보안 비밀을 만드세요.kubectl apply -f - <<EOF --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: inference-gateway-metrics-reader rules: - nonResourceURLs: - /metrics verbs: - get --- apiVersion: v1 kind: ServiceAccount metadata: name: inference-gateway-sa-metrics-reader namespace: default --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: inference-gateway-sa-metrics-reader-role-binding namespace: default subjects: - kind: ServiceAccount name: inference-gateway-sa-metrics-reader namespace: default roleRef: kind: ClusterRole name: inference-gateway-metrics-reader apiGroup: rbac.authorization.k8s.io --- apiVersion: v1 kind: Secret metadata: name: inference-gateway-sa-metrics-reader-secret namespace: default annotations: kubernetes.io/service-account.name: inference-gateway-sa-metrics-reader type: kubernetes.io/service-account-token --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: inference-gateway-sa-metrics-reader-secret-read rules: - resources: - secrets apiGroups: [""] verbs: ["get", "list", "watch"] resourceNames: ["inference-gateway-sa-metrics-reader-secret"] --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: gmp-system:collector:inference-gateway-sa-metrics-reader-secret-read namespace: default roleRef: name: inference-gateway-sa-metrics-reader-secret-read kind: ClusterRole apiGroup: rbac.authorization.k8s.io subjects: - name: collector namespace: gmp-system kind: ServiceAccount EOF
모델 서버 및 모델 배포 만들기
이 섹션에서는 모델 서버와 모델을 배포하는 방법을 보여줍니다. 이 예에서는 Llama3 모델이 있는 vLLM 모델 서버를 사용합니다. 배포에 app:vllm-llama3-8b-instruct 라벨이 지정됩니다. 이 배포에서는 Hugging Face의 food-review 및 cad-fabricator이라는 두 개의 LoRA 어댑터도 사용합니다.
자체 모델 서버 컨테이너와 모델, 제공 포트, 배포 이름으로 이 예시를 조정할 수 있습니다. 배포에서 LoRA 어댑터를 구성하거나 기본 모델을 배포할 수도 있습니다. 다음 단계에서는 필요한 Kubernetes 리소스를 만드는 방법을 설명합니다.
Hugging Face 토큰을 저장할 Kubernetes 보안 비밀을 만듭니다. 이 토큰은 기본 모델과 LoRA 어댑터에 액세스하는 데 사용됩니다.
kubectl create secret generic hf-token --from-literal=token=HF_TOKENHF_TOKEN을 Hugging Face 토큰으로 바꿉니다.모델 서버와 모델을 배포합니다. 다음 명령어는
Llama3모델이 있는vLLM모델 서버의 Kubernetes 배포를 정의하는 매니페스트를 적용합니다.kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api-inference-extension/release-1.0/config/manifests/vllm/gpu-deployment.yaml
추론 풀 만들기
InferencePool Kubernetes 커스텀 리소스는 공통 기본 대규모 언어 모델 (LLM) 및 컴퓨팅 구성이 있는 포드 그룹을 정의합니다. selector 필드는 이 풀에 속하는 포드를 지정합니다. 이 선택기의 라벨은 모델 서버 Pod에 적용된 라벨과 정확하게 일치해야 합니다. targetPort 필드는 모델 서버가 포드 내에서 사용하는 포트를 정의합니다.
extensionRef 필드는 추론 풀에 추가 기능을 제공하는 확장 프로그램 서비스를 참조합니다. InferencePool을 사용하면 GKE 추론 게이트웨이가 모델 서버 포드로 트래픽을 라우팅할 수 있습니다.
InferencePool를 만들기 전에 InferencePool가 선택하는 포드가 이미 실행 중인지 확인합니다.
Helm을 사용하여 InferencePool을 만들려면 다음 단계를 따르세요.
helm install vllm-llama3-8b-instruct \
--set inferencePool.modelServers.matchLabels.app=vllm-llama3-8b-instruct \
--set provider.name=gke \
--version v1.0.0 \
oci://registry.k8s.io/gateway-api-inference-extension/charts/inferencepool
다음 필드를 배포에 맞게 변경합니다.
inferencePool.modelServers.matchLabels.app: 모델 서버 포드를 선택하는 데 사용되는 라벨의 키입니다.
Helm 설치는 필요한 타임아웃 정책, 엔드포인트 선택기, 관측 가능성에 필요한 포드를 자동으로 설치합니다.
이렇게 하면 포드 내의 모델 엔드포인트 서비스를 참조하는 vllm-llama3-8b-instruct인 InferencePool 객체가 생성됩니다. 또한 이 생성된 InferencePool에 대해 app:vllm-llama3-8b-instruct-epp라는 엔드포인트 선택기 배포를 만듭니다.
추론 목표 지정
InferenceObjective 커스텀 리소스를 사용하면 요청의 우선순위를 지정할 수 있습니다.
InferenceObjective 리소스의 metadata.name 필드는 추론 목표의 이름을 지정하고, Priority 필드는 서비스 중요도를 지정하며, poolRef 필드는 모델이 제공되는 InferencePool을 지정합니다.
```yaml
apiVersion: inference.networking.k8s.io/v1alpha2
kind: InferenceObjective
metadata:
name: NAME
spec:
priority: VALUE
poolRef:
name: INFERENCE_POOL_NAME
group: "inference.networking.k8s.io"
```
다음을 바꿉니다.
NAME: 추론 목표의 이름입니다. 예를 들면food-review입니다.VALUE: 추론 목표의 우선순위입니다. 값이 클수록 요청이 더 중요함을 나타내는 정수입니다. 예를 들어 10입니다.INFERENCE_POOL_NAME: 이전 단계에서 만든InferencePool의 이름. 예를 들면vllm-llama3-8b-instruct입니다.
InferenceObjective을 만들려면 다음 단계를 따르세요.
다음 매니페스트를
inference-objectives.yaml로 저장합니다. 이 매니페스트는InferenceObjective리소스 두 개를 만듭니다. 첫 번째는 우선순위가 10인vllm-llama3-8b-instructInferencePool에서food-review추론 목표를 구성합니다. 두 번째는llama3-base-model추론 목표가 우선순위 20으로 게재되도록 구성합니다.apiVersion: inference.networking.x-k8s.io/v1alpha2 kind: InferenceObjective metadata: name: food-review spec: priority: 10 poolRef: name: vllm-llama3-8b-instruct group: "inference.networking.k8s.io" --- apiVersion: inference.networking.x-k8s.io/v1alpha2 kind: InferenceObjective metadata: name: llama3-base-model spec: priority: 20 # Higher priority poolRef: name: vllm-llama3-8b-instruct샘플 매니페스트를 클러스터에 적용합니다.
kubectl apply -f inferenceobjective.yaml
게이트웨이 만들기
게이트웨이 리소스는 Kubernetes 클러스터로 들어오는 외부 트래픽의 진입점입니다. 들어오는 연결을 수락하는 리스너를 정의합니다.
GKE 추론 게이트웨이는 다음 게이트웨이 클래스와 함께 작동합니다.
gke-l7-rilb: 리전 내부 애플리케이션 부하 분산기gke-l7-regional-external-managed: 리전 외부 애플리케이션 부하 분산기
자세한 내용은 게이트웨이 클래스 문서를 참고하세요.
게이트웨이를 만들려면 다음 단계를 수행하세요.
다음 샘플 매니페스트를
gateway.yaml로 저장합니다.apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: name: GATEWAY_NAME spec: gatewayClassName: GATEWAY_CLASS listeners: - protocol: HTTP port: 80 name: http다음을 바꿉니다.
GATEWAY_NAME: 게이트웨이 리소스의 고유한 이름입니다. 예를 들면inference-gateway입니다.GATEWAY_CLASS: 사용할 게이트웨이 클래스입니다. 예를 들면gke-l7-regional-external-managed입니다.
매니페스트를 클러스터에 적용합니다.
kubectl apply -f gateway.yaml
참고: HTTPS로 게이트웨이를 보호하기 위해 TLS를 구성하는 방법에 대한 자세한 내용은 TLS 구성에 관한 GKE 문서를 참고하세요.
HTTPRoute 만들기
HTTPRoute 리소스는 GKE 게이트웨이가 수신되는 HTTP 요청을 InferencePool과 같은 백엔드 서비스로 라우팅하는 방법을 정의합니다. HTTPRoute 리소스는 일치 규칙 (예: 헤더 또는 경로)과 트래픽을 전달해야 하는 백엔드를 지정합니다.
HTTPRoute를 만들려면 다음 샘플 매니페스트를httproute.yaml로 저장합니다.apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: HTTPROUTE_NAME spec: parentRefs: - name: GATEWAY_NAME rules: - matches: - path: type: PathPrefix value: PATH_PREFIX backendRefs: - name: INFERENCE_POOL_NAME group: "inference.networking.k8s.io" kind: InferencePool다음을 바꿉니다.
HTTPROUTE_NAME:HTTPRoute리소스의 고유한 이름. 예를 들면my-route입니다.GATEWAY_NAME: 만든Gateway리소스의 이름. 예를 들면inference-gateway입니다.PATH_PREFIX: 수신 요청을 일치시키는 데 사용하는 경로 접두사. 예를 들어/는 모두 일치를 의미합니다.INFERENCE_POOL_NAME: 트래픽을 라우트하려는InferencePool리소스의 이름. 예를 들면vllm-llama3-8b-instruct입니다.
매니페스트를 클러스터에 적용합니다.
kubectl apply -f httproute.yaml
추론 요청 보내기
GKE 추론 게이트웨이를 구성한 후 배포된 모델에 추론 요청을 보낼 수 있습니다. 이를 통해 입력 프롬프트와 지정된 매개변수를 기반으로 텍스트를 생성할 수 있습니다.
추론 요청을 보내려면 다음 단계를 따르세요.
다음 환경 변수를 설정합니다.
export GATEWAY_NAME=GATEWAY_NAME export PORT_NUMBER=PORT_NUMBER # Use 80 for HTTP다음을 바꿉니다.
GATEWAY_NAME: 게이트웨이 리소스의 이름PORT_NUMBER: 게이트웨이에서 구성한 포트 번호
게이트웨이 엔드포인트를 가져오려면 다음 명령어를 실행합니다.
echo "Waiting for the Gateway IP address..." IP="" while [ -z "$IP" ]; do IP=$(kubectl get gateway/${GATEWAY_NAME} -o jsonpath='{.status.addresses[0].value}' 2>/dev/null) if [ -z "$IP" ]; then echo "Gateway IP not found, waiting 5 seconds..." sleep 5 fi done echo "Gateway IP address is: $IP" PORT=${PORT_NUMBER}curl을 사용하여/v1/completions엔드포인트에 요청을 전송하려면 다음 명령어를 실행합니다.curl -i -X POST ${IP}:${PORT}/v1/completions \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer $(gcloud auth application-default print-access-token)' \ -d '{ "model": "MODEL_NAME", "prompt": "PROMPT_TEXT", "max_tokens": MAX_TOKENS, "temperature": "TEMPERATURE" }'다음을 바꿉니다.
MODEL_NAME: 사용할 모델 또는 LoRA 어댑터의 이름PROMPT_TEXT: 모델의 입력 프롬프트MAX_TOKENS: 응답에서 생성할 최대 토큰 수TEMPERATURE: 출력의 무작위성 제어. 확정적인 출력을 위해0값을 사용하거나 더 창의적인 출력을 위해 더 높은 숫자를 사용합니다.
다음 예에서는 GKE 추론 게이트웨이에 샘플 요청을 보내는 방법을 보여줍니다.
curl -i -X POST ${IP}:${PORT}/v1/completions -H 'Content-Type: application/json' -H 'Authorization: Bearer $(gcloud auth print-access-token)' -d '{
"model": "food-review-1",
"prompt": "What is the best pizza in the world?",
"max_tokens": 2048,
"temperature": "0"
}'
다음 동작에 유의하세요.
- 요청 본문: 요청 본문에는
stop,top_p과 같은 추가 매개변수가 포함될 수 있습니다. 전체 옵션 목록은 OpenAI API 사양을 참고하세요. - 오류 처리: 응답의 잠재적 오류를 처리하기 위해 클라이언트 코드에서 적절한 오류 처리를 구현합니다. 예를 들어
curl응답의 HTTP 상태 코드를 확인합니다.200이 아닌 상태 코드는 일반적으로 오류를 나타냅니다. - 인증 및 승인: 프로덕션 배포의 경우 인증 및 승인 메커니즘으로 API 엔드포인트를 보호합니다. 요청에 적절한 헤더(예:
Authorization)를 포함합니다.