이 페이지는 Cloud Translation API를 통해 번역되었습니다.
Switch to English

RESTful API

gRPC API 외에도 TensorFlow ModelServer는 RESTful API도 지원합니다. 이 페이지는 이러한 API 엔드 포인트와 사용법에 대한 엔드 투 엔드 예제 를 설명합니다.

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

오류가 발생하면 모든 API는 error 로 key를, 오류 메시지를 값으로하여 응답 본문에 JSON 객체를 반환합니다.

 {
  "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} 은 선택 사항입니다. 생략하면 모든 버전의 상태가 응답으로 리턴됩니다.

응답 형식

성공하면 GetModelStatusResponse protobuf의 JSON 표현을 리턴합니다.

모델 메타 데이터 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} 은 선택 사항입니다. 생략하면 최신 버전의 모델 메타 데이터가 응답으로 리턴됩니다.

응답 형식

성공하면 GetModelMetadataResponse protobuf의 JSON 표현을 리턴합니다.

API 분류 및 회귀

이 API는 PredictionService gRPC API의 ClassifyRegress 메소드를 밀접하게 따릅니다.

URL

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

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

요청 형식

classifyregress 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> 는 JSON 숫자 (정수 또는 십진수) 또는 문자열이며 <list> 는 이러한 값의 목록입니다. 이진 (바이트 스트림) 값을 나타내는 방법에 대한 자세한 내용은 아래 이진 값 인코딩 섹션을 참조하십시오. 이 형식은 gRPC의 ClassificationRequestRegressionRequest 프로토와 유사합니다. 두 버전 모두 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> 는 10 진수 (부동 소수점) 숫자입니다.

regress 요청은 다음과 같은 형식으로 응답 본문에 JSON 객체를 반환합니다.

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

<value> 은 10 진수입니다.

gRPC API 사용자는이 형식이 ClassificationResponseRegressionResponse 프로토와 유사하다는 것을 알 수 있습니다.

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 API의 요청 본문은 다음과 같은 형식의 JSON 객체 여야합니다.

 {
  // (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 차원이 다른 입력 이름을 지정한 경우 아래 설명 된 기둥 형식을 사용하십시오.

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

개별 명명 된 입력의 치수가 같지 않거나 더 작은 표현을 원하는 경우이 형식을 사용하여 입력 텐서를 지정하십시오. 이 형식은 gRPC Predict 요청의 inputs 필드와 유사합니다.

열 형식에서 입력은 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에서 표준 인코딩을 지원하므로 시스템간에 데이터를보다 쉽게 ​​공유 할 수 있습니다. 지원되는 유형의 경우, 인코딩은 유형별로 아래 표에 설명되어 있습니다. 아래에 나열되지 않은 유형은 지원되지 않는 것을 의미합니다.

TF 데이터 유형 JSON 가치 JSON 예 노트
DT_BOOL 허위 사실 허위 사실
DT_STRING "Hello World!" DT_STRING 2 진 바이트 (예 : 직렬화 된 이미지 바이트 또는 DT_STRING 나타내는 경우 Base64로 인코딩하십시오. 자세한 내용은 이진 값 인코딩을 참조하십시오.
DT_INT8, DT_UINT8, DT_INT16, DT_INT32, DT_UINT32, DT_INT64, DT_UINT64 번호 1, -10, 0 JSON 값은 10 진수입니다.
DT_FLOAT, DT_DOUBLE 번호 1.1, -10.0, 0, NaN , Infinity JSON 값은 NaN , Infinity-Infinity 와 같은 특수 토큰 값 중 하나이거나 숫자입니다. 자세한 정보는 JSON 준수 를 참조하십시오. 지수 표기법도 허용됩니다.

이진 값 인코딩

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 등) 외에도 NaNInfinity 아닌 ( Infinity-Infinity ) 값을 가질 수 있습니다. 불행히도 JSON 사양 ( RFC 7159 )은 이러한 값을 인식하지 못합니다 (JavaScript 사양은 해당).

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

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

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

NaN , Infinity , -Infinity 토큰은 proto3 , Python JSON 모듈 및 JavaScript 언어로 인식됩니다.

toy half_plus_three 모델을 사용하여 REST API가 작동하는지 확인할 수 있습니다.

REST API 엔드 포인트로 ModelServer 시작

git 저장소 에서 half_plus_three 모델을 다운로드하십시오.

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

Docker를 사용하여 ModelServer를 실행합니다. 시스템에 기본적으로 ModelServer를 설치하려면 설치 지시 사항 에 따라 대신 설치하고 --rest_api_port 옵션으로 ModelServer를 시작하여 REST API 엔드 포인트를 내보내십시오 (Docker를 사용할 때는 필요하지 않음).

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

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)" }
$