Configurez votre environnement AI Runtime

AI Runtime fournit deux environnements Python gérés. L’environnement standard inclut cuda. À compter de la version 5 de l’environnement, torch et torchvision ne sont plus préinstallés. L’environnement IA Databricks est préchargé avec PyTorch, Transformers et d’autres frameworks de ML et d’apprentissage profond. Choisissez l’environnement Standard pour un contrôle total sur votre pile de dépendances ou l’environnement IA pour une configuration de formation prête à l’emploi. Vous pouvez partir de l’un ou l’autre environnement et installer vous-même d’autres paquets.

Points clés sur cette page :

  • Choisissez l’environnement Standard pour le contrôle total des dépendances, ou l’environnement IA Databricks pour une pile ML prête à l’emploi.
  • La norme inclut cuda. À partir de la version 5 de l’environnement, torch et torchvision ne sont pas préinstallés. L’environnement IA ajoute PyTorch, Transformers et bien d’autres.
  • Installez plus de packages avec %uv pip install (environnement version 5 et ultérieure) ou %pip install dans un notebook, ou avec environment.dependencies dans la ligne de commande.

Environnement à utiliser

AI Runtime offre deux environnements de Python managés, l’environnement Standard et l’environnement Databricks AI. Les charges de travail que vous soumettez avec l’interface de commande Databricks peuvent également s’exécuter dans une image Docker personnalisée.

Environment Caractéristiques clés Quand utiliser
Environnement standard Minimal ; comprend cuda. À compter de la version 5 de l’environnement, torch et torchvision ne sont plus préinstallés. Vous souhaitez un contrôle total sur votre pile de dépendances et préférez installer uniquement ce dont vous avez besoin
Environnement d’IA Databricks Préchargé avec des frameworks ML populaires (PyTorch, Transformers, etc.) Vous souhaitez un environnement complet pour l’apprentissage, l’optimisation et l’expérimentation sans gestion manuelle des dépendances
Image Docker personnalisée (Aperçu public) Votre propre image stockée dans le registre d’artefacts, généralement construite à partir d’une image de base Databricks. Disponible pour les charges de travail de la CLI Databricks. Un administrateur d’espace de travail doit activer la préversion de Databricks Artifact Registry. Vous avez besoin de bibliothèques système, d’extensions CUDA compilées ou d’une configuration de conteneur existante que vous ne pouvez pas reproduire avec environment.dependencies

Vous pouvez aussi utiliser un environnement de base d’espace de travail qu’un administrateur de workspace a créé pour l’exécution IA. Consultez Créer pour le calcul GPU sans serveur (AI Runtime).

Pour choisir un environnement dans un carnet, ouvrez le panneau latéral Environnement et sélectionnez un environnement de base :

Sélection d’un environnement de base dans le panneau latéral Environnement du cahier.

Environnement standard (environnement minimal)

Un environnement minimal et stable contenant uniquement les packages requis pour l’opération AI Runtime. L’environnement comprend la prise en charge du GPU via cuda. À compter de la version 5 de l’environnement, torch et torchvision ne sont plus préinstallés. Installez les versions dont votre charge de travail a besoin avec %uv pip install ou %pip install. Pour connaître les packages installés dans chaque version de l’environnement, consultez les notes de publication ci-dessous.

Idéal pour : les utilisateurs qui veulent contrôler entièrement leur pile de dépendances et préfèrent installer uniquement ce dont ils ont besoin.

Pour sélectionner : Dans le panneau latéral Environnement , choisissez Standard v6 comme environnement de base.

Pour plus d’informations sur les versions de package installées dans différentes versions, consultez les notes de publication :

Environnement d’IA Databricks

Disponible dans l’environnement 4 et versions ultérieures. L’environnement IA repose sur l’environnement Standard, avec des packages d’exécution courants et des packages spécifiques à l’apprentissage automatique pour les GPU. Les packages préinstallés sont les suivants :

  • PyTorch (avec prise en charge de CUDA)
  • Transformers (Hugging Face)
  • Et d’autres dépendances ML/DL

Idéal pour : les praticiens ML qui souhaitent un environnement complet pour l'entraînement des charges de travail, le réglage fin et l’expérimentation sans gestion manuelle des dépendances.

Pour sélectionner : dans le panneau latéral Environnement , choisissez AI v6 comme environnement de base.

Pour plus d’informations sur les versions de package installées dans différentes versions, consultez les notes de publication :

Installer des paquets supplémentaires

Vous pouvez partir soit d’un environnement managé, soit d’un environnement de base workspace et installer vos propres paquets Python par-dessus. La façon dont vous les installez dépend de la façon dont vous vous connectez à l’exécution IA.

Dans un carnet

Installez des paquets au début de votre notebook ou de votre script d’entraînement avec %uv pip, qui s’installe avec uv et est plus rapide que %pip. Les versions à épingles pour que les runs restent reproductibles :

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

