自带集装箱 (BYOC) - Amazon Braket
什么时候自带集装箱才是正确的决定？自带集装箱的食谱在自己的容器中运行 Braket 混合作业

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

自带集装箱 (BYOC)

Amazon Braket Hybrid Jobs 提供了三个预先构建的容器，用于在不同的环境中运行代码。如果其中一个容器支持您的用例，则只需在创建混合作业时提供算法脚本即可。可以从算法脚本或使用requirements.txt文件中添加少量缺失的依赖关系pip。

如果这些容器都不支持你的用例，或者你想对其进行扩展，Braket Hybrid Jobs 支持使用你自己的自定义Docker容器镜像运行混合作业，或者自带容器 (BYOC)。但是在我们深入探讨之前，让我们确保它实际上是适合你的用例的功能。

什么时候自带集装箱才是正确的决定？

将自己的容器 (BYOC) 带到 Braket Hybrid Jobs 中，通过将自己的软件安装在打包环境中，可以灵活地使用自己的软件。根据您的具体需求，可能有一些方法可以实现同样的灵活性，而不必经历完整的BYOC Docker构建-Amazon ECR 上传-自定义图像 URI 周期。

注意

如果您想添加少量其他 Python 软件包（通常少于 10 个），且这些软件包已公开发布，BYOC 可能不是正确的选择。例如，如果你正在使用 PyPi.

在这种情况下，您可以使用其中一个预先构建的 Braket 镜像，然后在作业提交时在源目录中加入一个requirements.txt文件。该文件会自动读取，pip并将照常安装具有指定版本的软件包。如果您要安装大量软件包，则作业的运行时间可能会大大增加。检查要用来测试软件能否运行的预构建容器的 Python 和 CUDA 版本（如果适用）。

当你想在作业脚本中使用非 Python 语言（如 C++ 或 Rust），或者你想使用无法通过 Braket 预建容器提供的 Python 版本时，BYOC 是必需的。在以下情况下，这也是一个不错的选择：

  • 您正在使用带有许可证密钥的软件，需要通过许可服务器对该密钥进行身份验证才能运行该软件。使用 BYOC，您可以将许可证密钥嵌入Docker图像中，并包含用于对其进行身份验证的代码。

  • 你使用的软件不是公开的。例如，该软件托管在私有 GitHub 存储库 GitLab 或存储库上，您需要使用特定 SSH 密钥才能访问该存储库。

  • 您需要安装一套未打包在 Braket 提供的容器中的大型软件。BYOC 将允许您消除由于安装软件而导致混合作业容器的启动时间过长。

BYOC 还允许您使用您的软件构建Docker容器并将其提供给用户，从而使您的自定义 SDK 或算法可供客户使用。为此，您可以在 Amazon ECR 中设置适当的权限。

注意

您必须遵守所有适用的软件许可证。

自带集装箱的食谱

在本节中，我们提供了 Braket Hybrid Jobs 需要做什么的 step-by-step 指南，包括脚本、文件和将它们组合在一起的步骤，以便启动和运行自定义Docker映像。bring your own container (BYOC)我们提供两种常见案例的食谱：

  1. 在Docker镜像中安装其他软件，并在作业中仅使用 Python 算法脚本。

  2. 使用使用非 Python 语言编写的算法脚本与 Hybrid Jobs 或 x86 之外的 CPU 架构搭配使用。

对于案例 2，定义容器入口脚本更为复杂。

当 Braket 运行您的混合任务时，它会启动所请求的数量和类型的 Amazon EC2 实例，然后运行在Docker这些实例上创建任务时输入的图像 URI 所指定的映像。使用 BYOC 功能时，您可以指定托管在您拥有读取权限的私有 Amazon ECR 存储库中的图像 URI。Braket Hybrid Jobs 使用该自定义镜像来运行作业。

构建可用于 Hybrid Jobs 的Docker映像所需的特定组件。如果您不熟悉编写和构建Dockerfiles，我们建议您在阅读这些说明时根据需要参阅 Dockerfile 文档和Amazon ECR CLI文档。

你的 Dockerfile 的基础镜像

如果您使用的是 Python，并且想要在 Braket 提供的容器中提供的内容之上安装软件，那么基础映像的一个选项是托管在我们的GitHub 存储库和 Amazon ECR 上的 Brake t 容器镜像。您需要向 Amazon ECR 进行身份验证才能提取映像并在其上进行构建。例如，您的 BYOC Docker 文件的第一行可能是：FROM [IMAGE_URI_HERE]

