이 페이지는 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 메서드를 사용합니다.

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

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 데이터 세트 리전은 Vertex AI 일괄 예측 작업과 동일해야 합니다. 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-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://ENDPOINT_PREFIXaiplatform.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://ENDPOINT_PREFIXaiplatform.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는 지원되지 않습니다.

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. 작업 상태 및 진행 상황 모니터링

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

콘솔

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

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

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 응답이 수신됩니다.

응답

{
  "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에서 생성형 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": {}
}

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

1. 입력 준비

2. 일괄 작업 제출

콘솔

REST

curl

PowerShell

응답

Python

설치

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

콘솔

REST

curl

PowerShell

응답

Python

설치

4. 일괄 출력 검색

출력 예시

Cloud Storage의 일괄 예측