Freigeben über

Installieren von Databricks Connect für Python

  • Artikel

Hinweis

In diesem Artikel wird Databricks Connect für Databricks Runtime 13.0 und höher behandelt.

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

  • Ihr Azure Databricks-Zielarbeitsbereich und -Zielcluster müssen die Anforderungen für die Clusterkonfiguration für Databricks Connect erfüllen.

  • Sie müssen Python 3 auf Ihrem Entwicklungscomputer installieren, und die Nebenversion Ihrer Python-Clientinstallation muss mit der Python-Nebenversion Ihres Azure Databricks-Clusters identisch sein. Informationen zur Python-Nebenversion Ihres Clusters finden Sie im Abschnitt „Systemumgebung“ der Versionshinweise zu Databricks Runtime für Ihr Cluster. Weitere Informationen finden Sie unter Versionshinweise, Versionen und Kompatibilität von Databricks Runtime.

    Hinweis

    Wenn Sie PySpark-UDFs verwenden möchten, ist es wichtig, dass die installierte Nebenversion Ihres Entwicklungscomputers mit der Nebenversion von Python übereinstimmt, die mit der im Cluster installierten Databricks Runtime enthalten ist.

  • Die Databricks Connect-Haupt- und Nebenpaketversion sollte mit Ihrer Databricks Runtime-Version übereinstimmen. Databricks empfiehlt, dass Sie immer das neueste Paket von Databricks Connect verwenden, die mit Ihrer Databricks Runtime-Version übereinstimmt. Beispiel: Wenn Sie einen Databricks Runtime 14.0-Cluster verwenden, sollten Sie auch das die Version 14.0 des Pakets databricks-connect verwenden.

    Hinweis

    Eine Liste mit verfügbaren Databricks Connect-Releases und Wartungsupdates finden Sie in den Versionshinweisen zu Databricks Connect.

    Die Verwendung des neuesten Databricks Connect-Pakets, das Ihrer Databricks Runtime-Version entspricht, ist keine Anforderung. Für Databricks Runtime 13.3 LTS und höher können Sie das Databricks Connect-Paket für alle Versionen von Databricks Runtime ab der Version des Databricks Connect-Pakets verwenden. Wenn Sie jedoch Features verwenden möchten, die in späteren Versionen der Databricks Runtime verfügbar sind, müssen Sie das Databricks Connect-Paket entsprechend aktualisieren.

  • 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. Dies kann dazu beitragen, damit verbundene technische Probleme zu reduzieren oder die Zeit zum Beheben dieser Probleme zu verkürzen. In den folgenden Abschnitten erfahren Sie, wie Sie eine virtuelle Python-Umgebung für venv oder Poetry aktivieren. Weitere Informationen zu diesen Tools finden Sie unter venv oder Poetry.

Aktivieren einer virtuellen Python-Umgebung mit venv

Wenn Sie venv auf Ihrem Entwicklungscomputer verwenden und Ihr Cluster Python 3.10 ausführt, müssen Sie eine venv-Umgebung mit dieser Version erstellen. Der folgende Beispielbefehl generiert die Skripts, um eine venv-Umgebung mit Python 3.10 zu aktivieren, und dieser Befehl platziert diese Skripts dann in einem ausgeblendeten Ordner mit Namen .venv innerhalb des aktuellen Arbeitsverzeichnisses:

# Linux and macOS
python3.10 -m venv ./.venv

# Windows
python3.10 -m venv .\.venv

Um diese Skripts zu verwenden, um diese venv-Umgebung zu aktivieren, lesen Sie Funktionsweise von venvs (virtual environments, virtuelle Umgebungen).

Fahren Sie fort, um den Clienten einzurichten.

