推論的一般資料格式 - Amazon SageMaker
針對推論請求序列化轉換資料 針對推論回應還原序列化轉換資料適用於所有演算法的一般請求格式使用含內建演算法的批次轉換

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

推論的一般資料格式

Amazon SageMaker 演算法會接受並產生數種不同的 MIME 類型，用於擷取線上和迷你批次預測的 HTTP 承載。在執行推論之前，您可以使用各種 AWS 服務來轉換或預先處理記錄。至少需要為以下各項轉換資料：

  • 推論請求序列化 (由您處理)

  • 推論請求還原序列化 (由演算法處理)

  • 推論回應序列化 (由演算法處理)

  • 推論回應還原序列化 (由您處理)

針對推論請求序列化轉換資料

Amazon SageMaker 演算法推論請求的內容類型選項包括：text/csvapplication/json、和application/x-recordio-protobuf。不支援所有這些類型的演算法可以支援其他類型。例如，XGBoost 僅支援此清單中的 text/csv，但也支援 text/libsvm。

對 text/csv 而言，至 invoke_endpoint 的 Body 引數值應是由逗號將各功能值分隔開的字串。舉例而言，含有四個功能的模型的記錄可能看起來會是：1.5,16.0,14,23.0。在訓練資料上進行的任何轉換作業，在取得推論前，也應在資料上執行。功能的順序有其重要性，必須維持不變。

application/json 顯然更加靈活，為開發人員提供了多種可能的格式，可使用在應用程式中。在高層級中 JavaScript，裝載可能如下所示：

let request = {
  // Instances might contain multiple rows that predictions are sought for.
  "instances": [
    {
      // Request and algorithm specific inference parameters.
      "configuration": {},
      // Data in the specific format required by the algorithm.
      "data": {
         "<field name>": dataElement
       }
    }
  ]
}

您有以下選項可供指定 dataElement：

協定緩衝區相等

// Has the same format as the protocol buffers implementation described for training.
let dataElement = {
  "keys": [],
  "values": [],
  "shape": []
}

簡單數字向量

// An array containing numeric values is treated as an instance containing a
// single dense vector.
let dataElement = [1.5, 16.0, 14.0, 23.0]

// It will be converted to the following representation by the SDK.
let converted = {
  "features": {
    "values": dataElement
  }
}

多重記錄

let request = {
  "instances": [
    // First instance.
    {
      "features": [ 1.5, 16.0, 14.0, 23.0 ]
    },
    // Second instance.
    {
      "features": [ -2.0, 100.2, 15.2, 9.2 ]
    }
  ]
}

針對推論回應還原序列化轉換資料

Amazon SageMaker 算法以多種佈局返回 JSON。高階流程內的結構為：

let response = {
  "predictions": [{
    // Fields in the response object are defined on a per algorithm-basis.
  }]
}

預測中所包含的欄位會因演算法而各有不同。以下範例為 K 平均數演算法的輸出結果。

單一記錄推論 

let response = {
  "predictions": [{
    "closest_cluster": 5,
    "distance_to_cluster": 36.5
  }]
}

多重記錄推論

let response = {
  "predictions": [
    // First instance prediction.
    {
      "closest_cluster": 5,
      "distance_to_cluster": 36.5
    },
    // Second instance prediction.
    {
      "closest_cluster": 2,
      "distance_to_cluster": 90.3
    }
  ]
}

多重記錄推論 (含 protobuf 輸入)

{
  "features": [],
  "label": {
    "closest_cluster": {
      "values": [ 5.0 ] // e.g. the closest centroid/cluster was 1.0
    },
    "distance_to_cluster": {
      "values": [ 36.5 ]
    }
  },
  "uid": "abc123",
  "metadata": "{ "created_at": '2017-06-03' }"
}

SageMaker 演算法也支援 JSONLINES 格式，其中每筆記錄的回應內容與 JSON 格式的回應內容相同。多記錄結構是每項記錄回應物件的連接，以換行字元分隔。用於 2 輸入資料點之內建 KMeans 演算法的回應內容為：

{"distance_to_cluster": 23.40593910217285, "closest_cluster": 0.0}
{"distance_to_cluster": 27.250282287597656, "closest_cluster": 0.0}

執行批次轉換時，建議您將 CreateTransformJobRequest 的 Accept 欄位設定為 application/jsonlines，以使用 jsonlines 回應類型。

適用於所有演算法的一般請求格式

大多數演算法會使用以下多種推論請求格式。

JSON 請求格式

內容類型： 應用程式/JSON

密集格式

let request =   {
    "instances":    [
        {
            "features": [1.5, 16.0, 14.0, 23.0]
        }
    ]
}


let request =   {
    "instances":    [
        {
            "data": {
                "features": {
                    "values": [ 1.5, 16.0, 14.0, 23.0]
                }
            }
        }
    ]
}

稀疏格式

{
	"instances": [
		{"data": {"features": {
					"keys": [26, 182, 232, 243, 431],
					"shape": [2000],
					"values": [1, 1, 1, 4, 1]
				}
			}
		},
		{"data": {"features": {
					"keys": [0, 182, 232, 243, 431],
					"shape": [2000],
					"values": [13, 1, 1, 4, 1]
				}
			}
		},
	]
}

JSONLINES 請求格式

內容類型：應用程式/JSONLINES

密集格式

密集格式的單一記錄可以表示為：

{ "features": [1.5, 16.0, 14.0, 23.0] }

或：

{ "data": { "features": { "values": [ 1.5, 16.0, 14.0, 23.0] } }

稀疏格式

稀疏格式的單一記錄會表示為：

{"data": {"features": { "keys": [26, 182, 232, 243, 431], "shape": [2000], "values": [1, 1, 1, 4, 1] } } }

多記錄會表示為上述單一記錄表示的連接，以換行字元分隔：

{"data": {"features": { "keys": [0, 1, 3], "shape": [4], "values": [1, 4, 1] } } }
{ "data": { "features": { "values": [ 1.5, 16.0, 14.0, 23.0] } }
{ "features": [1.5, 16.0, 14.0, 23.0] }

CSV 請求格式

內容類型： text/CSV; label_size=0

注意

因式分解機不提供 CSV 支援。

RECORDIO 請求格式

資料類型:應用程式/x-recordio-protobuf

使用含內建演算法的批次轉換

執行批次轉換時，建議您使用 JSONLINES 回應類型，而非 JSON (如果演算法支援)。您可以將 CreateTransformJobRequest 中的 Accept 欄位設定為 application/jsonlines 來完成此操作。

建立轉換任務時，SplitType 必須根據輸入資料的 ContentType 來設定。同樣的，AssembleWith 必須根據 CreateTransformJobRequest 中的 Accept 欄位來設定。請使用下列資料表來適當設定這些欄位：

ContentType 推薦 SplitType
application/x-recordio-protobuf RecordIO
text/csv Line
application/jsonlines Line
application/json None
application/x-image None
image/* None
接受 推薦 AssembleWith
application/x-recordio-protobuf None
application/json None
application/jsonlines Line

如需特定演算法回應格式的詳細資訊，請參閱以下各項：