Hermetic CUDA – Übersicht

Bei hermetischer CUDA wird eine bestimmte herunterladbare Version von CUDA anstelle der lokal installierten CUDA-Version des Nutzers verwendet. Bazel lädt CUDA-, CUDNN- und NCCL-Distributionen herunter und verwendet dann CUDA-Bibliotheken und ‑Tools als Abhängigkeiten in verschiedenen Bazel-Zielen. Dies ermöglicht reproduzierbarere Builds für ML-Projekte von Google und unterstützte CUDA-Versionen.

Unterstützte hermetische CUDA- und CUDNN-Versionen

Die unterstützten CUDA-Versionen sind im CUDA_REDIST_JSON_DICT-Wörterbuch third_party/gpus/cuda/hermetic/cuda_redist_versions.bzl angegeben.

Die unterstützten CUDNN-Versionen sind im CUDNN_REDIST_JSON_DICTWörterbuch third_party/gpus/cuda/hermetic/cuda_redist_versions.bzl angegeben.

In den .bazelrc-Dateien einzelner Projekte sind die Umgebungsvariablen HERMETIC_CUDA_VERSION und HERMETIC_CUDNN_VERSION auf die Versionen festgelegt, die standardmäßig verwendet werden, wenn --config=cuda in den Bazel-Befehlsoptionen angegeben ist.

Umgebungsvariablen zur Steuerung der hermetischen CUDA-/CUDNN-Versionen

Die Umgebungsvariable HERMETIC_CUDA_VERSION sollte aus der Haupt-, Neben- und Patch-CUDA-Version bestehen, z. B. 12.3.2. Die Umgebungsvariable HERMETIC_CUDNN_VERSION sollte aus der Haupt-, Neben- und Patchversion von CUDNN bestehen, z. B. 9.1.1.

Es gibt drei Möglichkeiten, die Umgebungsvariablen für Bazel-Befehle festzulegen:

# Add an entry to your `.bazelrc` file
build:cuda --repo_env=HERMETIC_CUDA_VERSION="12.3.2"
build:cuda --repo_env=HERMETIC_CUDNN_VERSION="9.1.1"

# OR pass it directly to your specific build command
bazel build --config=cuda <target> \
--repo_env=HERMETIC_CUDA_VERSION="12.3.2" \
--repo_env=HERMETIC_CUDNN_VERSION="9.1.1"

# If .bazelrc doesn't have corresponding entries and the environment variables
# are not passed to bazel command, you can set them globally in your shell:
export HERMETIC_CUDA_VERSION="12.3.2"
export HERMETIC_CUDNN_VERSION="9.1.1"

Wenn HERMETIC_CUDA_VERSION und HERMETIC_CUDNN_VERSION nicht vorhanden sind, werden in den hermetischen CUDA-/CUDNN-Repository-Regeln die Werte der Umgebungsvariablen TF_CUDA_VERSION und TF_CUDNN_VERSION abgerufen. Dies dient der Abwärtskompatibilität mit nicht hermetischen CUDA-/CUDNN-Repository-Regeln.

Die Zuordnung zwischen CUDA-Version und heruntergeladener NCCL-Distributionsversion ist in third_party/gpus/cuda/hermetic/cuda_redist_versions.bzl angegeben.