Aktivieren einer virtuellen Python-Umgebung mit Poetry

  1. Installieren Sie Poetry, wenn Sie dies noch nicht getan haben.

  2. Wenn Sie Poetry auf Ihrem Entwicklungscomputer verwenden und Ihr Cluster Python 3.10 ausführt, müssen Sie eine virtuelle Poetry-Umgebung mit dieser Version erstellen. Weisen Sie im Stammverzeichnis Ihres vorhandenen Python-Codeprojekts poetry an, Ihr Python-Codeprojekt für Poetry zu initialisieren, indem Sie den folgenden Befehl ausführen:

    poetry init

  3. Poetry zeigt mehrere Eingabeaufforderungen an. Keine dieser Eingabeaufforderungen ist spezifisch für Databricks Connect. Informationen zu diesen Eingabeaufforderungen finden Sie unter init.

  4. Nachdem Sie die Eingabeaufforderungen abgeschlossen haben, fügt Poetry Ihrem Python-Projekt eine Datei vom Typ pyproject.toml hinzu. Informationen zur Datei pyproject.toml finden Sie unter Datei „pyproject.toml“.

  5. Weisen Sie im Stammverzeichnis Ihres Python-Codeprojekts poetry an, die Datei pyproject.toml zu lesen, die Abhängigkeiten aufzulösen und zu installieren sowie eine Datei vom Typ poetry.lock zum Sperren der Abhängigkeiten und schließlich eine virtuelle Umgebung zu erstellen. Führen Sie zu diesem Zweck den folgenden Befehl aus:

    poetry install

  6. Weisen Sie im Stammverzeichnis Ihres Python-Codeprojekts poetry an, die virtuelle Umgebung zu aktivieren und die Shell aufzurufen. Führen Sie zu diesem Zweck den folgenden Befehl aus:

    poetry shell

Sie wissen, dass Ihre virtuelle Umgebung aktiviert ist und die Shell aufgerufen wurde, wenn der Name der virtuellen Umgebung direkt vor der Terminalaufforderung in Klammern angezeigt wird, z. B. (my-project-py3.10).

Sie können die virtuelle Umgebung jederzeit deaktivieren und die Shell beenden, indem Sie den Befehl exit ausführen.

Sie wissen, dass Sie die Shell beendet haben, wenn der Name der virtuellen Umgebung nicht mehr direkt vor der Terminalaufforderung in Klammern angezeigt wird.

Weitere Informationen zum Erstellen und Verwalten von virtuellen Poetry-Umgebungen finden Sie unter Verwalten von Umgebungen.

Einrichten des Clients

Tipp

Wenn Sie bereits die Databricks-Erweiterung für Visual Studio Code installiert haben, müssen Sie diese Setupanweisungen nicht befolgen.

Die Databricks-Erweiterung für Visual Studio Code verfügt bereits über integrierten Support für Databricks Connect für Databricks Runtime ab Version 13.0. Fahren Sie mit dem Debuggen von Code fort, indem Sie Databricks Connect für die Databricks-Erweiterung für Visual Studio Code verwenden.

Nachdem Sie die Anforderungen für Databricks Connect erfüllt haben, schließen Sie die folgenden Schritte ab, um den Databricks Connect-Client einzurichten.

Schritt 1: Installieren des Databricks Connect-Clients

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

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==14.0.*"  # 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 Schritt 2: 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@~14.0  # Or X.Y to match your cluster version.

    Hinweis

    Databricks empfiehlt, die Notation „@-Tilde“ zu verwenden, um databricks-connect@~14.0 anstelle von databricks-connect==14.0 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.

Schritt 2: Konfigurieren von Verbindungseigenschaften

In diesem Abschnitt konfigurieren Sie Eigenschaften, um eine Verbindung zwischen Databricks Connect und Ihrem Azure Databricks-Remotecluster herzustellen. Diese Eigenschaften umfassen Einstellungen zum Authentifizieren von Databricks Connect bei Ihrem Cluster.

Ab Databricks Connect für Databricks Runtime 13.1 und höher umfasst Databricks Connect das Databricks SDK für Python. Dieses SDK implementiert den Standard für die einheitliche Databricks-Clientauthentifizierung, einen konsolidierten und konsistenten architektonischen und programmgesteuerten Ansatz für die Authentifizierung. Dieser Ansatz gestaltet die Einrichtung und Automatisierung der Authentifizierung mit Azure Databricks zentralisierter und vorhersagbarer. Er ermöglicht Ihnen, die Azure Databricks-Authentifizierung einmal zu konfigurieren und diese Konfiguration dann für mehrere Azure Databricks-Tools und -SDKs ohne weitere Änderungen an der Authentifizierungskonfiguration zu verwenden.

