일괄 예측

일괄 예측은 대규모 데이터 세트에 머신러닝 모델을 효율적으로 적용하는 데 유용한 기술입니다. 개별 데이터 포인트를 처리하는 대신 예측을 위해 Gemini에 일괄 데이터를 제출하여 시간과 계산 리소스를 절약할 수 있습니다. 한 번에 입력 프롬프트 하나로 제한되는 온라인 예측과 달리 단일 일괄 요청에서 다수의 멀티모달 프롬프트를 전송할 수 있습니다. 그러면 응답이 BigQuery 또는 Cloud Storage 저장소 출력 위치에 비동기식으로 채워집니다.

Gemini 모델의 일괄 요청은 표준 요청보다 50% 할인됩니다. 자세한 내용은 가격 책정 페이지를 참조하세요.

일괄 예측 사용 사례

데이터베이스에 수천 권의 책이 있는 온라인 서점을 생각해 보세요. 이 서점은 각 도서에 대해 개별적으로 설명을 생성하는 시간이 많이 걸리는 절차 대신 Gemini 일괄 예측을 사용하여 모든 도서 정보를 한 번에 처리할 수 있습니다. 이 접근 방식은 전반적인 처리 시간을 줄이고 필요한 계산 리소스를 최소화하여 효율성을 크게 개선합니다.

일괄 예측을 사용하면 자동화의 일관성도 개선할 수 있습니다. 모든 설명을 동시에 처리함으로써 모델은 도서 설명 전반에서 일관된 어조와 스타일을 유지하여 브랜드 아이덴티티를 강화합니다. 이 서점은 일괄 예측을 워크플로에 통합하여 새 책 항목의 설명을 자동으로 생성할 수도 있습니다. 이렇게 하면 수동 작업이 줄어들고 최소한의 사람의 개입으로 웹사이트가 최신 상태로 유지됩니다.

일괄 예측을 지원하는 Gemini 모델

다음 Gemini 모델은 일괄 예측을 지원합니다.

Gemini 모델에 대한 일괄 요청은 BigQuery 스토리지 소스와 Cloud Storage 소스를 허용합니다. BigQuery 테이블 또는 Cloud Storage 버킷의 JSONL 파일 중 하나에 예측을 출력하도록 독립적으로 선택할 수 있습니다.

Cloud Storage를 위한 일괄 예측

입력 준비

Cloud Storage 입력

  • 파일 형식: JSON Lines(JSONL)
  • 위치: us-central1
  • 서비스 계정에 적절한 Cloud Storage 권한이 있어야 합니다. Cloud Storage 버킷에 대한 읽기 및 쓰기 권한을 서비스 계정에 부여하려면 다음과 같이 gcloud iam service-accounts add-iam-policy-binding 명령어를 사용합니다.

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member="serviceAccount:SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com" \
        --role="storage.objectUser"
    

    다음 값을 바꿉니다.

    • PROJECT_ID: 서비스 계정이 생성된 프로젝트
    • SERVICE_ACCOUNT_ID: 서비스 계정의 ID
  • 다음 Gemini 모델은 fileData를 지원합니다.

    • gemini-2.0-flash-001
    • gemini-2.0-flash-lite-001
