AI Runtime 快速入門

Databricks 建議從 Databricks CLI 開始執行你的第一個 AI Runtime 工作負載。 Databricks CLI 允許你從終端機提交、監控和管理無伺服器 GPU 工作負載。 如果你偏好筆記本,請參考 AI 執行時筆記本快速入門。

Requirements

  • 一個啟用 AI 執行環境的 Azure Databricks 工作空間。 請參閱 需求說明。
  • Databricks CLI 版本 1.24.0 或更高。 較早的版本缺少本快速入門所使用的 databricks air 指令、code_source 格式或加速器類型清單。
  • Git 已安裝在您的PATH上,且可用來執行 Python 範例。 CLI 使用 Git 來打包本地程式碼。

執行你的第一個工作負載

  1. 安裝或更新 Databricks CLI,並向你的工作區進行驗證。 請參閱 安裝或更新 Databricks CLI 和 Databricks CLI 的驗證。

    Tip

    若要為逐步導覽選取工作區而不重複 --profile,請列出你的設定檔並設定預設值:

    databricks auth profiles
    databricks auth switch --profile <profile>
    databricks auth describe
    

    檢查輸出中的 Host 是否為你想執行工作負載的工作區。 若是 shell-session 預設,請使用 export DATABRICKS_CONFIG_PROFILE=<profile> 。 此環境變數優先於由 auth switch 設定的預設值。

    若要覆蓋單一指令的任一預設,請附加 --profile <other-profile>。 提交、狀態和日誌使用相同的設定檔:工作執行 ID 屬於你提交工作負載的工作區。 請參閱 Databricks CLI 的設定設定檔。

    確認 CLI 版本是否為 1.24.0 以上,且 air 指令可用:

    databricks --version
    databricks air --help
    

    如果 databricks air --help 回傳 unknown command "air" for "databricks",你的 CLI 版本太舊了。 更新 CLI 並再試一次。

  2. 建立一個最小的工作負載檔案。 以下 workload.yaml 請求一個 A10 GPU,並執行 nvidia-smi 以列印 GPU 名稱:

    experiment_name: air-quickstart
    compute:
      num_accelerators: 1
      accelerator_type: GPU_1xA10
    command: nvidia-smi --query-gpu=name --format=csv,noheader
    

    accelerator_type 值的形式為 GPU_<GPUs per node>x<GPU model>,例如 GPU_1xA10、GPU_1xH100 或 GPU_8xH100。 所有值請參見 加速器類型。 要列出工作區中可用的加速器類型,請執行 databricks air run -h config.compute.accelerator_type。

  3. 提交工作負載並使用 databricks air run 串流其日誌:

    databricks air run --file workload.yaml --watch
    

    CLI 會回傳工作執行 ID 以及工作區中該次執行的連結。 --watch 保持終端機連接並串流日誌直到工作負載結束。

    Submitting experiment: air-quickstart
    Submitted workload with Job Run ID: 783940125630184
    View job run at: https://example.cloud.databricks.com/jobs/runs/783940125630184?o=1234567890123456
    
    Monitoring run and streaming logs...
    ...
    Environment setup completed at Thu Oct 1 14:23:45 UTC 2026
    NVIDIA A10
    

Tip

如果你想獲得撰寫工作負載設定和管理執行的協助,可以為你的 AI 代理安裝這個 databricks-ai-runtime 技能。 請參見「使用 AI Runtime 的代理技能」。

自己跑 Python 程式碼

要上傳並執行本地 Python 程式碼,請建立一個 air-quickstart 目錄,並放入以下檔案:

air-quickstart/
├── workload.yaml
└── src/
    └── main.py

Tip

要從可執行的專案開始,而非手動建立這些檔案,請克隆 AI Runtime cookbook repository,並切換到 CLI 的 getting-started 目錄:

git clone https://github.com/databricks-solutions/ai-runtime-cookbook.git
cd ai-runtime-cookbook/getting-started/air-cli

這個食譜專案將 main.py 與 workload.yaml 放在同一個目錄中,並使用 root_path: .,因此其版面配置與此處所示的不同。

請使用以下簡短的 Python 程式碼來驗證 AI Runtime 是否在 GPU 上執行上傳的程式碼:

