Platform For AI：OSS使用

掛載方式

預設配置限制

當高级配置參數為空白時使用預設配置，限制如下：

• 為加速讀取，掛載OSS時會緩衝中繼資料（目錄與檔案清單）。

  分布式任務中，多個節點同時建立同一目錄時，中繼資料快取會讓每個節點都嘗試建立。最終只有一個節點成功，其餘報錯。

• 預設使用OSS的Multipart API建立檔案，寫入過程中OSS上看不到該對象，寫入完成後才能查看。

• 不支援同時讀寫同一檔案。

• 不支援隨機寫入檔案。

常見JindoFuse配置

您也可以按情境在進階配置中自訂JindoFuse參數。

以下僅提供部分情境建議，未覆蓋所有最優效能設定。更多配置請參見JindoFuse使用指南。

• 快速讀寫：允許使用者讀寫，讀取速度快，但並發讀寫可能會出現資料不一致的問題，適合掛載訓練資料和模型，不適合作為工作目錄。

  {
    "fs.oss.download.thread.concurrency": "cpu核心數2倍",
    "fs.oss.upload.thread.concurrency": "cpu核心數2倍",
    "fs.jindo.args": "-oattr_timeout=3 -oentry_timeout=0 -onegative_timeout=0 -oauto_cache -ono_symlink"
  }
  

• 增量讀寫：在增量寫入時能夠保證資料一致性，覆蓋原有資料會有一致性問題。讀取速度略慢，適合儲存訓練的模型權重檔案。

  {
    "fs.oss.upload.thread.concurrency": "cpu核心數2倍",
    "fs.jindo.args": "-oattr_timeout=3 -oentry_timeout=0 -onegative_timeout=0 -oauto_cache -ono_symlink"
  }
  

• 讀寫一致：在並發讀寫中能保持資料一致性，適用於對資料一致性要求高，可以容忍讀取速度慢的情境，適合儲存代碼專案。

  {
    "fs.jindo.args": "-oattr_timeout=0 -oentry_timeout=0 -onegative_timeout=0 -oauto_cache -ono_symlink"
  }
  

• 唯讀：僅允許讀取，不允許寫入，適合掛載公用資料集。

  {
    "fs.oss.download.thread.concurrency": "cpu核心數2倍",
    "fs.jindo.args": "-oro -oattr_timeout=7200 -oentry_timeout=7200 -onegative_timeout=7200 -okernel_cache -ono_symlink"
  }

常見配置如下：

掛載方式

常見ossfs配置

在進階配置中，通過fs.ossfs.args設定進階參數，多個參數之間使用半形逗號,分隔。進階參數說明請參見ossfs 2.0。常見情境樣本如下：

• 任務過程中資料來源不變：如果讀取過程中檔案不會被修改，可配置較大的緩衝時間，減少中繼資料請求次數。例如讀取一批已有舊檔案，處理後產生新檔案。

  {
      "mountType":"ossfs",
      "fs.ossfs.args": "-oattr_timeout=7200" 
  }

• 快速讀寫：使用較小的中繼資料快取時間，平衡緩衝效率與資料及時性。

  {
      "mountType":"ossfs",
      "fs.ossfs.args": "-oattr_timeout=3, -onegative_timeout=0"
  }

• 分布式任務讀寫一致：ossfs預設會緩衝中繼資料。通過以下配置實現多節點同步視圖。

  {   
      "mountType":"ossfs",
      "fs.ossfs.args": "-onegative_timeout=0, -oclose_to_open"
  }

• DLC/DSW情境中同時開啟過多檔案導致OOM：DLC或DSW情境中任務並發量較高，可能同時開啟大量檔案導致OOM（記憶體不足）。通過以下配置緩解記憶體壓力。

  {
      "mountType":"ossfs",
      "fs.ossfs.args": "-oreaddirplus=false, -oinode_cache_eviction_threshold=300000"
  }

• 寫入大檔案失敗：-oupload_buffer_size用於設定分區上傳緩衝區大小（Bytes）。該參數決定可寫入檔案的最大大小，計算方式為upload_buffer_size * 10000。

  ossfs 2.0預設分區大小為8 MiB，最大支援寫入78.125 GiB的檔案。超過該限制時寫入會失敗。可配置-oupload_buffer_size增加分區大小，從而提升可寫入檔案大小上限。例如將Part大小設為32 MiB（33554432位元組），可支援最大312.5 GiB的檔案。-upload_buffer_size越大，消耗記憶體越多，可配置-total_mem_limit控制記憶體使用量，詳情請參見掛載選項說明

  {
      "mountType":"ossfs",
      "fs.ossfs.args": "-oupload_buffer_size=33554432"
  }
  

