BigQuery용 일괄 예측

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

1. 입력 준비

BigQuery 스토리지 입력

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

다음 값을 바꿉니다.

*   <var>PROJECT_ID</var>: The project that your service account was
    created in.
*   <var>SERVICE_ACCOUNT_ID</var>: The ID for the service account.
  • request 열이 필요하며 유효한 JSON이어야 합니다. 이 JSON 데이터는 모델의 입력을 나타냅니다.
  • request 열의 콘텐츠는 GenerateContentRequest의 구조와 일치해야 합니다. + 입력 테이블에는 request 이외의 열 데이터 유형이 있을 수 있습니다. 이러한 열에는 array, struct, range, datetime, geography를 제외한 BigQuery 데이터 유형이 있을 수 있습니다. 이러한 열은 콘텐츠 생성 시 무시되지만 출력 테이블에는 포함됩니다.
입력 예시(JSON) 
        
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Give me a recipe for banana bread."
        }
      ]
    }
  ],
  "system_instruction": {
    "parts": [
      {
        "text": "You are a chef."
      }
    ]
  }
}

2. 일괄 작업 제출

Google Cloud 콘솔, Google Gen AI SDK 또는 REST API를 통해 일괄 작업을 만들 수 있습니다.

작업과 테이블이 동일한 리전에 있어야 합니다.

콘솔

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

    일괄 추론으로 이동

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

REST

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

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

  • LOCATION: Gemini 모델을 지원하는 리전
  • PROJECT_ID: 프로젝트 ID
  • MODEL_PATH: 게시자 모델 이름(예: publishers/google/models/gemini-2.0-flash-001) 또는 조정된 엔드포인트 이름(예: projects/PROJECT_ID/locations/LOCATION/models/MODEL_ID)입니다. 여기서 MODEL_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": "MODEL_PATH",
  "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 응답이 수신됩니다.

응답에는 일괄 작업의 고유 식별자가 포함됩니다. 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 = f"bq://your-project.your_dataset.your_table"

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",
    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

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

작업이 제출되면 API, SDK, Cloud 콘솔을 사용하여 일괄 작업의 상태를 확인할 수 있습니다.

콘솔

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

    일괄 추론으로 이동

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

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

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

특정 일괄 작업의 상태는 다음 중 하나일 수 있습니다.

  • JOB_STATE_PENDING: 용량 대기열 작업이 running 상태로 전환되기 전 최대 72시간 동안 queue 상태일 수 있습니다.
  • JOB_STATE_RUNNING: 입력 파일의 유효성 검사가 완료되었으며 현재 일괄 처리가 실행되고 있습니다.
  • JOB_STATE_SUCCEEDED: 배치가 완료되었으며 결과가 준비되었습니다.
  • JOB_STATE_FAILED: 입력 파일이 검증 프로세스를 통과하지 못했거나 RUNNING 상태로 전환된 후 24시간 이내에 완료되지 않았습니다.
  • JOB_STATE_CANCELLING: 일괄 처리가 취소되는 중입니다.
  • JOB_STATE_CANCELLED: 일괄 처리가 취소됨

4. 일괄 출력 검색

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

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

결과 예시

성공적인 예

{
  "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
  }
}

실패한 예

  • 요청

    {"contents":[{"parts":{"text":"Explain how AI works in a few words."},"role":"tester"}]}

  • 응답

    Bad Request: {"error": {"code": 400, "message": "Please use a valid role: user, model.", "status": "INVALID_ARGUMENT"}}