커스텀 학습 모델에서 온라인 예측 수행

Vertex AI 온라인 예측은 지연 시간을 최소화하면서 호스팅된 모델을 통해 데이터를 실행하는 데 최적화된 서비스입니다. 소규모의 데이터 배치를 서비스에 전송하면 AI Platform에서 응답을 통해 예측을 반환합니다.

시작하기 전에

예측을 요청하려면 먼저 다음을 수행해야 합니다.

• 모델을 학습시킵니다. 학습 코드에서 Vertex AI에 배포할 수 있는 하나 이상의 모델 아티팩트로 학습된 모델 아티팩트를 내보냅니다.

• 모델 아티팩트를 업로드하고 Vertex AI 엔드포인트에 모델을 배포하여 학습된 모델을 Vertex AI에 배포합니다.

모델 배포 구성

모델 배포 시 온라인 예측을 실행하는 방법에 대해 다음과 같은 중요한 사항을 결정해야 합니다.

생성된 리소스	리소스 생성 시 지정된 설정
엔드포인트	예측을 실행할 위치
모델	사용할 컨테이너(ModelContainerSpec)
DeployedModel	온라인 예측에 사용할 머신

모델 또는 엔드포인트를 처음 생성한 후에는 위의 목록 설정을 업데이트할 수 없으며 온라인 예측 요청에서 이 설정을 재정의할 수 없습니다. 이러한 설정을 변경해야 하는 경우 모델을 다시 배포해야 합니다.

온라인 예측 입력 형식 지정

사전 빌드된 컨테이너 중 하나를 사용하여 TensorFlow, scikit-learn 또는 XGBoost로 예측을 제공하는 경우 예측 입력 인스턴스의 형식은 JSON이어야 합니다.

모델에서 커스텀 컨테이너를 사용하는 경우, 입력은 JSON 형식이어야 하며 컨테이너에 사용할 수 있는 추가 parameters 필드가 있습니다. 커스텀 컨테이너를 사용한 예측 입력 형식 지정에 대해 자세히 알아보세요.

이 섹션에서는 예측 입력 인스턴스의 형식을 JSON으로 지정하는 방법과 base64 인코딩으로 바이너리 데이터를 처리하는 방법을 보여줍니다.

인스턴스 형식을 JSON 문자열로 지정

온라인 예측의 기본 형식은 데이터 인스턴스 목록입니다. 학습 애플리케이션에서 입력을 구성한 방법에 따라서 일반 값 목록이 될 수도 또는 JSON 객체의 멤버가 될 수도 있습니다. TensorFlow 모델은 더 복잡한 입력을 수락할 수 있지만 대부분의 scikit-learn 및 XGBoost 모델은 번호 목록을 입력으로 예상합니다.

이 예시에서는 TensorFlow 모델에 대한 입력 텐서와 인스턴스 키를 보여줍니다.

{"values": [1, 2, 3, 4], "key": 1}

JSON 문자열 구성은 다음 규칙을 따르는 한 복잡해도 괜찮습니다.

• 인스턴스 데이터의 최상위 수준은 키-값 쌍의 사전인 JSON 객체여야 합니다.

• 인스턴스 객체의 개별 값은 문자열, 숫자, 목록일 수 있습니다. JSON 객체를 삽입할 수 없습니다.

• 목록에는 같은 유형의 항목만 포함되어야 합니다(다른 목록 포함). 문자열과 숫자 값을 함께 사용할 수 없습니다.

온라인 예측의 입력 인스턴스를 projects.locations.endpoints.predict 호출의 메시지 본문으로 전달합니다. 요청 본문의 형식 요구사항에 대해 자세히 알아보세요.

각 인스턴스를 JSON 배열의 항목으로 만들고 배열을 JSON 객체의 instances 필드로 제공합니다. 예를 들면 다음과 같습니다.

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

예측 입력을 위한 바이너리 데이터 인코딩

참고: 다음 섹션은 TensorFlow를 사용한 예측에만 적용됩니다.

바이너리 데이터는 JSON이 지원하는 UTF-8 인코딩 문자열로 형식을 지정할 수 없습니다. 입력에 바이너리 데이터가 있는 경우 이 데이터를 표시하려면 base64 인코딩을 사용하고, 다음 특수 형식으로 지정해야 합니다.

