RESTful API

뿐만 아니라 gRPC API를 TensorFlow ModelServer 또한 편안하고 API를 지원합니다. 이 페이지는 이러한 API 엔드 포인트 및 엔드 - 투 - 엔드 설명 예 사용에 있습니다.

요청 및 응답은 JSON 개체입니다. 이 개체의 구성은 요청 유형 또는 동사에 따라 다릅니다. 자세한 내용은 아래 API별 섹션을 참조하세요.

오류가 발생하는 경우, 모든 API 함께 응답 본문에서 JSON 객체를 리턴 error 키 값과 에러 메세지로서 :

{
  "error": <error message string>
}

모델 상태 API

이 API는 밀접하게 다음과 ModelService.GetModelStatus gRPC API를. ModelServer에서 모델의 상태를 반환합니다.

URL

GET http://host:port/v1/models/${MODEL_NAME}[/versions/${VERSION}|/labels/${LABEL}]

포함 /versions/${VERSION} 또는 /labels/${LABEL} 선택 사항입니다. 생략된 경우 모든 버전에 대한 상태가 응답으로 반환됩니다.

응답 형식

성공하면,의 JSON 표현을 반환 GetModelStatusResponse protobuf을.

모델 메타데이터 API

이 API는 밀접하게 다음과 PredictionService.GetModelMetadata gRPC API를. ModelServer에 있는 모델의 메타데이터를 반환합니다.

URL

GET http://host:port/v1/models/${MODEL_NAME}[/versions/${VERSION}|/labels/${LABEL}]/metadata

포함 /versions/${VERSION} 또는 /labels/${LABEL} 선택 사항입니다. 생략하면 최신 버전의 모델 메타데이터가 응답으로 반환됩니다.

응답 형식

성공하면,의 JSON 표현을 반환 GetModelMetadataResponse protobuf을.

API 분류 및 회귀

이 API는 밀접하게 다음 Classify 및 Regress 방법 PredictionService gRPC API를.

URL

POST http://host:port/v1/models/${MODEL_NAME}[/versions/${VERSION}|/labels/${LABEL}]:(classify|regress)

포함 /versions/${VERSION} 또는 /labels/${LABEL} 선택 사항입니다. 생략하면 최신 버전이 사용됩니다.

요청 형식

에 대한 요청 본문 classify 및 regress 다음과 같이 API는 포맷 된 JSON 객체를해야합니다 :

{
  // Optional: serving signature to use.
  // If unspecifed default serving signature is used.
  "signature_name": <string>,

  // Optional: Common context shared by all examples.
  // Features that appear here MUST NOT appear in examples (below).
  "context": {
    "<feature_name3>": <value>|<list>
    "<feature_name4>": <value>|<list>
  },

  // List of Example objects
  "examples": [
    {
      // Example 1
      "<feature_name1>": <value>|<list>,
      "<feature_name2>": <value>|<list>,
      ...
    },
    {
      // Example 2
      "<feature_name1>": <value>|<list>,
      "<feature_name2>": <value>|<list>,
      ...
    }
    ...
  ]
}

<value> A (전체 또는 소수) JSON 번호 JSON 문자열이나 이진 데이터를 나타내는 객체 JSON (투시이다 인코딩 이진 값의 자세한 내용은 아래 섹션). <list> 이러한 값의리스트이다. 이 형식은 gRPC의 유사합니다 ClassificationRequest 및 RegressionRequest PROTOS. 두 버전의 목록을 받아 Example 객체.

응답 형식

classify 는 다음과 같이 요청 형식, 응답 본문에서 JSON 개체를 반환합니다 :

{
  "result": [
    // List of class label/score pairs for first Example (in request)
    [ [<label1>, <score1>], [<label2>, <score2>], ... ],

    // List of class label/score pairs for next Example (in request)
    [ [<label1>, <score1>], [<label2>, <score2>], ... ],
    ...
  ]
}

<label> (빈 문자열이 될 수있는 문자열이다 "" 모델이 점수와 관련된 라벨이없는 경우). <score> 소수 (부동 소수점) 수이다.

regress 다음과 같이 요청 형식, 응답 본문에서 JSON 개체를 반환합니다 :