Hermetisches CUDA konfigurieren

  1. Fügen Sie im von XLA abhängigen nachgelagerten Projekt am Ende der Datei WORKSPACE die folgenden Zeilen hinzu:

    load(
       "@tsl//third_party/gpus/cuda/hermetic:cuda_json_init_repository.bzl",
       "cuda_json_init_repository",
    )
    
    cuda_json_init_repository()
    
    load(
       "@cuda_redist_json//:distributions.bzl",
       "CUDA_REDISTRIBUTIONS",
       "CUDNN_REDISTRIBUTIONS",
    )
    load(
       "@tsl//third_party/gpus/cuda/hermetic:cuda_redist_init_repositories.bzl",
       "cuda_redist_init_repositories",
       "cudnn_redist_init_repository",
    )
    
    cuda_redist_init_repositories(
       cuda_redistributions = CUDA_REDISTRIBUTIONS,
    )
    
    cudnn_redist_init_repository(
       cudnn_redistributions = CUDNN_REDISTRIBUTIONS,
    )
    
    load(
       "@tsl//third_party/gpus/cuda/hermetic:cuda_configure.bzl",
       "cuda_configure",
    )
    
    cuda_configure(name = "local_config_cuda")
    
    load(
       "@tsl//third_party/nccl/hermetic:nccl_redist_init_repository.bzl",
       "nccl_redist_init_repository",
    )
    
    nccl_redist_init_repository()
    
    load(
       "@tsl//third_party/nccl/hermetic:nccl_configure.bzl",
       "nccl_configure",
    )
    
    nccl_configure(name = "local_config_nccl")
    
  2. Wenn Sie bestimmte Versionen von hermetischen CUDA- und CUDNN-Bibliotheken auswählen möchten, legen Sie die Umgebungsvariablen HERMETIC_CUDA_VERSION und HERMETIC_CUDNN_VERSION fest. Verwenden Sie nur unterstützte Versionen. Sie können die Umgebungsvariablen direkt in der Shell oder in der Datei .bazelrc festlegen, wie unten gezeigt:

    build:cuda --repo_env=HERMETIC_CUDA_VERSION="12.3.2"
    build:cuda --repo_env=HERMETIC_CUDNN_VERSION="9.1.1"
    build:cuda --repo_env=HERMETIC_CUDA_COMPUTE_CAPABILITIES="sm_50,sm_60,sm_70,sm_80,compute_90"
    
  3. Wenn Sie hermetisches CUDA während der Testausführung oder beim Ausführen eines Binärprogramms über bazel aktivieren möchten, fügen Sie dem bazel-Befehl das Flag --@local_config_cuda//cuda:include_cuda_libs=true hinzu. Sie können sie entweder direkt in einer Shell oder in .bazelrc angeben:

    build:cuda --@local_config_cuda//cuda:include_cuda_libs=true
    

    Das Flag ist erforderlich, damit CUDA-Abhängigkeiten für das Testen von ausführbaren Dateien korrekt bereitgestellt werden. Das Flag ist standardmäßig auf „false“ gesetzt, um eine unerwünschte Kopplung von von Google veröffentlichten Python-Wheels mit CUDA-Binärdateien zu vermeiden.

  4. Wenn Sie den CUDA-Forward-Kompatibilitätsmodus erzwingen möchten, fügen Sie dem bazel-Befehl das Flag --@cuda_driver//:enable_forward_compatibility=true hinzu. Sie können sie entweder direkt in einer Shell oder in .bazelrc angeben:

    test:cuda --@cuda_driver//:enable_forward_compatibility=true
    

    Der Standardwert für das Flag ist false.

    Wenn der CUDA-Forward-Kompatibilitätsmodus deaktiviert ist, verwenden Bazel-Ziele den Nutzermodus und die Kernel-Modus-Treiber, die auf dem System vorinstalliert sind.

    Wenn der CUDA-Modus für die zukünftige Kompatibilität aktiviert ist, verwenden Bazel-Ziele den User-Mode-Treiber aus der CUDA-Treiberweitergabe, der in den Bazel-Cache heruntergeladen wurde, und den im System vorinstallierten Kernel-Mode-Treiber. So können neue CUDA-Toolkit-Funktionen aktiviert werden, während ein älterer Kernel-Modus-Treiber verwendet wird.

    Der Vorwärtskompatibilitätsmodus sollte nur erzwungen werden, wenn dies angemessen ist. Weitere Informationen finden Sie in der NVIDIA-Dokumentation.

