初始化指南
此时，您已成功启动并运行 Docker 容器。本节将指导您设置主机环境，为各种常见工作流程提供 Docker 命令建议，并解释有用的 docker run 选项。
设置您的主机环境
为了有效地使用 BioNeMo 框架，我们建议组织化的环境配置和目录结构。具体来说，我们建议每个项目都有多个缓存目录。这些目录将包含项目文件，例如数据、模型检查点、训练脚本以及日志和预测等输出。为了方便容器设置，我们建议将这些目录的路径存储在 .env 文件中，该文件可以在容器运行时引用。下面，我们建议在此文件中定义有用的环境变量。
创建 .env 文件以进行首次设置
我们建议在本地工作区中使用 .env 文件来定义环境变量。具体来说，以下变量对于包含在您的 .env 文件中很有用
# Local Cache Directories
LOCAL_RESULTS_PATH
DOCKER_RESULTS_PATH
LOCAL_DATA_PATH
DOCKER_DATA_PATH
LOCAL_MODELS_PATH
DOCKER_MODELS_PATH
# Desired Jupyter Port
JUPYTER_PORT
# NGC Configuration Settings
NGC_CLI_API_KEY
NGC_CLI_ORG
NGC_CLI_TEAM
NGC_CLI_FORMAT_TYPE
# Weights and Biases API Key
WANDB_API_KEY
对于这些变量中的每一个，您可以使用 = 在 .env 文件中定义它们。例如，您可以使用 NGC_CLI_API_KEY=<您的 API 密钥> 设置 NGC API 密钥。然后，您可以使用以下命令在当前 shell 中定义这些变量
source .env
运行此命令将使这些变量可用于下面显示的 docker run 命令示例中。
数据下载所需的 NGC 凭据
上述 .env 文件中的某些凭据对于特定工作流程是可选的。但是，如果您打算使用 NGC 平台上托管的数据（例如，模型检查点和示例训练数据），则必须在容器运行时定义 NGC_CLI_API_KEY 和 NGC_CLI_ORG。确保设置这些变量的最简单方法是使用此处显示的 .env 文件以及您的特定变量定义。
请参阅下面的列表，了解对每个变量的解释
LOCAL_RESULTS_PATH和DOCKER_RESULTS_PATH：用于存储结果的路径，其中LOCAL指的是本地机器上的路径，而DOCKER指的是 Docker 容器内的路径。LOCAL_DATA_PATH和DOCKER_DATA_PATH：用于存储数据的路径，同样具有LOCAL和DOCKER的区分。LOCAL_MODELS_PATH和DOCKER_MODELS_PATH：用于存储机器学习模型的路径，具有相同的本地和 Docker 差异。JUPYTER_PORT：Jupyter Lab 服务器的端口号，默认端口为 8888。NGC_CLI_API_KEY、NGC_CLI_ORG、NGC_CLI_TEAM和NGC_CLI_FORMAT_TYPE：NVIDIA GPU Cloud (NGC) 命令行界面 (CLI) 的 API 密钥、组织、团队和格式类型。WANDB_API_KEY：Weights and Biases (W&B) 的 API 密钥，这是一个用于机器学习实验跟踪和可视化的平台。
Weights and Biases 设置 (WANDB_API_KEY，可选)
Weights and Biases (W&B) 是一个机器学习运营平台，提供工具和服务，以帮助机器学习从业者更有效地构建、训练和部署模型。 BioNeMo 旨在与 W&B 协同工作，只需要简单的设置步骤即可开始跟踪您的实验。要在您的容器内设置 W&B，请按照以下步骤操作
- 在 Weights and Biases 注册一个帐户。
- 使用 W&B 设置您的 API 密钥。
- 以与设置上述环境变量相同的方式，在您的
.env中设置WANDB_API_KEY变量。 - 使用
-e选项在您的容器内设置环境变量，如下一节所示。
启动 BioNeMo 容器以进行常见工作流程
下面我们描述了一些常见的 BioNeMo 工作流程，包括如何在每种情况下设置和运行容器。以下每个示例都将假定您具有如上所示的 .env 文件中定义的本地工作区目录，您将通过卷挂载将其附加到容器。
在容器内启动 Shell
通过 BioNeMo Docker 容器内的 shell，您可以执行命令、编辑文件和运行应用程序，就像直接在主机上工作一样。这种自包含的环境使您可以隔离地处理项目的依赖项和配置，从而确保结果的一致性和可重复性。您可以安装软件包、测试和调试应用程序，并自定义环境以满足您的需求。
您可以使用以下命令在 BioNeMo 容器内启动 Bash shell。请注意，在容器内挂载的目录中修改的任何文件都将保留在主机上，但其他修改（例如安装的软件）则不会。
docker run \
--rm -it \
--gpus all \
--network host \
--shm-size=4g \
-e WANDB_API_KEY \
-e NGC_CLI_API_KEY \
-e NGC_CLI_ORG \
-e NGC_CLI_TEAM \
-e NGC_CLI_FORMAT_TYPE \
-v $LOCAL_DATA_PATH:$DOCKER_DATA_PATH \
-v $LOCAL_MODELS_PATH:$DOCKER_MODELS_PATH \
-v $LOCAL_RESULTS_PATH:$DOCKER_RESULTS_PATH \
nvcr.io/nvidia/clara/bionemo-framework:2.3 \
/bin/bash
--rm：容器退出时移除容器。-it：分配伪 TTY 并保持容器在前台运行。--gpus all：分配主机上所有可用的 GPU。--network host：允许容器使用主机的网络堆栈，有效地共享主机的网络命名空间，并允许容器直接访问主机的网络接口。--shm-size=4g：将容器中共享内存 (/dev/shm) 的大小设置为 4 GB，这对于严重依赖共享内存的应用程序可能很有用。-e <VARIABLE>：在容器内设置环境变量，取主机上设置的值。-v <LOCAL DIRECTORY>:<DOCKER DIRECTORY>：将主机上的目录挂载为容器的卷。nvcr.io/nvidia/clara/bionemo-framework:2.3：要使用的 Docker 镜像的路径。/bin/bash：在容器内运行的命令，它启动一个 Bash shell。
在容器内运行模型训练脚本
在 BioNeMo Docker 容器内运行模型训练脚本是模型训练的首选工作流程。容器提供了一个封装且可重现的训练环境。通过从主机挂载卷，即使在容器移除后，包含日志和检查点等结果的输出目录也可以持久保存。训练脚本可以如下例所示运行。将 training.py 和选项（例如，--option1）分别替换为文件名和相关的命令行选项。
docker run --rm -it --gpus all \
-e NGC_CLI_API_KEY \
-e WANDB_API_KEY \
-v $LOCAL_DATA_PATH:$DOCKER_DATA_PATH \
-v $LOCAL_MODELS_PATH:$DOCKER_MODELS_PATH \
-v $LOCAL_RESULTS_PATH:$DOCKER_RESULTS_PATH \
nvcr.io/nvidia/clara/bionemo-framework:2.3 \
python $DOCKER_RESULTS_PATH/training.py --option1 --option2 --output=$DOCKER_RESULTS_PATH
许多 Docker run 选项与上面的 shell 示例相同，除了运行的命令
python $DOCKER_RESULTS_PATH/training.py --option1 --option2 --output=$DOCKER_RESULTS_PATH：在容器内运行的命令，它使用指定的命令行参数运行training.pyPython 脚本。
在容器内运行 Jupyter Lab
通过在 BioNeMo 框架容器内启动 Jupyter Lab 实例，用户可以利用容器针对机器学习工作负载优化的环境来加速其数据科学工作流程，同时还可以受益于 Jupyter Lab 的交互式和协作功能。这允许用户在数据准备、模型开发和可视化之间无缝切换，所有操作都在一个简化的环境中完成。然后您可以启动容器。我们建议使用以下命令在 Jupyter Lab 环境中运行容器
docker run --rm -d --gpus all \
-p $JUPYTER_PORT:$JUPYTER_PORT \
-e NGC_CLI_API_KEY \
-e WANDB_API_KEY \
-v $LOCAL_DATA_PATH:$DOCKER_DATA_PATH \
-v $LOCAL_MODELS_PATH:$DOCKER_MODELS_PATH \
-v $LOCAL_RESULTS_PATH:$DOCKER_RESULTS_PATH \
nvcr.io/nvidia/clara/bionemo-framework:2.3 \
jupyter lab \
--allow-root \
--ip=* \
--port=$JUPYTER_PORT \
--no-browser \
--NotebookApp.token='' \
--NotebookApp.allow_origin='*' \
--ContentsManager.allow_hidden=True \
--notebook-dir=$DOCKER_RESULTS_PATH
请参阅下面的指南，了解对推荐的 Jupyter Lab 选项的解释
jupyter lab ...：在容器内运行的命令，它启动一个 Jupyter Lab 服务器。选项包括--allow-root：允许 Jupyter Lab 服务器以 root 用户身份运行。--ip=*：监听所有可用的网络接口，这允许从容器外部访问。--port=$JUPYTER_PORT：监听端口 8888。--no-browser：不要自动打开浏览器窗口。--NotebookApp.token=''：为 Jupyter Lab 服务器设置一个空令牌（不需要身份验证）。--NotebookApp.allow_origin='*'：允许来自任何来源的请求。--ContentsManager.allow_hidden=True：允许内容管理器访问隐藏的文件和目录。--notebook-dir=$DOCKER_RESULTS_PATH：将笔记本目录设置为容器内的$DOCKER_RESULTS_PATH。
常见的 docker run 选项
下面我们解释一些常见的 docker run 选项以及如何在您的 BioNeMo 开发工作流程中使用它们。
使用 -v 选项挂载卷
-v 允许您将主机目录挂载为容器内的卷。即使在容器被删除或重启后，这也能实现数据持久性。在机器学习工作流程的上下文中，利用 -v 选项对于在主机上维护数据集、模型权重和结果的本地缓存至关重要，这样它们可以在容器终止后仍然存在，并在容器运行之间重复使用。
语法
docker run -v <host_directory>:<container_directory> <image_name>
docker run -v /path/to/local/cache:/workspace/bionemo2/cache \
nvcr.io/nvidia/clara/bionemo-framework:2.3
在此示例中，主机上的 /path/to/local/cache 目录被挂载为容器内 /workspace/bionemo2/cache 的卷。
使用 -e 选项设置环境变量
-e 选项允许您在容器内设置环境变量。您可以使用此选项定义将在容器内运行的应用程序可用的变量。
示例
docker run -e MY_VAR=value -e ANOTHER_VAR=another_value \
nvcr.io/nvidia/clara/bionemo-framework:2.3
-e MY_VAR=value将MY_VAR环境变量设置为容器内的value。-e ANOTHER_VAR=another_value将ANOTHER_VAR环境变量设置为容器内的another_value。
您可以通过重复 -e 选项来设置多个环境变量。这些变量的值将可用于在容器内运行的应用程序，从而允许您自定义其行为。
请注意，您还可以使用 shell 变量和命令替换来动态设置环境变量。例如
MY_EXTERNAL_VAR=external_value
docker run -e MY_INTERNAL_VAR=$MY_EXTERNAL_VAR \
nvcr.io/nvidia/clara/bionemo-framework:2.3
在此示例中，容器内的 MY_INTERNAL_VAR 环境变量将被设置为主机上 MY_EXTERNAL_VAR shell 变量的值。
使用 -u 选项设置用户和组 ID
-u 选项设置用于容器进程的用户和组 ID。通过匹配主机上用户的 ID，容器内的用户将具有与运行命令的用户相同的读取和写入挂载卷中文件的权限。您可以使用命令替换来自动检索您的用户和组 ID。
示例
docker run -u $(id -u):$(id -g) \
nvcr.io/nvidia/clara/bionemo-framework:2.3
$(id -u)是一个命令替换，它执行id -u命令并捕获其输出。id -u打印当前用户的有效用户 ID。$(id -g)是另一个命令替换，它执行id -g命令并捕获其输出。id -g打印当前用户的有效组 ID。