Bagikan melalui

Menginstal Databricks Connect untuk Python

  • Artikel

Catatan

Artikel ini membahas Databricks Connect untuk Databricks Runtime 13.3 LTS ke atas.

Artikel ini menjelaskan cara menginstal Databricks Connect untuk Python. Lihat Apa itu Databricks Connect?. Untuk versi Scala artikel ini, lihat Menginstal Databricks Connect untuk Scala.

Persyaratan

Untuk menginstal Databricks Connect untuk Python, persyaratan berikut harus dipenuhi:

  • Jika Anda tersambung ke komputasi tanpa server, ruang kerja Anda harus memenuhi persyaratan untuk komputasi tanpa server.

  • Jika Anda terhubung ke kluster, kluster target Anda harus memenuhi persyaratan konfigurasi kluster, yang mencakup persyaratan versi Databricks Runtime.

  • Anda harus menginstal Python 3 pada komputer pengembangan Anda, dan versi minor Python yang diinstal pada mesin pengembangan Anda harus memenuhi persyaratan versi dalam tabel di bawah ini.

    Versi Databricks Connect Tipe komputasi Versi Python yang kompatibel
    15,1 Kluster 3.11
    15,1 Tanpa server 3.10
    13.3 LTS hingga 14.3 LTS Kluster 3.10

  • Jika Anda ingin menggunakan PySpark UDF, Python versi minor yang diinstal mesin pengembangan Anda harus cocok dengan versi minor Python yang disertakan dengan Databricks Runtime yang diinstal pada kluster atau komputasi tanpa server. Untuk menemukan versi Python minor kluster Anda, lihat bagian Lingkungan sistem dari catatan rilis Databricks Runtime untuk kluster atau komputasi tanpa server Anda. Lihat Versi dan kompatibilitas catatan rilis Databricks Runtime serta Catatan rilis komputasi tanpa server.

Mengaktifkan lingkungan virtual Python

Databricks sangat menyarankan agar Anda mengaktifkan lingkungan virtual Python untuk setiap versi Python yang Anda gunakan dengan Databricks Connect. Lingkungan virtual Python membantu memastikan bahwa Anda menggunakan versi Python dan Databricks Connect yang benar bersama-sama. Untuk informasi selengkapnya tentang alat-alat ini dan cara mengaktifkannya, lihat venv atau Puisi.

Menginstal klien Databricks Connect

Bagian ini menjelaskan cara menginstal klien Databricks Connect dengan venv atau Poetry.

Catatan

Jika Anda sudah menginstal ekstensi Databricks untuk Visual Studio Code, Anda tidak perlu mengikuti instruksi penyiapan ini, karena ekstensi Databricks untuk Visual Studio Code sudah memiliki dukungan bawaan untuk Databricks Connect untuk Databricks Runtime 13.3 LTS ke atas. Lewati ke Kode debug dengan menggunakan Databricks Connect untuk ekstensi Databricks untuk Visual Studio Code.

Menginstal klien Databricks Connect dengan venv

  1. Dengan mengaktifkan lingkungan virtual Anda, hapus instalan PySpark, jika sudah diinstal, dengan menjalankan uninstall perintah . Ini diperlukan karena paket bertentangan databricks-connect dengan PySpark. Untuk detailnya, lihat Penginstalan PySpark yang Saling Bertentangan. Untuk memeriksa apakah PySpark sudah diinstal, jalankan show perintah .

    # Is PySpark already installed?
pip3 show pyspark

# Uninstall PySpark
pip3 uninstall pyspark

  2. Dengan lingkungan virtual Anda masih diaktifkan, instal klien Databricks Connect dengan menjalankan install perintah . --upgrade Gunakan opsi untuk meningkatkan penginstalan klien yang ada ke versi yang ditentukan.

    pip3 install --upgrade "databricks-connect==14.3.*"  # Or X.Y.* to match your cluster version.

    Catatan

    Databricks merekomendasikan agar Anda menambahkan notasi "tanda bintang titik" untuk menentukan databricks-connect==X.Y.* alih-alih databricks-connect=X.Y, untuk memastikan bahwa paket terbaru diinstal. Meskipun ini bukan persyaratan, ini membantu memastikan bahwa Anda dapat menggunakan fitur terbaru yang didukung untuk kluster tersebut.

Lewati ke depan untuk Mengonfigurasi properti koneksi.

