RESTful API

Ek olarak gRPC API'ler TensorFlow ModelServer da RESTful API'leri destekler. Bu sayfa, bu API uç noktaları ve bir uçtan uca açıklanır örnek kullanımı hakkında.

İstek ve yanıt bir JSON nesnesidir. Bu nesnenin bileşimi, istek türüne veya fiile bağlıdır. Ayrıntılar için aşağıdaki API'ye özel bölümlere bakın.

Hata durumunda, bütün API ile cevap gövdesinde bir JSON nesne döndürür error anahtar ve değer olarak hata mesajı olarak:

{
  "error": <error message string>
}

Model durumu API'si

Bu API yakından takip ModelService.GetModelStatus gRPC API. ModelServer'daki bir modelin durumunu döndürür.

URL

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

Dahil /versions/${VERSION} veya /labels/${LABEL} isteğe bağlıdır. Tüm sürümler için atlanırsa, yanıtta durum döndürülür.

Yanıt biçimi

Eğer başarılı olursa, bir JSON temsilini döndürür GetModelStatusResponse Protobuf.

Model Meta Veri API'sı

Bu API yakından takip PredictionService.GetModelMetadata gRPC API. ModelServer'daki bir modelin meta verilerini döndürür.

URL

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

Dahil /versions/${VERSION} veya /labels/${LABEL} isteğe bağlıdır. Atlanırsa, yanıtta en son sürüm için model meta verileri döndürülür.

Yanıt biçimi

Eğer başarılı olursa, bir JSON temsilini döndürür GetModelMetadataResponse Protobuf.

Sınıflandırma ve Regresyon API'si

Bu API yakından takip Classify ve Regress yöntemlerini PredictionService gRPC API.

URL

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

Dahil /versions/${VERSION} veya /labels/${LABEL} isteğe bağlıdır. Atlanırsa, en son sürüm kullanılır.

Talep formatı

Talebi vücut classify ve regress şöyle API'ler biçimlendirilmiş bir JSON nesnesi olması gerekir:

{
  // 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> bir (bütün veya onluk) JSON numarası JSON dizesi, veya ikili veri temsil eden bir JSON nesnesi (bakınız, kodlama iki haneli değerler, ayrıntılar için aşağıdaki bölümü). <list> tür değerlerin listesidir. Bu biçim gRPC en benzer ClassificationRequest ve RegressionRequest Protos. Her iki sürüm listesini kabul Example nesneler.

Yanıt biçimi

Bir classify aşağıdaki gibi istek biçimlendirilmiş cevap gövdesinde bir JSON nesnesi verir:

{
  "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> (boş bir dize olabilir bir dizedir "" modeli puanı ile ilişkili bir etiket yoksa). <score> ondalık (floating point) sayıdır.

regress aşağıdaki gibi istek biçimlendirilmiş cevap gövdesinde bir JSON nesnesi verir:

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

<value> , ondalık bir sayıdır.

GRPC API kullanıcıları bu formatın benzerliği göreceksiniz ClassificationResponse ve RegressionResponse Protos.

Tahmin API'sı

Bu API yakından takip PredictionService.Predict gRPC API.

URL

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

Dahil /versions/${VERSION} veya /labels/${LABEL} isteğe bağlıdır. Atlanırsa, en son sürüm kullanılır.

Talep formatı

Talebi vücut predict aşağıdaki gibi JSON nesnesi biçimlendirilmiş olması gerekir 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>
}

Giriş tensörlerini satır biçiminde belirtme.

Bu biçim benzer PredictRequest gRPC API proto ve CMLE API tahmin . Hepsinin adı giriş tansörleri aynı 0-inci boyut varsa bu biçimi kullanın. Aksi takdirde, aşağıda daha sonra açıklanan sütun biçimini kullanın.

Satır biçiminde, giriş JSON isteği örnekleri anahtarına kilitlenmiştir.

Sadece bir adlandırılmış giriş olduğunda, girişin değeri olarak anahtar örneklerinin değerini belirtmek:

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

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

Tensörler, listeyi manuel olarak düzleştirmeye gerek olmadığından, iç içe gösterimde doğal olarak ifade edilir.

Birden çok adlandırılmış girdi için, her öğenin, her adlandırılmış girdi için bir tane olmak üzere girdi adı/tensör değeri çiftini içeren bir nesne olması beklenir. Örnek olarak, aşağıdaki, her biri adlandırılmış üç giriş tensörü kümesine sahip iki örneği olan bir istektir:

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

Not adı geçen her girişi ( "etiket", "sinyal", "algılayıcı") örtülü (Örnek listesinde iki nesne olduğu gibi, yukarıdaki örnekte iki adet) aynı 0-inci boyuta sahip olduğu varsayılır. 0'ıncı boyutu farklı olan girdileri adlandırdıysanız, aşağıda açıklanan sütun biçimini kullanın.

Giriş tensörlerini sütun biçiminde belirtme.

Bireysel adlandırılmış girişler aynı 0. boyuta sahip değilse veya daha kompakt bir temsil istiyorsanız, giriş tensörlerinizi belirtmek için bu biçimi kullanın. Bu biçim benzer inputs gRPC alanında Predict isteği.

Sütun biçiminde, giriş JSON isteği girişler anahtarına kilitlenmiştir.

Giriş anahtarının değer tek bir giriş tensör veya tansörlerine giriş adına bir harita ya (doğal içiçe listelenmiştir) olabilir. Her girdi isteğe bağlı bir şekle sahip olabilir ve yukarıda açıklanan satır formatının gerektirdiği şekilde/aynı 0. boyutu (diğer bir deyişle parti boyutu) paylaşması gerekmez.

Önceki örneğin sütunlu gösterimi aşağıdaki gibidir:

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

Not, veriler bir JSON nesnesi olup (satır temsil kullanılan) örnekleri gibi bir liste bulunmaktadır. Ayrıca, daha önce açıklanan satır biçiminde yapılan tek tek satırlara açmak yerine, tüm adlandırılmış girdiler birlikte belirtilir. Bu, temsili kompakt hale getirir (ancak belki daha az okunabilir).

Yanıt biçimi

predict istek döner tepki vücutta bir JSON nesnesi.

Bir istek satır biçimi şöyle yanıt biçimlendirilmiş etti:

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

Modelin çıkış tek adlandırılmış tensörünü varsa, onu isim ve ihmal predictions anahtar skaler veya liste değerlerinin bir listesini eşler. Model birden çok adlandırılmış tensör verirse, bunun yerine yukarıda belirtilen satır biçimindeki isteğe benzer şekilde bir nesne listesi çıkartırız.

Bir istek sütunlu formatta aşağıdaki gibi tepki biçimlendirilmiş etti:

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

Modelin çıkış tek adlandırılmış tensörünü varsa, onu adını ihmal ve outputs anahtar skaler veya liste değerlerinin bir listesini eşler. Model birden çok adlandırılmış tensör verirse, bunun yerine bir nesne çıktısı alırız. Bu nesnenin her anahtarı, adlandırılmış bir çıktı tensörüne karşılık gelir. Biçim, yukarıda belirtilen sütun biçimindeki isteğe benzer.

İkili değerlerin çıktısı

TensorFlow, ikili olmayan ve ikili dizeler arasında ayrım yapmaz. Tüm edilir DT_STRING türü. Sahip Named tansörler _bytes kendi adlarına bir sonek olarak ikili değerlere sahip olduğu kabul edilir. De tarif edildiği gibi bu tür değerler, farklı kodlanmış kodlayan iki haneli değerler, aşağıdaki bölümde.

JSON eşlemesi

RESTful API'ler, JSON'da kurallı bir kodlamayı destekleyerek sistemler arasında veri paylaşımını kolaylaştırır. Desteklenen türler için kodlamalar, aşağıdaki tabloda tür bazında açıklanmıştır. Aşağıda listelenmeyen türlerin desteklenmediği ima edilmektedir.

TF Veri Türü JSON Değeri JSON örneği notlar
DT_BOOL doğru yanlış doğru yanlış
DT_STRING sicim "Selam Dünya!" Eğer DT_STRING ikili bayt (örn tefrika görüntü bayt veya protobuf), kodlamak Base64 bu temsil eder. Bkz ikili değerlerini Kodlama fazla bilgi için.
DT_INT8, DT_UINT8, DT_INT16, DT_INT32, DT_UINT32, DT_INT64, DT_UINT64 numara 1, -10, 0 JSON değeri ondalık bir sayı olacaktır.
DT_FLOAT, DT_DOUBLE numara 1.1, -10.0, 0, NaN , Infinity - JSON değer bir sayı ya da özel belirteç değerlerden biri olacak NaN , Infinity ve -Infinity . Bkz JSON uygunluğunu daha fazla bilgi için. Üs gösterimi de kabul edilir.

Kayan Nokta Hassasiyeti

JSON, tek bir sayı veri türüne sahiptir. Böylece, bir girdi için kesinlik kaybıyla sonuçlanan bir değer sağlamak mümkündür. Giriş Örneğin, x a, float veri tipi ve giriş {"x": 1435774380} modeli IEEE 754 kayan noktalı bir standarda (örneğin Intel veya AMD), değer olacak göre donanım üzerinde çalışan gönderilir sessizce için, altta yatan donanım tarafından dönüştürülebilir 1435774336 beri 1435774380 tam bir 32 bit kayan noktalı sayı temsil edilemez. Tipik olarak, hizmete yönelik girdiler eğitimle aynı dağıtım olmalıdır, bu nedenle aynı dönüşümler eğitim zamanında gerçekleştiğinden bu genellikle sorunlu olmaz. Bununla birlikte, tam kesinliğe ihtiyaç duyulması durumunda, modelinizde istenen kesinliği işleyebilecek bir temel veri türü kullandığınızdan emin olun ve/veya müşteri tarafı kontrolünü dikkate alın.

İkili değerleri kodlama

JSON, UTF-8 kodlamasını kullanır. Eğer (görüntü bayt gibi) ihtiyaç ikili olmak o giriş özelliğini veya tensör değerleri varsa, yapmanız gerekir Base64 verilerini kodlamak ve sahip bir JSON nesnesi hapsetmek b64 aşağıdaki gibi anahtar olarak:

{ "b64": <base64 encoded string> }

Bu nesneyi bir giriş özelliği veya tensör için bir değer olarak belirleyebilirsiniz. Aynı format, çıktı yanıtını kodlamak için de kullanılır.

A sınıflandırma talebi image (ikili veriler) ve caption özellikleri aşağıda gösterilmiştir:

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

JSON uygunluğu

Birçok özellik veya tensör değeri kayan nokta sayılarıdır. Yanı sıra, sonlu değerlere bu olabilir (3.14, 1.0 malzemeleri gibi) NaN olmayan sıvılan ( Infinity ve -Infinity ) değerleri. Maalesef JSON şartname ( , RFC 7159 ) (JavaScript şartname olsa) bu değerleri tanıması DEĞİLDİR.

Bu sayfada açıklanan REST API, istek/yanıt JSON nesnelerinin bu tür değerlere sahip olmasına izin verir. Bu, aşağıdaki gibi isteklerin geçerli olduğu anlamına gelir:

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

A (katı) standartlarına uyumlu JSON ayrıştırıcı (nedeniyle bir çözümleme hatası vererek bu reddeder NaN ve Infinity gerçek sayılar ile karışık belirteçleri). Kodunuzdaki istekleri/yanıtları doğru şekilde işlemek için bu belirteçleri destekleyen bir JSON ayrıştırıcısı kullanın.

NaN , Infinity , -Infinity belirteçleri tarafından tanınan proto3 , Python JSON modülü ve JavaScript dili.

Örnek

Biz oyuncak kullanabilirsiniz half_plus_three eylem DİNLENME API'leri görmek modeli.

ModelServer'ı REST API uç noktasıyla başlatın

İndir half_plus_three gelen modeli git depo :

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

ModelServer'ı çalıştırmak için Docker'ı kullanacağız. Eğer sisteminizde yerel olarak ModelServer yüklemek takip etmek isterseniz kurulum talimatlarını yerine yüklemek ve birlikte ModelServer başlamak --rest_api_port ihracat DİNLENME API bitiş seçeneği (Docker kullanırken bu gerekli değildir).

$ 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'a REST API çağrıları yapın

Farklı bir terminalde, kullanımı curl DİNLENME API çağrıları yapmak için bir araç.

Modelin durumunu aşağıdaki gibi alın:

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

Bir predict şöyle çağrı görünecektir:

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

Ve bir regress çağrı görünüyor olarak aşağıdaki gibidir:

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

Not regress varsayılan olmayan bir imza ismine mevcuttur ve açıkça belirtilmelidir. Yanlış bir istek URL'si veya gövdesi, bir HTTP hata durumu döndürür.

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