• 인코딩된 문자열 형식을 b64라는 단일 키를 사용하여 JSON 객체로 지정해야 합니다. Python 3에서는 base64 인코딩이 바이트 시퀀스를 출력합니다. JSON으로 직렬화할 수 있도록 문자열로 변환해야 합니다.

  {'image_bytes': {'b64': base64.b64encode(jpeg_data).decode()}}
  

• TensorFlow 모델 코드에서 바이너리 입력 및 출력 텐서의 별칭이 '_bytes'로 끝나도록 지정해야 합니다.

요청 및 응답 예시

이 섹션에서는 예측 요청 본문 및 응답 본문의 형식을 TensorFlow, scikit-learn, XGBoost에 대한 예시와 함께 설명합니다.

요청 본문 세부정보

TensorFlow

요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다(JSON 표현).

{
  "instances": [
    <value>|<simple/nested list>|<object>,
    ...
  ]
}

instances[] 객체는 필수 항목이며 예측 결과를 가져올 인스턴스의 목록을 포함해야 합니다.

인스턴스 목록의 각 요소에 대한 구조는 모델의 입력 정의에 따라 결정됩니다. 인스턴스는 이름이 지정된 입력을 객체로서 포함하거나 라벨이 없는 값만 포함할 수 있습니다.

일부 데이터는 이름이 지정된 입력을 포함하지 않습니다. 일부 인스턴스는 단순한 JSON 값(부울, 숫자, 문자열)입니다. 그러나 인스턴스가 단순한 값 목록 또는 복잡한 중첩 목록인 경우가 있습니다.

다음은 요청 본문의 몇 가지 예입니다.

각 행이 문자열 값으로 인코딩된 CSV 데이터는 다음과 같습니다.

{"instances": ["1.0,true,\\"x\\"", "-2.0,false,\\"y\\""]}

일반 텍스트는 다음과 같습니다.

{"instances": ["the quick brown fox", "the lazy dog"]}

단어 목록(문자열 벡터)으로 인코딩된 문장은 다음과 같습니다.

{
  "instances": [
    ["the","quick","brown"],
    ["the","lazy","dog"],
    ...
  ]
}

부동 소수점 스칼라 값은 다음과 같습니다.

{"instances": [0.0, 1.1, 2.2]}

정수 벡터는 다음과 같습니다.

{
  "instances": [
    [0, 1, 2],
    [3, 4, 5],
    ...
  ]
}

텐서(이 경우, 2차원 텐서)는 다음과 같습니다.

{
  "instances": [
    [
      [0, 1, 2],
      [3, 4, 5]
    ],
    ...
  ]
}

이미지는 다양한 방식으로 표현될 수 있습니다. 이 인코딩 스키마의 경우 앞에서 두 차원은 이미지의 행과 열을 나타내고 세 번째 차원은 각 픽셀의 R, G, B 값 목록(벡터)을 포함합니다.

{
  "instances": [
    [
      [
        [138, 30, 66],
        [130, 20, 56],
        ...
      ],
      [
        [126, 38, 61],
        [122, 24, 57],
        ...
      ],
      ...
    ],
    ...
  ]
}

데이터 인코딩

JSON 문자열은 UTF-8로 인코딩되어야 합니다. 바이너리 데이터를 보내려면 데이터를 base64로 인코딩하고 바이너리 데이터로 표시해야 합니다. JSON 문자열을 바이너리로 표시하려면 문자열을 b64라는 단일 속성의 JSON 객체로 대체합니다.

{"b64": "..."} 

다음 예시는 base64 인코딩을 필요로 하는 두 개의 직렬화된 tf.Examples 인스턴스를 보여줍니다(참고용 모의 데이터).

{"instances": [{"b64": "X5ad6u"}, {"b64": "IA9j4nx"}]}

다음 예시는 base64 인코딩을 필요로 하는 두 개의 JPEG 이미지 바이트 문자열을 보여줍니다(참고용 허위 데이터).

{"instances": [{"b64": "ASa8asdf"}, {"b64": "JLK7ljk3"}]}

여러 입력 텐서

일부 모델에는 여러 개의 입력 텐서를 허용하는 기본 텐서플로우 그래프가 있습니다. 이 경우 JSON 이름/값 쌍의 이름을 사용하여 입력 텐서를 식별합니다.

