本頁說明如何使用 Google Cloud 控制台或 Agent Platform API，從自訂訓練模型取得批次推論。
如要提出批次推論要求，請指定輸入來源和輸出位置 (Cloud Storage 或 BigQuery)，Gemini Enterprise Agent Platform 會將批次推論結果儲存在這些位置。
限制與需求
取得批次推論結果時，請考量下列限制和需求：
- 為盡量縮短處理時間，輸入和輸出位置必須位於相同區域或多區域。舉例來說，如果輸入內容位於
us-central1，輸出內容可以位於us-central1或US，但不能位於europe-west4。如要瞭解詳情，請參閱 Cloud Storage 位置和 BigQuery 位置。 - 輸入和輸出內容也必須與模型位於相同區域或多區域。
- 與線上推論不同，批次推論工作不會自動調度資源。由於系統會預先得知所有輸入資料，因此工作開始時，系統會將資料分割到每個副本。系統會使用
starting_replica_count參數。系統會忽略max_replica_count參數。 - BigQuery ML 模型並非自訂訓練模型。不過，在下列情況下，您可以使用本頁面的資訊，從 BigQuery ML 模型取得批次推論結果：
- BigQuery ML 模型必須註冊至 Gemini Enterprise Agent Platform Model Registry。
- 如要使用 BigQuery 資料表做為輸入內容，請使用 Agent Platform API 將
InstanceConfig.instanceType設為"object"。
- 載入批次推論模型約 40 分鐘後會逾時。
如果看到下列錯誤訊息，請使用較小的模型進行批次推論：
Error: model server never became ready. Please validate that your model file or container configuration are valid. - 自訂服務帳戶僅支援模型伺服器，不支援對 Cloud Storage 和 BigQuery 執行資料讀取和寫入作業的批次推論用戶端。
輸入資料規定
提交批次要求時，應在輸入內容中指定要送交模型推論的項目。我們支援下列輸入格式：
JSON Lines
使用 JSON Lines 檔案指定輸入執行個體清單，以進行推論。將檔案儲存在 Cloud Storage 值區中。
範例 1
下列範例顯示 JSON Lines 檔案，其中每行都包含一個陣列：
[1, 2, 3, 4]
[5, 6, 7, 8]
以下是 HTTP 要求主體中傳送至容器的內容：
所有其他容器
{"instances": [ [1, 2, 3, 4], [5, 6, 7, 8] ]}PyTorch 容器
{"instances": [
{ "data": [1, 2, 3, 4] },
{ "data": [5, 6, 7, 8] } ]}示例 2
下列範例顯示 JSON Lines 檔案，每行包含一個物件。
{ "values": [1, 2, 3, 4], "key": 1 }
{ "values": [5, 6, 7, 8], "key": 2 }
以下是 HTTP 要求主體中傳送至容器的內容。 請注意，系統會將相同要求主體傳送至所有容器。
{"instances": [
{ "values": [1, 2, 3, 4], "key": 1 },
{ "values": [5, 6, 7, 8], "key": 2 }
]}
範例 3
如果是 PyTorch 預先建構的容器，請務必按照 TorchServe 預設處理常式的要求，將每個執行個體包裝在 data 欄位中；Gemini Enterprise Agent Platform 不會為您包裝執行個體。例如：
{ "data": { "values": [1, 2, 3, 4], "key": 1 } }
{ "data": { "values": [5, 6, 7, 8], "key": 2 } }
以下是 HTTP 要求主體中傳送至推論容器的內容：
{"instances": [
{ "data": { "values": [1, 2, 3, 4], "key": 1 } },
{ "data": { "values": [5, 6, 7, 8], "key": 2 } }
]}
TFRecord
以 TFRecord 格式儲存輸入執行個體。您可以選擇使用 Gzip 壓縮 TFRecord 檔案。將 TFRecord 檔案儲存在 Cloud Storage 值區中。
Agent Platform 會將 TFRecord 檔案中的每個例項讀取為二進位檔，然後以 base64 編碼例項，做為具有 b64 單一索引鍵的 JSON 物件。
以下是 HTTP 要求主體中傳送至容器的內容：
所有其他容器
{"instances": [
{ "b64": "b64EncodedASCIIString" },
{ "b64": "b64EncodedASCIIString" } ]}PyTorch 容器
{"instances": [ { "data": {"b64": "b64EncodedASCIIString" } }, { "data": {"b64": "b64EncodedASCIIString" } }
]}請確認容器知道如何解碼執行個體。
CSV
在 CSV 檔案中，每列指定一個輸入例項。第一列必須是標題列。所有字串都必須括在雙引號 (") 中。Agent Platform 不接受含有換行的儲存格值。系統會將未加引號的值讀取為浮點數。
以下範例顯示含有兩個輸入例項的 CSV 檔案：
"input1","input2","input3"
0.1,1.2,"cat1"
4.0,5.0,"cat2"
以下是 HTTP 要求主體中傳送至容器的內容：
所有其他容器
{"instances": [ [0.1,1.2,"cat1"], [4.0,5.0,"cat2"] ]}PyTorch 容器
{"instances": [
{ "data": [0.1,1.2,"cat1"] },
{ "data": [4.0,5.0,"cat2"] } ]}檔案清單
建立文字檔，其中每列都是檔案的 Cloud Storage URI。Agent Platform 會以二進位形式讀取每個檔案的內容，然後以 base64 編碼將例項編碼為 JSON 物件，並使用名為 b64 的單一鍵。
如要使用 Google Cloud 控制台取得批次推論結果，請直接將檔案清單貼到 Google Cloud 控制台。否則，請將清單儲存在 Cloud Storage bucket 中。
以下範例顯示含有兩個輸入樣本的檔案清單：
gs://path/to/image/image1.jpg
gs://path/to/image/image2.jpg
以下是 HTTP 要求主體中傳送至容器的內容：
所有其他容器
{ "instances": [
{ "b64": "b64EncodedASCIIString" },
{ "b64": "b64EncodedASCIIString" } ]}PyTorch 容器
{ "instances": [ { "data": { "b64": "b64EncodedASCIIString" } }, { "data": { "b64": "b64EncodedASCIIString" } }
]}請確認容器知道如何解碼執行個體。
BigQuery
將 BigQuery 資料表指定為 projectId.datasetId.tableId。Agent Platform 會將資料表中的每一列轉換為 JSON 執行個體。
舉例來說，如果資料表包含下列項目：
| 第 1 欄 | 第 2 欄 | 第 3 欄 |
|---|---|---|
| 1.0 | 3.0 | 「Cat1」 |
| 2.0 | 4.0 | 「Cat2」 |
以下是 HTTP 要求主體中傳送至容器的內容：
所有其他容器
{"instances": [ [1.0,3.0,"cat1"], [2.0,4.0,"cat2"] ]}PyTorch 容器
{"instances": [
{ "data": [1.0,3.0,"cat1"] },
{ "data": [2.0,4.0,"cat2"] } ]}BigQuery 資料類型轉換為 JSON 的方式如下：
| BigQuery 類型 | JSON 類型 | 範例值 |
|---|---|---|
| 字串 | 字串 | "abc" |
| 整數 | 整數 | 1 |
| 浮點值 | 浮點值 | 1.2 |
| 數字 | 浮點值 | 4925.000000000 |
| 布林值 | 布林值 | true |
| TimeStamp | 字串 | "2019-01-01 23:59:59.999999+00:00" |
| 日期 | 字串 | "2018-12-31" |
| 時間 | 字串 | "23:59:59.999999" |
| DateTime | 字串 | "2019-01-01T00:00:00" |
| 錄製 | 物件 | { "A": 1,"B": 2} |
| 重複類型 | Array[Type] | [1, 2] |
| 巢狀記錄 | 物件 | {"A": {"a": 0}, "B": 1} |
分割資料
批次推論會使用 MapReduce，將輸入內容分片至每個副本。如要使用 MapReduce 功能，輸入內容應可分割。
Gemini Enterprise Agent Platform 會自動分割 BigQuery、檔案清單和 JSON 行輸入內容。
Gemini Enterprise Agent Platform 不會自動分割 CSV 檔案，因為這類檔案不適合分割。CSV 檔案中的資料列並非自我描述、已輸入，且可能含有換行符。建議不要將 CSV 輸入內容用於需要高輸送量的應用程式。
如果是 TFRecord 輸入，請務必手動分割資料，將例項分割為較小的檔案，並使用萬用字元 (例如 gs://my-bucket/*.tfrecord) 將檔案傳遞至工作。檔案數量應至少為指定的副本數量。
篩選及轉換輸入資料
您可以在 BatchPredictionJob 要求中指定 instanceConfig，藉此篩選及轉換批次輸入內容。
篩選功能可讓您從推論要求中排除輸入資料中的特定欄位，或只在推論要求中納入輸入資料的欄位子集，而不必在推論容器中進行任何自訂前處理或後處理。如果輸入資料檔案含有模型不需要的額外資料欄 (例如鍵或額外資料)，這項功能就非常實用。
轉換：您可以將執行個體傳送至容器，格式為 JSON array 或 object。詳情請參閱instanceType。
舉例來說，如果輸入資料表包含下列項目：
| customerId | col1 | col2 |
|---|---|---|
| 1001 | 1 | 2 |
| 1002 | 5 | 6 |
並指定下列 instanceConfig：
{
"name": "batchJob1",
...
"instanceConfig": {
"excludedFields":["customerId"]
"instanceType":"object"
}
}
接著，推論要求中的執行個體會以 JSON 物件的形式傳送，並排除 customerId 欄：
{"col1":1,"col2":2}
{"col1":5,"col2":6}
請注意，指定下列 instanceConfig 會產生相同結果：
{
"name": "batchJob1",
...
"instanceConfig": {
"includedFields": ["col1","col2"]
"instanceType":"object"
}
}
如要瞭解如何使用特徵篩選器，請參閱使用特徵篩選器進行自訂模型批次推論筆記本。
要求批次推論
如要發出批次推論要求，可以使用 Google Cloud 控制台或 Agent Platform API。視您提交的輸入項目數量而定，批次推論工作可能需要一些時間才能完成。
要求批次推論時，推論容器會以使用者提供的自訂服務帳戶執行。讀取推論例項 (來自資料來源) 或寫入推論結果等讀寫作業，都是使用 Gemini Enterprise Agent Platform 服務代理程式完成，該代理程式預設可存取 BigQuery 和 Cloud Storage。
Google Cloud 控制台
使用 Google Cloud 控制台要求批次推論。
- 在 Google Cloud 控制台的「Agent Platform」部分，前往「Batch predictions」頁面。
按一下「建立」，開啟「新批次預測」視窗。
如要「定義批次預測工作」，請完成下列步驟：
輸入批次推論的名稱。
在「模型名稱」中，選取要用於這項批次推論的模型名稱。
在「選取來源」部分，選取適用於輸入資料的來源：
- 如果輸入內容的格式為 JSON Lines、CSV 或 TFRecord，請選取「File on Cloud Storage (JSON Lines, CSV, TFRecord, TFRecord Gzip)」，然後在「Source path」欄位中指定輸入檔案。
- 如果使用檔案清單做為輸入內容，請選取「Cloud Storage 中的檔案 (其他)」，然後將檔案清單貼到下列欄位。
- 如要使用 BigQuery 輸入，請選取「BigQuery 路徑」。如果選取 BigQuery 做為輸入，也必須選取 BigQuery 做為輸出和 Google-managed encryption key。使用 BigQuery 做為輸入/輸出時，系統不支援客戶管理的加密金鑰 (CMEK)。
在「Destination path」(目的地路徑) 欄位中，指定要讓 Agent Platform 儲存批次推論輸出內容的 Cloud Storage 目錄。
您可以視需要勾選「為這個模型啟用特徵歸因功能」，在批次推論回應中取得特徵歸因。然後按一下「編輯」，設定說明設定。(如果您先前已為模型設定說明設定，則可選擇是否編輯說明設定，否則必須編輯。)
選用： 模型監控 批次推論分析功能目前為預先發布版。如要將偏差偵測設定新增至批次推論工作，請參閱必要條件。
點選以開啟「為這個批次預測啟用模型監控功能」。
選取「訓練資料來源」，然後輸入所選訓練資料來源的資料路徑或位置。
選用：在「警告門檻」下方，指定觸發警告的門檻。
如要設定通知電子郵件，請輸入一或多個以半形逗號分隔的電子郵件地址，以便在模型超過快訊門檻時收到通知。
選用：如要新增「通知管道」，請新增 Cloud Monitoring 管道，以便在模型超出警告門檻時接收快訊。您可以選取現有的 Cloud Monitoring 管道，也可以按一下「管理通知管道」建立新管道。 Google Cloud 控制台支援 PagerDuty、Slack 和 Pub/Sub 通知管道。
點選「建立」。
API
使用 Agent Platform API 傳送批次推論要求。請根據您用來取得批次推論結果的工具，選取對應的分頁標籤。
REST
使用任何要求資料之前，請先修改下列項目的值：
LOCATION_ID：儲存模型及執行批次預測工作的區域。例如：
us-central1。PROJECT_ID： 您的 [專案 ID](/resource-manager/docs/creating-managing-projects#identifiers)。 。
BATCH_JOB_NAME：批次預測工作的顯示名稱。
MODEL_ID：用於進行預測的模型 ID。
INPUT_FORMAT：輸入資料的格式：
jsonl、csv、tf-record、tf-record-gzip或file-list。INPUT_URI：輸入資料的 Cloud Storage URI。可能含有萬用字元。
OUTPUT_DIRECTORY：您希望 Agent Platform 儲存輸出內容的目錄 Cloud Storage URI。
MACHINE_TYPE：用於這項批次預測作業的機器資源。
您可以選擇設定
machineSpec欄位，使用加速器，但以下範例未說明這項操作。BATCH_SIZE：每次預測要求中要傳送的執行個體數量；預設為 64。增加批量可提高處理量，但也可能導致要求逾時。
STARTING_REPLICA_COUNT：這個批次預測工作的節點數量。
HTTP 方法和網址：
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/batchPredictionJobs
JSON 要求內文：
{
"displayName": "BATCH_JOB_NAME",
"model": "projects/PROJECT_ID/locations/LOCATION_ID/models/MODEL_ID",
"inputConfig": {
"instancesFormat": "INPUT_FORMAT",
"gcsSource": {
"uris": ["INPUT_URI"],
},
},
"outputConfig": {
"predictionsFormat": "jsonl",
"gcsDestination": {
"outputUriPrefix": "OUTPUT_DIRECTORY",
},
},
"dedicatedResources" : {
"machineSpec" : {
"machineType": MACHINE_TYPE
},
"startingReplicaCount": STARTING_REPLICA_COUNT
},
"manualBatchTuningParameters": {
"batch_size": BATCH_SIZE,
}
}
如要傳送要求，請選擇以下其中一個選項：
curl
將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/batchPredictionJobs"
PowerShell
將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/batchPredictionJobs" | Select-Object -Expand Content
您應該會收到如下的 JSON 回覆：
{
"name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/batchPredictionJobs/BATCH_JOB_ID",
"displayName": "BATCH_JOB_NAME 202005291958",
"model": "projects/PROJECT_ID/locations/LOCATION_ID/models/MODEL_ID",
"inputConfig": {
"instancesFormat": "jsonl",
"gcsSource": {
"uris": [
"INPUT_URI"
]
}
},
"outputConfig": {
"predictionsFormat": "jsonl",
"gcsDestination": {
"outputUriPrefix": "OUTPUT_DIRECTORY"
}
},
"state": "JOB_STATE_PENDING",
"createTime": "2020-05-30T02:58:44.341643Z",
"updateTime": "2020-05-30T02:58:44.341643Z",
}
Java
在試用這個範例之前，請先按照「使用用戶端程式庫的 Agent Platform 快速入門導覽課程」中的 Java 設定說明操作。
如要向 Agent Platform 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證機制」。
在下列範例中，請將 PREDICTIONS_FORMAT 替換為 jsonl。如要瞭解如何替換其他預留位置，請參閱本節的「REST & CMD LINE」
分頁。
Python
如要瞭解如何安裝或更新 Vertex AI SDK for Python，請參閱「安裝 Vertex AI SDK for Python」。 詳情請參閱 Python API 參考文件。
BigQuery
上述 REST 範例使用 Cloud Storage 做為來源和目的地。如要改用 BigQuery，請進行下列變更：
將
inputConfig欄位變更為下列內容："inputConfig": { "instancesFormat": "bigquery", "bigquerySource": { "inputUri": "bq://SOURCE_PROJECT_ID.SOURCE_DATASET_NAME.SOURCE_TABLE_NAME" } }將
outputConfig欄位變更為下列內容："outputConfig": { "predictionsFormat":"bigquery", "bigqueryDestination":{ "outputUri": "bq://DESTINATION_PROJECT_ID.DESTINATION_DATASET_NAME.DESTINATION_TABLE_NAME" } }更改下列內容：
SOURCE_PROJECT_ID：來源 Google Cloud 專案的 IDSOURCE_DATASET_NAME：來源 BigQuery 資料集名稱SOURCE_TABLE_NAME：BigQuery 來源資料表的名稱DESTINATION_PROJECT_ID：目的地 Google Cloud 專案的 IDDESTINATION_DATASET_NAME：目的地 BigQuery 資料集名稱DESTINATION_TABLE_NAME：BigQuery 目的地資料表名稱
特徵重要性
如要讓推論結果傳回特徵重要性值，請將 generateExplanation 屬性設為 true。請注意，預測模型不支援特徵重要性，因此您無法將其納入批次推論要求。
特徵重要性 (有時稱為「特徵歸因」) 是 Vertex Explainable AI 的一部分。
只有在為說明設定 Model，或指定 BatchPredictionJob 的 explanationSpec 欄位時，才能將 generateExplanation 設為 true。
選擇機型和副本數量
相較於使用較大的機器類型，增加副本數量進行水平擴充，可更線性且可預測地提升總處理量。
一般來說，我們建議您為工作指定最小的機器類型，並增加副本數量。
為提高成本效益，建議您選擇的副本數量應能讓批次推論作業至少執行 10 分鐘。這是因為系統會以每小時的副本節點時數為單位計費，包括每個副本啟動時約需 5 分鐘。如果只處理幾秒鐘就關閉，成本效益不高。
一般而言，如果執行個體數量達到數千個，建議您將 starting_replica_count 設為數十。如果是數百萬個執行個體，建議您將 starting_replica_count 設為數百。您也可以使用下列公式估算副本數量：
N / (T * (60 / Tb))
其中：
- N：工作中的批次數量。舉例來說，100 萬個樣本/100 個批量大小 = 10,000 個批次。
- T：批次推論工作的預計時間，例如 10 分鐘。
- Tb：副本處理單一批次所需的時間 (以秒為單位)。舉例來說，在 2 核心機型上，每個批次需要 1 秒。
在本範例中，10,000 個批次 / (10 分鐘 * (60 / 1 秒)) 四捨五入後為 17 個副本。
這些建議僅為概略指引，不一定能為每個模型提供最佳輸送量，也無法準確估算處理時間和費用，更不一定能為每個情境找出最佳的費用與輸送量取捨方案。建議您將這些建議做為合理的起點，並視需要進行調整。如要評估模型的輸送量等特性，請執行「尋找理想的機器類型」筆記本。
適用於 GPU 或 TPU 加速機器
請遵循上述指南 (也適用於僅使用 CPU 的模型)，並考量下列事項：
- 您可能需要更多 CPU 和 GPU (例如用於資料預先處理)。
- GPU 機型啟動時間較長 (10 分鐘)，因此您可能需要將批次推論工作的目標時間設得更長 (例如至少 20 分鐘，而非 10 分鐘)，確保有合理比例的時間和成本用於產生推論結果。
擷取批次推論結果
批次推論工作完成後，推論的輸出內容會儲存在您在要求中指定的 Cloud Storage bucket 或 BigQuery 位置。
批次推論結果範例
輸出資料夾包含一組 JSON Lines 檔案。
檔案名稱為 {gcs_path}/prediction.results-{file_number}-of-{number_of_files_generated}。由於批次推論的性質是分散式，因此檔案數量不確定。
檔案中的每一行都對應至輸入內容中的一個執行個體，並包含下列鍵/值組合：
prediction：包含容器傳回的值。instance：如果是檔案清單，則包含 Cloud Storage URI。如果是所有其他輸入格式，則包含在 HTTP 要求主體中傳送至容器的值。
範例 1
如果 HTTP 要求包含：
{
"instances": [
[1, 2, 3, 4],
[5, 6, 7, 8]
]}
容器會傳回：
{
"predictions": [
[0.1,0.9],
[0.7,0.3]
],
}
JSON Lines 輸出檔案如下：
{ "instance": [1, 2, 3, 4], "prediction": [0.1,0.9]}
{ "instance": [5, 6, 7, 8], "prediction": [0.7,0.3]}
範例 2
如果 HTTP 要求包含：
{
"instances": [
{"values": [1, 2, 3, 4], "key": 1},
{"values": [5, 6, 7, 8], "key": 2}
]}
容器會傳回：
{
"predictions": [
{"result":1},
{"result":0}
],
}
JSON Lines 輸出檔案如下：
{ "instance": {"values": [1, 2, 3, 4], "key": 1}, "prediction": {"result":1}}
{ "instance": {"values": [5, 6, 7, 8], "key": 2}, "prediction": {"result":0}}
面向使用者的端點
為提升觀測能力並減少要管理的配額數量，模型伺服器可做為面向使用者的 Agent Platform 端點。設定下列任一功能後，模型就會部署至面向使用者的端點：
- 共用預留項目
- Spot VM
- 彈性啟動型 VM
使用可解釋 AI
我們不建議對大量資料執行以特徵為準的說明，因為每個輸入內容可能會根據一組可能的特徵值，擴展為數千個要求，導致處理時間和成本大幅增加。一般來說，只要使用小型資料集，就足以瞭解特徵重要性。
批次推論不支援以範例為基礎的解釋。
筆記本
後續步驟
- 瞭解推論的運算資源。
- 瞭解如何搭配 Agent Platform 批次推論使用預留項目。