Menginstal klien Databricks Connect dengan Puisi

  1. Dengan mengaktifkan lingkungan virtual Anda, hapus instalan PySpark, jika sudah diinstal, dengan menjalankan remove perintah . Ini diperlukan karena paket bertentangan databricks-connect dengan PySpark. Untuk detailnya, lihat Penginstalan PySpark yang Saling Bertentangan. Untuk memeriksa apakah PySpark sudah diinstal, jalankan show perintah .

    # Is PySpark already installed?
poetry show pyspark

# Uninstall PySpark
poetry remove pyspark

  2. Dengan lingkungan virtual Anda masih diaktifkan, instal klien Databricks Connect dengan menjalankan add perintah .

    poetry add databricks-connect@~14.3  # Or X.Y to match your cluster version.

    Catatan

    Databricks merekomendasikan agar Anda menggunakan notasi "at-tilde" untuk menentukan databricks-connect@~14.3 alih-alih databricks-connect==14.3, untuk memastikan bahwa paket terbaru diinstal. Meskipun ini bukan persyaratan, ini membantu memastikan bahwa Anda dapat menggunakan fitur terbaru yang didukung untuk kluster tersebut.

Mengonfigurasi properti koneksi

Di bagian ini, Anda mengonfigurasi properti untuk membuat koneksi antara Databricks Connect dan kluster Azure Databricks atau komputasi tanpa server, yang mencakup hal berikut:

Catatan

Mengonfigurasi koneksi ke kluster

Untuk mengonfigurasi koneksi ke kluster, Anda akan memerlukan ID kluster Anda. Anda bisa mendapatkan ID kluster dari URL. Lihat URL dan ID kluster.

Anda dapat mengonfigurasi koneksi ke kluster Anda dengan salah satu cara berikut. Databricks Connect mencari properti konfigurasi dalam urutan berikut, dan menggunakan konfigurasi pertama yang ditemukannya. Untuk informasi konfigurasi tingkat lanjut, lihat Penggunaan tingkat lanjut Databricks Connect untuk Python.

  1. Metode remote() kelas DatabricksSession.
  2. Profil konfigurasi Databricks
  3. Variabel lingkungan DATABRICKS_CONFIG_PROFILE
  4. Variabel lingkungan untuk setiap properti konfigurasi
  5. Profil konfigurasi Databricks bernama DEFAULT

Metode DatabricksSession kelas remote()

Untuk opsi ini, yang hanya berlaku untuk autentikasi token akses pribadi Azure Databricks, tentukan nama instans ruang kerja, token akses pribadi Azure Databricks, dan ID kluster.

Anda dapat menginisialisasi kelas dengan DatabricksSession beberapa cara, sebagai berikut:

  • Atur hostbidang , token, dan cluster_id di DatabricksSession.builder.remote().
  • Gunakan kelas Databricks SDK Config .
  • Tentukan profil konfigurasi Databricks bersama dengan cluster_id bidang .
  • Atur string koneksi Spark Connect di DatabricksSession.builder.remote().

Alih-alih menentukan properti koneksi ini dalam kode Anda, Databricks merekomendasikan untuk mengonfigurasi properti melalui variabel lingkungan atau file konfigurasi, seperti yang dijelaskan di seluruh bagian ini. Contoh kode berikut mengasumsikan bahwa Anda menyediakan beberapa implementasi fungsi yang diusulkan retrieve_* untuk mendapatkan properti yang diperlukan dari pengguna atau dari beberapa penyimpanan konfigurasi lainnya, seperti Azure KeyVault.

Kode untuk masing-masing pendekatan ini adalah sebagai berikut:

# Set the host, token, and cluster_id fields in DatabricksSession.builder.remote.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.remote(
   host       = f"https://{retrieve_workspace_instance_name()}",
   token      = retrieve_token(),
   cluster_id = retrieve_cluster_id()
).getOrCreate()

# Use the Databricks SDK's Config class.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config

config = Config(
   host       = f"https://{retrieve_workspace_instance_name()}",
   token      = retrieve_token(),
   cluster_id = retrieve_cluster_id()
)

spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()

# Specify a Databricks configuration profile along with the `cluster_id` field.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config

config = Config(
   profile    = "<profile-name>",
   cluster_id = retrieve_cluster_id()
)

spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()

Profil konfigurasi Databricks

Untuk opsi ini, buat atau identifikasi profil konfigurasi Azure Databricks yang berisi bidang cluster_id dan bidang lain yang diperlukan untuk jenis autentikasi Databricks yang ingin Anda gunakan.

