Hub 文档

Docker Spaces

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

Docker Spaces

Spaces 支持自定义 Docker 容器,适用于 Streamlit 和 Gradio 范围之外的应用程序。Docker Spaces 允许用户超越标准 SDK 之前的限制。从 FastAPI 和 Go 端点到 Phoenix 应用程序和 ML Ops 工具,Docker Spaces 可以在许多不同的设置中提供帮助。

设置 Docker Spaces

创建新 Space 时选择 Docker 作为 SDK,将通过在 README.md 文件的 YAML 块中将 sdk 属性设置为 docker 来初始化你的 Space。或者,对于现有 Space 存储库,在 Spaces README.md 文件顶部的 YAML 块内设置 sdk: docker。你还可以通过设置 app_port: 7860 来更改默认暴露端口 7860。之后,你可以创建一个常规的 Dockerfile

---
title: Basic Docker SDK Space
emoji: 🐳
colorFrom: purple
colorTo: gray
sdk: docker
app_port: 7860
---

在内部,你可以拥有任意数量的开放端口。例如,你可以在 Space 中安装 Elasticsearch,并在其默认端口 9200 上内部调用它。

如果你想将多个端口上提供的应用程序暴露给外部世界,一个变通方法是使用反向代理(如 Nginx)将来自更广泛互联网的请求(在单个端口上)分派到不同的内部端口。

Secrets 和变量管理

你可以在 Space 设置中管理 Space 的环境变量。在此处阅读更多内容

变量

构建时

构建 Docker Space 时,变量作为 build-arg 传递。阅读 Docker 的专门文档,获取如何在 Dockerfile 中使用此功能的完整指南。

	# Declare your environment variables with the ARG directive
	ARG MODEL_REPO_NAME

	FROM python:latest
	# [...]
	# You can use them like environment variables
	RUN predict.py $MODEL_REPO_NAME

运行时

变量在运行时注入到容器的环境中。

Secrets

构建时

在 Docker Spaces 中,出于安全原因,secrets 管理有所不同。在 Settings 选项卡中创建 secret 后,可以通过在 Dockerfile 中添加以下行来公开该 secret

例如,如果 SECRET_EXAMPLE 是你在 Settings 选项卡中创建的 secret 的名称,则可以通过将其挂载到文件,然后使用 $(cat /run/secrets/SECRET_EXAMPLE) 读取它,在构建时读取它。

参见以下示例

# Expose the secret SECRET_EXAMPLE at buildtime and use its value as git remote URL
RUN --mount=type=secret,id=SECRET_EXAMPLE,mode=0444,required=true \
 git init && \
 git remote add origin $(cat /run/secrets/SECRET_EXAMPLE)
# Expose the secret SECRET_EXAMPLE at buildtime and use its value as a Bearer token for a curl request
RUN --mount=type=secret,id=SECRET_EXAMPLE,mode=0444,required=true \
	curl test -H 'Authorization: Bearer $(cat /run/secrets/SECRET_EXAMPLE)'

运行时

与公共变量一样,在运行时,你可以将 secrets 作为环境变量访问。例如,在 Python 中,你将使用 os.environ.get("SECRET_EXAMPLE")。请查看此示例,了解使用 secrets 的 Docker Space。

权限

容器以用户 ID 1000 运行。为避免权限问题,你应该创建一个用户并在任何 COPY 或下载之前设置其 WORKDIR

# Set up a new user named "user" with user ID 1000
RUN useradd -m -u 1000 user

# Switch to the "user" user
USER user

# Set home to the user's home directory
ENV HOME=/home/user \
	PATH=/home/user/.local/bin:$PATH

# Set the working directory to the user's home directory
WORKDIR $HOME/app

# Try and run pip command after setting the user with `USER user` to avoid permission issues with Python
RUN pip install --no-cache-dir --upgrade pip

# Copy the current directory contents into the container at $HOME/app setting the owner to the user
COPY --chown=user . $HOME/app

# Download a checkpoint
RUN mkdir content
ADD --chown=user https://<SOME_ASSET_URL> content/<SOME_ASSET_NAME>
始终在 `ADD` 和 `COPY` 中指定 `--chown=user`,以确保新文件归你的用户所有。

如果仍然遇到权限问题,你可能需要在 Dockerfile 中使用 chmodchown 来授予正确的权限。例如,如果你想使用目录 /data,你可以这样做

RUN mkdir -p /data
RUN chmod 777 /data

应始终避免不必要的 chown。

更新文件的元数据会创建存储在新层中的新副本。因此,递归 chown 可能会导致图像非常大,因为所有受影响的文件都会重复。

与其通过运行 chown 来修复权限

COPY checkpoint .
RUN chown -R user checkpoint

你应始终这样做

COPY --chown=user checkpoint .

ADD 命令也一样)

数据持久性

除非你选择持久存储升级,否则只要 Docker Space 重启,磁盘上写入的数据就会丢失。

如果你选择持久存储升级,可以使用 /data 目录来存储数据。此目录挂载在持久卷上,这意味着写入此目录的数据将在重启后持久化。

目前,/data 卷仅在运行时可用,即在 Dockerfile 的构建步骤中不能使用 /data

你还可以将我们的数据集 Hub 用于特定情况,你可以在其中将状态和数据存储在 git LFS 存储库中。你可以在此处找到一个持久性示例,它使用 huggingface_hub以编程方式将文件上传到数据集存储库。此 Space 示例以及此指南将帮助你确定哪种解决方案最适合你的数据类型。

最后,在某些情况下,你可能希望从你的 Space 代码中使用外部存储解决方案,例如外部托管数据库、S3 等。

带 GPU 的 Docker 容器

你可以通过使用我们支持 GPU 的 Spaces 硬件之一来运行带 GPU 支持的 Docker 容器。

我们建议使用 Docker Hub 中的 nvidia/cuda 作为基础镜像,它预装了 CUDA 和 cuDNN。

在 Docker 构建时,你无法访问 GPU 硬件。因此,在 Dockerfile 的构建步骤中不应尝试运行任何与 GPU 相关的命令。例如,你在构建镜像时不能运行 `nvidia-smi` 或 `torch.cuda.is_available()`。在此处阅读更多信息:[此处](https://github.com/NVIDIA/nvidia-docker/wiki/nvidia-docker#description)。

阅读更多

< > 在 GitHub 上更新