Cloud Run에서 Gemma 3 실행

이 가이드에서는 사전 빌드된 컨테이너를 사용하여 Cloud Run에 Gemma 3 개방형 모델을 배포하는 방법을 설명하고, Google Gen AI SDK를 사용하여 배포된 Cloud Run 서비스를 사용하는 방법을 안내합니다.

시작하기 전에

Google AI Studio를 사용하여 Cloud Run에 배포한 경우 Google Gen AI SDK와 안전하게 상호작용 섹션으로 건너뛰세요.

Google AI Studio를 사용하지 않은 경우 Cloud Run을 사용하여 새 서비스를 만들기 전에 다음 단계를 따르세요.

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. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

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

6. Google Cloud 프로젝트에서 Cloud Run 개발 환경을 설정합니다.
7. gcloud CLI를 설치하고 초기화합니다.
8. 계정에 다음 IAM 역할이 부여되었는지 확인합니다.
   • Cloud Run 관리자(roles/run.admin)
   • 프로젝트 IAM 관리자(roles/resourcemanager.projectIamAdmin)
   • 서비스 사용량 소비자(roles/serviceusage.serviceUsageConsumer)

역할 부여 방법 알아보기

콘솔

1. Google Cloud 콘솔에서 IAM 페이지로 이동합니다.

   IAM으로 이동
2. 프로젝트를 선택합니다.
3. person_add 액세스 권한 부여를 클릭합니다.

4. 새 주 구성원 필드에 사용자 식별자를 입력합니다. 일반적으로 Cloud Run 서비스를 배포하는 데 사용되는 Google 계정 이메일 주소입니다.

5. 역할 선택 목록에서 역할을 선택합니다.
6. 역할을 추가로 부여하려면 add 다른 역할 추가를 클릭하고 각 역할을 추가합니다.
7. 저장을 클릭합니다.

gcloud

프로젝트에서 계정에 필요한 IAM 역할을 부여하려면 다음 단계를 따르세요.

        gcloud projects add-iam-policy-binding PROJECT_ID \
            --member=PRINCIPAL \
            --role=ROLE
        

다음과 같이 바꿉니다.

• PROJECT_NUMBER를 Google Cloud 프로젝트 번호로 바꿉니다.
• PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.
• PRINCIPAL을 바인딩을 추가할 계정으로 바꿉니다. 일반적으로 Cloud Run 서비스를 배포하는 데 사용되는 Google 계정 이메일 주소입니다.
• ROLE: 배포자 계정에 추가할 역할입니다.
9. 할당량 및 시스템 한도 페이지의 Cloud Run Admin API 아래에서 Total Nvidia L4 GPU allocation, per project per region 할당량을 요청합니다.
10. Cloud Run 가격 책정 페이지를 검토합니다. 프로젝트 사용량을 기준으로 예상 비용을 산출하려면 가격 계산기를 사용하세요.

사전 빌드된 컨테이너를 사용하여 Gemma 모델 배포

Cloud Run은 Cloud Run에서 Gemma 개방형 모델을 서빙하기 위해 사전 빌드된 컨테이너를 제공합니다.

Cloud Run에 Gemma 모델을 배포하려면 권장 설정과 함께 다음 gcloud CLI 명령어를 사용하세요.

gcloud run deploy SERVICE_NAME \
   --image us-docker.pkg.dev/cloudrun/container/gemma/GEMMA_PARAMETER \
   --concurrency 4 \
   --cpu 8 \
   --set-env-vars OLLAMA_NUM_PARALLEL=4 \
   --gpu 1 \
   --gpu-type nvidia-l4 \
   --max-instances 1 \
   --memory 32Gi \
   --no-allow-unauthenticated \
   --no-cpu-throttling \
   --timeout=600 \
   --region REGION

다음과 같이 바꿉니다.

• SERVICE_NAME을 Cloud Run 서비스의 고유 이름으로 바꿉니다.

• GEMMA_PARAMETER를 사용한 Gemma 모델로 바꿉니다.

  • Gemma 3 1B(gemma-3-1b-it): gemma3-1b
  • Gemma 3 4B(gemma-3-4b-it): gemma3-4b
  • Gemma 3 12B(gemma-3-12b-it): gemma3-12b
  • Gemma 3 27B(gemma-3-27b-it): gemma3-27b

  원하는 경우 전체 이미지 URL을 Gemma-on-Cloudrun GitHub 저장소에서 빌드한 Docker 이미지로 바꿉니다.

