PAI-EasyVision離線預測輸入格式與命令參數-人工智慧平台 PAI-阿里雲

預測組件可以使用PAI-EasyVision訓練出的模型進行離線預測。本文介紹離線預測通用的輸入資料格式及PAI命令參數。

概述

PAI-EasyVision支援讀取MaxCompute表資料並將結果寫回MaxCompute表內。同時，支援讀取OSS檔案清單進行預測，並將結果寫回OSS檔案中。整個離線處理過程被抽象為一個流水線處理流程，每個原子過程在每個Worker上非同步多線程並發處理。不同Worker在IO時，通過資料分區擷取對應的輸入資料，寫出對應的輸出分區。例如，從表中讀取圖片進行模型預測，系統根據Worker數量對輸入表進行資料分區，每個Worker首先讀取屬於自己的分區資料，然後經過Base64解碼和模型預測，最後將結果寫入輸出表。其中Base64解碼和模型預測均是多線程非同步執行，可以充分利用CPU和GPU算力進行流水線平行處理。處理過程如下圖所示。

對於視頻資料，PAI-EasyVision提供了視頻層級的預測模型，同時支援使用者調用映像相關的模型進行視訊框架映像預測，PAI-EasyVision的離線處理架構會自動進行視頻解碼、單幀映像預測及所有視訊框架結果的匯總。

考慮到一部分使用者需要載入自己訓練的模型進行離線預測，PAI-EasyVision預設提供的預測代碼無法滿足需求。因此，PAI-EasyVision支援使用者自訂預測代碼，複用ev_predict已有的IO功能。例如，通過資料下載和資料解碼完成自己模型的離線預測。此外，PAI-EasyVision也支援在預測前插入使用者自訂的處理過程，先對輸入資料進行處理，再送入預測器，詳情請參見自訂離線預測。

輸入資料格式

讀MaxCompute表

輸入表可以是一列或多列，其中一列為映像的URL或映像編碼後的位元據經過Base64編碼的資料，Type為STRING類型。Schema樣本如下。

+------------------------------------------------------------------------------------+
| Field           | Type       | Label | Comment                                     |
+------------------------------------------------------------------------------------+
| id              | string     |       |                                             |
| url             | string     |       |                                             |
+------------------------------------------------------------------------------------+

讀OSS檔案
OSS輸入檔案的每一列為一個URL或OSS地址，樣本如下。
```
oss://your/path/to/image.jpg
http://your.path/to/image.jpg
```
自訂輸入資料
讀取MaxCompute表的輸入資料只有圖片的URL或圖片的Base64編碼，讀取OSS檔案的輸入資料只有圖片的URL，進行圖片下載解碼，這兩種方式都只能獲得映像的Numpy Array，以{"image": np.ndarray}的形式在整個預測過程中供各個Process和Predictor使用。隨著越來越多的使用者使用自訂Predictor和自訂Process，這種單一的輸入格式已經無法滿足使用者的需求。因此改進了OSS讀取方式，從而支援使用者自訂格式。
自訂格式支援原有的OSS檔案格式，同時支援JSON字串格式，檔案的每行是一個JSON字串。使用者可以傳入多個KV對，所有的KV對儲存到一個DICT中，傳遞給自訂Predictor和自訂Process，使用者可以方便地根據自訂的Key擷取對應的Value。
如果Value為OSS路徑或URL，則系統自動使用多線程下載檔案內容，並將Value轉換為一個Python file-like Object，使用者可以直接調用read()或readlines()等檔案方法擷取對應內容。如果Value指向一個檔案，且副檔名為圖片類型，則系統自動進行映像解碼，使用者從input_data這個DICT中根據Key擷取對應的Value，類型為numpy.ndarray。
輸入資料樣本如下所示。
```
{"image":"http://your/path/to/image.jpg", "prior":"oss://your/path/to/prior.txt", "config": {"key1":1, "key2":"value2"}}
{"image":"http://your/path/to/image.jpg", "prior":"oss://your/path/to/prior.txt", "config": {"key2":1, "key2":"value2"}}
```
上述的輸入資料會被轉換為input_data的DICT，其中：
- image欄位對應的值為一個映像解碼後的資料。
- prior欄位對應的值為檔案對象。
- config欄位對應一個DICT，即JSON字串內容。
input_data的DICT格式如下所示，使用者在自訂process和predictor中均可以通過Key擷取對應的資料。
```
input_dict = {
  "image": np.ndarray,
  "prior" : file_like_object,
  "config": {"key1":1, "key2":"value2"}
}
```
重要
所有內建的PAI-EasyVision Predictor會使用image這個Key擷取輸入映像。如果需要使用自訂輸入格式調用PAI-EasyVision內建的Predictor，則映像資料的key必須使用image。

參數說明

