Richten Sie Ihre KI-Laufzeitumgebung ein

AI Runtime bietet zwei verwaltete Python-Umgebungen. Die Standardumgebung umfasst cuda. Ab Umgebungsversion 5 sind torch und torchvision nicht mehr vorinstalliert. Die Databricks-KI-Umgebung ist mit PyTorch, Transformers und anderen ML- und Deep-Learning-Frameworks vorinstalliert. Wählen Sie die Standardumgebung für die vollständige Kontrolle über Ihren Abhängigkeitsstapel oder die KI-Umgebung für ein einsatzbereites Schulungssetup aus. Du kannst in beiden Umgebungen starten und mehr Pakete selbst installieren.

Wichtige Punkte auf dieser Seite:

  • Wählen Sie die Standardumgebung für die vollständige Kontrolle über Abhängigkeiten oder die Databricks-KI-Umgebung für einen einsatzbereiten ML-Stack.
  • Der Standard umfasst cuda. Ab Umgebungsversion 5 sind torch und torchvision nicht vorinstalliert. Die KI-Umgebung fügt PyTorch, Transformers und mehr hinzu.
  • Installiere weitere Pakete mit %uv pip install (Umgebungsversion 5 und höher) oder %pip install in einem Notebook oder mit environment.dependencies in der CLI.

Welche Umgebung verwendet werden soll

AI Runtime bietet zwei verwaltete Python Umgebungen, die Standardumgebung und die Databricks AI-Umgebung. Workloads, die Sie mit der Databricks-CLI übermitteln, können ebenfalls in einem benutzerdefinierten Docker-Image ausgeführt werden.

Umgebung Wichtige Merkmale Wann verwenden?
Standardumgebung Minimal; enthält cuda. Ab Umgebungsversion 5 sind torch und torchvision nicht mehr vorinstalliert. Sie möchten die vollständige Kontrolle über den Abhängigkeitsstapel haben und es vorziehen, nur das zu installieren, was Sie benötigen.
Databricks KI-Umgebung Vorinstalliert mit beliebten Maschinelles Lernen-Frameworks (PyTorch, Transformers und mehr) Sie benötigen eine vollständige Umgebung für Schulungen, Feinabstimmungen und Experimente ohne manuelle Abhängigkeitsverwaltung
Benutzerdefiniertes Docker-Image (Öffentliche Vorschau) Ihr eigenes Image ist in der Artifact Registry gespeichert und basiert üblicherweise auf einem Databricks-Basisimage. Verfügbar für Databricks CLI-Workloads. Ein Workspace-Administrator muss die Databricks Artifact Registry-Vorschau aktivieren. Sie benötigen Systembibliotheken, kompilierte CUDA-Erweiterungen oder ein bestehendes Container-Setup, das Sie nicht mit environment.dependencies reproduzieren können.

Du kannst auch eine Workspace-Basisumgebung verwenden, die ein Workspace-Administrator für AI Runtime gebaut hat. Siehe Build für serverlose GPU-Compute (KI-Laufzeit).

Um eine Umgebung in einem Notizbuch auszuwählen, öffnen Sie das Umgebungs-Seitenfeld und wählen Sie eine Basisumgebung aus:

Wähle eine Basisumgebung im Notebook-Umgebungs-Seitenpanel aus.

Standardumgebung (minimale Umgebung)

Eine minimale, stabile Umgebung, die nur die erforderlichen Pakete für den AI-Runtime-Vorgang enthält. Die Umgebung umfasst cuda zur GPU-Unterstützung. Ab Umgebungsversion 5 sind torch und torchvision nicht mehr vorinstalliert. Installiere die Versionen, die dein Workload benötigt, mit %uv pip install oder %pip install. Die in jeder Umgebungsversion installierten Pakete finden Sie in den nachstehenden Versionshinweisen.

Am besten geeignet für: Benutzer, die die vollständige Kontrolle über ihren Abhängigkeitsstapel wünschen und es vorziehen, nur das zu installieren, was sie benötigen.

Zum Auswählen: Im Environment-Seitenpanel wähle Standard v6 als Basisumgebung.

Weitere Informationen zu Paketversionen, die in verschiedenen Versionen installiert sind, finden Sie in den Versionshinweisen:

Databricks KI-Umgebung

