本頁面由 Cloud Translation API 翻譯而成。

在本機進行容器化及執行訓練程式碼

您可以使用 gcloud ai custom-jobs local-run 指令，根據訓練程式碼建構 Docker 容器映像檔，並在本機電腦上以容器形式執行該映像檔。這項功能的優點有：

您只需具備 Docker 的基本知識，就能建構容器映像檔。您不需要自行編寫 Dockerfile。您稍後可以將這個映像檔推送至 Artifact Registry，並用於自訂容器訓練。

如有進階需求，您可能仍想自行編寫 Dockerfile。
容器映像檔可以執行 Python 訓練應用程式或 Bash 指令碼。

您可以使用 Bash 指令碼執行以其他程式設計語言編寫的訓練程式碼 (只要您也指定支援其他語言的基本容器映像檔即可)。
在本地執行容器時，訓練程式碼的執行方式與在 Vertex AI 上執行時類似。

在本機執行程式碼有助於偵錯程式碼問題，再透過 Vertex AI 執行無伺服器訓練。

事前準備

設定 Vertex AI 開發環境。
安裝 Docker Engine。
如果您使用 Linux，請設定 Docker，這樣就能在不使用 sudo 的情況下執行 Docker。

local-run 指令需要這項設定才能使用 Docker。

使用 `local-run` 指令

執行下列指令，根據訓練程式碼建構容器映像檔，並在本機執行容器：

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME

更改下列內容：

BASE_IMAGE_URI：做為容器基礎的 Docker 映像檔 URI。選擇包含訓練程式碼所需依附元件的基本映像檔。

您可以將 URI 用於預先建構的訓練容器映像檔，或用於對 Dockerfile FROM 指令有效的任何其他值，例如公開的 Docker 映像檔，或您有權存取的 Artifact Registry 中的 Docker 映像檔。
WORKING_DIRECTORY：檔案系統中的最低層級目錄，內含所有訓練程式碼和本機依附元件，供您用於訓練。

根據預設，指令只會將 --script 旗標指定的檔案父項目錄 (請參閱下一個清單項目) 複製到產生的 Docker 映像檔。Docker 映像檔不一定會包含 WORKING_DIRECTORY 中的所有檔案；如要自訂要納入的檔案，請參閱本文中納入依附元件一節。

如果省略 --local-package-path 旗標 (和這個預留位置)，local-run 指令會使用目前的工作目錄做為這個值。
SCRIPT_PATH：相對於本機檔案系統上 WORKING_DIRECTORY 的路徑，這是訓練程式碼的進入點指令碼。可以是 Python 指令碼 (結尾為 .py) 或 Bash 指令碼。

舉例來說，如要執行 /hello-world/trainer/task.py，且 WORKING_DIRECTORY 為 /hello-world，請使用 trainer/task.py 做為這個值。

如果您指定 Python 指令碼，基本映像檔必須安裝 Python；如果您指定 Bash 指令碼，基本映像檔必須安裝 Bash。(所有預先建構的訓練容器和許多其他公開的 Docker 映像檔都包含這兩項依附元件)。

以 --python-module 取代 --script

如果省略 --script 標記 (和 SCRIPT_PATH)，則必須改用 --python-module 標記，在 WORKING_DIRECTORY 中指定要當做訓練進入點執行的 Python 模組名稱。舉例來說，您可能會指定 --python-module=trainer.task，而非 --script=trainer/task.py。

在這種情況下，產生的 Docker 容器會將程式碼載入為模組，而不是指令碼。如果進入點指令碼會匯入 WORKING_DIRECTORY 中的其他 Python 模組，您可能需要使用這個選項。
OUTPUT_IMAGE_NAME：指令建構的 Docker 映像檔名稱。您可以使用 docker build 的 -t 標記接受的任何值。

如果您打算稍後將映像檔推送至 Artifact Registry，建議使用符合 Artifact Registry 規定的映像檔名稱。 (或者，您也可以稍後為圖片加上其他名稱)。

如果省略 --output-image-uri 標記 (和這個預留位置)，local-run 指令會根據目前時間和進入點指令碼的檔案名稱，為映像檔加上標記。

這項指令會根據您的設定建構 Docker 容器映像檔。建構映像檔後，指令會列印下列輸出內容：

A training image is built.
Starting to run ...

然後，指令會立即使用這個容器映像檔，在本機電腦上執行容器。容器結束時，指令會列印下列輸出內容：

A local run is finished successfully using custom image: OUTPUT_IMAGE_NAME

其他選項

以下各節說明可用來自訂 local-run 指令行為的其他選項。

安裝依附元件

訓練程式碼可以依附於基本映像檔中安裝的任何依附元件 (例如預先建構的訓練容器映像檔包含許多機器學習 Python 程式庫)，以及您在 local-run 指令建立的 Docker 映像檔中納入的任何檔案。

使用 --script 旗標或 --python-module 旗標指定指令碼時，指令會將指令碼的父項目錄 (及其子目錄) 複製到 Docker 映像檔中。舉例來說，如果您指定 --local-package-path=/hello-world 和 --script=trainer/task.py，指令就會將 /hello-world/trainer/ 複製到 Docker 映像檔中。

您也可以加入其他 Python 依附元件，或檔案系統中的任意檔案，方法是完成下列其中一個章節所述的額外步驟：

使用 requirements.txt 檔案處理 Python 依附元件
使用 setup.py 檔案處理 Python 依附元件
指定個別 PyPI 依附元件
指定本機 Python 依附元件
包括其他檔案

安裝其他 Python 依附元件

您可以使用下列幾種方式，在 Docker 映像檔中加入其他 Python 依附元件：

使用 `requirements.txt` 檔案

