RESTful API

علاوه بر gRPC رابط های برنامه کاربردی TensorFlow ModelServer همچنین پشتیبانی از رابط های برنامه کاربردی آرام. این صفحه این نقطه انتهایی API و پایان به پایان توصیف به عنوان مثال در استفاده از.

درخواست و پاسخ یک شی JSON است. ترکیب این شی به نوع درخواست یا فعل بستگی دارد. برای جزئیات بیشتر به بخش های خاص API در زیر مراجعه کنید.

در صورت خطا، تمام API ها را به یک شی JSON در متن پاسخ با بازگشت error به عنوان کلید و پیغام خطا را به عنوان ارزش:

{
  "error": <error message string>
}

API وضعیت مدل

این API نزدیک به پیروی از ModelService.GetModelStatus API gRPC. وضعیت یک مدل را در 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 API gRPC. فراداده یک مدل را در 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 رابط های برنامه کاربردی باید یک شی قالب 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 (کل یا اعشاری)، رشته 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> A (اعشاری) عدد اعشاری است.

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 API gRPC.

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

تانسورها به طور طبیعی در نمادهای تودرتو بیان می شوند زیرا نیازی به صاف کردن دستی لیست وجود ندارد.

برای ورودی‌های نام‌گذاری‌شده چندگانه، انتظار می‌رود که هر آیتم یک شی حاوی جفت مقدار ورودی نام/تانسور باشد، یکی برای هر ورودی نام‌گذاری‌شده. به عنوان مثال، در زیر درخواستی با دو نمونه است که هر کدام دارای مجموعه ای از سه تانسور ورودی نامگذاری شده است:

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

توجه داشته باشید، هر ورودی به نام ( "برچسب ها"، "سیگنال"، "سنسور") به طور ضمنی فرض همان 0 ام بعد (دو در مثال بالا، به عنوان دو اشیاء در لیست مواردی وجود دارد). اگر ورودی‌هایی را نام‌گذاری کرده‌اید که بعد 0 متفاوتی دارند، از قالب ستونی که در زیر توضیح داده شده است استفاده کنید.

تعیین تانسورهای ورودی در قالب ستون.

از این قالب برای تعیین تانسورهای ورودی خود استفاده کنید، در صورتی که ورودی‌های نام‌گذاری شده تکی همان بعد 0 را ندارند یا می‌خواهید نمایش فشرده‌تری داشته باشید. این قالب شبیه به است inputs زمینه gRPC Predict درخواست.

در فرمت ستونی، به ورودی ها به کلید ورودی در درخواست JSON کوک شده است.

ارزش برای کلید ورودی هم می توانید یک تانسور ورودی یک یا یک نقشه از نام ورودی به تانسورها (ذکر شده در صورت تو در تو طبیعی خود). هر ورودی می‌تواند شکل دلخواه داشته باشد و نیازی نیست همان بعد صفر (معروف به اندازه دسته‌ای) که در قالب ردیف توضیح داده شده در بالا مورد نیاز است، به اشتراک بگذارد.

نمایش ستونی مثال قبلی به شرح زیر است:

{
 "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

API های RESTful از یک رمزگذاری متعارف در JSON پشتیبانی می کنند که اشتراک گذاری داده ها را بین سیستم ها آسان تر می کند. برای انواع پشتیبانی شده، کدگذاری ها بر اساس نوع به نوع در جدول زیر توضیح داده شده است. انواعی که در زیر فهرست نشده اند، به طور ضمنی پشتیبانی نمی شوند.

دقت نقطه شناور

JSON دارای یک نوع داده واحد است. بنابراین می توان مقداری برای ورودی ارائه داد که منجر به از دست دادن دقت شود. برای مثال، اگر ورودی x است 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 در عمل است.

ModelServer را با نقطه پایانی REST API شروع کنید

دانلود 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 ...

REST API را با ModelServer فراخوانی کنید

در یک ترمینال مختلف، استفاده از 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)" }
$