입력 텐서 별칭 '태그'(문자열) 및 '이미지'(base64로 인코딩된 문자열)가 있는 그래프의 경우는 다음과 같습니다.

{
  "instances": [
    {
      "tag": "beach",
      "image": {"b64": "ASa8asdf"}
    },
    {
      "tag": "car",
      "image": {"b64": "JLK7ljk3"}
    }
  ]
}

입력 텐서 별칭 '태그'(문자열) 및 '이미지'(8비트 정수의 3차원 배열)가 있는 그래프의 경우는 다음과 같습니다.

{
  "instances": [
    {
      "tag": "beach",
      "image": [
        [
          [138, 30, 66],
          [130, 20, 56],
          ...
        ],
        [
          [126, 38, 61],
          [122, 24, 57],
          ...
        ],
        ...
      ]
    },
    {
      "tag": "car",
      "image": [
        [
          [255, 0, 102],
          [255, 0, 97],
          ...
        ],
        [
          [254, 1, 101],
          [254, 2, 93],
          ...
        ],
        ...
      ]
    },
    ...
  ]
}

scikit-learn

요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다(JSON 표현).

{
  "instances": [
    <simple list>,
    ...
  ]
}

instances[] 객체는 필수 항목이며 예측 결과를 가져올 인스턴스의 목록을 포함해야 합니다. 다음 예시에서 각 입력 인스턴스는 부동 소수점의 목록입니다.

{
  "instances": [
    [0.0, 1.1, 2.2],
    [3.3, 4.4, 5.5],
    ...
  ]
}

입력 인스턴스의 차원은 모델에 필요한 차원과 일치해야 합니다. 예를 들어 모델에 세 가지 특성이 필요한 경우 각 입력 인스턴스의 길이는 3이어야 합니다.

XGBoost

요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다(JSON 표현).

{
  "instances": [
    <simple list>,
    ...
  ]
}

instances[] 객체는 필수 항목이며 예측 결과를 가져올 인스턴스의 목록을 포함해야 합니다. 다음 예시에서 각 입력 인스턴스는 부동 소수점의 목록입니다.

{
  "instances": [
    [0.0, 1.1, 2.2],
    [3.3, 4.4, 5.5],
    ...
  ]
}

입력 인스턴스의 차원은 모델에 필요한 차원과 일치해야 합니다. 예를 들어 모델에 세 가지 특성이 필요한 경우 각 입력 인스턴스의 길이는 3이어야 합니다.

XGBoost의 경우 Vertex AI는 입력 인스턴스의 희소 표현을 지원하지 않습니다.

온라인 예측 서비스는 0과 NaN을 다르게 해석합니다. 특성 값이 0이면 해당 입력에 0.0을 사용합니다. 특성 값이 누락된 경우 해당 입력에서 "NaN"을 사용합니다.

다음 예시는 첫 번째 특성 값이 0.0, 두 번째 특성 값이 1.1, 세 번째 특성 값이 누락된 단일 입력 인스턴스가 포함된 예측 요청을 나타냅니다.

{"instances": [[0.0, 1.1, "NaN"]]}

응답 본문 세부정보

응답은 요청과 매우 유사합니다.

호출이 성공한 경우 응답 본문은 요청 본문의 인스턴스당 하나의 예측 항목을 포함하며 동일한 순서로 표시됩니다.

{
  "predictions": [
    {
      object
    }
  ],
  "deployedModelId": string
}

모든 인스턴스에 대한 예측이 실패하면 응답 본문은 예측을 포함하지 않습니다. 대신 단일 오류 항목을 포함합니다.

{
  "error": string
}

predictions[] 객체에는 요청의 인스턴스마다 예측 목록이 하나씩 포함됩니다.

오류가 발생하면 error 문자열은 문제를 설명하는 메시지를 포함합니다. 인스턴스를 처리하는 동안 오류가 발생한 경우 예측 목록 대신 오류가 반환됩니다.

예측은 인스턴스당 하나씩이지만 예측의 형식은 인스턴스의 형식과 직접적인 관련이 없습니다. 예측은 모델에 정의된 출력 컬렉션에 지정된 형식을 취합니다. 예측 컬렉션은 JSON 목록으로 반환됩니다. 목록의 각 구성원은 단순한 값, 목록, 다양한 복잡성을 가지는 JSON 객체일 수 있습니다. 모델에 둘 이상의 출력 텐서가 있는 경우 각 예측은 출력마다 이름/값 쌍을 포함하는 JSON 객체가 됩니다. 이름은 그래프의 출력 별칭을 식별합니다.

