Tu primer Docker Space: generación de texto con T5

En las siguientes secciones, aprenderás lo básico para crear un Space de Docker, configurarlo y desplegar tu código en él. Crearemos un Space de Text Generation con Docker que se utilizará para demostrar el modelo google/flan-t5-small, el cual puede generar texto a partir de un texto de entrada, utilizando FastAPI como servidor.

Puedes encontrar una versión completada de este hospedado aquí.

Crear un nuevo Espacio de Docker

Comenzaremos creando un Space nuevo y eligiendo Docker como SDK.

Los Hugging Face Spaces son repositorios Git, lo que significa que puedes trabajar en tu Space de forma incremental (y colaborativa) mediante el envío de commits. Consulta la guía Getting Started with Repositories para aprender cómo crear y editar archivos antes de continuar. Si prefieres trabajar con una interfaz de usuario, también puedes realizar el trabajo directamente en el navegador.

Seleccionar Docker como SDK al crear un nuevo Space inicializará tu Space de Docker estableciendo la propiedad sdk en docker dentro del bloque YAML de tu archivo README.md.

sdk: docker

Puedes cambiar el puerto de aplicación predeterminado de tu Space estableciendo la propiedad app_port en el bloque YAML de tu archivo README.md. El puerto predeterminado es 7860.

app_port: 7860

Agregue las dependencias

Para el Space de Text Generation, crearemos una aplicación de FastAPI que muestre un modelo de generación de texto llamado Flan T5. Para la inferencia del modelo, utilizaremos un 🤗 Transformers pipeline para usar el modelo. Necesitamos comenzar instalando algunas dependencias. Esto se puede hacer creando un archivo requirements.txt en nuestro repositorio y añadiendo las siguientes dependencias:

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

Estas dependencias se instalarán en el Dockerfile que crearemos más adelante.

Crear la aplicación

Comencemos el proceso con una aplicación FastAPI de prueba para verificar que podemos hacer funcionar un endpoint. El primer paso es crear un archivo de la aplicación; en este caso, lo llamaremos main.py.

from fastapi import FastAPI

app = FastAPI()

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

Crear el Dockerfile

El paso principal para un Espacio de Docker es crear un Dockerfile. Puedes leer más sobre los Dockerfiles aquí. Aunque en este tutorial usamos FastAPI, los Dockerfiles ofrecen una gran flexibilidad a los usuarios, permitiéndoles construir una nueva generación de demos de ML. Escribamos el Dockerfile para nuestra aplicación

# 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"]

Cuando se guarden los cambios, el Space se reconstruirá y tu demo debería estar disponible en unos segundos. Aquí hay un ejemplo de resultado en este punto.

Pruebas locales

Consejo para usuarios avanzados (puedes omitirlo): Si estás desarrollando localmente, este es un buen momento para ejecutar docker build y docker run para depurar localmente, ¡pero es aún más fácil subir los cambios al Hub y ver cómo se ve!

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

Si tienes Secrets, puedes usar docker buildx y pasar los secretos como argumentos de compilación

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

y ejecutar con docker run pasando los secretos como variables de entorno

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

Añadiendo algo de ML a nuestra aplicación

Como se mencionó anteriormente, la idea es usar un modelo Flan T5 para la generación de texto. Queremos añadir algo de HTML y CSS para un campo de entrada, así que creemos un directorio llamado static con los archivos index.html, style.css y script.js. En este momento, la estructura de tus archivos debería verse así:

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

Pasemos por todos los pasos para que esto funcione. Omitiremos algunos detalles del CSS y el HTML. Puedes encontrar todo el código en la pestaña Files and versions del Space DockerTemplates/fastapi_t5.

1. Escribe el punto de acceso de FastAPI para realizar inferencia

Usaremos el pipeline de transformers para cargar el modelo google/flan-t5-small. Configuraremos un endpoint llamado infer_t5 que recibe una entrada y devuelve el resultado de la llamada de inferencia

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"]}

2. Escribe el index.html para tener un formulario simple que contenga el código de la página.

<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>

3. En el archivo main.py, monta los archivos estáticos y muestra el archivo html en la ruta raíz

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")

4. En el archivo script.js, haz que gestione la solicitud

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);
});

5. Conceder permisos a los directorios correctos

Como se discutió en la sección de permisos, el contenedor se ejecuta con el ID de usuario 1000. Esto significa que el Space podría tener problemas de permisos. Por ejemplo, transformers descarga y almacena en caché los modelos en la ruta bajo la ruta HF_HOME. La forma más sencilla de resolver esto es crear un usuario con los permisos adecuados y usarlo para ejecutar la aplicación del contenedor. Podemos hacer esto añadiendo las siguientes líneas al 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

El Dockerfile final debería verse así:

# 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"]

¡Éxito! ¡Tu aplicación debería estar funcionando ahora! Consulta DockerTemplates/fastapi_t5 para ver el resultado final.

¡Qué viaje! Recuerda que Docker Spaces te brindan mucha libertad, por lo que no estás limitado a usar FastAPI. Desde un Go Endpoint hasta una Shiny App, el límite es la luna! Echa un vistazo a algunos ejemplos oficiales. También puedes actualizar tu Space a GPU si es necesario 😃

Depuración

Puedes depurar tu Space consultando los registros de Build y Container. Haz clic en el botón Open Logs para abrir el modal.

Si todo fue bien, verás Pushing Image y Scheduling Space en la pestaña Build

En la pestaña Container, verás el estado de la aplicación, en este caso, Uvicorn running on http://0.0.0.0:7860

Además, puedes activar el modo de desarrollo en tu Space. El modo de desarrollo te permite conectarte a tu Space en ejecución mediante VSCode o SSH. Obtén más información aquí: https://huggingface.co/dev-mode-explorers

Leer más

• Espacios de Docker
• Lista de ejemplos de Docker Spaces