입력 예시(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"}}]}]}}
{"request":{"contents": [{"role": "user", "parts": [{"text": "Describe what is happening in this video."}, {"fileData": {"fileUri": "gs://cloud-samples-data/generative-ai/video/another_video.mov", "mimeType": "video/mov"}}]}]}}
        

일괄 예측 작업 요청

Cloud Storage 입력 테이블, 모델, 출력 위치를 지정합니다.

REST

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

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

  • LOCATION: Gemini 모델을 지원하는 리전
  • PROJECT_ID: 프로젝트 ID
  • INPUT_URI: JSONL 일괄 예측 입력의 Cloud Storage 위치(예: gs://bucketname/path/to/file.jsonl)
  • OUTPUT_FORMAT: BigQuery 테이블에 출력하려면 bigquery를 지정. 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": "publishers/google/models/gemini-2.0-flash-001",
  "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://LOCATION-aiplatform.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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs" | Select-Object -Expand Content

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

응답에는 일괄 작업의 고유 식별자가 포함됩니다. 작업 stateJOB_STATE_SUCCEEDED가 될 때까지 BATCH_JOB_ID를 사용하여 일괄 작업의 상태를 폴링할 수 있습니다. 예를 들면 다음과 같습니다.

curl \
  -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/batchPredictionJobs/BATCH_JOB_ID

Gen AI SDK for 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=us-central1
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(
    model="gemini-2.0-flash-001",
    # 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

일괄 예측 출력

일괄 예측 태스크가 완료되면 출력은 요청에 지정한 Cloud Storage 버킷이나 BigQuery 테이블에 저장됩니다. 성공한 행의 경우 모델 응답이 response 열에 저장됩니다. 그렇지 않으면 오류 세부정보가 추가 검사를 위해 status 열에 저장됩니다.

장기 실행 작업 중에 완료된 예측은 지정된 출력 대상으로 지속적으로 내보내집니다. 90분 후에 시작됩니다. 일괄 예측 작업이 취소되거나 실패하면 완료된 모든 예측이 내보내집니다.

Cloud Storage 출력 예시

{
  "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-1.5-flash-002@default",
    "usageMetadata": {
      "candidatesTokenCount": 36,
      "promptTokenCount": 29180,
      "totalTokenCount": 29216
    }
  }
}

BigQuery용 일괄 예측

BigQuery 입력 테이블, 모델, 출력 위치를 지정합니다. 일괄 예측 작업과 테이블이 동일한 리전에 있어야 합니다.

입력 준비

BigQuery 스토리지 입력

  • 서비스 계정에 적절한 BigQuery 권한이 있어야 합니다. 서비스 계정에 BigQuery 사용자 역할을 부여하려면 다음과 같이 gcloud iam service-accounts add-iam-policy-binding 명령어를 사용합니다.

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member="serviceAccount:SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com" \
        --role="roles/bigquery.user"
    

    다음 값을 바꿉니다.

    • PROJECT_ID: 서비스 계정이 생성된 프로젝트
    • SERVICE_ACCOUNT_ID: 서비스 계정의 ID
  • request 열은 필수이며 유효한 JSON이어야 합니다. 이 JSON 데이터는 모델의 입력을 나타냅니다.

  • request 열의 콘텐츠는 GenerateContentRequest의 구조와 일치해야 합니다.

  • 입력 테이블에는 request 이외의 열 데이터 유형이 있을 수 있습니다. 이러한 열에는 배열, 구조체, 범위, 날짜/시간, 지역을 제외한 모든 BigQuery 데이터 유형을 사용할 수 있습니다. 이러한 열은 콘텐츠 생성 시 무시되지만 출력 테이블에는 포함됩니다. 시스템은 출력용으로 두 개의 열 이름(responsestatus)을 예약합니다. 이는 일괄 예측 작업의 결과에 관한 정보를 제공하는 데 사용됩니다.

  • 다음 Gemini 모델은 fileData를 지원합니다.

    • gemini-2.0-flash-001
    • gemini-2.0-flash-lite-001
    • gemini-1.5-flash-002
    • gemini-1.5-flash-001
    • gemini-1.5-pro-002
    • gemini-1.5-pro-001
입력 예시(JSON)
        
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Give me a recipe for banana bread."
        }
      ]
    }
  ],
  "system_instruction": {
    "parts": [
      {
        "text": "You are a chef."
      }
    ]
  }
}
        
        

일괄 예측 작업 요청

REST

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

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

  • LOCATION: Gemini 모델을 지원하는 리전
  • PROJECT_ID: 프로젝트 ID
  • INPUT_URI: 일괄 예측 입력이 있는 BigQuery 테이블(예: bq://myproject.mydataset.input_table). 멀티 리전 데이터 세트는 지원되지 않습니다.
  • OUTPUT_FORMAT: BigQuery 테이블에 출력하려면 bigquery를 지정. 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-bigquery-batch-prediction-job",
  "model": "publishers/google/models/gemini-2.0-flash-001",
  "inputConfig": {
    "instancesFormat": "bigquery",
    "bigquerySource":{
      "inputUri" : "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://LOCATION-aiplatform.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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/batchPredictionJobs" | Select-Object -Expand Content

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

응답에는 일괄 작업의 고유 식별자가 포함됩니다. 작업 stateJOB_STATE_SUCCEEDED가 될 때까지 BATCH_JOB_ID를 사용하여 일괄 작업의 상태를 폴링할 수 있습니다. 예를 들면 다음과 같습니다.

curl \
  -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/batchPredictionJobs/BATCH_JOB_ID

Gen AI SDK for 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=us-central1
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 = f"bq://your-project.your_dataset.your_table"

job = client.batches.create(
    model="gemini-2.0-flash-001",
    src="bq://storage-samples.generative_ai.batch_requests_for_multimodal_input",
    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

일괄 출력 검색

일괄 예측 태스크가 완료되면 출력은 요청에 지정한 BigQuery 테이블에 저장됩니다.

성공한 행의 경우 모델 응답이 response 열에 저장됩니다. 그렇지 않으면 오류 세부정보가 추가 검사를 위해 status 열에 저장됩니다.

BigQuery 출력 예시

요청 응답 상태
{"content":[{...}]}
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "In a medium bowl, whisk together the flour, baking soda, baking powder."
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.14057204,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.14270912
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 8,
    "candidatesTokenCount": 396,
    "totalTokenCount": 404
  }
}

다음 단계