Cloud Storage에서 일괄 추론

이 페이지에서는 Cloud Storage를 사용하여 일괄 추론을 가져오는 방법을 설명합니다.

1. 입력 준비

Gemini 모델의 일괄 추론에서는 Cloud Storage에 저장된 하나의 JSON Lines (JSONL) 파일을 입력 데이터로 허용합니다. 일괄 입력 데이터의 각 행은 모델에 대한 요청입니다.

예를 들면 다음과 같습니다.

{"request":{"contents": [{"role": "user", "parts": [{"text": "What is the relation between the following video and image samples?"}, {"fileData": {"fileUri": "gs://cloud-samples-data/generative-ai/video/animals.mp4", "mimeType": "video/mp4"}}, {"fileData": {"fileUri": "gs://cloud-samples-data/generative-ai/image/cricket.jpeg", "mimeType": "image/jpeg"}}]}], "generationConfig": {"temperature": 0.9, "topP": 1, "maxOutputTokens": 256}}}

샘플 일괄 요청 파일 다운로드

입력 데이터를 준비하고 Cloud Storage에 업로드한 후 AI Platform 서비스 에이전트에게 Cloud Storage 파일을 읽을 권한이 있는지 확인합니다.

2. 일괄 작업 제출

Cloud de Confiance 콘솔, REST API 또는 Google 생성형 AI SDK를 사용하여 일괄 작업을 만들 수 있습니다.

콘솔

  1. 콘솔의 Agent Platform 섹션에서 Cloud de Confiance 일괄 추론 페이지로 이동합니다.

    일괄 추론으로 이동

  2. 만들기를 클릭합니다.

REST

