Freigeben über

Installieren von Databricks Connect für Python

  • Artikel

Hinweis

Dieser Artikel behandelt Databricks Connect für Databricks Runtime Version 13.3 LTS und höher.

In diesem Artikel wird beschrieben, wie Sie Databricks Connect für Python installieren. Weitere Informationen finden Sie unter Was ist Databricks Connect?. Die Scala-Version dieses Artikels finden Sie unter Installieren von Databricks Connect für Scala.

Anforderungen

Um Databricks Connect für Python zu installieren, müssen die folgenden Anforderungen erfüllt sein:

  • Wenn Sie eine Verbindung mit serverlosem Computeherstellen, muss Ihr Arbeitsbereich die Anforderungen für den serverlosen Compute erfüllen.

    Hinweis

    Serverloses Computing wird in Databricks Connect, Version 15.1 und höher, unterstützt. Darüber hinaus sind Databricks Connect-Versionen bei oder niedriger als die Databricks Runtime-Version auf serverlosen Servern vollständig kompatibel. (Siehe Versionshinweise). Informationen zum Überprüfen, ob die Databricks Connect-Version mit serverlosem Computing kompatibel ist, finden Sie unter Validieren Sie die Verbindung zu Databricks.

  • Wenn Sie eine Verbindung mit einem Clusterherstellen, muss Ihr Zielcluster die Anforderungen an die Clusterkonfiguration erfüllen, die Datenbricks Runtime-Versionsanforderungen enthält.

  • Sie müssen Python 3 auf Ihrem Entwicklungscomputer installiert haben, und die Nebenversion von Python auf Ihrem Entwicklungscomputer muss die Versionsanforderungen in der nachstehenden Tabelle erfüllen.

    Computetyp Databricks Connect-Version Kompatible Python-Version
    Serverlos 15.1 und höher 3.11
    Cluster 15.1 und höher 3.11
    Cluster 13.3 LTS bis 14.3 LTS 3.10

  • Wenn Sie PySpark UDFs verwenden möchten, muss die installierte Nebenversion Ihres Entwicklungscomputers mit der Nebenversion von Python übereinstimmen, die in der Databricks Runtime enthalten ist, die auf dem Cluster oder serverlosen Compute installiert ist. Informationen zur Python-Nebenversion Ihres Clusters finden Sie im Abschnitt Systemumgebung der Databricks Runtime-Versionshinweise zu Ihrem Cluster oder serverlosen Compute. Siehe Versionshinweise zu Databricks Runtime- und Kompatibilität und den Serverlosen Compute-Versionshinweisen.

Aktivieren einer virtuellen Python-Umgebung

Databricks empfiehlt dringend, eine virtuelle Python-Umgebung für jede Python-Version zu aktivieren, die Sie mit Databricks Connect verwenden. Mithilfe virtueller Python-Umgebungen kann sichergestellt werden, dass Sie die richtigen Versionen von Python und Databricks Connect zusammen verwenden. Weitere Informationen zu diesen Tools und zur Aktivierung finden Sie unter venv oder Poetry.

Installieren Sie den Databricks Connect-Client.

In diesem Abschnitt wird beschrieben, wie Sie den Databricks Connect-Client mit venv oder Poetry installieren.

Hinweis

Wenn Sie die Databricks-Erweiterung für Visual Studio Code bereits installiert haben, müssen Sie diese Setupanweisungen nicht befolgen, da die Databricks-Erweiterung für Visual Studio Code bereits integrierte Unterstützung für Databricks Connect für Databricks Runtime 13.3 LTS und höher verfügt. Gehen Sie zu Debugcode mithilfe von Databricks Connect für die Databricks-Erweiterung für Visual Studio Code.

Installieren des Databricks Connect-Clients mit venv

  1. Wenn Ihre virtuelle Umgebung aktiviert ist, deinstallieren Sie PySpark, falls es bereits installiert ist, indem Sie den uninstall-Befehl ausführen. Dieser Schritt ist erforderlich, da das databricks-connect-Paket mit PySpark in Konflikt steht. Weitere Informationen finden Sie unter In Konflikt stehende PySpark-Installationen. Um zu überprüfen, ob PySpark bereits installiert ist, führen Sie den show-Befehl aus.

    # Is PySpark already installed?
pip3 show pyspark

# Uninstall PySpark
pip3 uninstall pyspark

  2. Wenn Ihre virtuelle Umgebung immer noch aktiviert ist, installieren Sie den Databricks Connect-Client, indem Sie den install-Befehl ausführen. Verwenden Sie die --upgrade-Option, um für alle vorhandenen Clientinstallationen ein Upgrade auf die angegebene Version durchzuführen.

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

    Hinweis

    Databricks empfiehlt, die Notation „Punkt-Sternchen“ anzufügen, um databricks-connect==X.Y.* anstelle von databricks-connect=X.Y anzugeben, um sicherzustellen, dass das neueste Paket installiert ist. Dies ist zwar keine Anforderung, aber es hilft sicherzustellen, dass Sie die aktuellen unterstützten Features für diesen Cluster verwenden können.