接下来，填写Dockerfile要安装的其余部分，然后设置要添加到容器中的软件。预先构建的 Braket 镜像已经包含了相应的容器入口点脚本，因此您无需担心包含该脚本。

如果你想使用非 Python 语言，例如 C++、Rust 或 Julia，或者你想为非 x86 CPU 架构（例如 ARM）构建镜像，则可能需要在基本公共镜像的基础上构建。您可以在 Amazon Elastic Container Registry 公共图库中找到许多这样的图片。请务必选择适合 CPU 架构的 GPU，必要时还要选择要使用的 GPU。

（可选）修改后的容器入口点脚本

注意

如果您只是在预先构建的 Braket 镜像中添加其他软件，则可以跳过本节。

要在混合作业中运行非 Python 代码，您需要修改定义容器入口点的 Python 脚本。例如，亚马逊 Braket braket_container.py Github 上的 python 脚本。这是 Braket 预先构建的图像用来启动算法脚本和设置相应环境变量的脚本。容器入口点脚本本身必须使用 Python，但可以启动非 Python 脚本。在预先构建的示例中，您可以看到 Python 算法脚本要么作为 Python 子进程启动，要么作为全新的进程启动。通过修改此逻辑，您可以启用入口点脚本来启动非 Python 算法脚本。例如，您可以修改thekick_off_customer_script()函数以启动 Rust 进程，具体取决于文件扩展名的结尾。

你也可以选择写一个全新的东西braket_container.py。它应将输入数据、源档案和其他必要文件从 Amazon S3 复制到容器中，并定义相应的环境变量。

安装Dockerfile所有必需的软件并包含容器脚本

注意

如果您使用预先构建的 Braket 镜像作为Docker基础镜像，则容器脚本已经存在。

如果您在上一步中创建了修改后的容器脚本，则需要将其复制到容器中，然后将环境变量SAGEMAKER_PROGRAM定义为新容器入口点脚本braket_container.py，或者定义您为新容器入口点脚本命名的变量。

以下是允许您在 GPU 加速任务实例上使用 Julia 的示例：Dockerfile

FROM nvidia/cuda:12.2.0-devel-ubuntu22.04

    
 ARG DEBIAN_FRONTEND=noninteractive
 ARG JULIA_RELEASE=1.8
 ARG JULIA_VERSION=1.8.3


 ARG PYTHON=python3.11 
 ARG PYTHON_PIP=python3-pip
 ARG PIP=pip


 ARG JULIA_URL = https://julialang-s3.julialang.org/bin/linux/x64/${JULIA_RELEASE}/
 ARG TAR_NAME = julia-${JULIA_VERSION}-linux-x86_64.tar.gz


 ARG PYTHON_PKGS = # list your Python packages and versions here


 RUN curl -s -L ${JULIA_URL}/${TAR_NAME} | tar -C /usr/local -x -z --strip-components=1 -f -


 RUN apt-get update \

    && apt-get install -y --no-install-recommends \

    build-essential \

    tzdata \

    openssh-client \

    openssh-server \

    ca-certificates \

    curl \

    git \

    libtemplate-perl \

    libssl1.1 \

    openssl \

    unzip \ 

    wget \

    zlib1g-dev \

    ${PYTHON_PIP} \

    ${PYTHON}-dev \




 RUN ${PIP} install --no-cache --upgrade ${PYTHON_PKGS}


 RUN ${PIP} install --no-cache --upgrade sagemaker-training==4.1.3


 # Add EFA and SMDDP to LD library path
 ENV LD_LIBRARY_PATH="/opt/conda/lib/python${PYTHON_SHORT_VERSION}/site-packages/smdistributed/dataparallel/lib:$LD_LIBRARY_PATH"
 ENV LD_LIBRARY_PATH=/opt/amazon/efa/lib/:$LD_LIBRARY_PATH


 # Julia specific installation instructions
 COPY Project.toml /usr/local/share/julia/environments/v${JULIA_RELEASE}/
 RUN JULIA_DEPOT_PATH=/usr/local/share/julia \

    julia -e 'using Pkg; Pkg.instantiate(); Pkg.API.precompile()'
 # generate the device runtime library for all known and supported devices
 RUN JULIA_DEPOT_PATH=/usr/local/share/julia \

    julia -e 'using CUDA; CUDA.precompile_runtime()'


 # Open source compliance scripts
 RUN HOME_DIR=/root \

 && curl -o ${HOME_DIR}/oss_compliance.zip https://aws-dlinfra-utilities.s3.amazonaws.com/oss_compliance.zip \

 && unzip ${HOME_DIR}/oss_compliance.zip -d ${HOME_DIR}/ \

 && cp ${HOME_DIR}/oss_compliance/test/testOSSCompliance /usr/local/bin/testOSSCompliance \

 && chmod +x /usr/local/bin/testOSSCompliance \

 && chmod +x ${HOME_DIR}/oss_compliance/generate_oss_compliance.sh \

 && ${HOME_DIR}/oss_compliance/generate_oss_compliance.sh ${HOME_DIR} ${PYTHON} \

 && rm -rf ${HOME_DIR}/oss_compliance*


 # Copying the container entry point script
 COPY braket_container.py /opt/ml/code/braket_container.py
 ENV SAGEMAKER_PROGRAM braket_container.py