Bidang profil konfigurasi yang diperlukan untuk setiap jenis autentikasi adalah sebagai berikut:

  • Untuk autentikasi token akses pribadi Azure Databricks: host dan token.
  • Untuk autentikasi komputer-ke-mesin (M2M) OAuth (jika didukung): host, , client_iddan client_secret.
  • Untuk autentikasi pengguna-ke-mesin (U2M) OAuth (jika didukung): host.
  • Untuk autentikasi hostperwakilan layanan Microsoft Entra ID (sebelumnya Azure Active Directory): , , azure_tenant_idazure_client_id, azure_client_secret, dan mungkin azure_workspace_resource_id.
  • Untuk autentikasi Azure CLI: host.
  • Untuk autentikasi identitas terkelola Azure (jika didukung): host, , azure_use_msiazure_client_id, dan mungkin azure_workspace_resource_id.

Kemudian atur nama profil konfigurasi ini melalui Config kelas .

Anda dapat menentukan cluster_id dengan beberapa cara, sebagai berikut:

  • Sertakan cluster_id bidang di profil konfigurasi Anda, lalu cukup tentukan nama profil konfigurasi.
  • Tentukan nama profil konfigurasi bersama dengan cluster_id bidang .

Jika Anda telah mengatur DATABRICKS_CLUSTER_ID variabel lingkungan dengan ID kluster, Anda tidak perlu menentukan cluster_id.

Kode untuk masing-masing pendekatan ini adalah sebagai berikut:

# Include the cluster_id field in your configuration profile, and then
# just specify the configuration profile's name:
from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.profile("<profile-name>").getOrCreate()

# Specify the configuration profile name along with the cluster_id field.
# In this example, retrieve_cluster_id() assumes some custom implementation that
# you provide to get the cluster ID from the user or from some other
# configuration store:
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config

config = Config(
   profile    = "<profile-name>",
   cluster_id = retrieve_cluster_id()
)

spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()

Variabel DATABRICKS_CONFIG_PROFILE lingkungan

Untuk opsi ini, buat atau identifikasi profil konfigurasi Azure Databricks yang berisi bidang cluster_id dan bidang lain yang diperlukan untuk jenis autentikasi Databricks yang ingin Anda gunakan.

Jika Anda telah mengatur DATABRICKS_CLUSTER_ID variabel lingkungan dengan ID kluster, Anda tidak perlu menentukan cluster_id.

Bidang profil konfigurasi yang diperlukan untuk setiap jenis autentikasi adalah sebagai berikut:

  • Untuk autentikasi token akses pribadi Azure Databricks: host dan token.
  • Untuk autentikasi komputer-ke-mesin (M2M) OAuth (jika didukung): host, , client_iddan client_secret.
  • Untuk autentikasi pengguna-ke-mesin (U2M) OAuth (jika didukung): host.
  • Untuk autentikasi hostperwakilan layanan Microsoft Entra ID (sebelumnya Azure Active Directory): , , azure_tenant_idazure_client_id, azure_client_secret, dan mungkin azure_workspace_resource_id.
  • Untuk autentikasi Azure CLI: host.
  • Untuk autentikasi identitas terkelola Azure (jika didukung): host, , azure_use_msiazure_client_id, dan mungkin azure_workspace_resource_id.

Atur DATABRICKS_CONFIG_PROFILE variabel lingkungan ke nama profil konfigurasi ini. Kemudian inisialisasi DatabricksSession kelas sebagai berikut:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

Variabel lingkungan untuk setiap properti konfigurasi

Untuk opsi ini, atur DATABRICKS_CLUSTER_ID variabel lingkungan dan variabel lingkungan lain yang diperlukan untuk jenis autentikasi Databricks yang ingin Anda gunakan.