응답 본문 예시

TensorFlow

다음 예시에서는 몇 가지 가능한 응답을 보여줍니다.

• 3개의 입력 인스턴스에 대한 간단한 예측 집합으로 각 예측은 정수 값입니다.

  {"predictions":
     [5, 4, 3],
     "deployedModelId": 123456789012345678
  }
  

• 보다 복잡한 예측 집합으로 각 집합은 출력 텐서에 해당하는 두 개의 이름(각각 label 및 scores)이 지정된 값을 포함합니다. label 값은 예측 카테고리('car' 또는 'beach')이며 scores는 가능한 카테고리 범위에서 해당 인스턴스에 대한 확률 목록을 포함합니다.

  {
    "predictions": [
      {
        "label": "beach",
        "scores": [0.1, 0.9]
      },
      {
        "label": "car",
        "scores": [0.75, 0.25]
      }
    ],
    "deployedModelId": 123456789012345678
  }
  

• 입력 인스턴스를 처리하는 중 오류가 발생했을 때의 응답입니다.

  {"error": "Divide by zero"}
  

scikit-learn

다음 예시에서는 몇 가지 가능한 응답을 보여줍니다.

• 3개의 입력 인스턴스에 대한 간단한 예측 집합으로 각 예측은 정수 값입니다.

  {"predictions":
     [5, 4, 3],
     "deployedModelId": 123456789012345678
  }
  

• 입력 인스턴스를 처리하는 중 오류가 발생했을 때의 응답입니다.

  {"error": "Divide by zero"}
  

XGBoost

다음 예시에서는 몇 가지 가능한 응답을 보여줍니다.

• 3개의 입력 인스턴스에 대한 간단한 예측 집합으로 각 예측은 정수 값입니다.

  {"predictions":
     [5, 4, 3],
     "deployedModelId": 123456789012345678
  }
  

• 입력 인스턴스를 처리하는 중 오류가 발생했을 때의 응답입니다.

  {"error": "Divide by zero"}
  

온라인 예측 요청 전송

예측 요청에 입력 데이터 인스턴스를 JSON 문자열로 전송하여 온라인 예측을 요청합니다. 요청 및 응답 본문의 형식을 지정하려면 예측 요청 세부정보를 참조하세요.

모델이 공개 엔드포인트에 배포된 경우 각 예측 요청은 1.5MB 이하여야 합니다.

gcloud

다음 예시에서는 gcloud ai endpoints predict 명령어를 사용합니다.

1. 다음 JSON 객체를 작성하여 로컬 환경에 보관합니다. 파일 이름은 중요하지 않지만 이 예시에서는 파일 이름을 request.json으로 지정합니다.

   {
    "instances": INSTANCES
   }
   

   다음을 바꿉니다.

   • INSTANCES: 예측을 가져올 인스턴스의 JSON 배열입니다. 각 인스턴스의 형식은 특정 학습된 ML 모델이 예상하는 입력 내용에 따라 달라집니다. 이 문서의 온라인 예측 입력 형식 지정 섹션을 참조하세요.

2. 다음 명령어를 실행합니다.

   gcloud ai endpoints predict ENDPOINT_ID \
     --region=LOCATION \
     --json-request=request.json
   

   다음을 바꿉니다.

   • ENDPOINT_ID: 엔드포인트의 ID입니다.
   • LOCATION: Vertex AI를 사용하는 리전

REST 및 명령줄

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

• LOCATION: Vertex AI를 사용하는 리전
• PROJECT: 프로젝트 ID
• ENDPOINT_ID: 엔드포인트의 ID입니다.
• INSTANCES: 예측을 가져올 인스턴스의 JSON 배열입니다. 각 인스턴스의 형식은 특정 학습된 ML 모델이 예상하는 입력 내용에 따라 달라집니다. 이 문서의 온라인 예측 입력 형식 지정 섹션을 참조하세요.

HTTP 메서드 및 URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:predict

JSON 요청 본문:

{
  "instances": INSTANCES
}

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

curl

