DataWorks：Notebook 進階開發

引用專案資源（.py 檔案）

將通用的函數或類封裝在獨立的 .py 檔案中，通過##@resource_reference{"自訂名.py"}引用MaxCompute資源的方式，實現代碼的模組化與複用，提升代碼的可維護性。

1. 建立並發布 Python 資源

   1. 在 DataWorks Data Studio左側導覽列單擊，進入資源管理。

   2. 在資源管理分類樹下，按右鍵目標目錄或單擊右上方的 + ，選擇建立資源 > MaxCompute Python，命名為 my_utils.py。

   3. 在檔案內容處，點擊線上編輯，將您調試好的工具函數代碼粘貼到代碼編輯框並儲存。

      # my_utils.py
      def greet(name):
          return f"Hello, {name} from resource file!"

   4. 單擊工具列中的儲存，然後發布該資源，使其對開發和生產任務可見。

2. 在 Notebook 中引用資源

   在 Notebook 的Python 儲存格的第一行，使用 ##@resource_reference 文法引用發行的資源。

   ##@resource_reference{"my_utils.py"}
   # 如果資源在目錄下，比如 my_folder/my_utils.py，也是通過##@resource_reference{"my_utils.py"}，無需帶目錄名稱。
   from my_utils import greet
   
   message = greet('DataWorks')
   print(message)

3. 開發環境調試運行

   運行Python儲存格，將列印如下結果：

   Hello, DataWorks from resource file!

   重要

   在開發環境調試運行時，如果識別到代碼中包含##@resource_reference，系統將會把資源管理中的目標檔案自動下載至個人目錄的workspace/_dataworks/resource_references路徑中，從而進行目標檔案的引用。

   若報錯ModuleNotFoundError，點擊編輯器上方工具列的重啟按鈕重新載入資源後再重試。

4. 發布至生產環境並驗證

   儲存並發布此 Notebook 節點後，前往營運中心 > 周期任務單擊測試運行。任務成功後，您將在日誌中看到輸出 Hello, DataWorks from resource file!。

   重要

   若報錯There is no file with id ...，請先將Python資源發布至生產環境。

更多操作，請參見MaxCompute資源與函數。

讀寫資料集（OSS/NAS）

在 Notebook 任務運行時，方便地讀寫儲存在 OSS 或 NAS 上的大規模檔案資料。

更多操作，請參見在個人開發環境中使用資料集。

引用工作空間參數

DataWorks 在已有調度參數的基礎上引入工作空間參數，主要是為瞭解決跨任務、跨節點的全域配置複用與環境隔離問題。可在SQL儲存格和Python儲存格內以${workspace.param}格式來引用工作空間參數，其中param是您建立的工作空間參數名稱。

1、建立工作空間參數：使用前，需前往 DataWorks 營運中心 > 調度設定 > 工作空間參數 頁面建立所需參數。

2、引用工作空間參數：

• SQL儲存格參照工作空間參數。

  SELECT '${workspace.param}';

  查詢工作空間參數，運行成功後，將列印輸出工作空間參數的具體賦值。

• Python儲存格參照工作空間參數。

  print('${workspace.param}')

  輸出工作空間參數，運行成功後，將列印輸出工作空間參數的具體賦值。

更多詳情，請參見使用工作空間參數。

串連 MaxCompute

• %odps：擷取 PyODPS 入口對象

  此命令返回一個與當前MaxCompute專案綁定、已認證的 PyODPS 對象，避免在代碼中寫入程式碼 AccessKey，是與 MaxCompute 互動的推薦方式。

  1. 使用Magic Command建立MaxCompute串連。 輸入%odps，右下角會出現MaxCompute的計算資源選取器入口（並自動選擇計算資源）。點擊右下角的MaxCompute專案名稱，可更換MaxCompute專案。

     o=%odps 

  2. 使用擷取到的MaxCompute計算資源運行PyODPS指令碼。

     例如，擷取當前專案下的所有表：

     with o.execute_sql('show tables').open_reader() as reader:
         print(reader.raw)

• %maxframe：建立 MaxFrame 串連

  此命令用於建立 MaxFrame 會話，為 MaxCompute 提供類似 Pandas 的分布式資料處理能力。

  # 串連並訪問MaxCompute MaxFrame Session
  mf_session = %maxframe
  
  df = mf_session.read_odps_table('your_mc_table')
  print(df.head())
  
  # 開發調試結束後，應手動銷毀會話以釋放資源
  mf_session.destroy()

串連 Spark 計算資源

DataWorks Notebook 支援串連多種 Spark 引擎。不同引擎在串連方式、執行內容和資源管理上存在差異。

串連 Lindorm Ray 計算資源

Lindorm計算引擎的RAY資源群組提供分散式運算服務，支援AI負載端到端處理。通過 Magic Command，在 Notebook 中無縫串連 Lindorm Ray 資源，進行互動式開發、調試，並將其發布為生產調度任務。

