Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

格式化預測要求

如要依據應用程式輸入內容發出要求，或是需要及時進行推論 (即時回應)，您可以選用「線上預測」模式。

本頁面說明如何使用 Online Prediction API，為自訂訓練模型設定線上預測要求的格式，並提供要求和回應範例。設定要求格式後，即可取得線上預測結果。

事前準備

如要驗證模型部署狀態及傳送線上預測要求，請向管理員要求必要權限。

要求 IAM 角色

請與 IAM 專案管理員聯絡，要求在專案命名空間中取得下列角色：

Vertex AI 預測檢視者 (vertex-ai-prediction-viewer)：查看 DeployedModel 和 Endpoint 自訂資源，以及檢查部署狀態。
Vertex AI Prediction 使用者 (vertex-ai-prediction-user)：存取 Online Prediction 服務，將預測要求傳送至模型端點。

如要進一步瞭解這些角色，請參閱「準備 IAM 權限」。

確認模型和端點是否就緒

設定線上預測要求格式前，請先完成下列步驟：

匯出模型構件以進行預測。
將模型資源部署至端點。

這項操作會將運算資源與模型建立關聯，讓模型以低延遲的方式提供線上預測結果。

檢查模型的 DeployedModel 自訂資源狀態，確認已可接受預測要求：

kubectl --kubeconfig PREDICTION_CLUSTER_KUBECONFIG get -f DEPLOYED_MODEL_NAME.yaml -o jsonpath='{.status.primaryCondition}'

更改下列內容：

PREDICTION_CLUSTER_KUBECONFIG：預測叢集中的 kubeconfig 檔案路徑。
DEPLOYED_MODEL_NAME：DeployedModel 定義檔案的名稱。

主要條件必須顯示 DeployedModel 已就緒。

以下輸出內容顯示回應範例：

{"firstObservedTime":"2024-01-19T01:18:30Z","lastUpdateTime":"2024-01-19T01:35:47Z","message":"DeployedModel is ready", "observedGeneration":1, "reason":"Ready", "resourceName":"my-tf-model","type":"DeployedModel"}

檢查 Endpoint 自訂資源的狀態，確認已可接受預測要求：

kubectl --kubeconfig PREDICTION_CLUSTER_KUBECONFIG get -f ENDPOINT_NAME.yaml -o jsonpath='{$.status.conditions[?(@.type == "EndpointReady")]}'

更改下列內容：

PREDICTION_CLUSTER_KUBECONFIG：預測叢集中的 kubeconfig 檔案路徑。
ENDPOINT_NAME：Endpoint 定義檔案的名稱。

EndpointReady 條件的 status 欄位必須顯示 True 值。

以下輸出內容顯示回應範例：

{"lastTransitionTime":"2024-01-19T05:12:26Z","message":"Endpoint Ready", "observedGeneration":1,"reason":"ResourceReady","status":"True","type":"EndpointReady"}%

設定線上預測的輸入內容格式

線上預測功能提供下列兩種傳送要求的方法：

預測要求：傳送要求至 predict 方法，取得線上預測結果。
原始預測要求：向 rawPredict 方法傳送要求，即可使用任意 HTTP 酬載，不必遵循 JSON 格式。

如果您需要低延遲，請取得原始預測，因為 rawPredict 會略過序列化步驟，直接將要求轉送至預測容器。

本節說明如何使用 JSON 設定預測輸入執行個體的格式和編碼，如果您使用 predict 方法，就必須執行這項操作。如果您使用 rawPredict 方法，則不需要這項資訊。

如果您使用 Vertex AI SDK for Python 傳送預測要求，請指定不含 instances 欄位的執行個體清單。例如，指定 [ ["the","quick","brown"], ... ]，而非 { "instances": [ ["the","quick","brown"], ... ] }。

將執行個體格式化為 JSON 字串

線上預測的基本格式是資料執行個體清單。這些值可以是純值清單，也可以是 JSON 物件的成員，具體取決於您在訓練應用程式中設定輸入的方式。TensorFlow 模型可接受更複雜的輸入內容。

以下範例顯示 TensorFlow 模型的輸入張量和執行個體索引鍵：

 {"values": [1, 2, 3, 4], "key": 1}

只要 JSON 字串的格式符合下列規則，其構成內容就可以較為複雜：

執行個體資料的頂層必須是 JSON 物件，也就是鍵/值組合的字典。
樣本物件的個別值可以是字串、數字或清單。您無法嵌入 JSON 物件。
清單只能包含相同類型的項目 (包括其他清單)。請勿混用字串和數值。