import torch

print("Hello from Python on AI Runtime")
print(f"GPU: {torch.cuda.get_device_name(0)}")

為了延伸這個例子,你可以用自己的訓練、批次推論或其他 AI 應用程式來取代 src/main.py 。

請使用以下配置 workload.yaml:

experiment_name: python-quickstart
environment:
  version: databricks_ai_v6
compute:
  num_accelerators: 1
  accelerator_type: GPU_1xA10
code_source:
  root_path: ./src
command: python "$CODE_SOURCE_PATH/main.py"

此配置使用以下設定,並運行 src/main.py 於一顆 A10 顯示卡:

  • environment.version 會選取 Databricks AI 環境版本 6,其中包含 PyTorch。 此金鑰是選擇性的。 如果你省略它,CLI 會使用其預設值,也就是不包含 PyTorch 的 標準環境。 要查看預設版本,請執行 databricks air run -h config.environment.version。
  • root_path: ./src 會上傳與 workload.yaml 位於相同目錄中的 src 目錄。 執行時,$CODE_SOURCE_PATH 會指向已上傳的目錄。

預設輸出位置下, databricks air convert-to-dabs 當你 將工作負載轉換為套件時,需要將程式碼放在子目錄中,如同此版面配置所示。

Note

CLI 不會上傳 Git 忽略的檔案,包括被包覆的儲存庫忽略的檔案。 如果工作負載找不到 main.py,請執行 git check-ignore -v src 以檢查 src 目錄是否遭到忽略。 請參考code_source工作負載 YAML 參考資料。

在你自己的工作負載中,設定 environment.version 為固定程式碼依賴的預裝套件。 關於此鍵所接受的值,請參見 environment。 關於每個環境中的套件,請參見「設定你的 AI 執行環境」。

若要自備自己的相依性堆疊,請將該 environment 區塊替換為標準環境版本 6 及明確的相依關係:

environment:
  version: 6
  dependencies:
    - torch==2.11.0

CLI 工作負載會在每次執行時安裝這些相依關係。 此選項會增加 PyTorch 和 CUDA wheel 套件的下載時間。

從包含 workload.yaml 的目錄提交工作負載:

databricks air run --file workload.yaml --watch

串流日誌包括:

...
Hello from Python on AI Runtime
GPU: NVIDIA A10G

檢查並管理你的執行

每次執行都有一個工作執行 ID,databricks air run 會在你提交工作負載時列印此 ID。

若要在背景提交,請省略 --watch:

databricks air run --file workload.yaml

指令在提交後即返回,而工作負載則持續執行。 請使用回傳的工作執行 ID 和相同的工作區設定檔執行以下指令。

要檢查運行狀態、設定與時間,請執行:

databricks air get <job-run-id>

輸出包含工作執行的連結,以及(如有的話)的MLflow執行連結。

要查看執行日誌,請執行:

databricks air logs <job-run-id>

databricks air logs 列印現有的工作負載輸出,並在執行仍在進行時繼續串流。

使用工作執行連結檢查執行狀態、運算、嘗試次數及驅動程式輸出。 使用 MLflow 執行連結可查看持久日誌以及工作負載記錄的任何參數、指標和產物。

對於執行時間較長的工作負載,請使用 MLflow 的 系統指標 分頁來檢查自動收集的 GPU 使用率與記憶體。 若要記錄自訂指標與產物或比較執行,請參閱 實驗追蹤與可觀測性。

要列出包括已完成執行作業在內的執行作業,請執行:

databricks air list --all-status

要取消一個正在進行中的執行,請執行:

databricks air cancel <job-run-id>

若執行失敗,利用其狀態、日誌以及可用的工作或 MLflow 連結來識別可操作錯誤。 修正工作負載或設定,然後再提交一次。

繼續探索 Databricks CLI

這個快速入門使用最小的工作負載配置。 請參閱 工作負載 YAML 參考, 以設定環境、程式碼來源、運算、秘密、重試及其他設定。

如果標準環境不符合你的相依需求,可以使用 自訂的 Docker 映像檔。

要探索完整的訓練、微調、批次推論、分散式訓練及 Ray 工作負載,請複製 AI Runtime Cookbook 並執行食譜。

其他資源