Crear y compartir Model Cards

La biblioteca huggingface_hub ofrece una interfaz de Python para crear, compartir y actualizar Model Cards. Visita la página de documentación dedicada para una visión más profunda de qué son los Model Cards en el Hub y cómo funcionan por debajo.

Cargar una tarjeta de modelo desde el Hub

Para cargar una tarjeta existente desde el Hub, puedes usar la función ModelCard.load(). Aquí, cargaremos la tarjeta de nateraw/vit-base-beans.

from huggingface_hub import ModelCard

card = ModelCard.load('nateraw/vit-base-beans')

Esta tarjeta tiene algunos atributos útiles que puede ser que desee acceder o aprovechar:

• card.data: Devuelve una instancia de ModelCardData con los metadatos de la tarjeta del modelo. Llama a .to_dict() en esta instancia para obtener la representación como un diccionario.
• card.text: Devuelve el texto de la tarjeta, excluyendo la cabecera de metadatos.
• card.content: Devuelve el contenido de texto de la tarjeta, incluyendo la cabecera de metadatos.

Crear tarjetas de modelo

Desde texto

Para inicializar una Model Card a partir de texto, basta con pasar el contenido de texto de la tarjeta a ModelCard durante la inicialización.

content = """
---
language: en
license: mit
---

# My Model Card
"""

card = ModelCard(content)
card.data.to_dict() == {'language': 'en', 'license': 'mit'}  # True

Otra forma en la que podrías querer hacer esto es con f-strings. En el siguiente ejemplo,

• Use ModelCardData.to_yaml() para convertir los metadatos que definimos a YAML, de modo que podamos usarlo para insertar el bloque YAML en la tarjeta del modelo.
• Muestra cómo podrías usar una variable de plantilla mediante f-strings de Python.

card_data = ModelCardData(language='en', license='mit', library='timm')

example_template_var = 'nateraw'
content = f"""
---
{ card_data.to_yaml() }
---

# My Model Card

This model created by [@{example_template_var}](https://github.com/{example_template_var})
"""

card = ModelCard(content)
print(card)

El ejemplo anterior nos dejaría con una tarjeta que se vería así:

---
language: en
license: mit
library: timm
---

# My Model Card