使用限制

• 官方鏡像：僅當DLC任務或DSW執行個體選擇PyTorch 2.0及以上版本的鏡像時，可用OSS Connector for AI/ML模組。

• 自訂鏡像：僅支援PyTorch 2.0及以上版本。滿足版本要求後，運行以下命令安裝OSS Connector for AI/ML模組。

  pip install -i http://yum.tbsite.net/aliyun-pypi/simple/ --extra-index-url http://yum.tbsite.net/pypi/simple/ --trusted-host=yum.tbsite.net osstorchconnector

• Python版本：僅支援Python 3.8~3.12。

準備工作

1. 配置credential檔案。

   通過以下任一方式配置credential：

   • 參考配置DLC RAM角色，為DLC任務配置免密訪問OSS的credential。DLC任務會擷取STS臨時訪問憑證，安全訪問OSS或其他雲資源，無需在代碼中配置認證資訊，降低密鑰泄露風險。

   • 在代碼專案中配置credential檔案管理認證資訊。配置樣本如下：

     說明

     明文配置AK存在安全風險，建議在DLC執行個體內通過角色自動設定credential，詳情請參見配置DLC RAM角色。

     使用OSS Connector for AI/ML介面時，指定credential檔案路徑後自動擷取認證資訊，完成OSS資料請求認證。

     {
       "AccessKeyId": "<Access-key-id>",
       "AccessKeySecret": "<Access-key-secret>",
       "SecurityToken": "<Security-Token>",
       "Expiration": "2024-08-20T00:00:00Z"
     }

     具體配置項說明如下：

     配置項	是否必填	說明	樣本值
     AccessKeyId	是	阿里雲帳號或RAM使用者的AccessKey ID和AccessKey Secret。 說明 使用STS臨時訪問憑證訪問OSS時，請設定為臨時訪問憑證的AccessKey ID和AccessKey Secret。	NTS****
     AccessKeySecret	是		7NR2****
     SecurityToken	否	臨時存取權杖。使用STS臨時訪問憑證訪問OSS時，需要設定。	STS.6MC2****
     Expiration	否	鑒權資訊到期時間，Expiration為空白表示永不到期，到期後OSS Connector會重新讀取鑒權資訊。	2024-08-20T00:00:00Z

2. 配置config.json檔案，樣本如下：

   在代碼專案中配置config.json檔案，管理並發數、預取參數和日誌路徑等。使用OSS Connector for AI/ML介面時，指定config.json檔案路徑後，系統會自動讀取並發數和預取值，並將OSS資料請求日誌輸出到指定檔案。

   {
       "logLevel": 1,
       "logPath": "/var/log/oss-connector/connector.log",
       "auditPath": "/var/log/oss-connector/audit.log",
       "datasetConfig": {
           "prefetchConcurrency": 24,
           "prefetchWorker": 2
       },
       "checkpointConfig": {
           "prefetchConcurrency": 24,
           "prefetchWorker": 4,
           "uploadConcurrency": 64
       }
   }

   配置項說明如下：

   配置項		是否必填	說明	樣本值
   logLevel		是	日誌記錄層級。預設為INFO。取值如下： 0：表示Debug。 1：表示INFO。 2：表示WARN。 3：表示ERROR。	1
   logPath		是	connector日誌路徑。預設路徑為/var/log/oss-connector/connector.log。	/var/log/oss-connector/connector.log
   auditPath		是	connector IO審計日誌，記錄延遲大於100毫秒的讀寫請求。預設路徑為/var/log/oss-connector/audit.log。	/var/log/oss-connector/audit.log
   DatasetConfig	prefetchConcurrency	是	使用Dataset從OSS預取資料時的並發數，預設為24。	24
   	prefetchWorker	是	使用Dataset從OSS預取時可用的vCPU數，預設為4。	2
   checkpointConfig	prefetchConcurrency	是	使用checkpoint read從OSS預取資料時的並發數，預設為24。	24
   	prefetchWorker	是	使用checkpoint read從OSS預取時可用的vCPU數，預設為4。	4
   	uploadConcurrency	是	使用checkpoint write上傳資料時的並發數，預設為64。	64

使用方式

