使用無伺服器 Spark Connect 用戶端

Managed Service for Apache Spark Connect 用戶端 (google-cloud-spark-connect) 是以開放原始碼 Apache Spark Connect 用戶端為基礎建構的 Python 用戶端程式庫。本機應用程式、指令碼和筆記本可透過 Spark Connect 通訊協定,在遠端 Managed Service for Apache Spark 工作階段執行 PySpark 工作負載。

相較於直接使用標準 Apache Spark Connect 用戶端,google-cloud-spark-connect 具有下列優點:

  • 自動化工作階段生命週期和驗證:ManagedSparkSession.builder.getOrCreate() 會自動佈建、設定或重複使用遠端 Managed Service for Apache Spark 互動式工作階段,並附加重新整理的 Google Cloud 憑證。只要在批次工作負載的 Python 環境中安裝 google-cloud-spark-connect 套件,以 ManagedSparkSession 編寫的程式碼在提交為 Managed Service for Apache Spark 批次工作負載時,也能不經修改直接執行。
  • 即時進度列和監控連結:在建立工作階段和執行 Spark 工作期間,筆記本和互動式終端機會顯示即時進度列 (追蹤各階段的工作完成情況),並提供 Google Cloud 控制台工作階段詳細資料頁面、Spark UI 和個別 Spark 查詢執行頁面的直接連結。
  • 互動式筆記本額外功能:如果安裝時一併安裝 interactive 額外功能,在 IPython 或 Jupyter 筆記本中匯入 google.cloud.managed_spark_connect 時,系統會自動載入:
    • explore_dataframe() (由 google-colabsqlviz 提供技術支援):以互動方式探索、篩選、排序、匯總 PySpark DataFrame 並製作圖表,不必編寫繪圖程式碼。
    • %%sparksql 和 %sparksql 魔術指令:在筆記本儲存格中執行 Spark SQL 查詢,並以互動方式呈現結果,以及繫結 Python 變數或 DataFrame。
    • %dpip 魔法指令,直接將 PyPI 套件安裝到遠端工作階段的驅動程式和執行器,不必建構自訂容器映像檔。

與開放原始碼 Spark Connect 用戶端一樣,google-cloud-spark-connect 不需要安裝本機 Spark。使用 [client] 額外項目時,系統只會安裝輕量型 pyspark-client 套件,而非完整的 pyspark 發行版本,因此您不需要下載 Spark 或在機器上安裝 Java,即可在 Managed Service for Apache Spark 上執行 PySpark。

本文說明如何安裝、設定及使用用戶端。

事前準備

  1. 確認您具備 Identity and Access Management 角色,其中包含管理互動式工作階段和執行階段設定檔 (工作階段範本) 所需的權限。

  2. 如果您在 Google Cloud以外執行用戶端,請提供驗證憑證。將 GOOGLE_APPLICATION_CREDENTIALS 環境變數設為服務帳戶金鑰檔案的路徑。

安裝或解除安裝用戶端

您可以使用 pip 安裝或解除安裝 google-cloud-spark-connect 套件。

安裝

如果是本機筆記本和開發環境 (例如 VS Code 搭配 Google Cloud Data Agent Kit 或 JupyterLab),請在虛擬環境中透過指令列安裝用戶端:

pip install 'google-cloud-spark-connect[interactive,client]'

這會安裝 google-cloud-spark-connect,並提供兩個選用額外項目:

  • interactive:安裝互動式筆記本擴充功能 (explore_dataframe()、%%sparksql 和 %dpip)。如果是在筆記本以外的獨立 Python 指令碼,則可省略。
  • client:安裝輕量型 pyspark-client 套件,不需要本機 JVM。

在 Colab Enterprise 等代管筆記本環境中 (已預先安裝完整的 pyspark),請在筆記本頂端的專用設定儲存格中,執行 %pip install 和 spark 額外項目,而非 client:

%pip install 'google-cloud-spark-connect[interactive,spark]'

解除安裝

如要解除安裝用戶端,請執行下列指令:

pip uninstall google-cloud-spark-connect pyspark-client

設定用戶端

指定工作階段的專案和區域。您可以使用環境變數或程式碼中的建構工具 API 設定這些值。

環境變數

