일괄 예측 가져오기

일괄 예측 요청은 비동기식 요청입니다(반면 온라인 예측은 동기식 요청임). 모델 리소스에서 직접 일괄 예측을 요청합니다. 엔드포인트에 모델을 배포할 필요가 없습니다. 일괄 예측과 온라인 예측을 모두 지원하는 데이터 유형의 경우 즉각적인 응답이 필요하지 않고 단일 요청을 사용하여 누적된 데이터를 처리하려면 일괄 예측을 사용합니다.

일괄 예측을 수행하려면 Vertex AI가 예측 결과를 저장하는 입력 소스와 출력 위치를 지정합니다. 입력과 출력은 작업 중인 모델 유형에 따라 다릅니다. 예를 들어 AutoML 이미지 모델 유형의 일괄 예측에는 입력 JSON Lines 파일과 출력을 저장할 Cloud Storage 버킷 이름이 필요합니다.

일괄 요청 입력

일괄 요청의 입력은 예측을 위해 모델에 보낼 항목을 지정합니다. 다음 콘텐츠에서는 각 모델 유형의 입력 형식 요구사항을 제공합니다.

커스텀 학습됨

커스텀 학습 모델에서 일괄 예측을 가져오려면 다음 방법 중 하나로 입력 데이터를 준비합니다.

JSON Lines

JSON Lines 파일을 사용하여 예측할 입력 인스턴스 목록을 지정합니다. Cloud Storage 버킷에 JSON Lines 파일을 저장합니다.

예시 1

다음 예시에서는 입력 JSON Lines 파일의 인스턴스 두 개를 보여줍니다.

[1, 2, 3, 4]
[5, 6, 7, 8]

다음은 HTTP 요청 본문의 예측 컨테이너로 전송되는 항목입니다.

{"instances": [
  [1, 2, 3, 4],
  [5, 6, 7, 8]
]}

예시 2

다음 예시에서는 예측 컨테이너가 객체를 예상하는 입력 JSON Lines 파일의 인스턴스 두 개를 보여줍니다.

{"values": [1, 2, 3, 4], "key": 1}
{"values": [5, 6, 7, 8], "key": 2}

다음은 HTTP 요청 본문의 예측 컨테이너로 전송되는 항목입니다.

{"instances": [
  {"values": [1, 2, 3, 4], "key": 1},
  {"values": [5, 6, 7, 8], "key": 2}
]}

TFRecord

입력 인스턴스를 TFRecord 형식으로 저장합니다. 원하는 경우 Gzip으로 TFRecord 파일을 압축할 수 있습니다. TFRecord 파일을 Cloud Storage 버킷에 저장합니다.

Vertex AI는 TFRecord 파일의 각 인스턴스를 바이너리로 읽은 후 b64라는 단일 키를 사용하여 인스턴스를 JSON 객체로 base64로 인코딩합니다.

다음은 HTTP 요청 본문의 예측 컨테이너로 전송되는 항목입니다.

{"instances": [
 {"b64","b64EncodedASCIIString"},
 {"b64","b64EncodedASCIIString"}
]}

예측 컨테이너가 인스턴스를 디코딩하는 방법을 알고 있는지 확인합니다.

CSV