OSS Connector for AI/ML提供OssMapDataset和OssIterableDataset兩種資料集提供者，分別擴充Dataset和IterableDataset。OssIterableDataset有預取最佳化，訓練效率更高。OssMapDataset的讀取順序由DataLoader決定，支援shuffle。建議如下：

• 如果記憶體較小或資料量較大，只需順序讀取且對平行處理要求不高，建議使用OssIterableDataset。

• 如果記憶體充足、資料量較小，且需要隨機操作和平行處理，建議使用OssMapDataset。

OSS Connector for AI/ML還提供OssCheckpoint介面，支援模型載入和儲存。當前OssCheckpoint功能僅限通用資源環境使用。

下面介紹這三種介面的使用方式：

checkpoint = OssCheckpoint(endpoint="{oss_endpoint}", cred_path=cred_path, config_path=config_path)

checkpoint_read_uri = "{checkpoint_path}"
checkpoint_write_uri = "{checkpoint_path}"
with checkpoint.reader(checkpoint_read_uri) as reader:
    state_dict = torch.load(reader)
    model.load_state_dict(state_dict)
with checkpoint.writer(checkpoint_write_uri) as writer:
    torch.save(model.state_dict(), writer)

程式碼範例

以下是OSS Connector for AI/ML的範例程式碼，可直接用於訪問OSS資料：

from osstorchconnector import OssMapDataset, OssCheckpoint
import torchvision.transforms as transforms
import accimage
import torchvision.models as models
import torch

cred_path = "/mnt/.alibabacloud/credentials"  # 為DLC任務和DSW執行個體配置角色後credential的預設路徑。
config_path = "config.json"
checkpoint = OssCheckpoint(endpoint="{oss_endpoint}", cred_path=cred_path, config_path=config_path)
model = models.__dict__["resnet18"]()

epochs = 100  # 指定epoch
checkpoint_read_uri = "{checkpoint_path}"
checkpoint_write_uri = "{checkpoint_path}"
with checkpoint.reader(checkpoint_read_uri) as reader:
    state_dict = torch.load(reader)
    model.load_state_dict(state_dict)


def read_and_transform(data):
    normalize = transforms.Normalize(mean=[0.485, 0.456, 0.406],
                                     std=[0.229, 0.224, 0.225])
    transform = transforms.Compose([
        transforms.RandomResizedCrop(224),
        transforms.RandomHorizontalFlip(),
        transforms.ToTensor(),
        normalize,
    ])

    try:
        img = accimage.Image((data.read()))
        value = transform(img)
    except Exception as e:
        print("read failed", e)
        return None, 0
    return value, 0
dataset = OssMapDataset.from_prefix("{oss_data_folder_uri}", endpoint="{oss_endpoint}", transform=read_and_transform, cred_path=cred_path, config_path=config_path)
data_loader = torch.utils.data.DataLoader(
    dataset, batch_size="{batch_size}",num_workers="{num_workers"}, pin_memory=True)

for epoch in range(args.epochs):
    for step, (images, target) in enumerate(data_loader):
        # batch processing
        # model training
    # save model
    with checkpoint.writer(checkpoint_write_uri) as writer:
        torch.save(model.state_dict(), writer)

上述代碼的關鍵實現說明如下：

• OssMapDataset直接基於給定的OSS URI，構建與PyTorch DataLoader用法一致的dataset。

• 用該dataset構建標準DataLoader，並迴圈DataLoader執行訓練流程，如處理當前batch、模型訓練與儲存等。

• 該過程無需將資料集掛載到容器，也無需預先將資料存到本地，資料按需載入。

OSS Python SDK

您可直接使用OSS Python SDK讀寫OSS資料，操作步驟如下：

1. 安裝OSS Python SDK。詳情請參見安裝（Python SDK V1）。

2. 為OSS Python SDK配置訪問憑證。憑證用於驗證您對OSS的存取權限，詳情請參見配置訪問憑證（Python SDK V1）。

