本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# DeepAR 推論格式
<a name="deepar-in-formats"></a>

以下頁面說明使用 Amazon SageMaker AI DeepAR 模型進行推論的請求和回應格式。

## DeepAR JSON 請求格式
<a name="deepar-json-request"></a>

利用模型的端點來查詢訓練過的模型。該端點接受下列的 JSON 請求格式。

在請求中，`instances` 欄位對應於模型應該預測的時間序列。

如果模型是使用分類來進行訓練，您必須為每個執行個體提供 `cat`。如果模型在訓練時並未使用 `cat` 欄位，則應省略此欄位。

若模型是使用自訂特徵時間序列 (`dynamic_feat`) 進行訓練，您必須為每個執行個體提供相同數量的 `dynamic_feat` 值。每個值都必須具備 `length(target) + prediction_length` 所指定的長度，其中最後的 `prediction_length` 值會對應到將預測未來中的時間點。若模型並未使用自訂特徵時間序列進行訓練，則不應在請求中包含此欄位。

```
{
    "instances": [
        {
            "start": "2009-11-01 00:00:00",
            "target": [4.0, 10.0, "NaN", 100.0, 113.0],
            "cat": [0, 1],
            "dynamic_feat": [[1.0, 1.1, 2.1, 0.5, 3.1, 4.1, 1.2, 5.0, ...]]
        },
        {
            "start": "2012-01-30",
            "target": [1.0],
            "cat": [2, 1],
            "dynamic_feat": [[2.0, 3.1, 4.5, 1.5, 1.8, 3.2, 0.1, 3.0, ...]]
        },
        {
            "start": "1999-01-30",
            "target": [2.0, 1.0],
            "cat": [1, 3],
            "dynamic_feat": [[1.0, 0.1, -2.5, 0.3, 2.0, -1.2, -0.1, -3.0, ...]]
        }
    ],
    "configuration": {
         "num_samples": 50,
         "output_types": ["mean", "quantiles", "samples"],
         "quantiles": ["0.5", "0.9"]
    }
}
```

`configuration` 欄位是選擇性的。`configuration.num_samples` 會設定模型產生，以估計平均數和分位數的樣本路徑數。`configuration.output_types` 則描述了應在請求中傳回的資訊。有效值為 `"mean"` `"quantiles"` 和 `"samples"`。如果您指定 `"quantiles"`，則在 `configuration.quantiles` 中的每個分位數值都會以時間序列的形式傳回。如果您指定 `"samples"`，模型也會傳回用來計算其他輸出的原始樣本。

## DeepAR JSON 回應格式
<a name="deepar-json-response"></a>

下列是回應的格式，其中 `[...]` 為數字陣列：

```
{
    "predictions": [
        {
            "quantiles": {
                "0.9": [...],
                "0.5": [...]
            },
            "samples": [...],
            "mean": [...]
        },
        {
            "quantiles": {
                "0.9": [...],
                "0.5": [...]
            },
            "samples": [...],
            "mean": [...]
        },
        {
            "quantiles": {
                "0.9": [...],
                "0.5": [...]
            },
            "samples": [...],
            "mean": [...]
        }
    ]
}
```

DeepAR 的回應逾時為 60 秒。在單一請求中傳遞多個時間序列時，預測會依序產生。因為每個時間序列的預測通常需要 300 到 1000 毫秒以上的時間，根據模型的大小，在單一請求中傳遞太多時間序列可能會造成逾時。建議在每個請求中傳遞較少數量的時間序列，並傳送更多請求。因為 DeepAR 演算法針對每個執行個體使用多個工作者，您可以透過平行傳送多個請求來取得更高的輸送量。

根據預設，DeepAR 會針對每個 CPU 使用一個工作者進行推論 (若每個 CPU 有足夠的記憶體)。若模型較大且沒有足夠的記憶體來在每個 CPU 上執行模型，便會減少工作者的數量。用於推論的工作者數量可使用環境變數 `MODEL_SERVER_WORKERS` 覆寫。例如，在呼叫 SageMaker AI [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html) API 時設定 `MODEL_SERVER_WORKERS=1`)。

## 使用 DeepAR 演算法進行批次轉換
<a name="deepar-batch"></a>

DeepAR 預測支援使用 JSON Lines 格式，利用批次轉換從資料取得推論。在此格式中，每個記錄都會在單行上以 JSON 物件表示，每一行則會由換行字元分隔。其格式與用於模型訓練的 JSON Lines 格式完全相同。如需相關資訊，請參閱[DeepAR 演算法的輸入/輸出介面](deepar.md#deepar-inputoutput)。例如：

```
{"start": "2009-11-01 00:00:00", "target": [4.3, "NaN", 5.1, ...], "cat": [0, 1], "dynamic_feat": [[1.1, 1.2, 0.5, ..]]}
{"start": "2012-01-30 00:00:00", "target": [1.0, -5.0, ...], "cat": [2, 3], "dynamic_feat": [[1.1, 2.05, ...]]}
{"start": "1999-01-30 00:00:00", "target": [2.0, 1.0], "cat": [1, 4], "dynamic_feat": [[1.3, 0.4]]}
```

**注意**  
使用 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTransformJob.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTransformJob.html) 建立轉換任務時，將 `BatchStrategy` 值設為 `SingleRecord`，並將 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_TransformInput.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_TransformInput.html) 組態中的 `SplitType` 值設為 `Line`，因為預設值目前會導致導致執行期錯誤。

與託管端點推論請求格式相似，若符合下列條件，則每個執行個體的 `cat` 和 `dynamic_feat` 都是必要項目：
+ 模型是在同時包含 `cat` 和 `dynamic_feat` 欄位的資料集上訓練。
+ 訓練任務中所使用的對應 `cardinality` 和 `num_dynamic_feat` 值並未設為 `"".`

與託管端點推論不同，組態欄位只會使用名為 `DEEPAR_INFERENCE_CONFIG` 的環境變數，為整個批次推論任務設定一次。`DEEPAR_INFERENCE_CONFIG` 的值可以在呼叫 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTransformJob.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTransformJob.html) API 建立模型時傳遞。若容器環境中遺失 `DEEPAR_INFERENCE_CONFIG`，則推論容器會使用下列預設：

```
{
    "num_samples": 100,
    "output_types": ["mean", "quantiles"],
    "quantiles": ["0.1", "0.2", "0.3", "0.4", "0.5", "0.6", "0.7", "0.8", "0.9"]
}
```

輸出也是 JSON Lines 格式，每一行代表每一個預測，其順序則與對應輸入檔案中的執行個體順序相同。預測會編碼成物件，並且和線上推論模式中回應所傳回的物件完全相同。例如：

```
{ "quantiles": { "0.1": [...], "0.2": [...] }, "samples": [...], "mean": [...] }
```

請注意，在 SageMaker AI [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTransformJob.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTransformJob.html) 請求的 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_TransformInput.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_TransformInput.html) 組態中，用戶端必須將 `AssembleWith` 值明確設定為 `Line`，因為預設值 `None` 會將所有 JSON 物件串連在同一行。

例如，以下是具有自訂 `DEEPAR_INFERENCE_CONFIG` 之 DeepAR 任務的 SageMaker AI [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTransformJob.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTransformJob.html) 請求：

```
{
   "BatchStrategy": "SingleRecord",
   "Environment": { 
      "DEEPAR_INFERENCE_CONFIG" : "{ \"num_samples\": 200, \"output_types\": [\"mean\"] }",
      ...
   },
   "TransformInput": {
      "SplitType": "Line",
      ...
   },
   "TransformOutput": { 
      "AssembleWith": "Line",
      ...
   },
   ...
}
```