Verfügbar in Umgebung 4 und höher. Die KI-Umgebung basiert auf der Standardumgebung mit allgemeinen Laufzeitpaketen und Paketen speziell für maschinelles Lernen auf GPUs. Vorinstallierte Pakete umfassen:

  • PyTorch (mit CUDA-Unterstützung)
  • Transformers (Hugging Face)
  • Und zusätzliche ML/DL-Abhängigkeiten

Am besten geeignet für: ML-Praktiker, die eine vollständige Umgebung für Schulungsworkloads, Feinabstimmungen und Experimente ohne manuelle Abhängigkeitsverwaltung wünschen.

Um auszuwählen: Im Umgebungs-Seitenpanel wähle AI v6 als deine Basisumgebung.

Weitere Informationen zu Paketversionen, die in verschiedenen Versionen installiert sind, finden Sie in den Versionshinweisen:

Zusätzliche Pakete installieren

Du kannst entweder in einer verwalteten Umgebung oder einer Workspace-Basisumgebung starten und deine eigenen Python-Pakete darauf installieren. Wie du sie installierst, hängt davon ab, wie du dich mit AI Runtime verbindest.

In einem Notizbuch

Installiere Pakete oben in deinem Notebook oder Trainingsskript mit %uv pip, das mit UV installiert wird und schneller ist als %pip. Fixieren Sie die Versionen, damit die Abläufe reproduzierbar bleiben:

%uv pip install "trl==1.1.0"
%uv pip install "transformers==5.5.4"

Für die vollständige %pip Übersicht und %uv pip Referenz, einschließlich der Umgebungsversionen, die jede unterstützen, siehe Bibliotheken verwalten mit %uv Befehlen.

Wenn du den @distributed Decorator für Multi-GPU-Workloads verwendest, werden die Pakete, die du vor dem Aufruf .distributed() installierst, automatisch gesnapshott und an alle verteilten Prozesse weitergeleitet. Die Gesamtgröße der installierten Pakete darf 15 GB nicht überschreiten. Weitere Details finden Sie unter Hinzufügen von Abhängigkeiten zum Notizbuch.

Mit der CLI

Die air CLI verwendet dieselben verwalteten Umgebungen. Wähle eines mit environment.versionund liste dann die Pakete auf, die du darüber installieren sollst, unter environment.dependencies deinem Workload-YAML. Die CLI installiert sie mit UV in die ausgewählte Umgebung, sodass Sie keine separate virtuelle Umgebung selbst verwalten müssen:

environment:
  version: '6'
  dependencies:
    - trl==1.1.0
    - transformers==5.5.4

Die Standardumgebung enthält weder torch noch torchvision, also füge sie zu dependencies hinzu, wenn deine Arbeitslast sie importiert. Um stattdessen mit der Databricks-KI-Umgebung zu starten, die PyTorch beinhaltet, setzen Sie version auf eine KI-Umgebungskennung wie databricks_ai_v6. Für das vollständige Abhängigkeitsformat und die unterstützten Installationsflags siehe environment. Um die Workload in Ihrem eigenen Image statt in einer verwalteten Umgebung auszuführen, lesen Sie Benutzerdefinierte Docker-Images mit KI-Laufzeit verwenden.

Anmeldeinformationen über Secrets an eine Workload weitergeben