Hermetische CUDA-/CUDNN-Version aktualisieren

  1. Erstellen und senden Sie einen Pull-Request mit aktualisierten CUDA_REDIST_JSON_DICT- und CUDA_REDIST_JSON_DICT-Wörterbüchern in third_party/gpus/cuda/hermetic/cuda_redist_versions.bzl.

    Aktualisieren Sie bei Bedarf CUDA_NCCL_WHEELS in third_party/gpus/cuda/hermetic/cuda_redist_versions.bzl.

    Aktualisieren Sie bei Bedarf REDIST_VERSIONS_TO_BUILD_TEMPLATES in third_party/gpus/cuda/hermetic/cuda_redist_versions.bzl.

  2. Erstellen Sie für jedes Google ML-Projekt eine separate Pull-Anfrage mit aktualisierten HERMETIC_CUDA_VERSION und HERMETIC_CUDNN_VERSION in der Datei .bazelrc.

    Bei der Ausführung von Jobs vor der Einreichung des PR werden Bazel-Tests gestartet und hermetische CUDA-/CUDNN-Distributionen heruntergeladen. Prüfen Sie, ob die Jobs vor dem Einreichen bestanden haben, bevor Sie den PR einreichen.

Auf Umverteilung von CUDA/CUDNN/NCCL im lokalen Dateisystem verweisen

Sie können die lokalen CUDA-/CUDNN-/NCCL-Verzeichnisse als Quelle für die Weiterverteilung verwenden. Die folgenden zusätzlichen Umgebungsvariablen sind erforderlich:

LOCAL_CUDA_PATH
LOCAL_CUDNN_PATH
LOCAL_NCCL_PATH

Beispiel:

# Add an entry to your `.bazelrc` file
build:cuda --repo_env=LOCAL_CUDA_PATH="/foo/bar/nvidia/cuda"
build:cuda --repo_env=LOCAL_CUDNN_PATH="/foo/bar/nvidia/cudnn"
build:cuda --repo_env=LOCAL_NCCL_PATH="/foo/bar/nvidia/nccl"

# OR pass it directly to your specific build command
bazel build --config=cuda <target> \
--repo_env=LOCAL_CUDA_PATH="/foo/bar/nvidia/cuda" \
--repo_env=LOCAL_CUDNN_PATH="/foo/bar/nvidia/cudnn" \
--repo_env=LOCAL_NCCL_PATH="/foo/bar/nvidia/nccl"

# If .bazelrc doesn't have corresponding entries and the environment variables
# are not passed to bazel command, you can set them globally in your shell:
export LOCAL_CUDA_PATH="/foo/bar/nvidia/cuda"
export LOCAL_CUDNN_PATH="/foo/bar/nvidia/cudnn"
export LOCAL_NCCL_PATH="/foo/bar/nvidia/nccl"

Die Struktur der Ordner im CUDA-Verzeichnis sollte so aussehen, als wären die archivierten Redistributions an einem Ort entpackt worden:

<LOCAL_CUDA_PATH>/
    include/
    bin/
    lib/
    nvvm/

Die Ordnerstruktur im CUDNN-Verzeichnis sollte so aussehen:

<LOCAL_CUDNN_PATH>
    include/
    lib/

Die Struktur der Ordner im NCCL-Verzeichnis sollte so aussehen:

<LOCAL_NCCL_PATH>
    include/
    lib/

Benutzerdefinierte CUDA-/CUDNN-Archive und NCCL-Wheels

Es gibt drei Möglichkeiten, benutzerdefinierte CUDA-/CUDNN-Distributionen zu verwenden.

Benutzerdefinierte CUDA/CUDNN-Umverteilung von JSON-Dateien

