Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

您的第一个 Docker Space：使用 T5 进行文本生成

在以下章节中，您将学习创建 Docker Space、配置它以及将代码部署到其中的基础知识。我们将创建一个 Text Generation Space，使用 Docker 来演示 google/flan-t5-small 模型。该模型可以根据输入文本生成文本，并使用 FastAPI 作为服务器。

您可以在此处找到此托管的完整版本。

创建新的 Docker Space

我们将首先创建一个全新的 Space，并选择Docker作为我们的 SDK。

Hugging Face Spaces 是 Git 仓库，这意味着你可以通过推送提交来逐步（并协作地）开发你的 Space。在继续之前，请查看仓库入门指南，了解如何创建和编辑文件。如果你更喜欢使用 UI，也可以直接在浏览器中完成这些工作。

在创建新 Space 时选择 Docker 作为 SDK，会通过在 README.md 文件的 YAML 块中将 sdk 属性设置为 docker 来初始化您的 Docker Space。

sdk: docker

您可以通过在 README.md 文件的 YAML 块中设置 app_port 属性来更改 Space 的默认应用端口。默认端口为 7860。

app_port: 7860

添加依赖项

对于 Text Generation Space，我们将构建一个 FastAPI 应用，用于展示名为 Flan T5 的文本生成模型。在模型推理方面，我们将使用 🤗 Transformers pipeline 来调用该模型。首先，我们需要安装一些依赖项。可以通过在仓库中创建一个 requirements.txt 文件，并将以下依赖项添加到其中来实现：

fastapi==0.74.*
requests==2.27.*
sentencepiece==0.1.*
torch==1.11.*
transformers==4.*
uvicorn[standard]==0.17.*

这些依赖项将在我们稍后创建的 Dockerfile 中安装。

创建应用

让我们从一个简单的 FastAPI 应用开始，以验证端点可以正常工作。第一步是创建一个应用文件，在这里我们将其命名为 main.py。

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World!"}

创建 Dockerfile

Docker Space 的主要步骤是创建一个 Dockerfile。有关 Dockerfile 的更多信息，请参见此处。尽管本教程使用的是 FastAPI，但 Dockerfile 为用户提供了极大的灵活性，使您能够构建新一代的 ML 演示。让我们为应用程序编写 Dockerfile

# read the doc: https://huggingface.co/docs/hub/spaces-sdks-docker
# you will also find guides on how best to write your Dockerfile

FROM python:3.9

# The two following lines are requirements for the Dev Mode to be functional
# Learn more about the Dev Mode at https://huggingface.co/dev-mode-explorers
RUN useradd -m -u 1000 user
WORKDIR /app

COPY --chown=user ./requirements.txt requirements.txt
RUN pip install --no-cache-dir --upgrade -r requirements.txt

COPY --chown=user . /app
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

更改保存后，Space 将重新构建，几秒钟后您的演示即可上线！此处展示了此阶段的示例结果。

本地测试

高级用户提示（可跳过）：如果你正在本地开发，现在是一个很好的时机，你可以执行 docker build 和 docker run 在本地进行调试，但将更改推送到 Hub 并查看效果会更加简单！

docker build -t fastapi .
docker run  -it -p 7860:7860 fastapi

如果您拥有 Secrets，可以使用 docker buildx 并将这些密钥作为构建参数传入

export SECRET_EXAMPLE="my_secret_value"
docker buildx build --secret id=SECRET_EXAMPLE,env=SECRET_EXAMPLE -t fastapi .

并使用 docker run 运行，将密钥作为环境变量传入

export SECRET_EXAMPLE="my_secret_value"
docker run -it -p 7860:7860 -e SECRET_EXAMPLE=$SECRET_EXAMPLE fastapi

为我们的应用添加一些机器学习

如前所述，我们的想法是使用 Flan T5 模型进行文本生成。我们需要为输入字段添加一些 HTML 和 CSS，因此让我们创建一个名为 static 的目录，其中包含 index.html、style.css 和 script.js 文件。此时，你的文件结构应该如下所示：

/static
/static/index.html
/static/script.js
/static/style.css
Dockerfile
main.py
README.md
requirements.txt

让我们逐步完成所有步骤，使其能够正常运行。我们将跳过 CSS 和 HTML 的一些细节。你可以在 DockerTemplates/fastapi_t5 Space 的 Files and versions 选项卡中找到完整代码。

编写用于推理的 FastAPI 端点

我们将使用 transformers 中的 pipeline 来加载 google/flan-t5-small 模型。我们将设置一个名为 infer_t5 的端点，用于接收输入并输出推理调用的结果

from transformers import pipeline

pipe_flan = pipeline("text2text-generation", model="google/flan-t5-small")

@app.get("/infer_t5")
def t5(input):
    output = pipe_flan(input)
    return {"output": output[0]["generated_text"]}

编写 index.html，使其包含一个带有页面代码的简单表单。

<main>
  <section id="text-gen">
    <h2>Text generation using Flan T5</h2>
    <p>
      Model:
      <a
        href="https://huggingface.co/google/flan-t5-small"
        rel="noreferrer"
        target="_blank"
        >google/flan-t5-small
      </a>
    </p>
    <form class="text-gen-form">
      <label for="text-gen-input">Text prompt</label>
      <input
        id="text-gen-input"
        type="text"
        value="German: There are many ducks"
      />
      <button id="text-gen-submit">Submit</button>
      <p class="text-gen-output"></p>
    </form>
  </section>
</main>

在 main.py 文件中，挂载静态文件并在根路由中显示 html 文件

app.mount("/", StaticFiles(directory="static", html=True), name="static")

@app.get("/")
def index() -> FileResponse:
    return FileResponse(path="/app/static/index.html", media_type="text/html")

在 script.js 文件中，使其处理该请求

const textGenForm = document.querySelector(".text-gen-form");

const translateText = async (text) => {
  const inferResponse = await fetch(`infer_t5?input=${text}`);
  const inferJson = await inferResponse.json();

  return inferJson.output;
};

textGenForm.addEventListener("submit", async (event) => {
  event.preventDefault();

  const textGenInput = document.getElementById("text-gen-input");
  const textGenParagraph = document.querySelector(".text-gen-output");

  textGenParagraph.textContent = await translateText(textGenInput.value);
});

如权限部分所述，容器以用户 ID 1000 运行。这意味着 Space 可能会遇到权限问题。例如，transformers 会在 HF_HOME 路径下的路径中下载并缓存模型。最简单的解决方法是创建一个具有正确权限的用户，并使用该用户来运行容器应用。我们可以通过在 Dockerfile 中添加以下行来实现这一点。

# 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

最终的 Dockerfile 应该如下所示：


# read the doc: https://huggingface.co/docs/hub/spaces-sdks-docker
# you will also find guides on how best to write your Dockerfile

FROM python:3.9

# The two following lines are requirements for the Dev Mode to be functional
# Learn more about the Dev Mode at https://huggingface.co/dev-mode-explorers
RUN useradd -m -u 1000 user
WORKDIR /app

COPY --chown=user ./requirements.txt requirements.txt
RUN pip install --no-cache-dir --upgrade -r requirements.txt

COPY --chown=user . /app

USER user

ENV HOME=/home/user \
	PATH=/home/user/.local/bin:$PATH

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]