This model created by [@nateraw](https://github.com/nateraw)

Desde una plantilla Jinja

Si tienes Jinja2 instalado, puedes crear Model Cards a partir de un archivo de plantilla jinja. Veamos un ejemplo básico:

from pathlib import Path

from huggingface_hub import ModelCard, ModelCardData

# Define your jinja template
template_text = """
---
{{ card_data }}
---

# Model Card for MyCoolModel

This model does this and that.

This model was created by [@{{ author }}](https://hf.co/{{author}}).
""".strip()

# Write the template to a file
Path('custom_template.md').write_text(template_text)

# Define card metadata
card_data = ModelCardData(language='en', license='mit', library_name='keras')

# Create card from template, passing it any jinja template variables you want.
# In our case, we'll pass author
card = ModelCard.from_template(card_data, template_path='custom_template.md', author='nateraw')
card.save('my_model_card_1.md')
print(card)

El markdown de la tarjeta resultante se ve así:

---
language: en
license: mit
library_name: keras
---

# Model Card for MyCoolModel

This model does this and that.

This model was created by [@nateraw](https://hf.co/nateraw).

Si actualizas cualquier card.data, se reflejará en la propia card.

card.data.library_name = 'timm'
card.data.language = 'fr'
card.data.license = 'apache-2.0'
print(card)

Ahora, como puede ver, la cabecera de metadatos se ha actualizado:

---
language: fr
license: apache-2.0
library_name: timm
---

# Model Card for MyCoolModel

This model does this and that.

This model was created by [@nateraw](https://hf.co/nateraw).

A medida que actualizas los datos de la tarjeta, puedes validar que la tarjeta sigue siendo válida en el Hub llamando a ModelCard.validate(). Esto garantiza que la tarjeta cumpla con las reglas de validación configuradas en el Hugging Face Hub.

Desde la plantilla predeterminada

En lugar de usar tu propia plantilla, también puedes utilizar la plantilla predeterminada, que es una tarjeta de modelo completa con numerosas secciones que quizás quieras rellenar. Internamente, utiliza Jinja2 para completar un archivo de plantilla.

Tenga en cuenta que deberá tener Jinja2 instalado para usar from_template. Puede hacerlo con pip install Jinja2.

card_data = ModelCardData(language='en', license='mit', library_name='keras')
card = ModelCard.from_template(
    card_data,
    model_id='my-cool-model',
    model_description="this model does this and that",
    developers="Nate Raw",
    repo="https://github.com/huggingface/huggingface_hub",
)
card.save('my_model_card_2.md')
print(card)

Compartir tarjetas de modelos

Si has iniciado sesión en Hugging Face Hub (ya sea usando hf auth login o login()), puedes subir tarjetas al Hub simplemente llamando a ModelCard.push_to_hub(). Veamos cómo hacerlo…

Primero, crearemos un nuevo repositorio llamado ‘hf-hub-modelcards-pr-test’ en el espacio de nombres del usuario autenticado:

from huggingface_hub import whoami, create_repo

user = whoami()['name']
repo_id = f'{user}/hf-hub-modelcards-pr-test'
url = create_repo(repo_id, exist_ok=True)

Luego, crearemos una tarjeta a partir de la plantilla predeterminada (la misma que se definió en la sección anterior):

card_data = ModelCardData(language='en', license='mit', library_name='keras')
card = ModelCard.from_template(
    card_data,
    model_id='my-cool-model',
    model_description="this model does this and that",
    developers="Nate Raw",
    repo="https://github.com/huggingface/huggingface_hub",
)

Por último, subiremos eso al hub

card.push_to_hub(repo_id)

Puedes consultar la tarjeta resultante aquí.

Si en su lugar quisiera enviar una tarjeta como una solicitud de extracción, solo tiene que indicar create_pr=True al llamar a push_to_hub:

card.push_to_hub(repo_id, create_pr=True)

Un PR resultante creado desde este comando se puede ver aquí.

Actualizar metadatos

En esta sección veremos qué metadatos hay en las tarjetas de repositorios y cómo actualizarlos.

metadata se refiere a un mapa de hashes (o contexto de pares clave-valor) que proporciona información de alto nivel sobre un modelo, un conjunto de datos o un Space. Esa información puede incluir detalles como el pipeline type, el model_id o la model_description del modelo. Para más detalles, puedes consultar estas guías: Model Card, Dataset Card y Spaces Settings. Ahora veamos algunos ejemplos de cómo actualizar esos metadatos.

Comencemos con un primer ejemplo:

>>> from huggingface_hub import metadata_update
>>> metadata_update("username/my-cool-model", {"pipeline_tag": "image-classification"})

Con estas dos líneas de código actualizarás los metadatos para establecer una nueva pipeline_tag.

Por defecto, no se puede actualizar una clave que ya existe en la tarjeta. Si desea hacerlo, debe pasar explícitamente overwrite=True:

>>> from huggingface_hub import metadata_update
>>> metadata_update("username/my-cool-model", {"pipeline_tag": "text-generation"}, overwrite=True)

A menudo ocurre que deseas sugerir algunos cambios en un repositorio en el que no tienes permisos de escritura. Puedes hacerlo creando un PR en ese repositorio, lo que permitirá a los propietarios revisar y fusionar tus sugerencias.

>>> from huggingface_hub import metadata_update
>>> metadata_update("someone/model", {"pipeline_tag": "text-classification"}, create_pr=True)

Incluir resultados de evaluación

Para incluir los resultados de evaluación en los metadatos model-index, puedes pasar un EvalResult o una lista de EvalResult con tus resultados de evaluación asociados. Internamente, creará el model-index cuando llames a card.data.to_dict(). Para obtener más información sobre cómo funciona esto, puedes consultar esta sección de la documentación de Hub.

Tenga en cuenta que el uso de esta función requiere incluir el atributo model_name en ModelCardData.

card_data = ModelCardData(
    language='en',
    license='mit',
    model_name='my-cool-model',
    eval_results = EvalResult(
        task_type='image-classification',
        dataset_type='beans',
        dataset_name='Beans',
        metric_type='accuracy',
        metric_value=0.7
    )
)

card = ModelCard.from_template(card_data)
print(card.data)

El resultado de card.data debería ser así:

language: en
license: mit
model-index:
- name: my-cool-model
  results:
  - task:
      type: image-classification
    dataset:
      name: Beans
      type: beans
    metrics:
    - type: accuracy
      value: 0.7

Si tienes más de un resultado de evaluación que quieras compartir, simplemente pasa una lista de EvalResult:

card_data = ModelCardData(
    language='en',
    license='mit',
    model_name='my-cool-model',
    eval_results = [
        EvalResult(
            task_type='image-classification',
            dataset_type='beans',
            dataset_name='Beans',
            metric_type='accuracy',
            metric_value=0.7
        ),
        EvalResult(
            task_type='image-classification',
            dataset_type='beans',
            dataset_name='Beans',
            metric_type='f1',
            metric_value=0.65
        )
    ]
)
card = ModelCard.from_template(card_data)
card.data

Lo que debería dejarte con el siguiente card.data:

language: en
license: mit
model-index:
- name: my-cool-model
  results:
  - task:
      type: image-classification
    dataset:
      name: Beans
      type: beans
    metrics:
    - type: accuracy
      value: 0.7
    - type: f1
      value: 0.65