如果工作目錄中有名為 requirements.txt 的檔案，local-run 指令會將其視為 pip 需求檔案，並用來在 Docker 映像檔中安裝 Python 依附元件。

使用 `setup.py` 檔案

如果工作目錄中有名為 setup.py 的檔案，local-run 指令會將其視為 Python setup.py 檔案，並將該檔案複製到 Docker 映像檔，然後在 Docker 映像檔中包含該檔案的目錄上執行 pip install。

舉例來說，您可以在 setup.py 中新增 install_requires 引數，以便在 Docker 映像檔中安裝 Python 依附元件。

指定個別 PyPI 依附元件

您可以使用 --requirements 標記，從 Docker 映像檔中的 PyPI 安裝特定依附元件。例如：

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --requirements=REQUIREMENTS

將 REQUIREMENTS 替換為以半形逗號分隔的 Python 需求條件指定符清單。

指定其他本機 Python 依附元件

您可以使用 --extra-packages 旗標安裝特定本機 Python 依附元件。這些 Python 依附元件必須位於工作目錄下，且每個依附元件的格式都必須是 pip install 支援的格式，例如 wheel 檔案或 Python 來源發布套件。

例如：

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --extra-packages=LOCAL_DEPENDENCIES

將 LOCAL_DEPENDENCIES 替換為以半形逗號分隔的本機檔案路徑清單，以相對於工作目錄的方式表示。

加入其他檔案

如要將其他目錄複製到 Docker 映像檔 (而不將這些目錄安裝為 Python 依附元件)，可以使用 --extra-dirs 旗標。您只能指定工作目錄下的目錄。例如：

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --extra-dirs=EXTRA_DIRECTORIES

將 EXTRA_DIRECTORIES 替換為以半形逗號分隔的本機目錄清單，以工作目錄為基準表示。

訓練應用程式引數

如果訓練應用程式的進入點指令碼需要指令列引數，您可以在執行 local-run 指令時指定這些引數。這些引數不會儲存在 Docker 映像檔中，而是在映像檔以容器形式執行時，以引數形式傳遞。

如要將引數傳遞至進入點指令碼，請在所有其他指令旗標之後，將 -- 引數和指令碼的引數傳遞至 local-run 指令。

舉例來說，假設您在本機執行下列指令的指令碼：

python /hello-world/trainer/task.py \
  --learning_rate=0.1 \
  --input_data=gs://BUCKET/small-dataset/

使用 local-run 指令時，您可以透過下列旗標，在容器中執行指令碼並使用相同引數：

gcloud ai custom-jobs local-run \\
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=/hello-world \
  --script=/trainer/task.py \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  -- \
  --learning_rate=0.1 \
  --input_data=gs://BUCKET/small-dataset/

使用 GPU 加速模型訓練

如果您最終想將 local-run 指令建立的 Docker 映像檔部署至 Vertex AI，並使用 GPU 進行訓練，請務必編寫可善用 GPU 的訓練程式碼，並使用支援 GPU 的 Docker 映像檔做為 --executor-image-uri 標記的值。舉例來說，您可以使用支援 GPU 的預建訓練容器映像檔。

如果本機電腦執行 Linux 且有 GPU，您也可以設定 local-run 指令，在本機執行容器時使用 GPU。這是選用步驟，但如果您想測試訓練程式碼搭配 GPU 的運作方式，這會很有幫助。請執行下列步驟：

如果尚未安裝，請在本機電腦上安裝 NVIDIA Container Toolkit (nvidia-docker)。

執行 local-run 指令時，請指定 --gpu 旗標。例如：

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --gpu

指定自訂服務帳戶

根據預設，當 local-run 指令在本機容器中執行訓練程式碼時，會透過應用程式預設憑證 (ADC)，將本機環境中可用的 Google Cloud 憑證裝載至容器，因此訓練程式碼可以使用 ADC 進行驗證，且憑證相同。換句話說，當您執行 local-run 指令時，ADC 可在程式碼中使用 ADC 在本機殼層中提供的憑證。

您可以使用 gcloud auth application-default login 指令，透過使用者帳戶使用 ADC，也可以在 Shell 中設定環境變數，透過服務帳戶使用 ADC。

如要讓容器使用 Google Cloud 憑證 (而非本機殼層中 ADC 提供的憑證) 執行，請按照下列步驟操作：

建立或選取服務帳戶，並授予訓練程式碼所需的存取權。
將這個服務帳戶的服務帳戶金鑰下載至本機電腦。
執行 local-run 指令時，請指定 --service-account-key-file 旗標。例如：
```
gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --service-account-key-file=KEY_PATH
```
將 KEY_PATH 替換為本機檔案系統中服務帳戶金鑰的路徑。這必須是絕對路徑，或是相對於殼層目前工作目錄的路徑，而非相對於 --local-package-path 旗標所指定目錄的路徑。

在產生的容器中，訓練程式碼可以使用 ADC，透過指定的服務帳戶憑證進行驗證。

與在 Vertex AI 上訓練的比較

在 Vertex AI 上執行無伺服器訓練時，Vertex AI 預設會使用專案的 Vertex AI Custom Code Service Agent 執行程式碼。您也可以附加其他服務帳戶，以進行無伺服器訓練。

使用 local-run 指令時，您無法以 Vertex AI 自訂程式碼服務代理身分進行驗證，但可以建立具有類似權限的服務帳戶，並在本地使用。

後續步驟

瞭解訓練代碼的相關規定。
瞭解如何將 Docker 映像檔推送至 Artifact Registry，以及如何將其做為自訂容器，在 Vertex AI 上進行訓練。

在本機進行容器化及執行訓練程式碼 透過集合功能整理內容 你可以依據偏好儲存及分類內容。