對程式庫安裝錯誤進行疑難排解

發行項
12/18/2024

若要讓您的應用程式可以使用協力廠商或本機建置的程式碼，您可以將程式庫安裝到其中一個無伺服器 Apache Spark 集區中。當集區啟動時，會從 PyPi 下載 requirements.txt 檔案中列出的套件。每次從該 Spark 集區建立 Spark 執行個體時，就會使用此需求檔案。一旦為 Spark 集區安裝程式庫之後，該程式庫就可用於使用相同集區的所有工作階段。

在某些情況下，您可能會發現程式庫未出現在 Apache Spark 集區中。當提供的 requirements.txt 或指定的程式庫中發生錯誤時，通常會發生這種情況。當程式庫安裝過程中發生錯誤時，Apache Spark 集區會還原回 Synapse 基底執行階段中指定的程式庫。

本文件的目標是要提供常見問題，並協助您偵錯程式庫安裝錯誤。

強制更新您的 Apache Spark 集區

當您更新 Apache Spark 集區中的程式庫時，將會在集區重新啟動之後取得這些變更。如果您有作用中作業，這些作業會繼續在原始版本的 Spark 集區中執行。

您可以選取 [Force new settings] \(強制使用新設定\) 選項來強制套用變更。此設定會結束所選 Spark 集區的所有目前工作階段。工作階段結束之後，您必須等候集區重新啟動。

新增 Python 程式庫

追蹤安裝進度

每次使用一組新的程式庫更新集區時，都會啟動系統保留的 Spark 作業。此 Spark 作業有助於監視程式庫安裝的狀態。如果因為程式庫衝突或其他問題而導致安裝失敗，Spark 集區會還原為其先前或預設狀態。

此外，使用者也可以檢查安裝記錄來找出相依性衝突，或查看在集區更新期間安裝了哪些程式庫。

若要檢視這些記錄：

瀏覽至 [監視] 索引標籤中的 Spark 應用程式清單。
選取對應至集區更新的系統 Spark 應用程式作業。這些系統作業在 SystemReservedJob-LibraryManagement 標題下執行。
切換以檢視 [驅動程式] 和 [stdout] 記錄。
在結果中，您會看到與套件安裝相關的記錄。

追蹤安裝失敗

在某些狀況下，使用者也可以檢查 Spark 歷程記錄伺服器中可用的完整安裝記錄，識別複雜的相依性衝突。您可以截斷透過 Spark UI 提供的記錄並透過 Spark 歷程記錄伺服器存取完整的安裝記錄，這在複雜程式庫安裝案例中很實用。

若要檢視完整的安裝記錄：

瀏覽至 [監視] 索引標籤中的 Spark 應用程式清單。
選取對應至失敗集區更新的系統 Spark 應用程式作業。這些系統作業在 SystemReservedJob-LibraryManagement 標題下執行。
選取醒目提示的 Spark 歷程記錄伺服器 選項，以在新索引標籤中開啟 Spark 歷程記錄伺服器詳細數據頁面。
在此頁面中，您將看到 2 次嘗試，選取 [嘗試 1]，如下所示。
在Spark歷程記錄伺服器頁面頂端導覽列上，切換至 [執行程式] 索引 標籤。
下載 stdout 和 stderr 記錄檔，以存取完整的管理輸出和錯誤記錄。

驗證您的許可權

若要安裝及更新連結庫，您必須擁有 連結至 Azure Synapse Analytics 工作區之主要 Azure Data Lake Storage Gen2 儲存器帳戶的記憶體 Blob 數據參與者 或 記憶體 Blob 數據擁有者 許可權。

若要驗證您擁有這些許可權，您可以執行下列程式代碼：

from pyspark.sql.types import StructType,StructField, StringType, IntegerType
data2 = [("James","Smith","Joe","4355","M",3000),
    ("Michael","Rose","Edward","40288","F",4000)
  ]

schema = StructType([ \
    StructField("firstname",StringType(),True), \
    StructField("middlename",StringType(),True), \
    StructField("lastname",StringType(),True), \
    StructField("id", StringType(), True), \
    StructField("gender", StringType(), True), \
    StructField("salary", IntegerType(), True) \
  ])
 
df = spark.createDataFrame(data=data2,schema=schema)

df.write.csv("abfss://<<ENTER NAME OF FILE SYSTEM>>@<<ENTER NAME OF PRIMARY STORAGE ACCOUNT>>.dfs.core.windows.net/validate_permissions.csv")

如果您收到錯誤，您可能遺漏必要的許可權。若要瞭解如何取得所需的許可權，請流覽這份檔：指派記憶體 Blob 數據參與者或記憶體 Blob 資料擁有者許可權。

此外，如果您正在執行管線，則工作區 MSI 也必須具有記憶體 Blob 數據擁有者或記憶體 Blob 數據參與者許可權。若要瞭解如何授與工作區身分識別此許可權，請造訪：將許可權授與工作區受控識別。

檢查環境組態檔

環境組態檔可用來升級 Conda 環境。這個可接受的 Python 集區管理檔格式會列為環境規格。

請務必注意下列限制：

需求檔案的內容不得包含額外的空白行或字元。
Synapse Runtime 包含一組連結庫，這些連結庫會預安裝在每一個無伺服器 Apache Spark 集區上。無法移除或卸載預安裝在基底運行時間上的套件。
不支援 PySpark、Python、Scala/Java、.NET 或 Spark 版本。
Python 工作階段範圍的連結庫只接受具有YML擴展名的檔案。

驗證轉輪檔案

Synapse 無伺服器 Apache Spark 集區是以 Linux 發行版為基礎。直接從 PyPI 下載並安裝 Wheel 檔案時，請務必選取以 Linux 為基礎的版本，並在與 Spark 集區相同的 Python 版本上執行。

重要

您可以在工作階段之間新增或修改自訂套件。不過，您必須等候集區和會話重新啟動，才能看到更新的套件。

檢查相依性衝突

一般而言，Python 相依性解析可能難以管理。為了協助在本機偵錯相依性衝突，您可以根據 Synapse Runtime 建立自己的虛擬環境，並驗證您的變更。

若要重新建立環境並驗證您的更新：

下載範本以在本機重新建立 Synapse 執行時間。範本與實際 Synapse 環境之間可能稍有差異。
使用下列指示建立虛擬環境。此環境可讓您使用指定的連結庫清單來建立隔離的 Python 安裝。
```
conda myenv create -f environment.yml
conda activate myenv
```
使用 pip install -r <provide your req.txt file> 以指定的套件更新虛擬環境。如果安裝造成錯誤，則 Synapse 基底運行時間中預安裝的專案與所提供需求檔案中指定的項目之間可能會發生衝突。您必須解決這些相依性衝突，才能在無伺服器 Apache Spark 集區上取得更新的連結庫。

重要

在一起使用 pip 和 conda 時，可能會發生問題。結合 pip 和 conda 時，最好遵循這些建議的最佳做法。

下一步

檢視預設程式庫：Apache Spark 版本支援

共用方式為