Fahren Sie mit Konfigurieren von Verbindungseigenschaften fort.

Installieren des Databricks Connect-Clients mit Poetry

  1. Wenn Ihre virtuelle Umgebung aktiviert ist, deinstallieren Sie PySpark, falls es bereits installiert ist, indem Sie den remove-Befehl ausführen. Dieser Schritt ist erforderlich, da das databricks-connect-Paket mit PySpark in Konflikt steht. Weitere Informationen finden Sie unter In Konflikt stehende PySpark-Installationen. Um zu überprüfen, ob PySpark bereits installiert ist, führen Sie den show-Befehl aus.

    # Is PySpark already installed?
poetry show pyspark

# Uninstall PySpark
poetry remove pyspark

  2. Wenn Ihre virtuelle Umgebung immer noch aktiviert ist, installieren Sie den Databricks Connect-Client, indem Sie den add-Befehl ausführen.

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

    Hinweis

    Databricks empfiehlt, die Notation „@-Tilde“ zu verwenden, um databricks-connect@~15.4 anstelle von databricks-connect==15.4 anzugeben und sicherzustellen, dass das neueste Paket installiert ist. Dies ist zwar keine Anforderung, aber es hilft sicherzustellen, dass Sie die aktuellen unterstützten Features für diesen Cluster verwenden können.

Verbindungseigenschaften konfigurieren

In diesem Abschnitt konfigurieren Sie Eigenschaften, um eine Verbindung zwischen Databricks Connect und Ihrem Azure Databricks-Cluster oder serverlosen Compute herzustellen, was Folgendes umfasst:

Hinweis

Konfigurieren einer Verbindung mit einem Cluster

Um eine Verbindung mit einem Cluster zu konfigurieren, benötigen Sie die ID Ihres Clusters. Sie können die Cluster-ID über die URL abrufen. Weitere Informationen finden Sie unter Cluster-URL und -ID.

Sie können die Verbindung mit Ihrem Cluster auf eine der folgenden Arten konfigurieren. Databricks Connect sucht in der folgenden Reihenfolge nach Konfigurationseigenschaften und verwendet die erste gefundene Konfiguration. Erweiterte Konfigurationsinformationen finden Sie unter Erweiterte Verwendung von Databricks Connect for Python.

  1. Die Remote()-Methode der DatabricksSession-Klasse.
  2. Ein Databricks-Konfigurationsprofil
  3. Die Umgebungsvariable DATABRICKS_CONFIG_PROFILE
  4. Eine Umgebungsvariable für jede Verbindungseigenschaft
  5. Ein Azure Databricks-Konfigurationsprofil mit dem Namen DEFAULT

Die remote()-Methode der DatabricksSession-Klasse

Geben Sie für diese Option, die nur für die Authentifizierung mit persönlichem Zugriffstoken in Azure Databricks gilt, den Instanzname des Arbeitsbereichs, das persönliche Zugriffstoken in Azure Databricks und die ID des Clusters an.

Sie können die DatabricksSession-Klasse auf verschiedene Arten initialisieren, und zwar wie folgt:

  • Legen Sie die Felder host, token und cluster_id in DatabricksSession.builder.remote() fest.
  • Verwenden Sie die Config-Klasse des Databricks SDK.
  • Geben Sie ein Databricks-Konfigurationsprofil zusammen mit dem cluster_id-Feld an.
  • Legen Sie die Spark Connect-Verbindungszeichenfolge in DatabricksSession.builder.remote() fest.

Anstatt diese Verbindungseigenschaften in Ihrem Code anzugeben, empfiehlt Databricks, Eigenschaften über Umgebungsvariablen oder Konfigurationsdateien zu konfigurieren, wie in diesem Abschnitt beschrieben. In den folgenden Codebeispielen wird davon ausgegangen, dass Sie eine Implementierung der vorgeschlagenen retrieve_*-Funktionen bereitstellen, um die erforderlichen Eigenschaften vom Benutzer oder aus einem anderen Konfigurationsspeicher abzurufen, z. B. dem Azure KeyVault.

Der Code für jeden dieser Ansätze lautet wie folgt:

# 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()

Ein Azure Databricks-Konfigurationsprofil

Erstellen oder identifizieren Sie für diese Option ein Azure Databricks-Konfigurationsprofil mit dem Feld cluster_id und allen anderen Felder, die für den Databricks-Authentifizierungstyp erforderlich sind, den Sie verwenden möchten.

Die folgenden Konfigurationsprofilfelder sind für die einzelnen Authentifizierungstypen erforderlich:

Legen Sie dann den Namen dieses Konfigurationsprofils über die Config-Klasse fest.