{
  // One regression value for each example in the request in the same order.
  "result": [ <value1>, <value2>, <value3>, ...]
}

<value> 십진수이다.

gRPC API의 사용자는이 형식의 유사성 알 수 ClassificationResponse 및 RegressionResponse PROTOS을.

API 예측

이 API는 밀접하게 다음과 PredictionService.Predict gRPC API를.

URL

POST http://host:port/v1/models/${MODEL_NAME}[/versions/${VERSION}|/labels/${LABEL}]:predict

포함 /versions/${VERSION} 또는 /labels/${LABEL} 선택 사항입니다. 생략하면 최신 버전이 사용됩니다.

요청 형식

에 대한 요청 본문 predict 다음과 같이 JSON 객체를 포맷해야합니다 API를 :

{
  // (Optional) Serving signature to use.
  // If unspecifed default serving signature is used.
  "signature_name": <string>,

  // Input Tensors in row ("instances") or columnar ("inputs") format.
  // A request can have either of them but NOT both.
  "instances": <value>|<(nested)list>|<list-of-objects>
  "inputs": <value>|<(nested)list>|<object>
}

행 형식으로 입력 텐서를 지정합니다.

이 형식은 유사하다 PredictRequest gRPC의 API의 프로토과 CMLE는 API를 예측 . 모든 이름을 입력 텐서가 동일 0 번째 차원이있는 경우이 형식을 사용합니다. 그렇지 않은 경우 아래에 설명된 열 형식을 사용합니다.

행 형식에서 입력은 JSON 요청의 경우 키에 키가 있습니다.

단 하나의 이름 입력이있는 경우, 입력의 값으로 키 인스턴스의 값을 지정합니다 :

{
  // List of 3 scalar tensors.
  "instances": [ "foo", "bar", "baz" ]
}

{
  // List of 2 tensors each of [1, 2] shape
  "instances": [ [[1, 2]], [[3, 4]] ]
}

목록을 수동으로 평면화할 필요가 없기 때문에 텐서는 중첩 표기법으로 자연스럽게 표현됩니다.

여러 명명된 입력의 경우 각 항목은 각 명명된 입력에 대해 하나씩 입력 이름/텐서 값 쌍을 포함하는 객체여야 합니다. 예를 들어 다음은 각각 3개의 명명된 입력 텐서 세트가 있는 2개의 인스턴스가 있는 요청입니다.

{
 "instances": [
   {
     "tag": "foo",
     "signal": [1, 2, 3, 4, 5],
     "sensor": [[1, 2], [3, 4]]
   },
   {
     "tag": "bar",
     "signal": [3, 4, 1, 2, 5]],
     "sensor": [[4, 5], [6, 8]]
   }
 ]
}

참고 각 지명 입력 ( "태그", "신호", "센서") 암시 (인스턴스 목록의 두 개체가있는 한, 상기 예에서는 2 개) 동일 0 번째의 차원을 가정한다. 0차원이 다른 명명된 입력이 있는 경우 아래에 설명된 열 형식을 사용하십시오.

열 형식으로 입력 텐서를 지정합니다.

명명된 개별 입력에 동일한 0차원이 없거나 보다 간결한 표현을 원하는 경우 이 형식을 사용하여 입력 텐서를 지정합니다. 이 형식은 비슷합니다 inputs gRPC의 필드 Predict 요청을.

원주의 형식에서 입력은 JSON 요청의 입력 키에 키가 있습니다.

입력 키의 값은 단일 입력 텐서 또는 텐서에 입력 된 이름의지도 중 하나는 (자연 중첩 된 형태로 나열) 할 수 있습니다. 각 입력은 임의의 모양을 가질 수 있으며 위에서 설명한 행 형식에서 요구하는 것과 동일한 0차원(일명 배치 크기)을 공유할 필요가 없습니다.

이전 예제의 열 표현은 다음과 같습니다.

{
 "inputs": {
   "tag": ["foo", "bar"],
   "signal": [[1, 2, 3, 4, 5], [3, 4, 1, 2, 5]],
   "sensor": [[[1, 2], [3, 4]], [[4, 5], [6, 8]]]
 }
}