Mit dieser Option können benutzerdefinierte Verteilungen für alle CUDA/CUDNN-Abhängigkeiten in Google ML-Projekten verwendet werden.

  1. Erstellen Sie cuda_redist.json- und/oder cudnn_redist.json-Dateien.

    cuda_redist.json-Sendungen haben das folgende Format:

    {
       "cuda_cccl": {
          "linux-x86_64": {
             "relative_path": "cuda_cccl-linux-x86_64-12.4.99-archive.tar.xz",
          },
          "linux-sbsa": {
             "relative_path": "cuda_cccl-linux-sbsa-12.4.99-archive.tar.xz",
          }
       },
    }
    

    cudnn_redist.json-Anzeigen müssen dem folgenden Format entsprechen:

    {
       "cudnn": {
          "linux-x86_64": {
             "cuda12": {
             "relative_path": "cudnn/linux-x86_64/cudnn-linux-x86_64-9.0.0.312_cuda12-archive.tar.xz",
             }
          },
          "linux-sbsa": {
             "cuda12": {
             "relative_path": "cudnn/linux-sbsa/cudnn-linux-sbsa-9.0.0.312_cuda12-archive.tar.xz",
             }
          }
       }
    }
    

    Das Feld relative_path kann durch full_path ersetzt werden, wenn es sich um vollständige URLs und absolute lokale Pfade handelt, die mit file:/// beginnen.

  2. Aktualisieren Sie im von XLA abhängigen nachgelagerten Projekt den JSON-Repository-Aufruf hermetic cuda in der Datei WORKSPACE. Sowohl Weblinks als auch lokale Dateipfade sind zulässig. Beispiel:

    _CUDA_JSON_DICT = {
       "12.4.0": [
          "file:///home/user/Downloads/redistrib_12.4.0_updated.json",
       ],
    }
    
    _CUDNN_JSON_DICT = {
       "9.0.0": [
          "https://developer.download.nvidia.com/compute/cudnn/redist/redistrib_9.0.0.json",
       ],
    }
    
    cuda_json_init_repository(
       cuda_json_dict = _CUDA_JSON_DICT,
       cudnn_json_dict = _CUDNN_JSON_DICT,
    )
    

    Wenn JSON-Dateien relative Pfade zu Verteilungen enthalten, sollte das Pfadpräfix in cuda_redist_init_repositories()- und cudnn_redist_init_repository()-Aufrufen aktualisiert werden. Beispiel

    cuda_redist_init_repositories(
       cuda_redistributions = CUDA_REDISTRIBUTIONS,
       cuda_redist_path_prefix = "file:///usr/Downloads/dists/",
    )
    

Benutzerdefinierte CUDA/CUDNN-Verteilungen

Mit dieser Option können Sie benutzerdefinierte Distributionen für einige CUDA-/CUDNN-Abhängigkeiten in Google ML-Projekten verwenden.

  1. Entfernen Sie im Downstream-Projekt, das von XLA abhängig ist, die folgenden Zeilen:

    <...>
       "CUDA_REDIST_JSON_DICT",
    <...>
       "CUDNN_REDIST_JSON_DICT",
    <...>
    
    cuda_json_init_repository(
       cuda_json_dict = CUDA_REDIST_JSON_DICT,
       cudnn_json_dict = CUDNN_REDIST_JSON_DICT,
    )
    
    load(
       "@cuda_redist_json//:distributions.bzl",
       "CUDA_REDISTRIBUTIONS",
       "CUDNN_REDISTRIBUTIONS",
    )
    
  2. Erstellen Sie in derselben WORKSPACE-Datei Wörterbücher mit Distributionspfaden.

    Das Wörterbuch mit CUDA-Distributionen hat folgendes Format:

    _CUSTOM_CUDA_REDISTRIBUTIONS = {
       "cuda_cccl": {
          "linux-x86_64": {
             "relative_path": "cuda_cccl-linux-x86_64-12.4.99-archive.tar.xz",
          },
          "linux-sbsa": {
             "relative_path": "cuda_cccl-linux-sbsa-12.4.99-archive.tar.xz",
          }
       },
    }
    

    Das Wörterbuch mit CUDNN-Distributionen hat folgendes Format:

    _CUSTOM_CUDNN_REDISTRIBUTIONS = {
       "cudnn": {
          "linux-x86_64": {
             "cuda12": {
             "relative_path": "cudnn/linux-x86_64/cudnn-linux-x86_64-9.0.0.312_cuda12-archive.tar.xz",
             }
          },
          "linux-sbsa": {
             "cuda12": {
             "relative_path": "cudnn/linux-sbsa/cudnn-linux-sbsa-9.0.0.312_cuda12-archive.tar.xz",
             }
          }
       }
    }
    

    Das Feld relative_path kann durch full_path ersetzt werden, wenn es sich um vollständige URLs und absolute lokale Pfade handelt, die mit file:/// beginnen.

  3. Übergeben Sie in derselben WORKSPACE-Datei die erstellten Wörterbücher an die Repository-Regel. Wenn die Wörterbücher relative Pfade zu Distributionen enthalten, sollte das Pfadpräfix in den cuda_redist_init_repositories()- und cudnn_redist_init_repository()-Aufrufen aktualisiert werden.

    cuda_redist_init_repositories(
       cuda_redistributions = _CUSTOM_CUDA_REDISTRIBUTIONS,
       cuda_redist_path_prefix = "file:///home/usr/Downloads/dists/",
    )
    
    cudnn_redist_init_repository(
       cudnn_redistributions = _CUSTOM_CUDNN_REDISTRIBUTIONS,
       cudnn_redist_path_prefix = "file:///home/usr/Downloads/dists/cudnn/"
    )
    

    Kombination der oben genannten Optionen