참고: GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 서비스 계정 비공개 키 파일의 경로로 설정해야 합니다.

요청 본문을 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/endpoints/ENDPOINT_ID:predict"

PowerShell

참고: GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 서비스 계정 비공개 키 파일의 경로로 설정해야 합니다.

요청 본문을 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/endpoints/ENDPOINT_ID:predict" | Select-Object -Expand Content

성공하면 다음과 비슷한 JSON 응답이 표시됩니다. 응답에서 다음 값이 바뀝니다.

• PREDICTIONS: 요청 본문에 포함된 각 인스턴스당 하나의 JSON 요청 배열입니다.
• DEPLOYED_MODEL_ID: 이러한 예측을 제공한 DeployedModel의 ID입니다.

{
  "predictions": PREDICTIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Java

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

GitHub에서 보기 의견 보내기

import com.google.cloud.aiplatform.v1.EndpointName;
import com.google.cloud.aiplatform.v1.PredictRequest;
import com.google.cloud.aiplatform.v1.PredictResponse;
import com.google.cloud.aiplatform.v1.PredictionServiceClient;
import com.google.cloud.aiplatform.v1.PredictionServiceSettings;
import com.google.protobuf.ListValue;
import com.google.protobuf.Value;
import com.google.protobuf.util.JsonFormat;
import java.io.IOException;
import java.util.List;

public class PredictCustomTrainedModelSample {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String instance = "[{ “feature_column_a”: “value”, “feature_column_b”: “value”}]";
    String project = "YOUR_PROJECT_ID";
    String endpointId = "YOUR_ENDPOINT_ID";
    predictCustomTrainedModel(project, endpointId, instance);
  }

  static void predictCustomTrainedModel(String project, String endpointId, String instance)
      throws IOException {
    PredictionServiceSettings predictionServiceSettings =
        PredictionServiceSettings.newBuilder()
            .setEndpoint("us-central1-aiplatform.googleapis.com:443")
            .build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (PredictionServiceClient predictionServiceClient =
        PredictionServiceClient.create(predictionServiceSettings)) {
      String location = "us-central1";
      EndpointName endpointName = EndpointName.of(project, location, endpointId);

      ListValue.Builder listValue = ListValue.newBuilder();
      JsonFormat.parser().merge(instance, listValue);
      List<Value> instanceList = listValue.getValuesList();

      PredictRequest predictRequest =
          PredictRequest.newBuilder()
              .setEndpoint(endpointName.toString())
              .addAllInstances(instanceList)
              .build();
      PredictResponse predictResponse = predictionServiceClient.predict(predictRequest);

      System.out.println("Predict Custom Trained model Response");
      System.out.format("\tDeployed Model Id: %s\n", predictResponse.getDeployedModelId());
      System.out.println("Predictions");
      for (Value prediction : predictResponse.getPredictionsList()) {
        System.out.format("\tPrediction: %s\n", prediction);
      }
    }
  }
}

Node.js

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

GitHub에서 보기 의견 보내기

/**
 * TODO(developer): Uncomment these variables before running the sample.\
 * (Not necessary if passing values as arguments)
 */

// const filename = "YOUR_PREDICTION_FILE_NAME";
// const endpointId = "YOUR_ENDPOINT_ID";
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';
const util = require('util');
const {readFile} = require('fs');
const readFileAsync = util.promisify(readFile);

// Imports the Google Cloud Prediction Service Client library
const {PredictionServiceClient} = require('@google-cloud/aiplatform');

// Specifies the location of the api endpoint
const clientOptions = {
  apiEndpoint: 'us-central1-aiplatform.googleapis.com',
};

// Instantiates a client
const predictionServiceClient = new PredictionServiceClient(clientOptions);