參數名稱	是否必選	描述	類型	預設值
model_path	是	模型OSS路徑。例如"oss://your_bucket/your_model_dir"。	STRING	無
model_type	是	模型類型，取值範圍如下： feature_extractor：特徵抽取 classifier：映像分類 multilabel_classifier：多標籤分類 detector：物體檢測 text_detector：文字檢測 text_recognizer：文字行識別 text_detection_recognition：文字檢測識別 text_spotter：文字端到端識別 segmentor：映像分割 self_define：自訂預測當model_type為self_define時，會Load user_predictor_cls指定的預測類。	STRING	無
buckets	是	OSS Bucket資訊。如果您使用自己的模型預測，則需要指定儲存模型的OSS Bucket資訊，例如"oss://{bucket_name}.{oss_host}/{path}"。	STRING	無
arn	是	訪問OSS的授權，其擷取方式請參見PAI-TF任務參數介紹的IO相關參數說明部分。	STRING	無
feature_name	否	抽取特徵名稱。當model_type為feature_extractor時，需要指定該參數。例如resnet_v1_50/logits。	STRING	Null 字元串（""）
input_table	否	輸入表。例如，非分區表"odps://prj_name/tables/table_name"，分區表"odps://prj_name/tables/table_name/pt=xxx"。	STRING	Null 字元串（""）
image_col	否	圖片資料所在列名。	STRING	"image"
image_type	否	圖片資料格式，取值範圍如下： base64：表示圖片以Base64編碼存放在表內。 url：表示圖片的URL或OSS路徑存放在表內。	STRING	"base64"
reserved_columns	否	保留資料列名，多個列名間使用英文逗號（,）分隔。例如"col1,col2,col3"。	STRING	Null 字元串（""）
result_column	否	結果列名。	STRING	"prediction_result"
output_table	否	輸出表，同輸入表格式。如果不存在該表，則PAI命令會自動建立輸出表並建立分區。使用者也可以提前自行建立表和分區。	STRING	Null 字元串（""）
lifecycle	否	輸出表生命週期。	INT	10
num_worker	否	預測Worker數目。增加Worker數目可以加速離線預測整體速度。	INT	2
cpuRequired	否	每個Worker CPU資源，取值100表示一個CPU。	INT	1600
gpuRequired	否	每個Worker GPU資源，取值100表示一張GPU卡，不能超過100張GPU卡。如果取值為0，則使用CPU叢集。	INT	100
input_oss_file	否	輸入OSS檔案路徑。檔案內每行的格式支援以下兩種：一個待預測的圖片OSS路徑或URL，例如oss://your_bucket/filelist.txt。一個JSON字串，詳情請參見自訂輸入格式部分。	STRING	Null 字元串（""）
output_oss_file	否	輸出OSS檔案路徑，存放預測結果。系統會以該檔案名稱為首碼，產生num_worker個結果檔案，後續會將這些檔案Merge成一個結果檔案。	STRING	Null 字元串（""）
output_dir	否	輸出檔案目錄，例如"oss://your_bucket/dir"。如果使用自訂的輸出格式，所有的結果圖片檔案都會儲存至該檔案夾。	STRING	Null 字元串（""）
user_resource	否	使用者上傳資源路徑，可以為TAR.GZ、ZIP或Python檔案。支援OSS路徑或HTTP URL。例如oss://xxx/a.tar.gz或http://example.com/c.zip。	STRING	Null 字元串（""）
user_predictor_cls	否	使用者自訂predictor類別模組路徑。例如使用者在module.py中實現了Process A，則A的模組路徑為module.A。	STRING	Null 字元串（""）
user_process_config	否	使用者自訂process配置資訊。其中如下欄位用以配置process，使用者也可增加其他自訂配置欄位： job_name：自訂process名稱。 num_threads：自訂process並發運行線程數。 batch_size：處理資料的batch_size。 user_process_cls：使用者自訂process類別模組路徑。例如，使用者在module.py中實現了Process A，則A的模組路徑為module.A。樣本：'{["job_name":"myprocess","user_process_cls": module.ClassA"num_threads":2, "batch_size":1]}'	JSON字串	Null 字元串（""）
queue_size	否	緩衝隊列長度。	INT	1024
batch_size	否	預測Batch Size。	INT	1
preprocess_thread_num	否	預先處理（圖片解碼、下載）並發線程數。	INT	4
predict_thread_num	否	預測並發線程數。	INT	2
is_input_video	否	輸入是否為視頻，取值範圍如下： true：輸入為視頻 false：輸入為非視頻。	BOOL	false
use_image_predictor	否	使用的預測器是否只支援映像輸入。	BOOL	true
decode_type	否	視頻解碼方式，取值範圍如下： 1：Intra only 2：Keyframe only 3：Without bidir 4：Decode all	INT	4
sample_fps	否	抽幀頻率。	FLOAT	5
reshape_size	否	輸出幀的大小，-1表示使用原始大小。	INT	-1
decode_batch_size	否	每次Decode步驟中的Batch大小。	INT	10
decode_keep_size	否	不同Batch中Overlap的幀數量。	INT	0
enableDynamicCluster	否	開啟Dynamic Cluster，允許單個Worker Failover。如果任務經常異常出錯，則可以開啟該開關。取值範圍如下： true：開啟Dynamic Cluster false：關閉Dynamic Cluster	BOOL	false
useSparseClusterSchema	否	enableDynamicCluster設定為true時，需要將該參數設定為true。取值範圍如下： true：開啟稀疏叢集 false：關閉稀疏叢集	BOOL	false