3. 讀寫OSS資料。

   # -*- coding: utf-8 -*-
   import oss2
   from oss2.credentials import EnvironmentVariableCredentialsProvider
   
   # 使用環境變數中的RAM使用者存取金鑰配置訪問憑證
   auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
   bucket = oss2.Bucket(auth, '<Endpoint>', '<your_bucket_name>')
   # 讀取完整檔案。
   result = bucket.get_object('<your_file_path/your_file>')
   print(result.read())
   # 按Range讀取資料。
   result = bucket.get_object('<your_file_path/your_file>', byte_range=(0, 99))
   # 寫資料到OSS。
   bucket.put_object('<your_file_path/your_file>', '<your_object_content>')
   # 對Appendable類型檔案追加資料。
   result = bucket.append_object('<your_file_path/your_file>', 0, '<your_object_content>')
   result = bucket.append_object('<your_file_path/your_file>', result.next_position, '<your_object_content>')
   

   請按實際修改以下配置項：

   配置項	描述
   <Endpoint>	填寫Bucket所在地區的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。擷取Endpoint更多資訊，請參見地區和Endpoint。
   <your_bucket_name>	填寫儲存空間名稱。
   <your_file_path/your_file>	待讀寫的檔案路徑。填寫Object完整路徑，不包含Bucket名稱，例如testfolder/exampleobject.txt。
   <your_object_content>	待Append的內容，按實際情況修改。

OSS Python API

使用OSS Python API可方便儲存訓練資料和模型。開始前確保已安裝OSS Python SDK並正確設定訪問憑證，詳情請參見安裝（Python SDK V1）和配置訪問憑證（Python SDK V1）。

• 載入訓練資料

  您可將資料存放在一個OSS Bucket中，將資料路徑與對應Label存入同一OSS Bucket的索引檔案。通過自訂Dataset，在PyTorch中用DataLoaderAPI多進程並行讀取資料，可提升訓練效率，樣本如下。

  import io
  import oss2
  from oss2.credentials import EnvironmentVariableCredentialsProvider
  import PIL
  import torch
  
  class OSSDataset(torch.utils.data.dataset.Dataset):
      def __init__(self, endpoint, bucket, auth, index_file):
          self._bucket = oss2.Bucket(auth, endpoint, bucket)
          self._indices = self._bucket.get_object(index_file).read().split(',')
  
      def __len__(self):
          return len(self._indices)
  
      def __getitem__(self, index):
          img_path, label = self._indices(index).strip().split(':')
          img_str = self._bucket.get_object(img_path)
          img_buf = io.BytesIO()
          img_buf.write(img_str.read())
          img_buf.seek(0)
          img = Image.open(img_buf).convert('RGB')
          img_buf.close()
          return img, label
  
  
  # 從環境變數擷取訪問憑證。運行本代碼前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
  auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
  dataset = OSSDataset(endpoint, bucket, auth, index_file)
  data_loader = torch.utils.data.DataLoader(
      dataset,
      batch_size=batch_size,
      num_workers=num_loaders,
      pin_memory=True)
  

  關鍵配置說明如下：

  關鍵配置	描述
  endpoint	填寫Bucket所在地區的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。擷取Endpoint更多資訊，請參見地區和Endpoint。
  bucket	填寫Bucket名稱。
  index_file	索引檔案的路徑。 說明 樣本中索引檔案格式為每條樣本用英文逗號（,）分隔，樣本路徑與Label之間用英文冒號（:）分隔。

• Save或Load模型

  您可使用OSS Python API儲存或載入PyTorch模型（PyTorch儲存/載入模型詳情請參見PyTorch），樣本如下：

  • Save模型

    from io import BytesIO
    import torch
    import oss2
    from oss2.credentials import EnvironmentVariableCredentialsProvider
    
    auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
    # Bucket名稱
    bucket_name = "<your_bucket_name>"
    bucket = oss2.Bucket(auth, endpoint, bucket_name)
    buffer = BytesIO()
    torch.save(model.state_dict(), buffer)
    bucket.put_object("<your_model_path>", buffer.getvalue())
    

    其中

    • endpoint為Bucket所在地區的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。

    • <your_bucket_name>為OSS Bucket名稱，且開頭不帶oss://。

    • <your_model_path>為模型路徑，按實際情況修改。

  • Load模型

    from io import BytesIO
    import torch
    import oss2
    from oss2.credentials import EnvironmentVariableCredentialsProvider
    
    auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
    bucket_name = "<your_bucket_name>"
    bucket = oss2.Bucket(auth, endpoint, bucket_name)
    buffer = BytesIO(bucket.get_object("<your_model_path>").read())
    model.load_state_dict(torch.load(buffer))

    其中

    • endpoint為Bucket所在地區的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。

    • <your_bucket_name>為OSS Bucket名稱，且開頭不帶oss://。

    • <your_model_path>為模型路徑，按實際情況修改。