您會將線上預測的輸入執行個體，做為 predict 呼叫的訊息內文傳遞。進一步瞭解要求主體的格式規定。

將每個例項設為 JSON 陣列中的項目，並將陣列做為 JSON 物件的 instances 欄位提供，如下例所示：

{"instances": [
  {"values": [1, 2, 3, 4], "key": 1},
  {"values": [5, 6, 7, 8], "key": 2}
]}

為預測輸入內容編碼二進位資料

您無法將二進位資料格式化為 JSON 支援的 UTF-8 編碼字串。如果輸入內容含有二進位資料，請使用 Base64 編碼表示。您需要使用下列特殊格式：

將編碼字串格式化為 JSON 物件，並使用名為 b64 的單一鍵。在 Python 3 中，base64 編碼會輸出位元組序列。將這個序列轉換為字串，使其可序列化為 JSON：
```
{'image_bytes': {'b64': base64.b64encode(jpeg_data).decode()}}
```
在 TensorFlow 模型程式碼中，為二進位輸入和輸出張量的別名命名，結尾為 _bytes。

要求和回應範例

本節說明線上預測要求和回應主體的格式，並提供 TensorFlow 和 PyTorch 的範例。

要求主體詳細資料

TensorFlow

要求主體包含結構如下的資料 (JSON 表示法)：

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

instances[] 物件為必要項目，且必須包含要取得預測結果的執行個體清單。

執行個體清單中每個元素的結構，取決於模型的輸入定義。執行個體可以包含具名輸入內容 (做為物件)，也可以只包含未加上標籤的值。

只有部分資料會包含已命名的輸入。部分例項是 JSON 值 (布林值、數字或字串)。不過，例項通常是值清單或複雜的巢狀清單。

以下是幾個要求主體範例：

CSV 資料，每列編碼為字串值：

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

純文字：

{"instances": ["the quick brown fox", "the lazy dog"]}

編碼為字詞清單 (字串向量) 的句子：

{
  "instances": [
    ["the","quick","brown"],
    ["the","lazy","dog"],
    ...
  ]
}

浮點純量值：

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

以下範例顯示兩個 JPEG 圖片位元組字串，需要 base64 編碼 (假資料，僅供說明)：

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

PyTorch

如果模型使用 PyTorch 預建容器，TorchServe 的預設處理常式會預期每個執行個體都包裝在 data 欄位中。例如：

{
  "instances": [
    { "data": , <value> },
    { "data": , <value> }
  ]
}

回應主體詳細資料

如果呼叫成功，回應主體會包含要求主體中每個執行個體的一筆預測項目，並依相同順序提供：

{
  "predictions": [
    {
      object
    }
  ],
  "deployedModelId": string
}

如果任何執行個體的預測失敗，回應主體就不會包含任何預測。而是包含一個錯誤項目：

{
  "error": string
}

predictions[] 物件包含預測結果清單，要求中的每個執行個體各有一個。

發生錯誤時，error 字串會包含描述問題的訊息。如果處理任何執行個體時發生錯誤，系統會傳回錯誤，而非預測清單。

雖然每個執行個體都有一個預測，但預測的格式與執行個體的格式沒有直接關聯。預測結果會採用模型定義的輸出內容集合中指定的格式。預測結果集合會以 JSON 清單形式傳回。清單中的每個成員都可以是值、清單或任何複雜度的 JSON 物件。如果模型有多個輸出張量，則每項預測都是 JSON 物件，其中包含每個輸出的鍵/值組合。鍵會識別圖表中的輸出別名。

回應主體範例

以下範例顯示 TensorFlow 可能的回應：

三個輸入例項的一組預測，其中每個預測都是整數值：

{"predictions":
  [5, 4, 3],
  "deployedModelId": 123456789012345678
}

一組更複雜的預測，每個預測包含兩個具名值，分別對應至名為 label 和 scores 的輸出張量。label 的值是預測類別 (car 或 beach)，而 scores 則包含該執行個體在可能類別中的機率清單：

{
  "predictions": [
    {
      "label": "beach",
      "scores": [0.1, 0.9]
    },
    {
      "label": "car",
      "scores": [0.75, 0.25]
    }
  ],
  "deployedModelId": 123456789012345678
}

如果處理輸入樣本時發生錯誤，則回應如下：
```
{"error": "Divide by zero"}
```