1. 建立串連：在 Python 儲存格中運行 %lindorm_ray 命令。運行後，儲存格右下角將出現計算資源選取器，請在此處選擇您的Lindorm 計算資源和建立好的Ray 資源群組。

   # 串連到指定的Lindorm Ray資源群組
   %lindorm_ray

   重要

   • 串連Lindorm Ray計算資源後，同一個 Notebook將不再支援運行SQL儲存格。Lindorm Ray 引擎專註於執行 Python 和 Ray 代碼。

   • 當您多次運行同一個代碼儲存格時，系統會自動終止上一個正在啟動並執行 Ray Job，並啟動一個新的 Job。這可以有效避免資源浪費和任務衝突。

2. 執行 Ray 代碼：串連成功後，在新的 Python 儲存格中直接編寫和執行 Ray 代碼。日誌會即時回傳到儲存格的輸出地區，方便您進行互動式調試。

   以下樣本定義了一個簡單的遠程任務（使用 @ray.remote 裝飾器），它會在 Ray 叢集上執行，並將日誌和最終結果返回到儲存格的輸出區。

   import ray
   import time
   
   @ray.remote
   def hello_world():
     print("Hello from Lindorm Ray!")
     time.sleep(5)
     return "Task finished."
   # 提交遠程任務
   result_ref = hello_world.remote()
   print(ray.get(result_ref))

3. （可選）自訂啟動參數：如需為 Ray 環境指定額外的配置，例如安裝第三方 Python 包或上傳本地代碼檔案，可以使用 %%lindorm_ray 命令建立串連。

   • 樣本1：安裝依賴包

     通過 pip 參數在 Ray 環境中安裝 jieba 包。

     %%lindorm_ray
     {
       "runtime_env": {
         "pip": ["jieba"]
       }
     }

     環境準備就緒後，在後續的 Ray 任務中匯入並使用該包。以下樣本示範如何在遠程函數中調用jieba進行中文分詞：

     import ray 
     
     @ray.remote
     def do_work(x):
         import jieba
     
         return "/".join(jieba.cut(x))
     
     print(ray.get(do_work.remote("歡迎使用DataWorks+LindormRay解決方案")))

   • 樣本2：上傳並使用DataWorks資源

     通過 working_dir 參數，將 DataWorks 資源管理中已上傳的資源進一步上傳到 Ray 叢集，使其可以在任務中被匯入和調用。

     重要

     • 使用 working_dir 上傳資源時，檔案會直接從您的開發環境上傳到 Ray 叢集，存在 100MB 的大小限制。如果資源套件過大，可能導致上傳失敗或 Ray 節點不穩定。

     • 對於體積較大的資源檔或依賴（超過100MB），建議您先將其上傳到 OSS，然後在代碼中從 OSS 下載和讀取，或者直接將其打包到自訂鏡像中。這能提供更好的穩定性和效能。

     # 引用Data Studio資源管理中上傳的資源，聲明路徑
     %%lindorm_ray
     {
         "runtime_env": {
             "working_dir": "/mnt/workspace/_dataworks/resource_references"
         }
     }

     假設在DataWorks的Data Stuido資源管理中上傳了一個ray_resource.py檔案，編寫並執行以下儲存格時，系統會自動解析後續代碼中的##@resource_reference 聲明，並將下載相應資源到 /mnt/workspace/_dataworks/resource_references路徑。

     ray_resource.py的代碼內容樣本如下：

     def fun():
         print("This is a test function in ray_resource.py")

     重要

     在開發環境中，當執行完包含##@resource_reference的儲存格後，您需要重新運行上面的%%lindorm_ray儲存格，會將下載好的資源套件含在working_dir中上傳到Ray叢集。在生產環境中，您無需重新運行。

     import ray 
     
     ##@resource_reference{"ray_resource.py"}
     
     @ray.remote
     def do_work(x):
         print('Ray says:', x)
     
         from ray_resource import fun
         fun()
         return x
     
     worker = do_work.remote("歡迎使用DataWorks+LindormRay解決方案")
     print(ray.get(worker))

4. 生產調度與營運：開發調試完成後，您可以將此 Notebook 節點提交發布，它將作為一個 Lindorm Ray 節點在 DAG 中進行周期性調度。

   • 參數化：您的代碼可以正常使用 DataWorks 的標準調度參數，例如 ${bizdate}。

   • 日誌查看：在生產環境中，為了避免日誌過多影響效能，系統預設只載入前 1MB 的日誌。如果日誌被截斷，輸出結果中會提供一個連結，引導您跳轉至 Lindorm 控制台查看完整的任務日誌。

   • 資源釋放：生產調度任務結束後，Lindorm Ray任務的狀態會變為終態，不再佔用資源；互動式開發時，你可以通過重啟Kernel、關閉Notebook將Lindorm Ray的任務變為終態。

附錄：Magic Command 速查表