Pour la référence complète sur %pip et %uv pip, y compris les versions d’environnement compatibles avec chacune d’elles, consultez Gérer les bibliothèques avec les commandes %uv.

Lorsque vous utilisez le @distributed décorateur pour des charges de travail multi-GPU, les packages que vous installez avant d’appeler .distributed() sont automatiquement instantanés et propagés à tous les processus distribués. La taille totale des packages installés ne doit pas dépasser 15 Go. Pour plus d’informations, consultez Ajouter des dépendances au notebook.

Avec le CLI

La air CLI utilise les mêmes environnements gérés. Sélectionnez-en un avec environment.version, puis listez les paquets à installer par-dessus sous environment.dependencies dans votre fichier YAML de charge de travail. La CLI les installe dans l’environnement sélectionné avec uv, vous n’avez donc pas à gérer vous-même un environnement virtuel séparé :

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

L’environnement Standard n’inclut torch pas ni torchvision, donc si votre charge de travail les importe, ajoutez-les à dependencies. Pour commencer à partir de l’environnement IA Databricks, qui inclut PyTorch, réglez version sur un identifiant d’environnement IA tel que databricks_ai_v6. Pour le format complet de dépendance et les indicateurs d’installation pris en charge, voir environment. Pour exécuter la charge de travail dans votre propre image plutôt que dans un environnement géré, voir Utiliser des images Docker personnalisées avec AI Runtime.

Transmettre des identifiants à une charge de travail avec des secrets

Utilisez les secrets de l’espace de travail pour transmettre des identifiants aux charges de travail soumises avec la CLI Databricks. La charge de travail s’exécute en tant qu’utilisateur ou principal de service authentifié par le profil CLI sélectionné. La procédure suivante utilise un jeton Hugging Face comme exemple. Pour utiliser d’autres informations d’identification, remplacez HF_TOKEN par la variable d’environnement que votre application utilise. Pour les exigences du jeton Hugging Face, voir Jetons Hugging Face.

  1. Sélectionnez l’espace de travail où vous soumettez la charge de travail et confirmez son hôte :

    export DATABRICKS_CONFIG_PROFILE=<profile>
    databricks auth describe
    
  2. Créez un secret scope adossé à Databricks, ou utilisez un scope existant sur lequel vous pouvez écrire. Remplacez les espaces réservés du scope et de la clé par les noms que vous utilisez dans votre YAML de charge de travail :

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

    Saisissez le jeton à l’invite interactive. Gardez le jeton hors du YAML, des arguments de commande et du contrôle source. Si vous utilisez un périmètre existant, passez create-scope. Les noms de clé ne peuvent pas contenir /. Si la clé existe déjà, put-secret en remplace la valeur.

  3. Si l’utilisateur authentifié ou le principal de service n’a pas accès au READ scope, demandez à un utilisateur ayant l’autorisation MANAGE sur le scope d’accorder l’accès au scope. Si vous avez créé le scope avec la même identité, vous avez MANAGEdéjà , qui inclut READ, et vous pouvez sauter cette étape. Remplacez <principal> par l’adresse e-mail de l’utilisateur authentifié, l’ID de l’application du principal de service ou le nom du groupe :

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

    Accorder des autorisations sur une portée de secrets nécessite le forfait Premium. Les autorisations de scope s’appliquent à chaque secret du scope. Utilisez un scope dédié lorsque vous devez restreindre l’accès. Voir autorisations de la portée des secrets.

  4. Faites référence au secret dans le YAML de votre charge de travail :

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

    AI Runtime résout la référence et fournit le jeton comme variable d’environnement HF_TOKEN pour la charge de travail. Le simple réglage HF_TOKEN dans votre shell local ne configure pas la charge de travail distante.

  5. Vérifiez les permissions de clé et de portée sans récupérer ni imprimer le jeton :

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

    Confirmez que la clé attendue existe et que l’utilisateur authentifié ou le principal de service dispose READ d’une permission ou d’une permission, directement ou via un groupe. Ces commandes affichent les métadonnées de la clé et les permissions de portée. Ils ne valident pas le token ni l’approbation du modèle. Si vous ne pouvez pas afficher la liste des autorisations du périmètre, demandez à un utilisateur disposant de l’autorisation MANAGE pour le périmètre de vérifier l’accès.

Les secrets sont limités à l’espace de travail. Lorsque vous modifiez les profils CLI ou les espaces de travail, répétez les vérifications hôte, clé et accès dans l’espace de travail de destination. Le même périmètre et les mêmes noms de clés peuvent faire référence à différents secrets dans différents espaces de travail.

Après avoir mis à jour un secret, une charge de travail réessayée reçoit la nouvelle valeur. Dans le code du carnet, relisez le secret pour récupérer sa valeur mise à jour.