참고 입력은 JSON 객체 아닌 (행 표현을 사용)와 같은 인스턴스 목록이다. 또한 이전에 설명한 행 형식으로 수행된 개별 행으로 펼치는 것과 달리 명명된 모든 입력이 함께 지정됩니다. 이것은 표현을 간결하게 만듭니다(그러나 덜 읽을 수 있음).

응답 형식

는 predict 요청을 반환 응답 본문에서 JSON 개체를.

에 요청 행 형식은 다음과 같이 응답 포맷하고있다 :

{
  "predictions": <value>|<(nested)list>|<list-of-objects>
}

모델의 출력은 하나의 이름 텐서가 포함되어있는 경우, 우리는 이름과 생략 predictions 키가 스칼라 또는 목록 값 목록에 매핑됩니다. 모델이 여러 명명된 텐서를 출력하는 경우 위에서 언급한 행 형식의 요청과 유사한 객체 목록을 대신 출력합니다.

에 요청 원주 형식은 다음과 같이 응답 포맷하고있다 :

{
  "outputs": <value>|<(nested)list>|<object>
}

모델의 출력은 하나의 이름 텐서가 포함되어있는 경우, 우리는 이름을 생략하고 outputs 키 스칼라 또는 목록 값 목록에 매핑됩니다. 모델이 여러 명명된 텐서를 출력하는 경우 대신 객체를 출력합니다. 이 객체의 각 키는 명명된 출력 텐서에 해당합니다. 형식은 위에서 언급한 열 형식의 요청과 유사합니다.

이진 값의 출력

TensorFlow는 이진이 아닌 문자열과 이진 문자열을 구분하지 않습니다. 모든있다 DT_STRING 유형입니다. 이 명명 된 텐서 _bytes 자신의 이름에 접미사로는 바이너리 값을 가질 것으로 간주됩니다. 에서 설명한 바와 같이 이러한 값은 다르게 인코딩 된 인코딩 이진 값 아래 섹션.

JSON 매핑

RESTful API는 JSON의 표준 인코딩을 지원하므로 시스템 간에 데이터를 더 쉽게 공유할 수 있습니다. 지원되는 유형의 경우 아래 표에 유형별로 인코딩이 설명되어 있습니다. 아래에 나열되지 않은 유형은 지원되지 않는 것으로 간주됩니다.

부동 소수점 정밀도

JSON에는 단일 숫자 데이터 유형이 있습니다. 따라서 정밀도 손실을 초래하는 입력 값을 제공할 수 있습니다. 입력하면 예를 들어, x A는 float 데이터 유형 및 입력은 {"x": 1435774380} 모델이 IEEE 754 부동 소수점 표준 (예를 들어 인텔 또는 AMD), 값이 의지에 따라 하드웨어에서 실행에 보내진다 자동으로 underyling 하드웨어 변환 1435774336 때문에 1435774380 정확히 32 비트 부동 소수점 수로 표현 될 수 없다. 일반적으로 제공에 대한 입력은 훈련과 동일한 분포여야 하므로 훈련 시간에 동일한 변환이 발생하기 때문에 일반적으로 문제가 되지 않습니다. 그러나 완전한 정밀도가 필요한 경우 원하는 정밀도를 처리할 수 있고/거나 클라이언트 측 검사를 고려할 수 있는 기본 데이터 유형을 모델에 사용해야 합니다.

이진 값 인코딩

JSON은 UTF-8 인코딩을 사용합니다. 당신은 (이미지 바이트 등) 필요가 바이너리 것을 입력 기능이나 텐서 값이있는 경우, 당신이해야 Base64로 데이터를 인코딩 갖는 JSON 객체를 캡슐화 b64 다음과 같이 키로 :

{ "b64": <base64 encoded string> }

이 개체를 입력 기능 또는 텐서의 값으로 지정할 수 있습니다. 동일한 형식이 출력 응답을 인코딩하는 데에도 사용됩니다.

함께 분류 요청 image (이진 데이터) 및 caption 기능은 아래에 도시된다 :

{
  "signature_name": "classify_objects",
  "examples": [
    {
      "image": { "b64": "aW1hZ2UgYnl0ZXM=" },
      "caption": "seaside"
    },
    {
      "image": { "b64": "YXdlc29tZSBpbWFnZSBieXRlcw==" },
      "caption": "mountains"
    }
  ]
}