• REGION을 Cloud Run이 배포될 Google Cloud 리전으로 바꿉니다(예: europe-west1). 리전을 수정해야 하는 경우 GPU 구성을 참조하여 GPU 지원 배포에 지원되는 리전을 알아보세요.

기타 설정은 다음과 같습니다.

옵션	설명
--concurrency	지정된 인스턴스에서 동시에 처리할 수 있는 최대 요청 수입니다(예: 4). 최적의 요청 지연 시간에 관한 권장사항은 최적의 성능을 위한 동시 실행 설정을 참조하세요.
--cpu	서비스에 할당된 CPU의 양입니다(예: 8).
--set-env-vars	서비스에 설정된 환경 변수입니다. 예를 들면 OLLAMA_NUM_PARALLEL=4입니다. 최적의 요청 지연 시간에 관한 권장사항은 최적의 성능을 위한 동시 실행 설정을 참조하세요.
--gpu	서비스의 GPU 값입니다(예: 1).
--gpu-type	서비스에 사용할 GPU 유형입니다(예: nvidia-l4).
--max-instances	서비스의 최대 컨테이너 인스턴스 수입니다(예: 1).
--memory	서비스의 할당된 메모리 양입니다(예: 32Gi).
--no-invoker-iam-check	호출자 IAM 검사를 중지합니다. 앱을 더 안전하게 보호하는 방법에 관한 권장사항은 Google Gen AI SDK와 안전하게 상호작용을 참조하세요.
--no-cpu-throttling	이 설정은 컨테이너가 요청을 적극적으로 처리하지 않는 경우 CPU 제한을 중지합니다.
--timeout	응답이 반환되어야 하는 시간입니다(예: 600초).

기본 설정을 수정하거나 Cloud Run 서비스에 맞춤 설정을 추가해야 하는 경우 서비스 구성을 참조하세요.

배포된 서비스가 완료되면 run.app으로 끝나는 Cloud Run 엔드포인트 URL과 함께 성공 메시지가 표시됩니다.

curl로 배포된 Gemma 서비스 테스트

이제 Gemma 서비스를 배포했으므로 요청을 보낼 수 있습니다. 하지만 요청을 직접 전송하면 Cloud Run이 HTTP 401 Unauthorized로 응답합니다. LLM 추론 API는 프런트엔드 애플리케이션과 같이 다른 서비스를 호출하기 위한 것이므로 이는 의도된 것입니다. Cloud Run에서 서비스 간 인증에 대한 자세한 내용은 서비스 간 인증을 참조하세요.

Gemma 서비스에 요청을 전송하려면 Cloud Run 개발자 프록시를 사용하는 등 요청에 유효한 OIDC 토큰이 포함된 헤더를 추가합니다.

1. 프록시를 시작하고 cloud-run-proxy 구성요소를 설치하라는 메시지가 표시되면 Y를 선택합니다.

   gcloud run services proxy ollama-gemma --port=9090

2. 프록시를 실행 상태로 둔 채 별도의 터미널 탭에서 요청을 전송합니다. 프록시는 localhost:9090에서 실행됩니다.

   curl http://localhost:9090/api/generate -d '{
     "model": "gemma3:4b",
     "prompt": "Why is the sky blue?"
   }'

   이 명령어는 다음과 유사한 스트리밍 출력을 제공합니다.

   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.641492408Z","response":"That","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.687529153Z","response":"'","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.753284927Z","response":"s","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.812957381Z","response":" a","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.889102649Z","response":" fantastic","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.925748116Z","response":",","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.958391572Z","response":" decept","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.971035028Z","response":"ively","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.989678484Z","response":" tricky","done":false}
   {"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.999321940Z","response":" question","done":false}
   ...
   

Google Gen AI SDK와 안전하게 상호작용

Cloud Run 서비스를 배포한 후 Google Gen AI SDK와 함께 Cloud Run 엔드포인트를 사용할 수 있습니다.

Google Gen AI SDK를 사용하기 전에 수신 요청이 적절한 ID 토큰을 전달하는지 확인하세요. IAM 인증 및 Cloud Run 사용에 대해 자세히 알아보려면 서비스 간 인증을 참조하세요.

다음 예에서는 IAM 인증과 함께 Google Gen AI SDK를 사용하는 방법을 보여줍니다.

JavaScript 또는 TypeScript