CSV 파일에서 행마다 입력 인스턴스를 한 개 지정하세요. 첫 번째 행은 헤더 행이어야 합니다. 모든 문자열을 큰따옴표(")로 묶어야 합니다. 줄바꿈 문자를 포함한 셀 값은 허용되지 않습니다. 따옴표가 없는 값은 부동 소수점 숫자로 읽힙니다.

다음 예시는 두 개의 입력 인스턴스가 있는 CSV 파일을 보여줍니다.

"input1","input2","input3"
0.1,1.2,"cat1"
4.0,5.0,"cat2"

다음은 HTTP 요청 본문의 예측 컨테이너로 전송되는 항목입니다.

{"instances": [
 [0.1,1.2,"cat1"],
 [4.0,5.0,"cat2"]
]}

파일 목록

각 행이 파일의 Cloud Storage URI인 텍스트 파일을 만듭니다. Vertex AI는 각 파일의 콘텐츠를 바이너리로 읽은 후 b64라는 단일 키를 사용하여 인스턴스를 JSON 객체로 base64로 인코딩합니다.

Google Cloud Console을 사용하여 일괄 예측을 가져오려면 먼저 Google Cloud Console에 직접 파일 목록을 붙여넣습니다. 그렇지 않으면 파일 목록을 Cloud Storage 버킷에 저장합니다.

다음 예시는 두 개의 입력 인스턴스가 있는 파일 목록을 보여줍니다.

gs://path/to/image/image1.jpg
gs://path/to/image/image2.jpg

다음은 HTTP 요청 본문의 예측 컨테이너로 전송되는 항목입니다.

{"instances": [
 {"b64","b64EncodedASCIIString"},
 {"b64","b64EncodedASCIIString"}
]}

예측 컨테이너가 인스턴스를 디코딩하는 방법을 알고 있는지 확인합니다.

BigQuery

BigQuery 테이블을 projectId.datasetId.tableId로 지정합니다. Vertex AI는 테이블의 각 행을 JSON 인스턴스로 변환합니다.

예를 들어 테이블에 다음이 포함되어 있다고 가정합니다.

열 1	열 2	열 3
1.0	3.0	"Cat1"
2.0	4.0	"Cat2"

다음은 HTTP 요청 본문의 예측 컨테이너로 전송되는 항목입니다.

{"instances": [
 [1.0,3.0,"cat1"],
 [2.0,4.0,"cat2"]
]}

BigQuery 데이터 유형이 JSON으로 변환되는 방식은 다음과 같습니다.

BigQuery 유형	JSON 유형	예시 값
문자열	문자열	"abc"
정수	정수	1
부동 소수점	부동 소수점	1.2
숫자	부동 소수점	4925.000000000
불리언	불리언	true
TimeStamp	문자열	"2019-01-01 23:59:59.999999+00:00"
Date	문자열	"2018-12-31"
시간	문자열	"23:59:59.999999"
DateTime	문자열	"2019-01-01T00:00:00"
레코드	객체	{ "A": 1,"B": 2}
반복 유형	Array[Type]	[1, 2]
중첩 레코드	객체	{"A": {"a": 0}, "B": 1}

이미지

JSON Lines 파일을 사용하여 예측을 수행할 이미지 목록을 지정한 후 JSON Lines 파일을 Cloud Storage 버킷에 저장합니다. 다음 샘플에서는 입력 JSON Lines 파일의 단일 줄을 보여줍니다.

{"content": "gs://sourcebucket/datasets/images/source_image.jpg", "mimeType": "image/jpeg"}

테이블 형식

테이블 형식 데이터의 경우 Cloud Storage 버킷의 CSV 파일 또는 BigQuery의 테이블을 사용할 수 있습니다. Cloud Storage의 CSV로 또는 BigQuery의 테이블로 예측 데이터를 제공할 수 있습니다. 학습 및 예측 데이터에 동일한 입력 형식을 사용하는 것이 좋습니다. Vertex AI는 모든 CSV 입력 필드를 문자열로 취급하므로 학습 및 예측에서 다른 입력 형식을 사용하면 오류가 발생할 수 있습니다. 예를 들어 BigQuery에서 데이터를 사용하여 모델을 학습시켰으면 BigQuery 테이블을 일괄 예측의 소스로 사용하는 것이 가장 좋습니다.

데이터 소스에는 모델 학습에 사용된 모든 열을 어떤 순서대로든 포함하는 테이블 형식 데이터가 있어야 합니다. 학습 데이터에 없거나, 학습 데이터에는 있지만 학습에 사용할 수 없는 열을 포함할 수 있습니다. 이러한 추가 열은 예측 출력에 포함되지만 예측 생성에는 사용되지 않습니다.

결과에 예측 데이터와 동일한 대상을 사용할 필요가 없습니다. 예를 들어 예측 데이터 소스에 BigQuery를 사용한 경우 Cloud Storage의 CSV 파일로 결과를 보낼 수 있습니다.

BigQuery 테이블 요구사항

BigQuery 데이터 소스 테이블은 100GB를 넘지 않아야 합니다.
US 또는 EU 위치에 있는 멀티 리전 BigQuery 데이터 세트를 사용해야 합니다.
테이블이 다른 프로젝트에 있으면 해당 프로젝트의 Vertex AI 서비스 계정에 BigQuery Data Editor 역할을 제공해야 합니다.

CSV 파일 요구사항

데이터 소스는 열 이름이 있는 헤더 행으로 시작해야 합니다.
각 데이터 소스 파일은 10GB를 넘지 않아야 합니다. 여러 파일을 포함할 수도 있지만 최대 용량은 100GB로 제한됩니다.
Cloud Storage 버킷이 Vertex AI를 사용하는 곳과 다른 프로젝트에 있는 경우, Storage Object Creator 역할을 해당 프로젝트의 Vertex AI 서비스 계정에 제공해야 합니다.
모든 문자열을 큰따옴표(")로 묶어야 합니다.

예측 요구사항

BigQuery 테이블 또는 CSV 파일 요구사항 외에도 예측 모델의 입력은 다음 요구사항을 준수해야 합니다.

시간 열의 모든 값이 있고 유효해야 합니다.
일괄 예측 테이블의 데이터 빈도는 학습 데이터와 동일한 빈도여야 합니다. 시계열에 누락된 행이 있으면 안 됩니다. 적절한 도메인 지식에 따라 누락된 행을 수동으로 삽입합니다.
타임스탬프가 중복된 시계열은 예측에서 삭제됩니다. 이러한 시계열을 포함하려면 중복 타임스탬프를 삭제하세요.
예측할 각 시계열의 이전 데이터를 제공합니다. 가장 정확한 예측을 얻으려면 데이터 양이 학습에 설정된 환경설정 기간과 같아야 합니다. 데이터를 더 적게 제공하는 경우 Vertex AI는 값이 비어 있는 데이터를 패딩합니다. 예를 들어 환경설정 기간이 14일인 경우 최소 14일의 이전 데이터를 제공합니다.
예측은 대상 열의 null 값이 있는 시계열의 첫 번째 행(시간순)에서 시작합니다. null 값은 시계열 내에서 연속적이어야 합니다. 예를 들어 대상 열을 시간순으로 정렬하는 경우 단일 시계열에 `1`, `2`, `null`, `3`, `4`, `null`, `null`과 같이 정렬할 수 없습니다. CSV 파일의 경우 Vertex AI가 빈 문자열을 null로 취급하며 BigQuery의 경우 기본적으로 null 값이 지원됩니다.

텍스트

분류 및 감정 분석

JSON Lines 파일을 사용하여 예측을 수행할 문서 목록을 지정한 후 JSON Lines 파일을 Cloud Storage 버킷에 저장합니다. 다음 샘플에서는 입력 JSON Lines 파일의 단일 줄을 보여줍니다.

{"content": "gs://sourcebucket/datasets/texts/source_text.txt", "mimeType": "text/plain"}

항목 추출

항목 추출의 경우 Cloud Storage 버킷에 있는 문서에 인라인 텍스트 또는 참조를 포함할 수 있습니다. 각 문서의 경우 입력에 key 필드를 추가할 수도 있습니다.

일반적으로 일괄 예측 결과는 content 및 mimeType 필드가 포함된 instance 필드를 사용하여 입력 및 출력을 매핑합니다. 입력에 key 필드를 사용하는 경우 일괄 예측 출력은 instance 필드를 key 필드로 바꿉니다. 예를 들어 입력에 큰 텍스트 스니펫이 포함되어 있는 경우 일괄 예측 출력을 간소화하는 데 도움이 됩니다.

다음 샘플에서는 key 필드 유무에 관계없이 문서 및 인라인 텍스트 스니펫에 대한 참조가 포함된 JSON Lines 파일을 보여줍니다.

{"content": "gs://sourcebucket/datasets/texts/source_text.txt", "mimeType": "text/plain"}
{"content": "gs://bucket/sample.txt", "mimeType": "text/plain", "key": "sample-file"}
{"content": "Text snippet", "mimeType": "text/plain"}
{"content": "Sample text snippet", "mimeType": "text/plain", "key": "sample-snippet"}

동영상

JSON Lines 파일을 사용하여 예측을 수행할 동영상 목록을 지정한 후 JSON Lines 파일을 Cloud Storage 버킷에 저장합니다. timeSegmentEnd 필드에 Infinity를 지정하여 동영상 종료 지점을 지정할 수 있습니다. 다음 샘플에서는 입력 JSON Lines 파일의 단일 줄을 보여줍니다.

{'content': 'gs://sourcebucket/datasets/videos/source_video.mp4', 'mimeType': 'video/mp4', 'timeSegmentStart': '0.0s', 'timeSegmentEnd': '2.366667s'}

배치 예측 요청

일괄 예측 요청의 경우 Google Cloud Console 또는 Vertex AI API를 사용할 수 있습니다. 제출한 입력 항목 수에 따라 일괄 예측 태스크를 완료하는 데 다소 시간이 걸릴 수 있습니다.

Google Cloud Console

Google Cloud Console을 사용하여 일괄 예측을 요청합니다.

Google Cloud Console의 Vertex AI 섹션에서 일괄 예측 페이지로 이동합니다.

일괄 예측 페이지로 이동
만들기를 클릭하여 새 일괄 예측 창을 엽니다.
일괄 예측 정의에서 다음 단계를 완료합니다.
커스텀 학습됨
1. 일괄 예측의 이름을 입력합니다.
2. 모델 이름에서 이 일괄 예측에 사용할 모델의 이름을 선택합니다.
3. 버전에서 이 일괄 예측에 사용할 모델 버전을 선택합니다.
4. 소스 선택:
  
  입력 형식을 JSON Lines, CSV 또는 TFRecord로 지정한 경우 Cloud Storage의 파일(JSON Lines, CSV, TFRecord, TFRecord Gzip)을 선택합니다. 그런 다음 소스 경로 필드에 입력 파일을 지정합니다.
  
  파일 목록을 입력으로 사용하는 경우 Cloud Storage의 파일(기타)을 선택하고 다음 텍스트 상자에 파일 목록을 붙여넣습니다.
  
  BigQuery 입력에 BigQuery 경로를 선택합니다. BigQuery를 입력으로 선택하면 BigQuery를 출력으로 선택해야 합니다.
5. 대상 경로 필드에 Vertex AI에서 일괄 예측 출력을 저장할 Cloud Storage 디렉터리를 지정합니다.
6. 원하는 경우 일괄 예측 응답의 일부로 특성 기여 분석을 가져오려면 이 모델에 특성 기여 분석 사용 설정을 선택하면 됩니다. 그런 다음 수정을 클릭하여 설명 설정을 구성합니다. 이전에 모델에 대한 설명 설정을 구성한 경우 설명 설정 수정은 선택사항이며 그렇지 않으면 필요합니다.
7. 일괄 예측 작업의 컴퓨팅 옵션인 컴퓨팅 노드 수, 머신 유형, 원하는 경우 가속기 유형 및 가속기 수를 지정합니다.
이미지, 텍스트 또는 동영상
1. 일괄 예측의 이름을 입력합니다.
2. 모델 이름에서 이 일괄 예측에 사용할 모델의 이름을 선택합니다.
3. 소스 경로에서 JSON Lines 입력 파일이 있는 Cloud Storage 위치를 지정합니다.
4. 대상 경로에서 일괄 예측 결과가 저장되는 Cloud Storage 위치를 지정합니다. 출력 형식은 모델의 목표에 따라 결정됩니다. 예를 들어 텍스트 목표의 AutoML 모델은 JSON Lines 파일을 출력합니다.
테이블 형식
1. 일괄 예측의 이름을 입력합니다.
2. 모델 이름에서 이 일괄 예측에 사용할 모델의 이름을 선택합니다.
3. 소스 선택에서 소스 입력 데이터가 Cloud Storage의 CSV 파일인지, BigQuery의 테이블인지 선택합니다.
  
  CSV 파일의 경우 CSV 입력 파일이 있는 Cloud Storage 위치를 지정합니다.
  
  BigQuery 테이블의 경우 테이블이 있는 프로젝트 ID, BigQuery 데이터 세트 ID, BigQuery 테이블 또는 뷰 ID를 지정합니다.
4. 출력에서 CSV 또는 BigQuery를 선택합니다.
  
  CSV의 경우 Vertex AI에서 출력을 저장하는 Cloud Storage 버킷을 지정합니다.
  
  BigQuery의 경우 프로젝트 ID 또는 기존 데이터 세트를 지정할 수 있습니다.
  
  프로젝트 ID를 지정하려면 Google Cloud 프로젝트 ID 필드에 프로젝트 ID를 입력합니다. Vertex AI는 새로운 출력 데이터 세트를 만듭니다.
  
  기존 데이터 세트를 지정하려면 Google Cloud 프로젝트 ID 필드에 BigQuery 경로를 입력합니다(예: bq://projectid.datasetid).
  
  BigQuery를 출력 대상으로 지정하고 예측의 특성 중요도 값을 반환하려는 경우 특성 중요도 생성 체크박스를 선택합니다.
  
  Cloud Storage에서 또는 예측 모델에 대해 예측 데이터가 반환될 때 특성 중요도가 지원되지 않습니다.
선택사항: 테이블 형식 커스텀 학습 및 테이블 형식 AutoML 모델에 모델 모니터링 분석을 사용할 수 있습니다. 일괄 예측 작업에 편향 감지 구성을 추가하는 방법은 기본 요건을 참조하세요.
1. 이 일괄 예측에 모델 모니터링 사용 설정을 클릭하여 켜거나 끕니다.
2. 학습 데이터 소스를 선택합니다.
3. 선택한 학습 데이터 소스의 학습 데이터 경로를 입력합니다.
만들기를 클릭합니다.

API

Vertex AI API를 사용하여 일괄 예측 요청을 전송합니다.

커스텀 학습됨

일괄 예측을 가져오는 데 사용할 도구에 따라 탭을 선택합니다.

REST 및 명령줄

REST API 참조는 BatchPredictionJob을 참조하세요.

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

LOCATION: 모델이 저장되고 일괄 예측 작업이 실행되는 리전입니다. us-central1).
PROJECT: 프로젝트 ID입니다.
BATCH_JOB_NAME: 일괄 예측 작업의 표시 이름입니다.
MODEL_ID: 예측을 수행하는 데 사용할 모델의 ID입니다.
INPUT_FORMAT: 입력 데이터의 형식(jsonl, csv, tf-record, tf-record-gzip 또는 file-list)입니다.
INPUT_URI: 입력 데이터의 Cloud Storage URI입니다. 와일드 카드를 포함할 수도 있습니다.
OUTPUT_DIRECTORY: Vertex AI에서 출력을 저장할 디렉터리의 Cloud Storage URI입니다.
MACHINE_TYPE: 이 일괄 예측 작업에 사용할 머신 리소스입니다.

원하는 경우 가속기를 사용하도록 machineSpec 필드를 구성할 수 있지만 다음 예시에서는 이를 보여주지 않습니다.
BATCH_SIZE: 각 예측 요청에서 전송할 인스턴스 수로, 기본값은 64입니다. 배치 크기를 늘리면 처리량이 증가할 수 있지만 요청 시간 초과가 발생할 수도 있습니다.
STARTING_REPLICA_COUNT: 이 일괄 예측 작업의 노드 수입니다.

HTTP 메서드 및 URL:

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

JSON 요청 본문:

{
  "displayName": "BATCH_JOB_NAME",
  "model": "projects/PROJECT/locations/LOCATION/models/MODEL_ID",
  "inputConfig": {
    "instancesFormat": "INPUT_FORMAT",
    "gcsSource": {
      "uris": ["INPUT_URI"],
    },
  },
  "outputConfig": {
    "predictionsFormat": "jsonl",
    "gcsDestination": {
      "outputUriPrefix": "OUTPUT_DIRECTORY",
    },
  },
  "dedicatedResources" : {
    "machineSpec" : {
      "machineType": MACHINE_TYPE
    },
    "startingReplicaCount": STARTING_REPLICA_COUNT
  },
  "manualBatchTuningParameters": {
    "batch_size": BATCH_SIZE,
  }
}

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

curl

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

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

PowerShell

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

$cred = gcloud auth application-default 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/locations/LOCATION/batchPredictionJobs" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "name": "projects/PROJECT_NUMBER/locations/us-central1/batchPredictionJobs/BATCH_JOB_ID",
  "displayName": "BATCH_JOB_NAME 202005291958",
  "model": "projects/PROJECT/locations/us-central1/models/MODEL_ID",
  "inputConfig": {
    "instancesFormat": "jsonl",
    "gcsSource": {
      "uris": [
        "INPUT_URI"
      ]
    }
  },
  "outputConfig": {
    "predictionsFormat": "jsonl",
    "gcsDestination": {
      "outputUriPrefix": "OUTPUT_DIRECTORY"
    }
  },
  "state": "JOB_STATE_PENDING",
  "createTime": "2020-05-30T02:58:44.341643Z",
  "updateTime": "2020-05-30T02:58:44.341643Z",
}

Java

Vertex AI용 클라이언트 라이브러리를 설치하고 사용하는 방법은 Vertex AI 클라이언트 라이브러리를 참조하세요. 자세한 내용은 Vertex AI Java API 참조 문서를 참조하세요.

다음 샘플에서 PREDICTIONS_FORMAT을 jsonl로 바꿉니다. 다른 자리표시자를 바꾸는 방법을 알아보려면 이 섹션의 REST & CMD LINE 탭을 참조하세요.

일괄 예측 가져오기

일괄 요청 입력

커스텀 학습됨

JSON Lines

TFRecord

CSV

파일 목록

BigQuery

이미지

테이블 형식

BigQuery 테이블 요구사항

CSV 파일 요구사항

예측 요구사항

텍스트

분류 및 감정 분석

항목 추출

동영상

배치 예측 요청

Google Cloud Console

커스텀 학습됨

이미지, 텍스트 또는 동영상

테이블 형식

API

커스텀 학습됨

REST 및 명령줄

curl

PowerShell

Java

Python

특성 중요도

이미지

REST 및 명령줄

curl

PowerShell

Python

테이블 형식

CSV 파일을 사용한 일괄 예측 요청

REST 및 명령줄

curl

PowerShell

BigQuery를 사용한 일괄 예측 요청

REST 및 명령줄

curl

PowerShell

Java

Python

특성 중요도

텍스트

분류

REST 및 명령줄

curl

PowerShell

Java

Node.js

Python

항목 추출

REST 및 명령줄

curl

PowerShell

Java

Node.js

Python

감정 분석

REST 및 명령줄

curl

PowerShell

Java

Node.js

Python

동영상

동작 인식

REST 및 명령줄

curl

PowerShell

Java

Python

분류

REST 및 명령줄

curl

PowerShell