예측 요청 형식 지정

애플리케이션 입력에 대한 응답으로 요청하거나 적시의 추론 (실시간 응답)이 필요한 상황에서 요청하는 경우에 온라인 예측을 사용하세요.

이 페이지에서는 맞춤 학습 모델에 온라인 예측 API를 사용하여 온라인 예측 요청을 포맷하는 방법을 보여주고 요청 및 응답의 예를 제공합니다. 요청 형식을 지정한 후 온라인 예측을 가져올 수 있습니다.

시작하기 전에

온라인 예측을 요청하기 위해 요청을 포맷하기 전에 다음 단계를 실행하세요.

  1. 예측용 모델 아티팩트 내보내기

  2. 모델 리소스를 엔드포인트에 배포

    이 작업은 컴퓨팅 리소스를 모델과 연결하여 짧은 지연 시간으로 온라인 예측을 제공할 수 있도록 합니다.

  3. 모델의 DeployedModel 커스텀 리소스 상태를 확인하고 예측 요청을 수락할 준비가 되었는지 확인합니다.

    kubectl --kubeconfig PREDICTION_CLUSTER_KUBECONFIG get -f DEPLOYED_MODEL_NAME.yaml -o jsonpath='{.status.primaryCondition}'

    다음을 바꿉니다.

    • PREDICTION_CLUSTER_KUBECONFIG: 예측 클러스터의 kubeconfig 파일 경로입니다.
    • DEPLOYED_MODEL_NAME: DeployedModel 정의 파일의 이름입니다.

    기본 조건은 DeployedModel가 준비되었음을 보여줘야 합니다.

    다음 출력은 샘플 응답을 보여줍니다.

    {"firstObservedTime":"2024-01-19T01:18:30Z","lastUpdateTime":"2024-01-19T01:35:47Z","message":"DeployedModel is ready", "observedGeneration":1, "reason":"Ready", "resourceName":"my-tf-model","type":"DeployedModel"}

  4. Endpoint 커스텀 리소스의 상태를 확인하고 예측 요청을 수락할 준비가 되었는지 확인합니다.

    kubectl --kubeconfig PREDICTION_CLUSTER_KUBECONFIG get -f ENDPOINT_NAME.yaml -o jsonpath='{$.status.conditions[?(@.type == "EndpointReady")]}'

    다음을 바꿉니다.

    • PREDICTION_CLUSTER_KUBECONFIG: 예측 클러스터의 kubeconfig 파일 경로입니다.
    • ENDPOINT_NAME: Endpoint 정의 파일의 이름입니다.

    EndpointReady 조건의 status 필드에는 True 값이 표시되어야 합니다.

    다음 출력은 샘플 응답을 보여줍니다.

    {"lastTransitionTime":"2024-01-19T05:12:26Z","message":"Endpoint Ready", "observedGeneration":1,"reason":"ResourceReady","status":"True","type":"EndpointReady"}%

온라인 예측 입력 형식 지정

온라인 예측에는 요청을 전송하는 다음 두 가지 방법이 있습니다.

  • 예측 요청: 온라인 예측을 가져오는 predict 메서드에 요청을 보냅니다.
  • 원시 예측 요청: rawPredict 메서드에 요청을 보냅니다. JSON 형식을 따르는 대신 임의 HTTP 페이로드를 사용할 수 있습니다.

지연 시간이 짧아야 하는 경우 rawPredict는 직렬화 단계를 건너뛰고 요청을 예측 컨테이너로 직접 전달하므로 원시 예측을 가져오세요.

이 섹션에서는 예측 입력 인스턴스의 형식을 JSON으로 지정하는 방법을 보여주는데, 이는 predict 메서드를 사용하는 경우에 필요합니다. rawPredict 메서드를 사용하는 경우에는 이 정보가 필요하지 않습니다.

Python용 Vertex AI SDK를 사용하여 예측 요청을 전송하는 경우 instances 필드 없이 인스턴스 목록을 지정합니다. 예를 들어 { "instances": [ ["the","quick","brown"], ... ] } 대신 [ ["the","quick","brown"], ... ]을 지정합니다.

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

온라인 예측의 기본 형식은 데이터 인스턴스 목록입니다. 학습 애플리케이션에서 입력을 구성한 방법에 따라 일반 값 목록 또는 JSON 객체의 멤버가 될 수 있습니다. TensorFlow 모델은 더 복잡한 입력을 수락할 수 있습니다.

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

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

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

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

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

  • 목록에는 같은 유형의 항목만 포함되어야 합니다(다른 목록 포함). 문자열과 숫자 값을 함께 사용하지 마세요.

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

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

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

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

바이너리 데이터는 JSON이 지원하는 UTF-8 인코딩된 문자열로 형식을 지정할 수 없습니다. 입력에 바이너리 데이터가 있는 경우 base64 인코딩을 사용하여 데이터를 나타냅니다. 다음 특수 형식이 필요합니다.

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

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

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

요청 및 응답 예시

이 섹션에서는 TensorFlow 및 PyTorch의 예를 사용하여 온라인 예측 요청 및 응답 본문의 형식을 설명합니다.

요청 본문 세부정보

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

여러 입력 텐서

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

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

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

입력 텐서 별칭 tag (문자열) 및 image(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],
          ...
        ],
        ...
      ]
    },
    ...
  ]
}

PyTorch

모델에서 PyTorch의 사전 빌드된 컨테이너를 사용하는 경우 TorchServe의 기본 핸들러는 각 인스턴스가 data 필드로 래핑될 것으로 예상합니다. 예를 들면 다음과 같습니다.

{
  "instances": [
    { "data": , <value> },
    { "data": , <value> }
  ]
}

응답 본문 세부정보

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

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

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

{
  "error": string
}

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

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

예측은 인스턴스당 하나씩이지만 예측의 형식은 인스턴스의 형식과 직접적인 관련이 없습니다. 예측은 모델에 정의된 출력 컬렉션에 지정된 형식을 취합니다. 예측 컬렉션은 JSON 목록으로 반환됩니다. 목록의 각 구성원은 값, 목록, 다양한 복잡성을 가지는 JSON 객체일 수 있습니다. 모델에 출력 텐서가 2개 이상 있는 경우 각 예측은 출력마다 키-값 쌍을 포함하는 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"}