設定 GOOGLE_CLOUD_PROJECT 和 GOOGLE_CLOUD_REGION 環境變數。

# Google Cloud Configuration for Managed Spark Connect Integration Tests
# Copy this file to .env and fill in your actual values

# ============================================================================
# REQUIRED CONFIGURATION
# ============================================================================

# Your Google Cloud Project ID
GOOGLE_CLOUD_PROJECT="your-project-id"

# Google Cloud Region where Managed Spark sessions will be created
# Integration tests also accept a comma-separated ordered list of fallback regions
# (e.g. "us-east1,us-central1,us-west1") when using a short subnet name.
GOOGLE_CLOUD_REGION="us-central1"

# Path to service account key file (if using SERVICE_ACCOUNT auth)
GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"

# ============================================================================
# AUTHENTICATION CONFIGURATION
# ============================================================================

# Authentication type (SERVICE_ACCOUNT or END_USER_CREDENTIALS). If not set, API default is used.
# MANAGED_SPARK_CONNECT_AUTH_TYPE="SERVICE_ACCOUNT"
# MANAGED_SPARK_CONNECT_AUTH_TYPE="END_USER_CREDENTIALS"

# Service account email for workload authentication (optional)
# MANAGED_SPARK_CONNECT_SERVICE_ACCOUNT="your-service-account@your-project.iam.gserviceaccount.com"

# ============================================================================
# SESSION CONFIGURATION
# ============================================================================

# Session timeout in seconds (how long session stays active)
# MANAGED_SPARK_CONNECT_TTL_SECONDS="3600"

# Session idle timeout in seconds (how long session stays active when idle)
# MANAGED_SPARK_CONNECT_IDLE_TTL_SECONDS="900"

# Automatically terminate session when Python process exits (true/false)
# MANAGED_SPARK_CONNECT_SESSION_TERMINATE_AT_EXIT="false"

# Custom file path for storing active session information
# MANAGED_SPARK_CONNECT_ACTIVE_SESSION_FILE_PATH="/tmp/managed_spark_connect_session"

# ============================================================================
# DATA SOURCE CONFIGURATION
# ============================================================================

# Default data source for Spark SQL (currently only supports "bigquery")
# Only available for Managed Spark runtime version 2.3
# MANAGED_SPARK_CONNECT_DEFAULT_DATASOURCE="bigquery"

# ============================================================================
# ADVANCED CONFIGURATION
# ============================================================================

# Custom Dataproc API endpoint (uncomment if needed)
# GOOGLE_CLOUD_DATAPROC_API_ENDPOINT="your-region-dataproc.googleapis.com"

# Subnet name or URI for Managed Spark Connect (optional; defaults to "default" in tests)
# Accepts a short subnet name (e.g. "default") or full resource URI:
# MANAGED_SPARK_CONNECT_SUBNET="default"
# MANAGED_SPARK_CONNECT_SUBNET="projects/your-project-id/regions/us-central1/subnetworks/your-subnet-name"


Builder API

請使用 .projectId()、.location() 和 .sessionId() 方法。

spark = (
    ManagedSparkSession.builder
    .projectId("my-project")
    .location("us-central1")
    .sessionId("my-spark-session")
    .getOrCreate()
)

啟動 Spark 工作階段

如要啟動 Spark 工作階段,請在 PySpark 應用程式或筆記本中匯入 ManagedSparkSession,然後呼叫 ManagedSparkSession.builder.getOrCreate() API。建議使用 .sessionId() 設定自訂工作階段 ID,這樣一來,在工作階段存留時間 (TTL) 內重新執行筆記本或執行多個筆記本時,就會重複使用有效工作階段,並省去工作階段啟動時間。

  1. 匯入 ManagedSparkSession 類別。在 IPython 或 Jupyter 筆記本中,如果已安裝 interactive 額外項目,匯入 google.cloud.managed_spark_connect 也會自動載入互動式筆記本額外項目 (explore_dataframe()、%%sparksql 和 %dpip)。

  2. 呼叫 .sessionId() 和 .getOrCreate(),啟動或重複使用工作階段。

    from google.cloud.managed_spark_connect import ManagedSparkSession
    spark = ManagedSparkSession.builder.sessionId("my-spark-session").getOrCreate()
    

