이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Cloud Storage의 일괄 예측

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

1. 입력 준비

Gemini 모델의 배치에서는 Cloud Storage에 저장된 하나의 JSON Lines (JSONL) 파일을 입력 데이터로 허용합니다. 일괄 입력 데이터의 각 행은 Gemini API와 동일한 형식을 따르는 모델에 대한 요청입니다.

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

{"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. 일괄 작업 제출

Google Cloud 콘솔, REST API 또는 Google Gen AI SDK를 사용하여 배치 작업을 만들 수 있습니다.

콘솔

Google Cloud 콘솔의 Vertex AI 섹션에서 일괄 추론 페이지로 이동합니다.

일괄 추론으로 이동
만들기를 클릭합니다.

REST

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

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

LOCATION: Gemini 모델을 지원하는 리전
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 데이터 세트 리전은 Vertex AI 일괄 예측 작업과 동일해야 합니다. Cloud Storage의 경우 버킷과 디렉터리 위치를 지정합니다(예: gs://mybucket/path/to/output).

HTTP 메서드 및 URL:

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

JSON 요청 본문:

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

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

curl

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs"

PowerShell

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs" | Select-Object -Expand Content

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

응답

{
  "name": "projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs/BATCH_JOB_ID",
  "displayName": "my-cloud-storage-batch-prediction-job",
  "model": "publishers/google/models/gemini-2.5-flash",
  "inputConfig": {
    "instancesFormat": "jsonl",
    "gcsSource": {
      "uris": [
        "INPUT_URI"
      ]
    }
  },
  "outputConfig": {
    "predictionsFormat": "OUTPUT_FORMAT",
    "DESTINATION": {
      "OUTPUT_URI_FIELD_NAME": "OUTPUT_URI"
    }
  },
  "state": "JOB_STATE_PENDING",
  "createTime": "2024-10-16T19:33:59.153782Z",
  "updateTime": "2024-10-16T19:33:59.153782Z",
  "modelVersionId": "1"
}

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

Python

설치

pip install --upgrade google-genai

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

Vertex AI에서 Gen 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/%PROJECT_ID%/locations/us-central1/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. 작업 상태 및 진행 상황 모니터링

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

콘솔

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

일괄 추론으로 이동
일괄 작업을 선택하여 진행 상황을 모니터링합니다.

REST

일괄 예측 작업을 모니터링하려면 projects.locations.batchPredictionJobs.get 메서드를 사용하고 응답에서 CompletionStats 필드를 확인합니다.

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

LOCATION: Gemini 모델을 지원하는 리전
PROJECT_ID: .
BATCH_JOB_ID: 일괄 작업 ID입니다.

HTTP 메서드 및 URL:

GET https://LOCATION-aiplatform.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://LOCATION-aiplatform.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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs/BATCH_JOB_ID" | Select-Object -Expand Content

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

응답

{
  "name": "projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs/BATCH_JOB_ID",
  "displayName": "my-cloud-storage-batch-prediction-job",
  "model": "publishers/google/models/gemini-2.5-flash",
  ...
  "state": "JOB_STATE_PENDING",
  "completionStats": {
    "successfulCount": "10",
    "failedCount": "1"
  },
  "createTime": "2024-10-16T19:33:59.153782Z",
  "updateTime": "2024-10-16T19:33:59.153782Z",
  "modelVersionId": "1"
}

Python

설치

pip install --upgrade google-genai

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

Vertex AI에서 Gen 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/us-central1/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": {}
}

Cloud Storage의 일괄 예측 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

1. 입력 준비

2. 일괄 작업 제출

콘솔

REST

curl

PowerShell

응답

Python

설치

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

콘솔

REST

curl

PowerShell

응답

Python

설치

4. 일괄 출력 검색

출력 예

Cloud Storage의 일괄 예측