Method: projects.predict

Performs online prediction on the data in the request.

AI Platform Prediction은 HTTP POST 메서드를 사용하여 커스텀 predict 동사를 구현합니다. predict 메서드는 요청 데이터에 대한 예측을 수행합니다.

URL은 Google API HTTP 주석 구문에 설명되어 있습니다.

POST https://ml.googleapis.com/v1/{name=projects/**}:predict

name 매개변수는 필수 항목입니다. 모델 이름과 버전 이름(선택사항)을 포함해야 합니다. 모델 버전을 지정하지 않으면 해당 모델의 기본 버전을 사용합니다.

모델과 버전을 모두 지정하는 예시입니다.

POST https://ml.googleapis.com/v1/projects/your-project-id/models/your-model-name/versions/your-version-name:predict

모델만 지정하는 예시입니다. 해당 모델의 기본 버전을 사용합니다.

POST https://ml.googleapis.com/v1/projects/your-project-id/models/your-model-name:predict

이 페이지에서는 예측 요청 본문 및 응답 본문의 형식을 설명합니다. 예측 요청을 보내는 방법을 보여주는 코드 샘플은 온라인 예측 요청 가이드를 참조하세요.

요청 본문 세부정보

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의 경우 AI Platform Prediction은 입력 인스턴스의 희소 표현을 지원하지 않습니다.

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

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

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

커스텀 예측 루틴

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

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

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

필요에 따라 다른 유효한 JSON 키-값 쌍을 제공해도 됩니다. AI Platform Prediction에서 JSON을 파싱하고 이 필드를 Predictor 클래스predict 메서드에 **kwargs 사전의 항목으로 제공합니다.

인스턴스 목록을 구조화하는 방법

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

일부 데이터는 이름이 지정된 입력을 포함하지 않습니다. 일부 인스턴스는 단순한 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 이름/값 쌍의 이름을 사용하여 입력 텐서를 식별합니다.

입력 텐서 별칭 '태그'(문자열) 및 '이미지'(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],
          ...
        ],
        ...
      ]
    },
    ...
  ]
}

응답 본문 세부정보

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

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

{
  "predictions": [
    {
      object
    }
  ]
}

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

{
  "error": string
}

predictions[] 객체에는 요청의 인스턴스마다 예측 목록이 하나씩 포함됩니다. 커스텀 예측 루틴(베타)의 경우에는 predictionsPredictor 클래스predict 메서드 반환 값이 JSON으로 직렬화되어 포함됩니다.

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

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

응답 본문 예시

TensorFlow

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

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

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

    {
      "predictions": [
        {
          "label": "beach",
          "scores": [0.1, 0.9]
        },
        {
          "label": "car",
          "scores": [0.75, 0.25]
        }
      ]
    }
    
  • 입력 인스턴스를 처리하는 중 오류가 발생했을 때의 응답입니다.

    {"error": "Divide by zero"}
    

scikit-learn

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

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

    {"predictions": [5, 4, 3]}
    
  • 입력 인스턴스를 처리하는 중 오류가 발생했을 때의 응답입니다.

    {"error": "Divide by zero"}
    

XGBoost

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

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

    {"predictions": [5, 4, 3]}
    
  • 입력 인스턴스를 처리하는 중 오류가 발생했을 때의 응답입니다.

    {"error": "Divide by zero"}
    

커스텀 예측 루틴

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

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

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

    {
      "predictions": [
        {
          "label": "beach",
          "scores": [0.1, 0.9]
        },
        {
          "label": "car",
          "scores": [0.75, 0.25]
        }
      ]
    }
    
  • 입력 인스턴스를 처리하는 중 오류가 발생했을 때의 응답입니다.

    {"error": "Divide by zero"}
    

API 사양

다음 섹션에서는 AI Platform Training 및 Prediction API 검색 문서에 정의된 predict 메서드의 사양을 설명합니다. 메서드에 대한 자세한 내용은 이 문서의 이전 섹션을 참조하세요.

HTTP request

POST https://{endpoint}/v1/{name=projects/**}:predict

Where {endpoint} is one of the supported service endpoints.

The URLs use gRPC Transcoding syntax.

Path parameters

Parameters
name

string

Required. The resource name of a model or a version.

Authorization: requires the predict permission on the specified resource.

Authorization requires one or more of the following IAM permissions on the specified resource name:

  • ml.models.predict
  • ml.versions.predict

Request body

The request body contains data with the following structure:

JSON representation
{
  "httpBody": {
    object (HttpBody)
  }
}
Fields
httpBody

object (HttpBody)

Required. The prediction request body. Refer to the request body details section for more information on how to structure your request.

Response body

If successful, the response is a generic HTTP response whose format is defined by the method.

Authorization Scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.