Hinweis

  1. Sammeln Sie die folgenden Konfigurationseigenschaften.

  2. Konfigurieren Sie die Verbindung innerhalb Ihres Codes. Databricks Connect sucht nach Konfigurationseigenschaften in der folgenden Reihenfolge, bis diese gefunden werden. Sobald sie gefunden werden, wird die Suche nach den verbleibenden Optionen beendet. Die Details für jede Option werden nach der folgenden Tabelle angezeigt:

    Konfigurationseigenschaftenoption Gilt für:
    1. Die remote()-Methode der DatabricksSession-Klasse Nur Authentifizierung mit persönlichem Zugriffstoken für Azure Databricks
    2. Ein Azure Databricks-Konfigurationsprofil Alle Azure Databricks-Authentifizierungstypen
    3. Die SPARK_REMOTE-Umgebungsvariable Nur Authentifizierung mit persönlichem Zugriffstoken für Azure Databricks
    4. Die DATABRICKS_CONFIG_PROFILE-Umgebungsvariable Alle Azure Databricks-Authentifizierungstypen
    5. Eine Umgebungsvariable für jede Konfigurationseigenschaft Alle Azure Databricks-Authentifizierungstypen
    6. Ein Azure Databricks-Konfigurationsprofil mit dem Namen DEFAULT Alle Azure Databricks-Authentifizierungstypen

    1. 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.

      Databricks empfiehlt nicht, diese Verbindungseigenschaften direkt in Ihrem Code anzugeben. Stattdessen empfiehlt Databricks, Eigenschaften über Umgebungsvariablen oder Konfigurationsdateien zu konfigurieren, wie in späteren Optionen beschrieben. In den folgenden Codebeispielen wird davon ausgegangen, dass Sie selbst 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 jede 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()

# Set the Spark Connect connection string in DatabricksSession.builder.remote.
from databricks.connect import DatabricksSession

workspace_instance_name = retrieve_workspace_instance_name()
token                   = retrieve_token()
cluster_id              = retrieve_cluster_id()

spark = DatabricksSession.builder.remote(
  f"sc://{workspace_instance_name}:443/;token={token};x-databricks-cluster-id={cluster_id}"
).getOrCreate()

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

    3. Die SPARK_REMOTE-Umgebungsvariable

      Legen Sie für diese Option, die nur für die Authentifizierung mit persönlichem Zugriffstoken in Azure Databricks gilt, die SPARK_REMOTE-Umgebungsvariable auf die folgende Zeichenfolge fest, und ersetzen Sie die Platzhalter durch die entsprechenden Werte.

      sc://<workspace-instance-name>:443/;token=<access-token-value>;x-databricks-cluster-id=<cluster-id>

      Initialisieren Sie dann die DatabricksSession-Klasse wie folgt:

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

      Informationen zum Festlegen von Umgebungsvariablen finden Sie in der Dokumentation des Betriebssystems.

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

      Informationen zum Festlegen von Umgebungsvariablen finden Sie in der Dokumentation des Betriebssystems.

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

      Informationen zum Festlegen von Umgebungsvariablen finden Sie in der Dokumentation des Betriebssystems.

    6. Ein Azure Databricks-Konfigurationsprofil mit 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()

  3. Überprüfen Ihrer Umgebung und der Verbindung mit dem Databricks-Cluster

    • Der folgende Befehl überprüft, ob Ihre Umgebung, die Standardanmeldeinformationen und die Verbindung mit dem Cluster für Databricks Connect ordnungsgemäß eingerichtet sind.

      databricks-connect test

      Mit diesem Befehl werden die in der Umgebung konfigurierten Standardanmeldeinformationen ausgewählt (z. B. das DEFAULT-Konfigurationsprofil oder über Umgebungsvariablen).

      Der Befehl schlägt mit einem Exitcode ungleich 0 und einer entsprechenden Fehlermeldung fehl, wenn eine Inkompatibilität im Setup erkannt wird.

    • Darüber hinaus können Sie auch die pyspark-Shell verwenden, die im Rahmen von Databricks Connect für Python enthalten ist. Starten Sie die Shell, indem Sie Folgendes ausführen:

      pyspark

      Die Spark-Shell wird angezeigt, z. B.:

      Python 3.10 ...
[Clang ...] on darwin
Type "help", "copyright", "credits" or "license" for more information.
Welcome to
      ____              __
     / __/__  ___ _____/ /__
    _\ \/ _ \/ _ `/ __/  '_/
   /__ / .__/\_,_/_/ /_/\_\   version 13.0
      /_/

Using Python version 3.10 ...
Client connected to the Spark Connect server at sc://...:.../;token=...;x-databricks-cluster-id=...
SparkSession available as 'spark'.
>>>

      Führen Sie an der >>>-Eingabeaufforderung einen einfachen PySpark-Befehl aus, z. B. spark.range(1,10).show(). Wenn keine Fehler vorhanden sind, haben Sie erfolgreich eine Verbindung hergestellt.

      Wenn Sie die Verbindung erfolgreich hergestellt haben, drücken Sie Ctrl + d oder Ctrl + z, oder führen Sie den Befehl quit() oder exit() aus, um die Spark-Shell zu beenden.

      Weitere Details zur databricks-connect-Binärdatei finden Sie unter Erweiterte Verwendung von Databricks Connect für Python