JSON 적합성

많은 기능 또는 텐서 값은 부동 소수점 숫자입니다. 아파트에서 유한 값이 가질 수있는 (3.14, 1.0 등의 예) NaN 비 한정된 ( Infinity 와 -Infinity ) 값. 불행히도 JSON 사양 ( RFC 7159는 ) (자바 스크립트 사양 않습니다하지만) 이러한 값을 인식하지 않습니다.

이 페이지에 설명된 REST API를 사용하면 요청/응답 JSON 객체가 이러한 값을 가질 수 있습니다. 이는 다음과 같은 요청이 유효함을 의미합니다.

{
  "example": [
    {
      "sensor_readings": [ 1.0, -3.14, Nan, Infinity ]
    }
  ]
}

A (엄격한) 표준을 준수 JSON 파서 (인해 구문 분석 오류로이를 거부 NaN 와 Infinity 실제 번호로 혼합 토큰). 코드에서 요청/응답을 올바르게 처리하려면 이러한 토큰을 지원하는 JSON 파서를 사용하십시오.

NaN , Infinity , -Infinity 토큰으로 인식 proto3 , 파이썬 JSON의 모듈과 자바 스크립트 언어입니다.

예시

우리는 장난감 사용할 수 있습니다 half_plus_three의 행동에 REST API를 참조하는 모델.

REST API 끝점으로 ModelServer 시작

다운로드 half_plus_three 에서 모델 자식 저장소 :

$ mkdir -p /tmp/tfserving
$ cd /tmp/tfserving
$ git clone --depth=1 https://github.com/tensorflow/serving

Docker를 사용하여 ModelServer를 실행합니다. 당신이 당신의 시스템에 기본적으로 ModelServer를 설치 따르십시오 설치 방법을 대신 설치하고, 함께 ModelServer 시작 --rest_api_port 수출 REST API를 엔드 포인트에 대한 옵션을 (부두 노동자를 사용하는 경우이 필요하지 않습니다).

$ cd /tmp/tfserving
$ docker pull tensorflow/serving:latest
$ docker run --rm -p 8501:8501 \
    --mount type=bind,source=$(pwd),target=$(pwd) \
    -e MODEL_BASE_PATH=$(pwd)/serving/tensorflow_serving/servables/tensorflow/testdata \
    -e MODEL_NAME=saved_model_half_plus_three -t tensorflow/serving:latest
...
.... Exporting HTTP/REST API at:localhost:8501 ...

ModelServer에 대한 REST API 호출 만들기

다른 단말기에서 사용 curl REST API를 호출하는 도구.

다음과 같이 모델의 상태를 가져옵니다.

$ curl http://localhost:8501/v1/models/saved_model_half_plus_three
{
 "model_version_status": [
  {
   "version": "123",
   "state": "AVAILABLE",
   "status": {
    "error_code": "OK",
    "error_message": ""
   }
  }
 ]
}

A는 predict 다음과 같이 호출이 보일 것이다 :

$ curl -d '{"instances": [1.0,2.0,5.0]}' -X POST http://localhost:8501/v1/models/saved_model_half_plus_three:predict
{
    "predictions": [3.5, 4.0, 5.5]
}

그리고 regress 호출 모습은 다음과 같습니다 :

$ curl -d '{"signature_name": "tensorflow/serving/regress", "examples": [{"x": 1.0}, {"x": 2.0}]}' \
  -X POST http://localhost:8501/v1/models/saved_model_half_plus_three:regress
{
    "results": [3.5, 4.0]
}

참고 regress 아닌 기본 서명 이름을 볼 수 있습니다 명시 적으로 지정해야합니다. 잘못된 요청 URL 또는 본문은 HTTP 오류 상태를 반환합니다.

$ curl -i -d '{"instances": [1.0,5.0]}' -X POST http://localhost:8501/v1/models/half:predict
HTTP/1.1 404 Not Found
Content-Type: application/json
Date: Wed, 06 Jun 2018 23:20:12 GMT
Content-Length: 65

{ "error": "Servable not found for request: Latest(half)" }
$