Pour les charges de travail du bloc-notes, utilisez dbutils.secrets.get pour lire un secret d’espace de travail. Par exemple, pour définir HF_TOKEN dans le processus Python du bloc-notes :

import os

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

N’imprimez pas le secret. L’identité du carnet a besoin d’accéder à la portée READ. Voir get command (dbutils.secrets.get).

Jetons Hugging Face

Avant d’exécuter une charge de travail qui lit un modèle privé ou verrouillé, créez un jeton d’accès Hugging Face avec accès en lecture au référentiel de modèles. Pour un jeton à grain fin, accordez un accès en lecture à ce référentiel. Le compte Hugging Face qui possède le token doit avoir accès au modèle. Créer un jeton ne donne pas accès au modèle.

Le mappage secret dans la procédure fournit le jeton sous la forme HF_TOKEN, que les bibliothèques Hugging Face lisent depuis l’environnement de la charge de travail.

Dépanner l’accès secret et l’accès au modèle

Si la charge de travail échoue, retrouvez le symptôme dans le tableau suivant :

Problème Corriger
Le workload ne trouve ni le scope ni la clé. Confirmez que le périmètre et la clé dans le YAML de la charge de travail correspondent à ceux que vous avez créés dans l’espace de travail où vous soumettez la charge de travail.
Erreur d’autorisation du secret. Accorder à l’utilisateur ou au principal de service authentifié par l’interface CLI READ l’accès au scope. Voir la procédure précédente.
Hugging Face rejette le jeton (401). Vérifiez que le jeton est valide et dispose d’un accès en lecture au référentiel du modèle. Remplacez un jeton expiré ou révoqué.
GatedRepoError ou une réponse 403 pour un dépôt à accès restreint. Confirmez que l’accès du propriétaire du token au modèle a été approuvé et que le token a un accès en lecture à ce référentiel.

Environnements de base d’espace de travail

Un administrateur d’espace de travail peut construire un environnement de base de l’espace de travail pour AI Runtime, qui le rend accessible à tous les utilisateurs de l’espace via le menu déroulant Environnement de base. Pour plus d’informations, consultez Créer pour le calcul GPU sans serveur (AI Runtime).

Pour utiliser un environnement de base dans une charge de travail planifiée, référencez-le par son identifiant dans le environments bloc d’un travail ou d’un bundle. Par exemple, cette tâche Declarative Automation Bundles sélectionne l’environnement d’IA Databricks :

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

Pour un exemple complet de travail, voir Planifier les charges de travail GPU et composer les tâches.

Mise en cache de l’environnement et modules personnalisés

Quand les environnements sont-ils mis en cache ?

AI Runtime met en cache l’environnement de votre ordinateur portable, donc lorsque vous le rouvrez, vous n’avez pas besoin de réinstaller les paquets. Pour plus de détails, voir Réinitialiser les dépendances de l’environnement.

La mise en cache s’applique aux carnets interactifs. Les charges de travail qui passent par la air CLI ou sont planifiées comme des tâches n’utilisent pas ce cache ; chaque exécution installe ses dépendances de nouveau.

Par bonne pratique, épinglez les packages vers une version spécifique afin que votre environnement en cache reste valide et que vos exécutions restent reproductibles.

Comment importer des modules personnalisés ?

Les étapes suivantes montrent comment utiliser vos propres modules Python.

  1. Synchronisez votre code avec l’espace de travail. Clonez un dépôt Git dans l’espace de travail avec un dossier Git, ou téléchargez les fichiers directement en fichiers d’espace de travail. Stockez le code partagé sous /Workspace/Shared pour les projets d’équipe, ou dans un dossier utilisateur pour le développement personnel. Garder le code dans un dossier Git le maintient contrôlé par version.
  2. Ajoutez le dossier à sys.path et importez-le en haut de votre carnet ou script d’entraînement :
import sys
sys.path.append("/Workspace/Shared/my-project/src")
from my_module import my_function

Limitations

Les fonctionnalités suivantes ne sont pas disponibles sur AI Runtime :

  • Fonctions Spark : vous ne pouvez pas importer ou utiliser directement des fonctions PySpark. AI Runtime est un environnement Python uniquement ; Spark n’est pas disponible en tant que runtime local. Toutefois, Spark Connect est disponible pour le chargement des données. Consultez Charger des données sur AI Runtime.
  • Bibliothèques ML de Databricks Runtime : les paquets préinstallés ne remplacent pas Databricks Runtime ML. Certaines bibliothèques ML disponibles dans Databricks Runtime ML peuvent ne pas être préinstallées sur AI Runtime.
  • Artefacts privés : AI Runtime prend en charge les artefacts privés dans certains cas. Pour plus d’informations, contactez l’équipe de votre compte.