Im folgenden Beispiel wird CUDA_REDIST_JSON_DICT mit benutzerdefinierten JSON-Daten in _CUDA_JSON_DICT zusammengeführt und CUDNN_REDIST_JSON_DICT mit _CUDNN_JSON_DICT.

Die Verteilungsdaten in _CUDA_DIST_DICT überschreiben den Inhalt der resultierenden CUDA-JSON-Datei und die Verteilungsdaten in _CUDNN_DIST_DICT überschreiben den Inhalt der resultierenden CUDNN-JSON-Datei. Die NCCL-Raddaten werden aus CUDA_NCCL_WHEELS und _NCCL_WHEEL_DICT zusammengeführt.

load(
    //third_party/gpus/cuda/hermetic:cuda_redist_versions.bzl",
    "CUDA_REDIST_PATH_PREFIX",
    "CUDA_NCCL_WHEELS",
    "CUDA_REDIST_JSON_DICT",
    "CUDNN_REDIST_PATH_PREFIX",
    "CUDNN_REDIST_JSON_DICT",
)

_CUDA_JSON_DICT = {
   "12.4.0": [
      "file:///usr/Downloads/redistrib_12.4.0_updated.json",
   ],
}

_CUDNN_JSON_DICT = {
   "9.0.0": [
      "https://developer.download.nvidia.com/compute/cudnn/redist/redistrib_9.0.0.json",
   ],
}

cuda_json_init_repository(
   cuda_json_dict = CUDA_REDIST_JSON_DICT | _CUDA_JSON_DICT,
   cudnn_json_dict = CUDNN_REDIST_JSON_DICT | _CUDNN_JSON_DICT,
)

load(
   "@cuda_redist_json//:distributions.bzl",
   "CUDA_REDISTRIBUTIONS",
   "CUDNN_REDISTRIBUTIONS",
)

load(
   "//third_party/gpus/cuda/hermetic:cuda_redist_init_repositories.bzl",
   "cuda_redist_init_repositories",
   "cudnn_redist_init_repository",
)

_CUDA_DIST_DICT = {
   "cuda_cccl": {
      "linux-x86_64": {
            "relative_path": "cuda_cccl-linux-x86_64-12.4.99-archive.tar.xz",
      },
      "linux-sbsa": {
            "relative_path": "cuda_cccl-linux-sbsa-12.4.99-archive.tar.xz",
      },
   },
   "libcusolver": {
      "linux-x86_64": {
            "full_path": "file:///usr/Downloads/dists/libcusolver-linux-x86_64-11.6.0.99-archive.tar.xz",
      },
      "linux-sbsa": {
         "relative_path": "libcusolver-linux-sbsa-11.6.0.99-archive.tar.xz",
      },
   },
}

_CUDNN_DIST_DICT = {
   "cudnn": {
      "linux-x86_64": {
            "cuda12": {
               "relative_path": "cudnn-linux-x86_64-9.0.0.312_cuda12-archive.tar.xz",
            },
      },
      "linux-sbsa": {
            "cuda12": {
               "relative_path": "cudnn-linux-sbsa-9.0.0.312_cuda12-archive.tar.xz",
            },
      },
   },
}

cudnn_redist_init_repositories(
   cuda_redistributions = CUDA_REDISTRIBUTIONS | _CUDA_DIST_DICT,
   cuda_redist_path_prefix = "file:///usr/Downloads/dists/",
)

