علاوه بر 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 پشتیبانی می کنند که اشتراک گذاری داده ها را بین سیستم ها آسان تر می کند. برای انواع پشتیبانی شده، کدگذاری ها بر اساس نوع به نوع در جدول زیر توضیح داده شده است. انواعی که در زیر فهرست نشده اند، به طور ضمنی پشتیبانی نمی شوند.
نوع داده TF | مقدار JSON | مثال JSON | یادداشت |
---|---|---|---|
DT_BOOL | درست غلط | درست غلط | |
DT_STRING | رشته | "سلام دنیا!" | اگر DT_STRING نشان دهنده بایت باینری (به عنوان مثال بایت تصویر مرتب یا protobuf)، رمزگذاری این در با Base64. مشاهده : رمز گذاری ارزش های دودویی برای اطلاعات بیشتر. |
DT_INT8، DT_UINT8، DT_INT16، DT_INT32، DT_UINT32، DT_INT64، DT_UINT64 | عدد | 1، -10، 0 | مقدار JSON یک عدد اعشاری خواهد بود. |
DT_FLOAT، DT_DOUBLE | عدد | 1.1، -10.0، 0، NaN ، Infinity | ارزش JSON خواهد بود تعداد و یا یکی از مقادیر نمادین ویژه - NaN ، Infinity ، و -Infinity . مشاهده 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)" }
$