Sie können cluster_id auf verschiedene Arten wie folgt angeben:

  • Fügen Sie das cluster_id-Feld in Ihr Konfigurationsprofil ein, und geben Sie dann einfach den Namen des Konfigurationsprofils an.
  • Geben Sie den Konfigurationsprofilnamen zusammen mit dem cluster_id-Feld an.

Wenn Sie die DATABRICKS_CLUSTER_ID-Umgebungsvariable bereits mit der Cluster-ID festgelegt haben, müssen Sie cluster_id nicht ebenfalls angeben.

Der Code für jeden dieser Ansätze lautet wie folgt:

# 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()

Die DATABRICKS_CONFIG_PROFILE-Umgebungsvariable

Erstellen oder identifizieren Sie für diese Option ein Azure Databricks-Konfigurationsprofil mit dem Feld cluster_id und allen anderen Felder, die für den Databricks-Authentifizierungstyp erforderlich sind, den Sie verwenden möchten.

Wenn Sie die DATABRICKS_CLUSTER_ID-Umgebungsvariable bereits mit der Cluster-ID festgelegt haben, müssen Sie cluster_id nicht ebenfalls angeben.

Die folgenden Konfigurationsprofilfelder sind für die einzelnen Authentifizierungstypen erforderlich:

Legen Sie die DATABRICKS_CONFIG_PROFILE-Umgebungsvariable auf den Namen dieses Konfigurationsprofils fest. Initialisieren Sie dann die DatabricksSession-Klasse wie folgt:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

Eine Umgebungsvariable für jede Verbindungseigenschaft

Legen Sie für diese Option die DATABRICKS_CLUSTER_ID-Umgebungsvariable und alle anderen Umgebungsvariablen fest, die für den Databricks-Authentifizierungstyp erforderlich sind, den Sie verwenden möchten.

Die folgenden Umgebungsvariablen sind für die einzelnen Authentifizierungstypen erforderlich:

Initialisieren Sie dann die DatabricksSession-Klasse wie folgt:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

Ein Azure Databricks-Konfigurationsprofil mit dem Namen DEFAULT

Erstellen oder identifizieren Sie für diese Option ein Azure Databricks-Konfigurationsprofil mit dem Feld cluster_id und allen anderen Felder, die für den Databricks-Authentifizierungstyp erforderlich sind, den Sie verwenden möchten.

Wenn Sie die DATABRICKS_CLUSTER_ID-Umgebungsvariable bereits mit der Cluster-ID festgelegt haben, müssen Sie cluster_id nicht ebenfalls angeben.

Die folgenden Konfigurationsprofilfelder sind für die einzelnen Authentifizierungstypen erforderlich:

Benennen Sie dieses Konfigurationsprofil DEFAULT.

Initialisieren Sie dann die DatabricksSession-Klasse wie folgt:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

Konfigurieren einer Verbindung mit serverlosem Compute

Wichtig

Dieses Feature befindet sich in der Public Preview.

Databricks Connect unterstützt die Verbindung mit serverlosem Compute. Um dieses Feature zu verwenden, müssen die Anforderungen für die Verbindung mit serverlosen Servern erfüllt sein. Siehe Anforderungen.

Wichtig

Für diese Funktion gelten folgende Einschränkungen:

Sie können eine Verbindung mit serverlosem Compute auf eine der folgenden Arten konfigurieren:

  • Legen Sie stattdessen die lokale Umgebungsvariable DATABRICKS_SERVERLESS_COMPUTE_ID auf auto fest. Wenn diese Umgebungsvariable festgelegt ist, ignoriert Databricks Connect die cluster_id.

  • Legen Sie in einem lokalen Databricks-Konfigurationsprofil serverless_compute_id = auto fest, und verweisen Sie dann auf dieses Profil aus Ihrem Databricks Connect Python-Code.

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

  • Alternativ können Sie einfach Ihren Databricks Connect Python-Code wie folgt aktualisieren:

    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()

Hinweis

Die serverlose Computesitzung ist nach 10 Minuten Inaktivität nicht mehr vorhanden. Danach muss eine neue Spark-Sitzung erstellt werden, um eine Verbindung mit serverlosem Compute herzustellen. Dies kann mit spark = DatabricksSession.builder.serverless(True).getOrCreate() erreicht werden.

Überprüfen der Verbindung mit Databricks

Um Ihre Umgebung zu überprüfen, werden Standardanmeldeinformationen und die Verbindung zur Berechnung ordnungsgemäß für Databricks Connect eingerichtet, führen Sie den databricks-connect test-Befehl aus, der mit einem Nicht-Null-Exitcode fehlschlägt und eine entsprechende Fehlermeldung angezeigt wird, wenn eine Inkompatibilität im Setup erkannt wird.

databricks-connect test

Sie können Ihre Umgebung auch in Ihrem Python-Code überprüfen, indem Sie validateSession() verwenden:

DatabricksSession.builder.validateSession(True).getOrCreate()