新工作階段啟動時,用戶端會顯示即時進度列,以及 Google Cloud 控制台中工作階段詳細資料頁面的連結 (在 VS Code 中,連結會在 Data Agent Kit 中開啟工作階段)。如果已有指定 ID 的有效工作階段,用戶端會連線至該工作階段,而不是建立新的工作階段。在這種情況下,用戶端會忽略程式碼中的工作階段設定。如要套用設定變更,請終止現有工作階段 (spark.stop(terminate=True)),或使用其他工作階段 ID。如果指定 ID 的工作階段已終止,用戶端會自動刪除舊工作階段,並建立 ID 相同的新工作階段。工作階段啟用後:

  • 在筆記本儲存格中評估 spark,會顯示工作階段詳細資料頁面和 Spark UI 的直接連結。
  • 執行 Spark 動作 (例如 df.show()、df.collect() 或 df.toPandas()) 時,系統會顯示即時工作進度列,以及 Spark UI 中作業執行頁面的「Spark Query」(Spark 查詢) 連結。

設定 Spark 屬性

如要設定 Spark 屬性,請將一或多個 .config() 方法鏈結至建構工具。

from google.cloud.managed_spark_connect import ManagedSparkSession

spark = (
    ManagedSparkSession.builder
    .sessionId('my-spark-session')
    .config('spark.executor.memory', '48g')
    .config('spark.executor.cores', '8')
    .getOrCreate()
)

使用進階設定

您可以使用建構工具方法,直接設定常見的工作階段設定,例如工作階段 ID、執行階段版本、子網路、服務帳戶、工作階段範本、存留時間 (.ttl()/.ttlSeconds() 和 .idleTtl()/.idleTtlSeconds()) 或標籤:

import datetime
from google.cloud.managed_spark_connect import ManagedSparkSession

spark = (
    ManagedSparkSession.builder
    .projectId('my-project')
    .location('us-central1')
    .sessionId('my-spark-session')
    .runtimeVersion('3.0')
    .subnetwork('SUBNET')
    .idleTtl(datetime.timedelta(minutes=30))
    .getOrCreate()
)

如要完整自訂基礎工作階段資源,請將 google.cloud.dataproc_v1.Session 物件傳遞至 .sessionConfig():

from google.cloud.managed_spark_connect import ManagedSparkSession
from google.cloud.dataproc_v1 import Session

session_config = Session()
session_config.environment_config.execution_config.subnetwork_uri = 'SUBNET'
session_config.runtime_config.version = '3.0'

spark = (
    ManagedSparkSession.builder
    .projectId('my-project')
    .location('us-central1')
    .sessionId('my-spark-session')
    .sessionConfig(session_config)
    .getOrCreate()
)

重複使用具名工作階段

使用 .sessionId() 設定自訂工作階段 ID,即可在工作階段存留時間內,跨多個筆記本或核心重新啟動作業,重複使用單一 Spark 工作階段,進而消除工作階段啟動延遲並降低成本。

  1. 在第一個筆記本中,建立具有自訂 ID 的工作階段。

    from google.cloud.managed_spark_connect import ManagedSparkSession
    
    session_id = 'my-ml-pipeline-session'
    spark = ManagedSparkSession.builder.sessionId(session_id).getOrCreate()
    df = spark.createDataFrame([(1, 'data')], ['id', 'value'])
    df.show()
    
  2. 在另一個筆記本中 (或重新啟動核心後),指定相同的工作階段 ID,即可重複使用工作階段。

    from google.cloud.managed_spark_connect import ManagedSparkSession
    
    session_id = 'my-ml-pipeline-session'
    spark = ManagedSparkSession.builder.sessionId(session_id).getOrCreate()
    df = spark.createDataFrame([(2, 'more-data')], ['id', 'value'])
    df.show()
    

工作階段 ID 必須介於 4 至 63 個半形字元之間,開頭須為小寫英文字母,而且只能使用小寫英文字母、數字和連字號。ID 結尾不得為連字號。具名工作階段會持續存在,直到明確終止或達到設定的存留時間為止。如果指定 ID 的工作階段已處於 TERMINATED、TERMINATING 或 FAILED 狀態,用戶端會發出警告、刪除舊工作階段,並建立具有相同 ID 的新工作階段 (刪除舊工作階段會從 Managed Service for Apache Spark 移除先前的中繼資料和 Spark UI 記錄,但記錄仍會保留在 Cloud Logging 中)。