JavaScript 및 TypeScript용 Google Gen AI SDK를 사용하는 경우 코드가 다음과 같을 수 있습니다.

import { GoogleGenAI, setDefaultBaseUrls } from "@google/genai";
import { GoogleAuth} from 'google-auth-library'

const cloudrunurl = 'https://CLOUD_RUN_SERVICE_URL';
const targetAudience = url;

const auth = new GoogleAuth();

async function main() {

  const client = await auth.getIdTokenClient(targetAudience);
  const headers = await client.getRequestHeaders(targetAudience);
  const idToken = headers['Authorization']

const ai = new GoogleGenAI({
  apiKey:"placeholder",
  httpOptions: { baseUrl: url, headers: {'Authorization': idToken}  },
});

  const response = await ai.models.generateContent({
    model: "gemma-3-1b-it",
    contents: "I want a pony",
  });
  console.log(response.text);
}

main();

curl

curl을 사용하는 경우 다음 명령어를 실행하여 Google Gen AI SDK 엔드포인트에 도달합니다.

• 콘텐츠 생성의 경우 /v1beta/{model=models/*}:generateContent를 사용합니다. 입력 GenerateContentRequest가 주어지면 모델 대답을 생성합니다.

  curl "<cloud_run_url>/v1beta/models/<model>:generateContent" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  -X POST \
  -d '{
    "contents": [{
      "parts":[{"text": "Write a story about a magic backpack. You are the narrator of an interactive text adventure game."}]
      }]
      }'
  

• 스트림 콘텐츠 생성의 경우 /v1beta/{model=models/*}:streamGenerateContent를 사용합니다. 입력 GenerateContentRequest가 주어지면 모델에서 스트리밍된 대답을 생성합니다.

  curl "<cloud_run_url>/v1beta/models/<model>:streamGenerateContent" \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
    -X POST \
    -d '{
      "contents": [{
        "parts":[{"text": "Write a story about a magic backpack. You are the narrator of an interactive text adventure game."}]
        }]
        }'
  

최적의 성능을 위한 동시 실행 설정

이 섹션에서는 권장되는 동시 실행 설정에 대한 컨텍스트를 제공합니다. 최적의 요청 지연 시간을 위해 --concurrency 설정이 Ollama의 OLLAMA_NUM_PARALLEL 환경 변수와 동일한지 확인합니다.

• OLLAMA_NUM_PARALLEL는 추론 요청을 동시에 처리하기 위해 각 모델당 사용할 수 있는 요청 슬롯 수를 결정합니다.
• --concurrency는 Cloud Run이 Ollama 인스턴스에 동시에 전송하는 요청 수를 결정합니다.

--concurrency가 OLLAMA_NUM_PARALLEL을 초과하면 Cloud Run은 Ollama의 모델에 사용 가능한 요청 슬롯보다 더 많은 요청을 보낼 수 있습니다. 이로 인해 Ollama 내에서 요청 큐가 발생하여 큐에 추가된 요청에 대해 요청 지연 시간이 늘어납니다. 또한 대기열에 추가된 요청이 Cloud Run을 수평 확장하고 새 인스턴스를 시작하도록 트리거하지 않으므로 자동 확장의 응답성이 떨어집니다.

Ollama는 또한 하나의 GPU에서 여러 모델을 서빙하도록 지원합니다. Ollama 인스턴스에서 요청 큐를 완전히 방지하려면 여전히 OLLAMA_NUM_PARALLEL와 일치하도록 --concurrency를 설정해야 합니다.

OLLAMA_NUM_PARALLEL을 늘리면 동시 요청 시간이 더 오래 걸릴 수 있습니다.

사용률 최적화

최적의 GPU 사용률을 위해서는 --concurrency를 늘려서 OLLAMA_NUM_PARALLEL 값의 두 배 이내로 유지합니다. 이렇게 하면 Ollama에서 요청이 큐에 추가되지만 사용률을 개선하는 데 도움이 될 수 있습니다. Ollama 인스턴스는 큐의 요청을 즉시 처리할 수 있으며 큐는 트래픽 급증을 흡수하는 데 도움이 됩니다.

삭제

생성된 다음 Google Cloud 리소스를 삭제합니다.

• Cloud Run 서비스
• 컨테이너 이미지

다음 단계

• GPU 구성
• 권장사항: GPU를 사용하는 Cloud Run의 AI 추론
• 다양한 AI 런타임 프레임워크로 Gemma 3 모델 실행