async function predictCustomTrainedModel() {
  // Configure the parent resource
  const endpoint = `projects/${project}/locations/${location}/endpoints/${endpointId}`;
  const parameters = {
    structValue: {
      fields: {},
    },
  };
  const instanceDict = await readFileAsync(filename, 'utf8');
  const instanceValue = JSON.parse(instanceDict);
  const instance = {
    structValue: {
      fields: {
        Age: {stringValue: instanceValue['Age']},
        Balance: {stringValue: instanceValue['Balance']},
        Campaign: {stringValue: instanceValue['Campaign']},
        Contact: {stringValue: instanceValue['Contact']},
        Day: {stringValue: instanceValue['Day']},
        Default: {stringValue: instanceValue['Default']},
        Deposit: {stringValue: instanceValue['Deposit']},
        Duration: {stringValue: instanceValue['Duration']},
        Housing: {stringValue: instanceValue['Housing']},
        Job: {stringValue: instanceValue['Job']},
        Loan: {stringValue: instanceValue['Loan']},
        MaritalStatus: {stringValue: instanceValue['MaritalStatus']},
        Month: {stringValue: instanceValue['Month']},
        PDays: {stringValue: instanceValue['PDays']},
        POutcome: {stringValue: instanceValue['POutcome']},
        Previous: {stringValue: instanceValue['Previous']},
      },
    },
  };

  const instances = [instance];
  const request = {
    endpoint,
    instances,
    parameters,
  };

  // Predict request
  const [response] = await predictionServiceClient.predict(request);

  console.log('Predict custom trained model response');
  console.log(`\tDeployed model id : ${response.deployedModelId}`);
  const predictions = response.predictions;
  console.log('\tPredictions :');
  for (const prediction of predictions) {
    console.log(`\t\tPrediction : ${JSON.stringify(prediction)}`);
  }
}
predictCustomTrainedModel();

Python

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

GitHub에서 보기 의견 보내기

def endpoint_predict_sample(
    project: str, location: str, instances: list, endpoint: str
):
    aiplatform.init(project=project, location=location)

    endpoint = aiplatform.Endpoint(endpoint)

    prediction = endpoint.predict(instances=instances)
    print(prediction)
    return prediction

온라인 원시 예측 요청 보내기

또는 이 가이드의 이전 섹션에서 설명한 엄격한 가이드라인을 따르지 않고 임의의 HTTP 페이로드를 사용할 수 있는 원시 예측 요청을 보낼 수 있습니다.

가이드라인과 다른 요청을 수신하고 응답을 전송하는 커스텀 컨테이너를 사용하는 경우 원시 예측을 가져오는 것이 좋습니다.

gcloud

다음 예시에서는 gcloud ai endpoints raw-predict 명령어를 사용합니다.

• 명령줄에 지정된 REQUEST의 JSON 객체를 사용하여 예측을 요청하려면 다음 명령어를 사용합니다.

  gcloud ai endpoints raw-predict ENDPOINT_ID \
    --region=LOCATION \
    --request REQUEST
  

• image.jpeg 파일에 저장된 이미지와 적절한 Content-Type 헤더를 사용하여 예측을 요청하려면 다음 명령어를 사용합니다.

  gcloud ai endpoints raw-predict ENDPOINT_ID \
    --region=LOCATION \
    --http-headers=Content-Type=image/jpeg \
    --request @image.jpeg
  

다음을 바꿉니다.

• ENDPOINT_ID: 엔드포인트의 ID입니다.
• LOCATION: Vertex AI를 사용하는 리전입니다.
• REQUEST: 예측을 수행할 요청의 콘텐츠입니다. 요청 형식은 커스텀 컨테이너가 예상하는 대상에 따라 달라지며 JSON 객체일 필요는 없습니다.

응답에는 다음 HTTP 헤더가 포함됩니다.

• X-Vertex-AI-Endpoint-Id: 이 예측을 제공한 Endpoint의 ID입니다.

• X-Vertex-AI-Deployed-Model-Id: 이 예측을 제공한 엔드포인트의 DeployedModel ID입니다.

참고: 컨테이너가 가이드라인과 다른 요청을 받거나 응답을 보내는 경우 컨테이너는 Vertex Explainable AI 또는 Vertex AI Model Monitoring과 호환되지 않습니다.

온라인 설명 요청 보내기

Vertex Explainable AI용으로 Model을 구성한 경우 온라인 설명을 가져올 수 있습니다. 온라인 설명 요청의 형식은 온라인 예측 요청과 동일하며 유사한 응답을 반환합니다. 유일한 차이는 온라인 설명 응답에는 예측뿐 아니라 특성 기여 분석이 포함된다는 점입니다.

다음 예시는 앞의 섹션의 예시와 거의 동일하지만, 약간 다른 명령어를 사용합니다.

gcloud

다음 예시에서는 gcloud ai endpoints explain 명령어를 사용합니다.