일괄 추론 작업을 만들려면 projects.locations.batchPredictionJobs.create 메서드를 사용합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • ENDPOINT_PREFIX: 모델 리소스의 리전이며 뒤에 -이 이어집니다. 예를 들면 us-central1-입니다. 전역 엔드포인트를 사용하는 경우 비워 둡니다. 참고: 조정된 모델을 사용한 일괄 추론에는 전역 엔드포인트가 지원되지 않습니다.
  • LOCATION: Gemini 모델을 지원하는 리전. 전역 엔드포인트를 사용하는 경우 global을 입력합니다.
  • PROJECT_ID: 프로젝트 ID
  • MODEL_PATH: 게시자 모델 이름(예: publishers/google/models/gemini-2.5-flash) 또는 조정된 엔드포인트 이름(예: projects/PROJECT_ID/locations/LOCATION/models/MODEL_ID). 여기서 MODEL_ID는 조정된 모델의 모델 ID입니다.
  • INPUT_URI: JSONL 일괄 추론 입력의 Cloud Storage 위치(예: gs://bucketname/path/to/file.jsonl)
  • OUTPUT_FORMAT: Cloud Storage 버킷에 출력하려면 jsonl을 지정합니다.
  • DESTINATION: BigQuery의 경우 bigqueryDestination을 지정합니다. Cloud Storage의 경우 gcsDestination을 지정합니다.
  • OUTPUT_URI_FIELD_NAME: BigQuery의 경우 outputUri을 지정합니다. Cloud Storage의 경우 outputUriPrefix을 지정합니다.
  • OUTPUT_URI: BigQuery의 경우 테이블 위치(예: bq://myproject.mydataset.output_result)를 지정합니다. 출력 BigQuery 데이터 세트 리전은 Agent Platform 일괄 추론 작업의 리전과 동일해야 합니다. Cloud Storage의 경우 버킷과 디렉터리 위치를 지정합니다(예: gs://mybucket/path/to/output).

HTTP 메서드 및 URL: 

POST https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs

JSON 요청 본문: 

{
  "displayName": "my-cloud-storage-batch-inference-job",
  "model": "MODEL_PATH",
  "inputConfig": {
    "instancesFormat": "jsonl",
    "gcsSource": {
      "uris" : "INPUT_URI"
    }
  },
  "outputConfig": {
    "predictionsFormat": "OUTPUT_FORMAT",
    "DESTINATION": {
      "OUTPUT_URI_FIELD_NAME": "OUTPUT_URI"
    }
  }
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다. 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs"

PowerShell

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다. 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 수신됩니다.

응답에는 일괄 작업의 고유 식별자가 포함됩니다. BATCH_JOB_ID를 사용하여 일괄 작업의 상태를 폴링할 수 있습니다. 자세한 내용은 작업 상태 모니터링을 참조하세요. 참고: 커스텀 서비스 계정과 CMEK는 지원되지 않습니다.

Python

설치

pip install --upgrade google-genai

자세한 내용은 SDK 참고 문서를 참고하세요.

Vertex AI에서 생성형 AI SDK를 사용하도록 환경 변수를 설정합니다. 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 

import time

from google import genai
from google.genai.types import CreateBatchJobConfig, JobState, HttpOptions

client = genai.Client(http_options=HttpOptions(api_version="v1"))
# TODO(developer): Update and un-comment below line
# output_uri = "gs://your-bucket/your-prefix"

# See the documentation: https://googleapis.github.io/python-genai/genai.html#genai.batches.Batches.create
job = client.batches.create(
    # To use a tuned model, set the model param to your tuned model using the following format:
    # model="projects/{PROJECT_ID}/locations/{LOCATION}/models/{MODEL_ID}
    model="gemini-2.5-flash",
    # Source link: https://storage.cloud.google.com/cloud-samples-data/batch/prompt_for_batch_gemini_predict.jsonl
    src="gs://cloud-samples-data/batch/prompt_for_batch_gemini_predict.jsonl",
    config=CreateBatchJobConfig(dest=output_uri),
)
print(f"Job name: {job.name}")
print(f"Job state: {job.state}")
# Example response:
# Job name: projects/.../locations/.../batchPredictionJobs/9876453210000000000
# Job state: JOB_STATE_PENDING

# See the documentation: https://googleapis.github.io/python-genai/genai.html#genai.types.BatchJob
completed_states = {
    JobState.JOB_STATE_SUCCEEDED,
    JobState.JOB_STATE_FAILED,
    JobState.JOB_STATE_CANCELLED,
    JobState.JOB_STATE_PAUSED,
}

while job.state not in completed_states:
    time.sleep(30)
    job = client.batches.get(name=job.name)
    print(f"Job state: {job.state}")
# Example response:
# Job state: JOB_STATE_PENDING
# Job state: JOB_STATE_RUNNING
# Job state: JOB_STATE_RUNNING
# ...
# Job state: JOB_STATE_SUCCEEDED

3. 작업 상태 및 진행 상황 모니터링

작업이 제출된 후에는 Cloud de Confiance 콘솔, REST API 또는 Google Gen AI SDK를 사용하여 일괄 작업의 상태를 확인할 수 있습니다.

콘솔

  1. 일괄 추론 페이지로 이동합니다.

    일괄 추론으로 이동

  2. 일괄 작업을 선택하여 진행 상황을 모니터링합니다.

REST

일괄 추론 작업을 모니터링하려면 projects.locations.batchPredictionJobs.get 메서드를 사용하고 응답에서 CompletionStats 필드를 봅니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • ENDPOINT_PREFIX: 모델 리소스의 리전이며 뒤에 -이 이어집니다. 예를 들면 us-central1-입니다. 전역 엔드포인트를 사용하는 경우 비워 둡니다.
  • LOCATION: Gemini 모델을 지원하는 리전. 전역 엔드포인트를 사용하는 경우 global을 입력합니다.
  • PROJECT_ID: 프로젝트 ID
  • BATCH_JOB_ID: 일괄 작업 ID

HTTP 메서드 및 URL: 

GET https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs/BATCH_JOB_ID

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

다음 명령어를 실행합니다. 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs/BATCH_JOB_ID"

PowerShell

다음 명령어를 실행합니다. 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://ENDPOINT_PREFIXaiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs/BATCH_JOB_ID" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 수신됩니다.

Python

설치

pip install --upgrade google-genai

자세한 내용은 SDK 참고 문서를 참고하세요.

Vertex AI에서 생성형 AI SDK를 사용하도록 환경 변수를 설정합니다. 

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
 

    from google import genai
    from google.genai.types import HttpOptions

    client = genai.Client(http_options=HttpOptions(api_version="v1"))

    # Get the batch job
# Eg. batch_job_name = "projects/123456789012/locations/.../batchPredictionJobs/1234567890123456789"
    batch_job = client.batches.get(name=batch_job_name)

    print(f"Job state: {batch_job.state}")
    # Example response:
    # Job state: JOB_STATE_PENDING
    # Job state: JOB_STATE_RUNNING
    # Job state: JOB_STATE_SUCCEEDED

작업 상태에 대한 설명은 JobState를 참조하세요.

4. 일괄 출력 검색

일괄 추론 작업이 완료되면 작업 생성 시 지정한 Cloud Storage 버킷에 출력이 저장됩니다. 성공한 행의 경우 모델 응답이 response 필드에 저장됩니다. 그렇지 않으면 오류 세부정보가 status 필드에 저장되어 추가 검사를 받을 수 있습니다.

장기 실행 작업 중에 완료된 추론은 지정된 출력 대상으로 지속적으로 내보내집니다. 일괄 추론 작업이 종료되면 완료된 모든 행이 내보내집니다. 완료된 추론에 대해서만 비용이 청구됩니다.

출력 예시

성공적인 예시

{
  "status": "",
  "processed_time": "2024-11-01T18:13:16.826+00:00",
  "request": {
    "contents": [
      {
        "parts": [
          {
            "fileData": null,
            "text": "What is the relation between the following video and image samples?"
          },
          {
            "fileData": {
              "fileUri": "gs://cloud-samples-data/generative-ai/video/animals.mp4",
              "mimeType": "video/mp4"
            },
            "text": null
          },
          {
            "fileData": {
              "fileUri": "gs://cloud-samples-data/generative-ai/image/cricket.jpeg",
              "mimeType": "image/jpeg"
            },
            "text": null
          }
        ],
        "role": "user"
      }
    ]
  },
  "response": {
    "candidates": [
      {
        "avgLogprobs": -0.5782725546095107,
        "content": {
          "parts": [
            {
              "text": "This video shows a Google Photos marketing campaign where animals at the Los Angeles Zoo take self-portraits using a modified Google phone housed in a protective case. The image is unrelated."
            }
          ],
          "role": "model"
        },
        "finishReason": "STOP"
      }
    ],
    "modelVersion": "gemini-2.0-flash-001@default",
    "usageMetadata": {
      "candidatesTokenCount": 36,
      "promptTokenCount": 29180,
      "totalTokenCount": 29216
    }
  }
}

실패한 예시

{
  "status": "Bad Request: {\"error\": {\"code\": 400, \"message\": \"Please use a valid role: user, model.\", \"status\": \"INVALID_ARGUMENT\"}}",
  "processed_time": "2025-07-09T19:57:43.558+00:00",
  "request": {
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ],
        "role": "tester"
      }
    ]
  },
  "response": {}
}