Verwenden Sie Workspace-Secrets, um Zugangsdaten an Workloads weiterzugeben, die mit der Databricks-CLI eingereicht wurden. Die Workload läuft als Benutzer- oder Serviceprincipal, authentifiziert durch das ausgewählte CLI-Profil. Das folgende Verfahren verwendet ein Hugging Face-Token als Beispiel. Um eine andere Anmeldeinformation zu übergeben, ersetzen Sie HF_TOKEN durch die Umgebungsvariable, die Ihre Anwendung liest. Informationen zu den Anforderungen an Hugging Face-Token finden Sie unter.

  1. Wählen Sie den Arbeitsbereich aus, in dem Sie die Workload einreichen, und bestätigen Sie dessen Host:

    export DATABRICKS_CONFIG_PROFILE=<profile>
    databricks auth describe
    
  2. Erstellen Sie einen Databricks-gestützten Secret Scope oder verwenden Sie einen bestehenden Scope, in den Sie schreiben können. Ersetzen Sie die Scope- und Key-Platzhalter durch die Namen, die Sie in Ihrem Workload-YAML verwenden:

    databricks secrets create-scope <scope-name>
    databricks secrets put-secret <scope-name> <key-name>
    

    Geben Sie das Token im interaktiven Prompt ein. Halte das Token aus YAML, Befehlsargumenten und Versionskontrolle heraus. Wenn du einen bestehenden Scope verwendest, überspringe create-scope. Schlüsselnamen können / nicht enthalten. Wenn der Schlüssel bereits existiert, put-secret wird sein Wert überschrieben.

  3. Wenn der authentifizierte Benutzer oder Service-Principal keinen Zugriff auf den Scope hat READ , bitten Sie einen Benutzer mit MANAGE Berechtigung zum Scope, den Zugriff zu gewähren. Wenn Sie den Scope mit derselben Identität erstellt haben, haben Sie bereits MANAGE, das READ einschließt, und können diesen Schritt überspringen. Ersetzen Sie <principal> durch die E-Mail-Adresse des authentifizierten Benutzers, die Anwendungs-ID des Service-Principals oder den Gruppennamen:

    databricks secrets put-acl <scope-name> <principal> READ
    

    Berechtigungen für einen Secret Scope zu erteilen erfordert den Premium-Plan. Bereichsberechtigungen gelten für jedes Secret im Bereich. Verwenden Sie einen dedizierten Scope, wenn Sie den Zugriff einschränken müssen. Siehe Berechtigungen für Secret-Scopes.

  4. Beziehe dich auf das Secret in deiner Workload-YAML:

    secrets:
      HF_TOKEN: <scope-name>/<key-name>
    

    AI Runtime löst die Referenz auf und stellt das Token als Umgebungsvariable HF_TOKEN für die Workload bereit. Das Setzen von HF_TOKEN allein in Ihrer lokalen Shell konfiguriert die entfernte Workload nicht.

  5. Überprüfen Sie die Schlüssel- und Berechtigungen für den Gültigkeitsbereich, ohne das Token abzurufen oder zu drucken:

    databricks secrets list-secrets <scope-name>
    databricks secrets list-acls <scope-name>
    

    Bestätigen Sie, dass der erwartete Schlüssel existiert und dass der authentifizierte Benutzer oder Service Principal READ oder eine höhere Berechtigung besitzt, direkt oder über eine Gruppe. Diese Befehle zeigen Schlüsselmetadaten und Umfangsberechtigungen an. Sie überprüfen weder den Token noch die Modellgenehmigung. Wenn Sie Scope-Berechtigungen nicht auflisten können, bitten Sie einen Benutzer mit MANAGE Berechtigung im Scope, den Zugriff zu überprüfen.

Geheimnisse sind auf den Arbeitsbereich beschränkt. Wenn Sie CLI-Profile oder Arbeitsbereiche wechseln, wiederholen Sie die Host-, Schlüssel- und Zugriffsprüfungen im Ziel-Arbeitsbereich. Derselbe Umfang und derselbe Schlüsselname können sich auf unterschiedliche Geheimnisse in unterschiedlichen Arbeitsbereichen beziehen.

Nachdem Sie ein Secret aktualisiert haben, erhält eine erneut ausgeführte Workload den neuen Wert. Lesen Sie im Notebook-Code das Secret erneut, um den aktualisierten Wert abzurufen.

Für Notizbuch-Workloads verwenden Sie dbutils.secrets.get, um ein Arbeitsbereichsgeheimnis zu lesen. Zum Beispiel, um HF_TOKEN im Python-Prozess des Notizbuchs festzulegen:

import os

os.environ["HF_TOKEN"] = dbutils.secrets.get(scope="<scope-name>", key="<key-name>")

Drucke das Secret nicht aus. Die Notebook-Identität benötigt READ Zugriff auf den Scope. Siehe Get Command (dbutils.secrets.get).

Hugging Face-Tokens

Bevor Sie eine Workload ausführen, die ein privates oder gated Modell liest, erstellen Sie ein Hugging Face Access Token mit Lese-Zugriff auf das Modell-Repository. Für ein granulares Token erteilen Sie Lesezugriff auf dieses Repository. Das Hugging Face-Konto, dem der Token gehört, muss Zugriff auf das Modell haben. Das Erstellen eines Tokens gewährt keine Modellgenehmigung.

Das geheime Mapping in der Prozedur stellt das Token als HF_TOKEN bereit, das Hugging Face-Bibliotheken in der Workload-Umgebung lesen.

Fehlerbehebung bei Geheim- und Modellzugriff

Wenn die Workload fehlschlägt, finden Sie das Symptom in der folgenden Tabelle:

Symptom Beheben
Die Workload kann weder den Scope noch den Schlüssel finden. Stellen Sie sicher, dass der Umfang und der Schlüssel im Workload-YAML mit denen übereinstimmen, die Sie im Arbeitsbereich erstellt haben, in dem Sie die Workload einreichen.
Fehler bei Secret-Berechtigungen. Gewähren Sie dem vom CLI READ authentifizierten Benutzer oder Serviceprincipal Zugriff auf den Scope. Siehe das vorstehende Verfahren.
Hugging Face lehnt das Token ab (401). Überprüfen Sie, ob das Token gültig ist und Lese-Zugriff auf das Modell-Repository hat. Ersetzen Sie einen abgelaufenen oder widerrufenen Token.
GatedRepoError oder eine 403-Antwort für ein gegated Repository. Bestätigen Sie, dass der Zugriff des Token-Eigentümers auf das Modell genehmigt wurde und dass das Token Lese-Zugriff auf dieses Repository hat.

Arbeitsbereichsbasisumgebungen

Ein Workspace-Administrator kann eine Workspace-Basisumgebung für AI Runtime erstellen, wodurch sie allen Benutzern im Workspace über das Dropdown-Menü „Basisumgebung“ zur Verfügung steht. Ausführliche Informationen finden Sie unter Build für serverlose GPU-Compute (AI Runtime).

Um eine Basisumgebung in einem geplanten Workload zu verwenden, verweisen Sie im environments-Block eines Auftrags oder Bundles anhand ihres Bezeichners darauf. Zum Beispiel wählt diese Declarative Automation Bundles-Aufgabe die Databricks-KI-Umgebung aus:

resources:
  jobs:
    train:
      tasks:
        - task_key: train
          environment_key: default
      environments:
        - environment_key: default
          spec:
            base_environment: databricks_ai_v6

Ein vollständiges Jobbeispiel finden Sie unter GPU-Workloads planen und Aufgaben zusammensetzen.

Caching von Umgebungen und benutzerdefinierten Modulen

Wann werden Umgebungen zwischengespeichert?

AI Runtime speichert die Umgebung deines Notebooks, sodass du beim erneuten Öffnen der Notebooks keine Pakete neu installieren musst. Weitere Informationen finden Sie unter Zurücksetzen der Umgebungsabhängigkeiten.

Caching gilt für interaktive Notizbücher. Workloads, die über die air CLI laufen oder als Jobs geplant werden, nutzen diesen Cache nicht; jeder Run installiert seine Abhängigkeiten frisch.

Als Best Practice pinnen Sie Pakete an eine bestimmte Version, damit Ihre zwischengespeicherte Umgebung gültig bleibt und Ihre Durchläufe reproduzierbar bleiben.

Wie importiere ich benutzerdefinierte Module?

Die folgenden Schritte zeigen, wie man eigene Python-Module verwendet.

  1. Synchronisiere deinen Code mit dem Arbeitsbereich. Klone ein Git-Repository mit einem Git-Ordner in den Arbeitsbereich oder lade die Dateien direkt als Arbeitsbereichsdateien hoch. Speichern Sie gemeinsam genutzten Code für Teamprojekte unter /Workspace/Shared oder in einem Benutzerordner für die persönliche Entwicklung. Wenn man den Code in einem Git-Ordner speichert, bleibt er versionskontrolliert.
  2. Füge den Ordner hinzu sys.path und importiere ihn oben in deinem Notizbuch oder Trainingsskript:
import sys
sys.path.append("/Workspace/Shared/my-project/src")
from my_module import my_function

Limitations

Die folgenden Funktionen sind für KI-Runtime nicht verfügbar:

  • Spark-Funktionen: Sie können PySpark-Funktionen nicht direkt importieren oder verwenden. AI Runtime ist eine Nur-Python-Umgebung; Spark ist nicht als lokale Laufzeit verfügbar. Spark Connect steht jedoch zum Laden von Daten zur Verfügung. Siehe Laden von Daten auf AI-Runtime.
  • Databricks Runtime ML-Bibliotheken: Vorinstallierte Pakete sind kein Ersatz für Databricks Runtime ML. Einige ML-Bibliotheken, die in Databricks Runtime ML verfügbar sind, sind möglicherweise nicht auf AI Runtime vorinstalliert.
  • Private Artefakte: KI-Runtime unterstützt private Artefakte in bestimmten Fällen. Wenden Sie sich an Ihr Kontoteam, um weitere Details zu erhalten.