RESTful API

นอกจาก gRPC API แล้ว TensorFlow ModelServer ยังรองรับ RESTful API อีกด้วย หน้านี้อธิบายจุดสิ้นสุด API เหล่านี้และ ตัวอย่าง การใช้งานแบบครบวงจร

คำขอและการตอบสนองเป็นวัตถุ JSON องค์ประกอบของวัตถุนี้ขึ้นอยู่กับประเภทคำขอหรือกริยา ดูส่วนเฉพาะของ API ด้านล่างสำหรับรายละเอียด

ในกรณีที่เกิดข้อผิดพลาด API ทั้งหมดจะส่งคืนออบเจ็กต์ JSON ในเนื้อหาการตอบสนองโดยมี error เป็นคีย์และข้อความแสดงข้อผิดพลาดเป็นค่า:

{
  "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} เป็นทางเลือก หากละเว้นสถานะสำหรับทุกเวอร์ชันจะถูกส่งกลับในการตอบกลับ

รูปแบบการตอบสนอง

หากสำเร็จ ส่งคืนการแสดง JSON ของโปรโตบัฟ GetModelStatusResponse

API ข้อมูลเมตาของโมเดล

API นี้ติดตาม API ของ PredictionService.GetModelMetadata gRPC อย่างใกล้ชิด ส่งคืนข้อมูลเมตาของโมเดลใน ModelServer

URL

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

การรวม /versions/${VERSION} หรือ /labels/${LABEL} เป็นทางเลือก หากละเว้นข้อมูลเมตาของโมเดลสำหรับเวอร์ชันล่าสุดจะถูกส่งกลับในการตอบกลับ

รูปแบบการตอบสนอง

หากสำเร็จ ส่งคืนการแสดง JSON ของโปรโตบัฟ GetModelMetadataResponse

จัดประเภทและย้อนกลับ 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 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 (ทั้งหมดหรือทศนิยม) สตริง JSON หรือวัตถุ JSON ที่แสดงถึงข้อมูลไบนารี (ดูรายละเอียดในส่วน การเข้ารหัสค่าไบนารี ด้านล่าง) <list> คือรายการของค่าดังกล่าว รูปแบบนี้คล้ายกับโปรโต ClassificationRequest และ RegressionRequest ของ gRPC ทั้งสองเวอร์ชันยอมรับรายการวัตถุ 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> เป็นตัวเลขทศนิยม (ทศนิยม)

คำขอ regress ส่งคืนวัตถุ JSON ในเนื้อหาการตอบสนอง โดยมีรูปแบบดังนี้:

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

<value> เป็นเลขฐานสิบ

ผู้ใช้ gRPC API จะสังเกตเห็นความคล้ายคลึงกันของรูปแบบนี้กับโปรโตคอล ClassificationResponse และ RegressionResponse

คาดการณ์ API

API นี้เป็นไปตาม PredictionService.Predict gRPC API อย่างใกล้ชิด

URL

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

การรวม /versions/${VERSION} หรือ /labels/${LABEL} เป็นทางเลือก หากละเว้นจะใช้เวอร์ชันล่าสุด

ขอแบบ

เนื้อหาคำขอสำหรับ API predict ต้องเป็นวัตถุ 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]] ]
}

Tensors จะแสดงอย่างเป็นธรรมชาติในสัญกรณ์ที่ซ้อนกัน เนื่องจากไม่จำเป็นต้องทำให้รายการแบนลงด้วยตนเอง

สำหรับอินพุตที่มีชื่อหลายรายการ แต่ละรายการคาดว่าจะเป็นวัตถุที่มีคู่ของชื่ออินพุต/ค่าเทนเซอร์ หนึ่งรายการสำหรับแต่ละอินพุตที่มีชื่อ ดังตัวอย่าง ต่อไปนี้เป็นคำขอที่มีสองอินสแตนซ์ แต่ละรายการมีชุดของเทนเซอร์อินพุตที่มีชื่อสามชุด:

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

ค่าสำหรับคีย์ อินพุต อาจเป็นเทนเซอร์อินพุตเดียวหรือแมปชื่ออินพุตกับเทนเซอร์ (แสดงรายการในรูปแบบที่ซ้อนกันโดยธรรมชาติ) แต่ละอินพุตสามารถมีรูปร่างได้ตามอำเภอใจและไม่จำเป็นต้องแชร์/ เดียวกันในมิติที่ 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 สตริง "สวัสดีชาวโลก!" ถ้า 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 (เช่น Intel หรือ AMD) ค่าดังกล่าวจะ ถูกแปลงอย่างเงียบ ๆ โดยฮาร์ดแวร์ที่อยู่ด้านล่างเป็น 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 ) ไม่ รู้จักค่าเหล่านี้ (แม้ว่าข้อมูลจำเพาะ JavaScript จะรับรู้ก็ตาม)

REST API ที่อธิบายในหน้านี้อนุญาตให้อ็อบเจ็กต์ JSON คำขอ/ตอบกลับมีค่าดังกล่าว นี่หมายความว่าคำขอดังต่อไปนี้ถูกต้อง:

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

ตัวแยกวิเคราะห์ JSON ที่สอดคล้องกับมาตรฐาน (เข้มงวด) จะปฏิเสธสิ่งนี้โดยมีข้อผิดพลาดในการแยกวิเคราะห์ (เนื่องจากโทเค็น NaN และ Infinity ผสมกับตัวเลขจริง) หากต้องการจัดการคำขอ/การตอบกลับในโค้ดของคุณอย่างถูกต้อง ให้ใช้ตัวแยกวิเคราะห์ JSON ที่รองรับโทเค็นเหล่านี้

โทเค็น NaN , Infinity , -Infinity เป็นที่รู้จักโดย proto3 โมดูล Python JSON และภาษา JavaScript

ตัวอย่าง

เราสามารถใช้โมเดลของเล่น half_plus_three เพื่อดูการทำงานของ REST API

เริ่ม ModelServer ด้วยจุดสิ้นสุด REST API

ดาวน์โหลดโมเดล half_plus_three จาก ที่เก็บ git :

$ 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 (ไม่จำเป็นเมื่อใช้ 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 ...

ทำการเรียก 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)" }
$