cudnn_redist_init_repository(
   cudnn_redistributions = CUDNN_REDISTRIBUTIONS | _CUDNN_DIST_DICT,
   cudnn_redist_path_prefix = "file:///usr/Downloads/dists/cudnn/"
)

load(
    "//third_party/nccl/hermetic:nccl_redist_init_repository.bzl",
    "nccl_redist_init_repository",
)

_NCCL_WHEEL_DICT = {
   "12.4.0": {
      "x86_64-unknown-linux-gnu": {
            "url": "https://files.pythonhosted.org/packages/38/00/d0d4e48aef772ad5aebcf70b73028f88db6e5640b36c38e90445b7a57c45/nvidia_nccl_cu12-2.19.3-py3-none-manylinux1_x86_64.whl",
      },
   },
}

nccl_redist_init_repository(
   cuda_nccl_wheels = CUDA_NCCL_WHEELS | _NCCL_WHEEL_DICT,
)

EINGESTELLT: Nicht hermetische CUDA/CUDNN-Nutzung

Obwohl die nicht hermetische CUDA/CUDNN-Nutzung eingestellt wurde, kann sie für einige Tests verwendet werden, die derzeit offiziell nicht unterstützt werden (z. B. das Erstellen von Rädern unter Windows mit CUDA).

So verwenden Sie nicht hermetische CUDA-Versionen, die lokal in Google ML-Projekten installiert sind:

  1. Löschen Sie Aufrufe von hermetischen CUDA-Repository-Regeln aus der WORKSPACE-Datei des XLA-abhängigen Projekts.

  2. Fügen Sie die Aufrufe nicht hermetischer CUDA-Repository-Regeln unten in die Datei WORKSPACE ein.

    Für XLA und JAX:

    load("@tsl//third_party/gpus:cuda_configure.bzl", "cuda_configure")
    cuda_configure(name = "local_config_cuda")
    load("@tsl//third_party/nccl:nccl_configure.bzl", "nccl_configure")
    nccl_configure(name = "local_config_nccl")
    

    Für TensorFlow:

    load("@local_tsl//third_party/gpus:cuda_configure.bzl", "cuda_configure")
    cuda_configure(name = "local_config_cuda")
    load("@local_tsl//third_party/nccl:nccl_configure.bzl", "nccl_configure")
    nccl_configure(name = "local_config_nccl")
    
  3. Legen Sie die folgenden Umgebungsvariablen direkt in Ihrer Shell oder in der Datei .bazelrc fest, wie unten gezeigt:

    build:cuda --action_env=TF_CUDA_VERSION=<locally installed cuda version>
    build:cuda --action_env=TF_CUDNN_VERSION=<locally installed cudnn version>
    build:cuda --action_env=TF_CUDA_COMPUTE_CAPABILITIES=<CUDA compute capabilities>
    build:cuda --action_env=LD_LIBRARY_PATH=<CUDA/CUDNN libraries folder locations divided by : sign>
    build:cuda --action_env=CUDA_TOOLKIT_PATH=<preinstalled CUDA folder location>
    build:cuda --action_env=TF_CUDA_PATHS=<preinstalled CUDA/CUDNN folder locations divided by , sign>
    build:cuda --action_env=NCCL_INSTALL_PATH=<preinstalled NCCL library folder location>
    

    TF_CUDA_VERSION und TF_CUDNN_VERSION sollten nur aus Haupt- und Nebenversionen bestehen (z.B. 12.3 für CUDA und 9.1 für CUDNN).

  4. Sie können jetzt den Befehl bazel ausführen, um lokal installierte CUDA- und CUDNN-Versionen zu verwenden.

    Für XLA sind keine Änderungen an den Befehlsoptionen erforderlich.

    Verwenden Sie für JAX das Flag --override_repository=tsl=<tsl_path> in den Bazel-Befehlsoptionen.

    Verwenden Sie für TensorFlow das Flag --override_repository=local_tsl=<tsl_path> in den Bazel-Befehlsoptionen.