此示例下载并运行提供的脚本 AWS ，以确保符合所有相关的开源许可证。例如，通过正确归因任何受控制的已安装代码。MIT license

如果您需要包含非公开代码，例如托管在私有代码 GitHub 或 GitLab 存储库中的代码，请不要在Docker映像中嵌入 SSH 密钥来访问它。相反，请在构建Docker Compose时使用Docker，以允许在其构建的主机上访问 SSH。有关更多信息，请参阅《在 Docker 中安全使用 SSH 密钥访问私有 Github 存储库指南》。

创建和上传您的Docker图片

有了正确定义的Dockerfile，您现在就可以按照步骤创建私有 Amazon ECR 存储库了（如果尚不存在）。您也可以构建、标记容器映像并将其上传到存储库。

您已准备好构建、标记和推送映像。有关选项的完整说明docker build和一些示例，请参阅 Docker 构建文档。

对于上面定义的示例文件，你可以运行：

aws ecr get-login-password --region ${your_region} | docker login --username AWS --password-stdin ${aws_account_id}.dkr.ecr.${your_region}.amazonaws.com
 docker build -t braket-julia .
 docker tag braket-julia:latest ${aws_account_id}.dkr.ecr.${your_region}.amazonaws.com/braket-julia:latest
 docker push ${aws_account_id}.dkr.ecr.${your_region}.amazonaws.com/braket-julia:latest

分配相应的 Amazon ECR 权限

Braket Hybrid Jobs Docker图片必须托管在私有 Amazon ECR 存储库中。默认情况下，私有 Amazon ECR 存储库不向Braket Hybrid Jobs IAM role或任何其他想要使用您的图像的用户（例如合作者或学生）提供读取权限。您必须设置存储库策略才能授予相应的权限。通常，仅向您想要访问图像的特定用户和IAM角色授予权限，而不允许任何人提取图像。image URI

在自己的容器中运行 Braket 混合作业

要使用自己的容器创建混合作业，请AwsQuantumJob.create()使用image_uri指定的参数调用。你可以使用 QPU、按需模拟器，也可以在 Braket Hybrid Jobs 提供的经典处理器上本地运行代码。我们建议先在 SV1、DM1 或 TN1 等模拟器上测试代码，然后再在真正的 QPU 上运行。

要在经典处理器上运行代码，请通过更新来指定instanceType和使用的InstanceConfig。instanceCount请注意，如果您指定 instance_count > 1，则需要确保您的代码可以在多个主机上运行。您可以选择的实例数量上限为 5。例如：

job = AwsQuantumJob.create(
    source_module="source_dir",
    entry_point="source_dir.algorithm_script:start_here",
    image_uri="111122223333.dkr.ecr.us-west-2.amazonaws.com/my-byoc-container:latest",
    instance_config=InstanceConfig(instanceType="ml.p3.8xlarge", instanceCount=3),
    device="local:braket/braket.local.qubit",
    # ...)
注意

使用设备 ARN 跟踪您用作混合作业元数据的模拟器。可接受的值必须遵循格式device = "local:<provider>/<simulator_name>"。请记住，<provider>并且<simulator_name>必须仅包含字母、数字_、-、和.。该字符串限制为 256 个字符。

如果您计划使用 BYOC，但不使用 Braket SDK 创建量子任务，则应将环境变量的值传递AMZN_BRAKET_JOB_TOKEN给请求中的jobTokenCreateQuantumTask参数。如果你不这样做，量子任务就不会获得优先级，而是作为常规的独立量子任务计费。