如果已有指定 ID 的有效工作階段,用戶端會連線至該工作階段,並忽略程式碼中的工作階段設定。如要套用設定變更,請終止現有工作階段,或使用其他工作階段 ID。

如要終止具名工作階段,請呼叫 spark.stop(terminate=True)。呼叫 spark.stop() 時不帶引數會中斷用戶端連線,但會保留已命名的工作階段。如果建立工作階段時未指定 .sessionId(),spark.stop() 會終止該工作階段。

使用 Spark SQL 魔術指令

interactive 額外項目包含 %%sparksql 儲存格魔術指令和 %sparksql 行魔術指令,可在 Jupyter 筆記本中執行 Spark SQL 查詢,並使用 google-colabsqlviz (explore_dataframe() 使用的相同視覺化小工具) 算繪互動式表格和圖表。

使用 interactive 額外功能安裝 google-cloud-spark-connect,並在筆記本中匯入 google.cloud.managed_spark_connect 時,系統會自動載入魔術擴充功能。

  1. 選用:如果尚未匯入 google.cloud.managed_spark_connect,請明確載入 magic 擴充功能。

    %load_ext google.cloud.managed_spark_magics
    
  2. 選用:調整預設設定。

    %config SparkSql.limit=20
    
  3. 使用 %%sparksql 儲存格魔術指令 (會轉譯互動式資料表,並預設將完整 DataFrame 儲存在 _df 中) 或 %sparksql 行魔術指令 (會隱藏資料表顯示,並直接傳回 DataFrame) 執行 SQL 查詢:

    %%sparksql
    SELECT * FROM your_table
    
    df = %sparksql SELECT * FROM your_table
    
  4. 選用:將 Python 變數和 DataFrame 傳遞至查詢。輸入的 SQL 常值可與 :name 繫結,資料表或資料欄 ID 可與 IDENTIFIER(:name) 繫結,筆記本命名空間中的 DataFrame 則可與 {df} 繫結:

    min_id = 10
    df = spark.createDataFrame([(5, 'a'), (15, 'b')], ['id', 'val'])
    
    %%sparksql
    SELECT * FROM {df} WHERE id >= :min_id
    

如要使用進階選項,請在 %%sparksql 指令中新增旗標。例如,如要快取結果並建立檢視表,請執行下列指令:

%%sparksql --cache --view result_view df
SELECT * FROM your_table WHERE condition = true

可用選項如下:

  • --cache 或 -c:快取 DataFrame。
  • --eager 或 -e:使用 localCheckpoint(eager=True) 立即計算結果。
  • --view VIEW 或 -v VIEW:建立臨時檢視畫面。
  • --limit N 或 -l N:覆寫預設的資料列顯示限制 (僅限儲存格魔術指令)。
  • --display MODE 或 -d MODE:設定顯示模式 (colabsqlviz 或 html;僅限儲存格魔術指令)。
  • --quiet 或 -q:不顯示表格。
  • --explain [MODE]:列印查詢計畫,而非顯示結果。
  • --session NAME 或 -s NAME:針對變數 NAME 中的 SparkSession 執行。
  • variable_name:將結果儲存在變數中 (僅限儲存格魔術指令,預設為 _df)。

在遠端工作階段安裝 PyPI 套件

如要在 PySpark user-defined function (UDF) 中使用第三方 Python 套件,而不建構自訂容器映像檔或重新啟動工作階段,可以直接在遠端工作階段的驅動程式和執行器上安裝 PyPI 套件:

Notebook 魔法

在具有有效 ManagedSparkSession 的互動式筆記本中,使用 %dpip magic 指令 (安裝 interactive 額外項目時,會自動載入 google.cloud.managed_spark_connect):

%dpip install scipy

%dpip 只會在遠端工作階段安裝套件。如要在 Spark 以外的本機程式碼中匯入套件,請在本機 Python 環境中安裝該套件。

Python API

在指令碼或筆記本中,將 pypi=True 傳遞至 spark.addArtifacts():

spark.addArtifacts("scipy", pypi=True)

後續步驟