Bu sayfa, Cloud Translation API ile çevrilmiştir.
Switch to English

RESTful API

GRPC API'lerine ek olarak TensorFlow ModelServer, RESTful API'leri de destekler. Bu sayfada, bu API uç noktaları ve kullanımla ilgili uçtan uca bir örnek açıklanmaktadır .

İ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 özgü 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, ModelService.GetModelStatus gRPC API'sini yakından takip eder. ModelServer'daki bir modelin durumunu döndürür.

URL

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

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

Yanıt biçimi

Başarılı olursa, GetModelStatusResponse JSON temsilini döndürür.

Model Meta Veri API'si

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

URL

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

/versions/${VERSION} veya /labels/${LABEL} dahil olmak isteğe bağlıdır. Atlanırsa, en son sürüme ilişkin model meta verileri yanıtta döndürülür.

Yanıt biçimi

Başarılı olursa, GetModelMetadataResponse JSON temsilini döndürür.

API'yi Sınıflandırın ve Yeniden Düzenleyin

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)

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

İstek biçimi

classify ve regress API'leri için istek gövdesi, aşağıdaki gibi biçimlendirilmiş bir JSON nesnesi olmalıdır:

{
  // 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 JSON numarası (tam veya ondalık) veya dizedir ve <list> bu tür değerlerin bir listesidir. İkili (bayt akışı) bir değerin nasıl temsil edileceğiyle ilgili ayrıntılar için aşağıdaki İkili değerleri kodlama bölümüne bakın. Bu biçim, gRPC'nin ClassificationRequest ve RegressionRequest prototiplerine benzer. Her iki sürüm de Example nesnelerin listesini kabul eder.

Yanıt biçimi

classify isteği, yanıt gövdesinde aşağıdaki gibi biçimlendirilmiş bir JSON nesnesi döndürür:

{
  "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> bir dizedir (modelin puanla ilişkilendirilmiş bir etiketi yoksa "" boş bir dize olabilir). <score> , ondalık (kayan nokta) bir sayıdır.

regress isteği, yanıt gövdesinde aşağıdaki gibi biçimlendirilmiş bir JSON nesnesi döndürür:

{
  // 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 ClassificationResponse ve RegressionResponse protoları ile benzerliğini fark edeceklerdir.

Predict API

Bu API, PredictionService.Predict gRPC API'sini yakından takip eder.

URL

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

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

İstek biçimi

predict API'si için istek gövdesi, aşağıdaki gibi biçimlendirilmiş JSON nesnesi olmalıdır:

{
  // (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>
}

Satır formatında girdi tensörlerini belirleme.

Bu biçim, gRPC API'sinin PredictRequest protokolüne ve CMLE tahmin API'sine benzer . Tüm adlandırılmış giriş tensörleri aynı 0-inci boyuta sahipse 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şler JSON isteğindeki örnekler anahtarına anahtarlanır.

Yalnızca bir adlandırılmış girdi olduğunda, girdinin değeri olarak örnek anahtarının değerini belirtin:

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

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

Listeyi manuel olarak düzleştirmeye gerek olmadığından, tensörler 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ğer ç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ğe sahip 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. Farklı 0-inci boyuta sahip girdileri adlandırdıysanız, aşağıda açıklanan sütun biçimini kullanın.

Giriş tensörlerini sütun formatında belirleme.

Tek tek adlandırılmış girişler aynı 0-inci boyuta sahip değilse veya daha kompakt bir gösterim istiyorsanız, giriş tensörlerinizi belirtmek için bu biçimi kullanın. Bu biçim, gRPC Predict isteğinin inputs alanına benzer.

Sütunlu formatta, girdiler JSON isteğindeki giriş anahtarına anahtarlanır.

Giriş anahtarının değeri, tek bir giriş tensörü veya tensörlere giriş adının bir haritası olabilir (doğal iç içe formlarında listelenir). Her girdi keyfi bir şekle sahip olabilir ve yukarıda açıklanan satır formatının gerektirdiği / aynı 0-inci boyutu (diğer bir deyişle toplu iş boyutu) paylaşması gerekmez.

Önceki örneğin sütunlu temsili 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]]]
 }
}

