預測要求細節

predict 方法會根據要求中的資料執行預測。

本頁將說明預測要求主體和回應主體的格式,以及 HTTP 要求的網址格式。如需傳送預測要求的程式碼範例,請參閱使用 TensorFlow 要求線上預測的相關指南,以及透過 scikit-learn 和 XGBoost 取得線上預測的教學課程。

要求主體

TensorFlow

要求主體包含採用下列結構的資料 (JSON 表示法):

{
  "instances": [
    <value>|<simple/nested list&gt|<object>,
    ...
  ]
}

instances[] 是必要物件,而且必須包含要取得預測的樣本清單。

樣本清單內每項元素的結構取決於您的模型輸入定義。樣本可以包含已命名的輸入 (做為物件),也可以僅包含未加標籤的值。

只有部分資料會包含已命名的輸入。某些樣本屬於簡易的 JSON 值 (布林值、數值或字串),但樣本通常是包含簡單值或複雜巢狀結構的清單。

以下是幾個要求主體的範例。

將每一資料列都編碼為字串值的 CSV 資料:

{"instances": ["1.0,true,\\"x\\"", "-2.0,false,\\"y\\""]}

純文字:

{"instances": ["the quick brown fox", "la bruja le dio"]}

編碼為字詞清單的語句 (字串向量):

{
  "instances": [
    ["the","quick","brown"],
    ["la","bruja","le"],
    ...
  ]
}

浮點純量值:

{"instances": [0.0, 1.1, 2.2]}

整數向量:

{
  "instances": [
    [0, 1, 2],
    [3, 4, 5],
    ...
  ]
}

張量 (下列範例是二維張量):

{
  "instances": [
    [
      [0, 1, 2],
      [3, 4, 5]
    ],
    ...
  ]
}

可透過不同方式來表示的圖片。在此編碼配置中,前兩個維度代表圖片的列和欄,第三個維度則包含每個像素的 R、G、B 值的清單 (向量):

{
  "instances": [
    [
      [
        [138, 30, 66],
        [130, 20, 56],
        ...
      ],
      [
        [126, 38, 61],
        [122, 24, 57],
        ...
      ],
      ...
    ],
    ...
  ]
}

資料編碼

JSON 字串的編碼必須為 UTF-8。如要傳送二進位資料,您必須使用 base64 編碼並將資料標示為二進位。如要將 JSON 字串標示為二進位,請將字串替換為具備 b64 單一屬性的 JSON 物件:

{"b64": "..."} 

下列範例顯示了兩個序列化 tf.Examples 樣本,這些樣本必須採用 base64 編碼 (此為假資料,僅用於說明):

{"instances": [{"b64": "X5ad6u"}, {"b64": "IA9j4nx"}]}

下列範例顯示須採用 base64 編碼兩個 JPEG 圖片位元組字串 (此為僅供說明之用的偽資料):

{"instances": [{"b64": "ASa8asdf"}, {"b64": "JLK7ljk3"}]}

多個輸入張量

部分模型具有可接受多個輸入張量的基礎 TensorFlow 圖形。此案例採用 JSON 名稱/值組合中的名稱來識別輸入張量,

輸入張量別名為「tag」(字串) 和「image」(base64 編碼字串) 的圖表:

{
  "instances": [
    {
      "tag": "beach",
      "image": {"b64": "ASa8asdf"}
    },
    {
      "tag": "car",
      "image": {"b64": "JLK7ljk3"}
    }
  ]
}

輸入張量別名為「tag」(字串) 和「image」(8 位元整數的 3 維陣列) 的圖表:

{
  "instances": [
    {
      "tag": "beach",
      "image": [
        [
          [138, 30, 66],
          [130, 20, 56],
          ...
        ],
        [
          [126, 38, 61],
          [122, 24, 57],
          ...
        ],
        ...
      ]
    },
    {
      "tag": "car",
      "image": [
        [
          [255, 0, 102],
          [255, 0, 97],
          ...
        ],
        [
          [254, 1, 101],
          [254, 2, 93],
          ...
        ],
        ...
      ]
    },
    ...
  ]
}

scikit-learn

要求主體包含採用下列結構的資料 (JSON 表示法):

{
  "instances": [
    <simple list>,
    ...
  ]
}

instances[] 是必要物件,而且必須包含要取得預測的樣本清單。在下列範例中,每個輸入樣本都是浮點清單:

{
  "instances": [
    [0.0, 1.1, 2.2],
    [3.3, 4.4, 5.5],
    ...
  ]
}

輸入樣本的維度必須與模型預期的維度相符。比方說,如果模型須具備三個特徵,則每個輸入樣本的長度必須為 3。

XGBoost

要求主體包含採用下列結構的資料 (JSON 表示法):

{
  "instances": [
    <simple list>,
    ...
  ]
}

instances[] 是必要物件,而且必須包含要取得預測的樣本清單。在下列範例中,每個輸入樣本都是浮點清單:

{
  "instances": [
    [0.0, 1.1, 2.2],
    [3.3, 4.4, 5.5],
    ...
  ]
}

輸入樣本的維度必須與模型預期的維度相符。比方說,如果模型須具備三個特徵,則每個輸入樣本的長度必須為 3。

針對 XGBoost 輸入樣本,AI Platform 不支援稀疏表示法。

線上預測服務對零和 NaN 有不同的解釋。如果某個特徵的值為零,請在對應的輸入中使用 0.0。如果特徵的值遺失,請在對應的輸入中使用 NaN

下列範例表示具有單一輸入樣本的預測要求,其中第一個特徵的值是 0.0,第二個特徵值的是 1.1,沒有第三個特徵的值:

{"instances": [[0.0, 1.1, NaN]]}

自訂預測處理常式

要求主體包含採用下列結構的資料 (JSON 表示法):

{
  "instances": [
    <value>|<simple/nested list&gt|<object>,
    ...
  ],
  "<other-key>": <value>|<simple/nested list&gt|<object>,
  ...
}

instances[] 是必要物件,而且必須包含要取得預測的樣本清單。

您可選擇性地提供其他任何有效的 JSON 鍵/值組合。AI Platform 會剖析 JSON,並向預測者類別predict 方法提供這些欄位,以做為 **kwargs 目錄中的項目。

如何結構化樣本清單

樣本清單內每項元素的結構,取決於預測者類別predict 方法。樣本可以包含已命名的輸入 (作為物件),也可以僅包含未加標籤的值。

只有部分資料會包含已命名的輸入。某些樣本屬於簡易的 JSON 值 (布林值、數值或字串),但樣本通常是包含簡單值或複雜巢狀結構的清單。

以下是幾個要求主體的範例。

將每一資料列都編碼為字串值的 CSV 資料:

{"instances": ["1.0,true,\\"x\\"", "-2.0,false,\\"y\\""]}

純文字:

{"instances": ["the quick brown fox", "la bruja le dio"]}

編碼為字詞清單的語句 (字串向量):

{
  "instances": [
    ["the","quick","brown"],
    ["la","bruja","le"],
    ...
  ]
}

浮點純量值:

{"instances": [0.0, 1.1, 2.2]}

整數向量:

{
  "instances": [
    [0, 1, 2],
    [3, 4, 5],
    ...
  ]
}

張量 (下列範例是二維張量):

{
  "instances": [
    [
      [0, 1, 2],
      [3, 4, 5]
    ],
    ...
  ]
}

可透過不同方式來表示的圖片。在此編碼配置中,前兩個維度代表圖片的列和欄,第三個維度則包含每個像素的 R、G、B 值清單 (向量):

{
  "instances": [
    [
      [
        [138, 30, 66],
        [130, 20, 56],
        ...
      ],
      [
        [126, 38, 61],
        [122, 24, 57],
        ...
      ],
      ...
    ],
    ...
  ]
}

多個輸入張量

部分模型具有可接受多個輸入張量的基礎 TensorFlow 圖形。此案例採用 JSON 名稱/值組合中的名稱來識別輸入張量。

輸入張量別名為「tag」(字串) 和「image」(8 位元整數的 3 維陣列) 的圖表:

{
  "instances": [
    {
      "tag": "beach",
      "image": [
        [
          [138, 30, 66],
          [130, 20, 56],
          ...
        ],
        [
          [126, 38, 61],
          [122, 24, 57],
          ...
        ],
        ...
      ]
    },
    {
      "tag": "car",
      "image": [
        [
          [255, 0, 102],
          [255, 0, 97],
          ...
        ],
        [
          [254, 1, 101],
          [254, 2, 93],
          ...
        ],
        ...
      ]
    },
    ...
  ]
}

回應主體

回應和要求非常相似。

如果呼叫成功,要求主體中的每個樣本都會在回應主體中產生一個預測項目,提供順序如下所示:

{
  "predictions": [
    {
      object
    }
  ]
}

如果任何樣本的預測失敗,回應主體將不會包含任何預測內容,而是包含一個錯誤項目:

{
  "error": string
}

predictions[] 物件包含預測清單,其中一個預測適用於要求中的每個樣本。針對自訂預測處理常式 (Beta 版),predictions 會包含預測者類別predict 方法傳回值,並序列化為 JSON。

如果發生錯誤,error 字串將包含一個描述問題的訊息。如果處理任何樣本時發生錯誤,服務會傳回錯誤,而不是傳回預測清單。

雖然每個樣本都會有一個預測,但是預測的格式與樣本的格式沒有直接的關聯。預測的格式是由模型中定義的輸出集合所指定。預測集合會以 JSON 清單的形式傳回。清單的每個成員可為簡單值、清單或任意複雜度的 JSON 物件。如果模型擁有的輸入張量不只一個,每個預測就會是包含每個輸出名稱/值組合的 JSON 物件。這些名稱可識別圖表中的輸出別名。

回應主體範例

TensorFlow

下列範例顯示幾種可能的回應:

  • 針對三個輸入樣本產生一組簡單預測,其中每個預測都是整數值:

    {"predictions": [5, 4, 3]}
    
  • 一組較為複雜的預測,每個預測都包含兩個已命名的值。這些值對應到名為 labelscores 的輸出張量。label 的值為預測類別 (「car」或「beach」),而 scores 則包含該樣本在各可能類別的機率清單。

    {
      "predictions": [
        {
          "label": "beach",
          "scores": [0.1, 0.9]
        },
        {
          "label": "car",
          "scores": [0.75, 0.25]
        }
      ]
    }
    
  • 如果處理輸入樣本時發生錯誤,則回應如下:

    {"error": "Divide by zero"}
    

scikit-learn

下列範例顯示幾種可能的回應:

  • 針對三個輸入樣本產生一組簡單預測,其中每個預測都是整數值:

    {"predictions": [5, 4, 3]}
    
  • 如果處理輸入樣本時發生錯誤,則回應如下:

    {"error": "Divide by zero"}
    

XGBoost

下列範例顯示幾種可能的回應:

  • 針對三個輸入樣本產生一組簡單預測,其中每個預測都是整數值:

    {"predictions": [5, 4, 3]}
    
  • 如果處理輸入樣本時發生錯誤,則回應如下:

    {"error": "Divide by zero"}
    

自訂預測處理常式

下列範例顯示幾種可能的回應:

  • 針對三個輸入樣本產生一組簡單預測,其中每個預測都是整數值:

    {"predictions": [5, 4, 3]}
    
  • 一組較為複雜的預測,每個預測都包含兩個已命名的值。這些值對應到名為 labelscores 的輸出張量。label 的值為預測類別 (「car」或「beach」),而 scores 則包含該樣本在各可能類別的機率清單。

    {
      "predictions": [
        {
          "label": "beach",
          "scores": [0.1, 0.9]
        },
        {
          "label": "car",
          "scores": [0.75, 0.25]
        }
      ]
    }
    
  • 如果處理輸入樣本時發生錯誤,則回應如下:

    {"error": "Divide by zero"}
    

HTTP 網址格式

如需傳送預測要求的程式碼範例,請參閱使用 TensorFlow 要求線上預測的相關指南,以及透過 scikit-learn 和 XGBoost 取得線上預測的教學課程。本頁面接下來的部分詳細說明 AI Platform 實作的 HTTP 網址格式。

AI Platform 會在 HTTP POST 方法上實作自訂的 predict 動詞。此網址使用 Google API HTTP 註解語法:

POST https://ml.googleapis.com/v1/{name=projects/**}:predict

name 為必要參數,其中必須包含模型名稱,也可以選擇是否包含版本。如果您指定的模型不包含版本,則會使用該模型的預設版本。

下列是同時指定模型和版本的範例:

POST https://ml.googleapis.com/v1/projects/my-project/models/my-model/versions/my-version:predict

下列是僅指定模型的範例,在此使用該模型的預設版本:

POST https://ml.googleapis.com/v1/projects/my-project/models/my-model:predict

路徑結尾的 :predict 片段表示 AI Platform 使用在 Google API HTTP 說明文件中定義的「自訂動詞」。在此案例中,自訂動詞為 predict

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
AI Platform