Variabel lingkungan yang diperlukan untuk setiap jenis autentikasi adalah sebagai berikut:

  • Untuk autentikasi token akses pribadi Azure Databricks: DATABRICKS_HOST dan DATABRICKS_TOKEN.
  • Untuk autentikasi komputer-ke-mesin (M2M) OAuth (jika didukung): DATABRICKS_HOST, , DATABRICKS_CLIENT_IDdan DATABRICKS_CLIENT_SECRET.
  • Untuk autentikasi pengguna-ke-mesin (U2M) OAuth (jika didukung): DATABRICKS_HOST.
  • Untuk autentikasi DATABRICKS_HOSTperwakilan layanan Microsoft Entra ID (sebelumnya Azure Active Directory): , , ARM_TENANT_IDARM_CLIENT_ID, ARM_CLIENT_SECRET, dan mungkin DATABRICKS_AZURE_RESOURCE_ID.
  • Untuk autentikasi Azure CLI: DATABRICKS_HOST.
  • Untuk autentikasi identitas terkelola Azure (jika didukung): DATABRICKS_HOST, , ARM_USE_MSIARM_CLIENT_ID, dan mungkin DATABRICKS_AZURE_RESOURCE_ID.

Kemudian inisialisasi DatabricksSession kelas sebagai berikut:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

Profil konfigurasi Databricks bernama DEFAULT

Untuk opsi ini, buat atau identifikasi profil konfigurasi Azure Databricks yang berisi bidang cluster_id dan bidang lain yang diperlukan untuk jenis autentikasi Databricks yang ingin Anda gunakan.

Jika Anda telah mengatur DATABRICKS_CLUSTER_ID variabel lingkungan dengan ID kluster, Anda tidak perlu menentukan cluster_id.

Bidang profil konfigurasi yang diperlukan untuk setiap jenis autentikasi adalah sebagai berikut:

  • Untuk autentikasi token akses pribadi Azure Databricks: host dan token.
  • Untuk autentikasi komputer-ke-mesin (M2M) OAuth (jika didukung): host, , client_iddan client_secret.
  • Untuk autentikasi pengguna-ke-mesin (U2M) OAuth (jika didukung): host.
  • Untuk autentikasi hostperwakilan layanan Microsoft Entra ID (sebelumnya Azure Active Directory): , , azure_tenant_idazure_client_id, azure_client_secret, dan mungkin azure_workspace_resource_id.
  • Untuk autentikasi Azure CLI: host.
  • Untuk autentikasi identitas terkelola Azure (jika didukung): host, , azure_use_msiazure_client_id, dan mungkin azure_workspace_resource_id.

Beri nama profil DEFAULTkonfigurasi ini .

Kemudian inisialisasi DatabricksSession kelas sebagai berikut:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

Mengonfigurasi koneksi ke komputasi tanpa server

Penting

Fitur ini ada di Pratinjau Publik.

Databricks Connect mendukung penyambungan ke komputasi tanpa server. Untuk menggunakan fitur ini, persyaratan untuk menyambungkan ke tanpa server harus dipenuhi. Lihat Persyaratan.

Penting

Fitur ini memiliki batasan berikut ini:

Anda dapat mengonfigurasi koneksi ke komputasi tanpa server dengan salah satu cara berikut:

  • Atur variabel DATABRICKS_SERVERLESS_COMPUTE_ID lingkungan lokal ke auto. Jika variabel lingkungan ini diatur, Databricks Connect mengabaikan cluster_id.

  • Di profil konfigurasi Databricks lokal, atur serverless_compute_id = auto, lalu referensikan profil tersebut dari kode Databricks Connect Python Anda.

    [DEFAULT]
host = https://my-workspace.cloud.databricks.com/
serverless_compute_id = auto
token = dapi123...

  • Atau, cukup perbarui kode Databricks Connect Python Anda sebagai berikut:

    from databricks.connect import DatabricksSession as SparkSession

spark = DatabricksSession.builder.serverless(True).getOrCreate()

    from databricks.connect import DatabricksSession as SparkSession

spark DatabricksSession.builder.remote(serverless=True).getOrCreate()

Catatan

Waktu sesi komputasi tanpa server habis setelah 10 menit tidak aktif. Setelah ini, proses Python perlu dimulai ulang di sisi klien untuk membuat sesi Spark baru untuk terhubung ke komputasi tanpa server.

Memvalidasi koneksi ke Databricks

Untuk memvalidasi lingkungan Anda, kredensial default, dan koneksi ke komputasi disiapkan dengan benar untuk Databricks Connect, jalankan databricks-connect test perintah, yang gagal dengan kode keluar non-nol dan pesan kesalahan yang sesuai saat mendeteksi ketidaksesuaian dalam penyiapan.

databricks-connect test

Atau, Anda dapat menggunakan pyspark shell yang disertakan sebagai bagian dari Databricks Connect for Python, dan menjalankan perintah sederhana. Untuk detail selengkapnya tentang shell PySpark, lihat shell Pyspark.