Unutmayın, girişler bir JSON nesnesidir ve örnekler gibi bir liste değildir (satır gösteriminde kullanılır). Ayrıca, daha önce açıklanan satır biçiminde yapılan tek tek satırlara kaydırmanın tersine, tüm adlandırılmış girdiler birlikte belirtilir. Bu, gösterimi kompakt hale getirir (ancak belki daha az okunabilir).

Yanıt biçimi

predict isteği, yanıt gövdesinde bir JSON nesnesi döndürür.

Satır biçimindeki bir isteğin yanıtı aşağıdaki gibi biçimlendirilmiştir:

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

Modelin çıktısı yalnızca bir adlandırılmış tensör içeriyorsa, ad ve predictions anahtar eşlemelerini bir skaler veya liste değerleri listesine dahil etmeyiz. Model birden çok adlandırılmış tensör çıkarsa, bunun yerine yukarıda bahsedilen satır biçimindeki isteğe benzer şekilde bir nesne listesi çıkarırız.

Sütunlu biçimdeki bir istek yanıtı aşağıdaki gibi biçimlendirilmiştir:

{
  "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 çıkarsa, bunun yerine bir nesne çıkarı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. Hepsi DT_STRING tipindedir. _bytes son ek olarak _bytes olan adlandırılmış tensörlerin ikili değerleri olduğu kabul edilir. Bu tür değerler, aşağıdaki ikili değerleri kodlama bölümünde açıklandığı gibi farklı şekilde kodlanır.

JSON eşlemesi

RESTful API'ler, JSON'da kanonik 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ürlere göre 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 dizi "Selam Dünya!" DT_STRING ikili baytları temsil ediyorsa (örn. Serileştirilmiş görüntü baytları veya protobuf), bunları Base64'te kodlayın. Daha fazla bilgi için İkili değerleri kodlama konusuna bakın.
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ğeri, NaN , Infinity ve -Infinity özel belirteç değerlerinden biri veya bir sayı olacaktır. Daha fazla bilgi için JSON uyumluluğuna bakın. Üs gösterimi de kabul edilir.

İ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 belirtebilirsiniz. Aynı format çıktı yanıtını kodlamak için de kullanılır.

image (ikili veri) ve caption özellikleri içeren bir sınıflandırma talebi aşağıda gösterilmiştir:

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

JSON uyumluluğu

Çoğu özellik veya tensör değeri kayan nokta sayılarıdır. Sonlu değerlerin (ör. 3.14, 1.0 vb.) Dışında, bunlar NaN ve sonlu olmayan ( Infinity ve -Infinity ) değerlere sahip olabilir. 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 ]
    }
  ]
}

(Katı) standartlarla uyumlu bir JSON ayrıştırıcısı, bunu bir ayrıştırma hatasıyla reddeder (gerçek sayılarla karıştırılan NaN ve Infinity belirteçleri nedeniyle). Kodunuzdaki istekleri / yanıtları doğru şekilde işlemek için, bu simgeleri destekleyen bir JSON ayrıştırıcısı kullanın.

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

Misal

REST API'leri çalışırken görmek için toy half_plus_three modelini kullanabiliriz.

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

half_plus_three modelini git deposundan indirin :

$ 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. ModelServer'ı sisteminize yerel olarak kurmak istiyorsanız, kurulum talimatlarını izleyin ve REST API uç noktasını dışa aktarmak için ModelServer'ı --rest_api_port seçeneğiyle başlatın (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, REST API çağrıları yapmak için curl aracını kullanın.

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 çağrısı aşağıdaki gibi 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ısı aşağıdaki gibi görünür:

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

Unutmayın, regress varsayılan olmayan bir imza adında mevcuttur ve açıkça belirtilmelidir. Yanlış bir istek URL'si veya gövde, 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)" }
$