1. 다음 JSON 객체를 작성하여 로컬 환경에 보관합니다. 파일 이름은 중요하지 않지만 이 예시에서는 파일 이름을 request.json으로 지정합니다.

   {
    "instances": INSTANCES
   }
   

   다음을 바꿉니다.

   • INSTANCES: 예측을 가져올 인스턴스의 JSON 배열입니다. 각 인스턴스의 형식은 특정 학습된 ML 모델이 예상하는 입력 내용에 따라 달라집니다. 이 문서의 온라인 예측 입력 형식 지정 섹션을 참조하세요.

2. 다음 명령어를 실행합니다.

   gcloud ai endpoints explain ENDPOINT_ID \
     --region=LOCATION \
     --json-request=request.json
   

   다음을 바꿉니다.

   • ENDPOINT_ID: 엔드포인트의 ID입니다.
   • LOCATION: Vertex AI를 사용하는 리전

   원하는 경우 Endpoint의 특정 DeployedModel에 설명 요청을 보내려면 --deployed-model-id 플래그를 지정할 수 있습니다.

   gcloud ai endpoints explain ENDPOINT_ID \
     --region=LOCATION \
     --deployed-model-id=DEPLOYED_MODEL_ID \
     --json-request=request.json
   

   앞에서 설명한 자리표시자 외에도 다음을 바꿉니다.

   • DEPLOYED_MODEL_ID(선택사항): 설명을 가져올 배포된 모델의 ID입니다. ID는 predict 메서드의 응답에 포함됩니다. 특정 모델에 대한 설명을 요청해야 하며 동일 엔드포인트에 배포된 모델이 2개 이상 있는 경우, 이 ID를 사용하여 특정 모델에 대한 설명이 반환되도록 할 수 있습니다.

REST 및 명령줄

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

• LOCATION: Vertex AI를 사용하는 리전
• PROJECT: 프로젝트 ID
• ENDPOINT_ID: 엔드포인트의 ID입니다.
• INSTANCES: 예측을 가져올 인스턴스의 JSON 배열입니다. 각 인스턴스의 형식은 특정 학습된 ML 모델이 예상하는 입력 내용에 따라 달라집니다. 이 문서의 온라인 예측 입력 형식 지정 섹션을 참조하세요.

HTTP 메서드 및 URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:explain

JSON 요청 본문:

{
  "instances": INSTANCES
}

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

curl

참고: GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 서비스 계정 비공개 키 파일의 경로로 설정해야 합니다.

요청 본문을 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/endpoints/ENDPOINT_ID:explain"

PowerShell

참고: GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 서비스 계정 비공개 키 파일의 경로로 설정해야 합니다.

요청 본문을 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/endpoints/ENDPOINT_ID:explain" | Select-Object -Expand Content

성공하면 다음과 비슷한 JSON 응답이 표시됩니다. 응답에서 다음 값이 바뀝니다.

• PREDICTIONS: 요청 본문에 포함된 각 인스턴스당 하나의 JSON 요청 배열입니다.
• EXPLANATIONS: 예측마다 하나의 설명의 JSON 배열입니다.
• DEPLOYED_MODEL_ID: 이러한 예측을 제공한 DeployedModel의 ID입니다.

{
  "predictions": PREDICTIONS,
  "explanations": EXPLANATIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Python

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

GitHub에서 보기 의견 보내기

def explain_tabular_sample(
    project: str, location: str, endpoint_id: str, instance_dict: Dict
):

    aiplatform.init(project=project, location=location)

    endpoint = aiplatform.Endpoint(endpoint_id)

    response = endpoint.explain(instances=[instance_dict], parameters={})

    for explanation in response.explanations:
        print(" explanation")
        # Feature attributions.
        attributions = explanation.attributions
        for attribution in attributions:
            print("  attribution")
            print("   baseline_output_value:", attribution.baseline_output_value)
            print("   instance_output_value:", attribution.instance_output_value)
            print("   output_display_name:", attribution.output_display_name)
            print("   approximation_error:", attribution.approximation_error)
            print("   output_name:", attribution.output_name)
            output_index = attribution.output_index
            for output_index in output_index:
                print("   output_index:", output_index)

    for prediction in response.predictions:
        print(prediction)

다음 단계

• AutoML 모델에서 예측을 가져오는 방법 알아보기