Tarjetas de modelos

¿Qué son las Model Cards?

Las tarjetas de modelo son archivos que acompañan a los modelos y proporcionan información útil. En el fondo, las tarjetas de modelo son simples archivos Markdown con metadatos adicionales. Las tarjetas de modelo son esenciales para la descubribilidad, la reproducibilidad y el intercambio. Puedes encontrar una tarjeta de modelo como el archivo README.md en cualquier repositorio de modelos.

La tarjeta del modelo debe describir:

• el modelo
• sus usos previstos y posibles limitaciones, incluidos los sesgos y las consideraciones éticas, tal como se detalla en Mitchell, 2018
• los parámetros de entrenamiento y la información experimental (puede incrustar o enlazar a una plataforma de seguimiento de experimentos como referencia)
• qué conjuntos de datos se utilizaron para entrenar tu modelo
• los resultados de evaluación del modelo

La plantilla de la tarjeta del modelo está disponible aquí.

Cómo completar cada sección de la tarjeta del modelo se describe en la Tarjeta de Modelo Anotada.

Las Model Cards en el Hub tienen dos partes clave, con información superpuesta:

• Metadatos
• Descripciones de texto

Metadatos de la tarjeta del modelo

Un repositorio de modelo renderiza su README.md como una tarjeta de modelo. La tarjeta de modelo es un archivo Markdown con una sección YAML en la parte superior que contiene metadatos sobre el modelo.

Los metadatos que agregas a la tarjeta del modelo facilitan su descubrimiento y uso. Por ejemplo:

• Permitir a los usuarios filtrar modelos en https://huggingface.co/models.
• Mostrando la licencia del modelo.
• Agregar conjuntos de datos a los metadatos añadirá un mensaje que dice Datasets used to train: a la página de tu modelo y enlazará los conjuntos de datos relevantes, si están disponibles en el Hub.

Los identificadores de conjunto de datos y de idioma son los que se enumeran en las páginas Datasets y Languages.

Agregar metadatos a la tarjeta de tu modelo

Hay varias formas de agregar metadatos a la tarjeta de tu modelo, entre ellas:

• Usando la interfaz de metadatos
• Editar directamente la sección YAML del archivo README.md
• A través de la biblioteca de Python huggingface_hub, consulte la documentación para más detalles.

Muchas bibliotecas con integración con Hub añadirán automáticamente metadatos a la tarjeta del modelo cuando subas un modelo.

Usando la interfaz de metadatos

Puedes añadir metadatos a la tarjeta de tu modelo usando la interfaz de metadatos. Para acceder a la interfaz de metadatos, ve a la página del modelo y haz clic en el botón Edit model card en la esquina superior derecha de la tarjeta del modelo. Esto abrirá un editor que muestra el archivo README.md de la tarjeta del modelo, así como una interfaz para editar los metadatos.

Esta interfaz de usuario te permitirá agregar metadatos clave a la tarjeta de tu modelo y muchos de los campos se autocompletarán en función de la información que proporciones. Usar la interfaz de usuario es la forma más sencilla de agregar metadatos a la tarjeta de tu modelo, pero no admite todos los campos de metadatos. Si deseas agregar metadatos que no son compatibles con la interfaz de usuario, puedes editar directamente la sección YAML del archivo README.md.

Editar la sección YAML del archivo README.md

También puedes editar directamente la sección YAML del archivo README.md. Si la tarjeta del modelo no tiene una sección YAML, puedes añadirla colocando tres --- al inicio del archivo, incluyendo todos los metadatos relevantes y cerrando la sección con otro grupo de ---, como se muestra en el siguiente ejemplo:

---
language: 
  - "List of ISO 639-1 code for your language"
  - lang1
  - lang2
thumbnail: "url to a thumbnail used in social sharing"
tags:
- tag1
- tag2
license: "any valid license identifier"
datasets:
- dataset1
- dataset2
base_model: "base model Hub identifier"
---

Puedes encontrar la especificación detallada de los metadatos de la tarjeta del modelo aquí.

Especificar una biblioteca

Puede especificar las bibliotecas admitidas en la sección de metadatos de la tarjeta del modelo. Encuentre más información sobre nuestras bibliotecas admitidas aquí. La biblioteca se especificará en el siguiente orden de prioridad:

1. Especificar library_name en la tarjeta del modelo (recomendado si su modelo no es un modelo de transformers). Esta información se puede agregar a través de la interfaz de metadatos o directamente en la sección YAML de la tarjeta del modelo:

library_name: flair

2. Tener una etiqueta con el nombre de una biblioteca que se admite

tags:
- flair

Si no se especifica, el Hub intentará detectar automáticamente el tipo de biblioteca. Sin embargo, se desaconseja este enfoque y los creadores de repositorios deben utilizar library_name explícito siempre que sea posible.

1. Al buscar la presencia de archivos como *.nemo o *.mlmodel, el Hub puede determinar si un modelo proviene de NeMo o CoreML.
2. En el pasado, si no se detectaba nada y existía un archivo config.json, se asumía que la biblioteca era transformers. Para los repositorios de modelos creados después de agosto de 2024, esto ya no es así, por lo que necesitas establecer library_name: transformers de forma explícita.

Especificar un modelo base

Si tu modelo es un fine-tune, un adaptador o una versión cuantizada de un modelo base, puedes especificar el modelo base en la sección de metadatos de la tarjeta del modelo. Esta información también se puede utilizar para indicar si tu modelo es una fusión de varios modelos existentes. Por lo tanto, el campo base_model puede ser un solo ID de modelo o una lista de uno o más base_models (especificados por sus identificadores de Hub).

base_model: HuggingFaceH4/zephyr-7b-beta

Esta metadatos se utilizará para mostrar el modelo base en la página del modelo. Los usuarios también pueden usar esta información para filtrar modelos por modelo base o encontrar modelos derivados de un modelo base específico:

Para un modelo afinado:

Para un adaptador (LoRA, PEFT, etc.):

Para una versión cuantizada de otro modelo:

Para una fusión de dos o más modelos:

En el caso de fusión, especifica una lista de dos o más base_models:

base_model:
- Endevor/InfinityRP-v1-7B
- l3utterfly/mistral-7b-v0.1-layla-v4

El Hub inferirá el tipo de relación entre el modelo actual y el modelo base ("adapter", "merge", "quantized", "finetune"), pero también puedes establecerlo explícitamente si es necesario: por ejemplo, base_model_relation: quantized.

Especificar una nueva versión

Si hay una nueva versión de tu modelo disponible en el Hub, puedes especificarla en un campo new_version.

Por ejemplo, en l3utterfly/mistral-7b-v0.1-layla-v3:

new_version: l3utterfly/mistral-7b-v0.1-layla-v4

Esta metadatos se utilizará para mostrar un enlace a la última versión de un modelo en la página del modelo. Si el modelo vinculado en new_version también tiene un campo new_version, siempre se mostrará la versión más reciente.

Especificar un conjunto de datos

Puedes especificar los conjuntos de datos utilizados para entrenar tu modelo en la sección de metadatos de la tarjeta del modelo. Los conjuntos de datos se mostrarán en la página del modelo y los usuarios podrán filtrar modelos por conjunto de datos. Debes usar el identificador del conjunto de datos del Hub, que es el mismo que el nombre del repositorio del conjunto de datos, como identificador:

datasets:
- stanfordnlp/imdb
- HuggingFaceFW/fineweb

Especificar un bucket

Puedes especificar los storage buckets vinculados a tu modelo en la sección de metadatos de la tarjeta del modelo. Los buckets se mostrarán como etiquetas en la página del modelo y las páginas de los buckets vinculados mostrarán el modelo a cambio. Debes usar el identificador de bucket del Hub, que es el mismo que el nombre del repositorio del bucket:

buckets:
- my-org/my-bucket
- my-org/another-bucket

Especificar una tarea ( pipeline_tag )

Puedes especificar el pipeline_tag en los metadatos de la tarjeta del modelo. El pipeline_tag indica el tipo de tarea para la que está destinado el modelo. Esta etiqueta se mostrará en la página del modelo y los usuarios pueden filtrar modelos en el Hub por tarea. Esta etiqueta también se utiliza para determinar qué widget usar para el modelo y qué APIs usar por debajo.

Para los modelos de transformers, la etiqueta de pipeline se infiere automáticamente desde el archivo config.json del modelo, pero puedes sobrescribirla en los metadatos de la tarjeta del modelo si es necesario. Editar este campo en la interfaz de metadatos garantiza que la etiqueta de pipeline sea válida. Otras bibliotecas con integración con Hub también añaden automáticamente la etiqueta de pipeline a los metadatos de la tarjeta del modelo.

Especificar una licencia

Puede especificar la licencia en la sección de metadatos de la tarjeta del modelo. La licencia se mostrará en la página del modelo y los usuarios podrán filtrar modelos por licencia. Al usar la interfaz de metadatos, verá un menú desplegable con las licencias más comunes.

Si es necesario, también puedes especificar una licencia personalizada añadiendo other como valor de la licencia y especificando el nombre y un enlace a la licencia en los metadatos.

# Example from https://huggingface.co/coqui/XTTS-v1
---
license: other
license_name: coqui-public-model-license
license_link: https://coqui.ai/cpml
---

Si la licencia no está disponible a través de una URL, puede enlazar a un LICENSE almacenado en el repositorio del modelo.

Resultados de la evaluación

Puedes especificar los resultados de evaluación de tu modelo de manera estructurada en los metadatos de la tarjeta del modelo. Los resultados se analizan en el Hub y se muestran en un widget en la página del modelo. A continuación, se muestra un ejemplo de cómo se ve para el modelo bigcode/starcoder:

La especificación de metadatos inicial se basaba en la especificación model-index de Papers with code. Esto nos permitía indexar directamente los resultados en los tableros de clasificación de Papers with code cuando correspondía. También era posible enlazar la fuente desde la que se calcularon los resultados de la evaluación.

NUEVO: Tenemos un nuevo formato de metadatos más simple para los resultados de evaluación. Revísalo en la página de documentación dedicada.

A continuación se muestra un ejemplo parcial de un model-index que describía la puntuación de 01-ai/Yi-34B en el benchmark ARC. El resultado provenía del Open LLM Leaderboard, que se define como la source:

---
model-index:
  - name: Yi-34B
    results:
      - task:
          type: text-generation
        dataset:
          name: ai2_arc
          type: ai2_arc
        metrics:
          - name: AI2 Reasoning Challenge (25-Shot)
            type: AI2 Reasoning Challenge (25-Shot)
            value: 64.59
        source:
          name: Open LLM Leaderboard
          url: https://huggingface.co/spaces/open-llm-leaderboard/open_llm_leaderboard
---

Para más detalles sobre cómo formatear estos datos, consulta las especificaciones de la tarjeta de modelo.

Emisiones de CO2

La tarjeta del modelo también es un excelente lugar para mostrar información sobre el impacto de CO₂ de tu modelo. Visita nuestra guía sobre el seguimiento e informe de emisiones de CO₂ para obtener más información.

Vincular un artículo

Si la tarjeta del modelo incluye un enlace a una página de Paper (ya sea en HF o un resumen/PDF de Arxiv), el Hugging Face Hub extraerá el ID de arXiv y lo incluirá en las etiquetas del modelo con el formato arxiv:<PAPER ID>. Al hacer clic en la etiqueta podrás:

• Visite la página del Paper
• Filtrar por otros modelos en el Hub que citan el mismo artículo.

Lee más sobre las páginas de Paper aquí.

Texto de la Model Card

Los detalles sobre cómo completar la parte legible por humanos de la tarjeta del modelo (para que pueda imprimirse, recortarse y pegarse, etc.) están disponibles en la tarjeta del modelo anotada.

Preguntas frecuentes

¿Cómo se determinan las etiquetas de los modelos?

Cada página de modelo enumera todas las etiquetas del modelo en el encabezado de la página, debajo del nombre del modelo. Estas se calculan principalmente a partir de los metadatos de la tarjeta del modelo, aunque algunas se agregan automáticamente, como se describe en Enabling a Widget.

¿Puedo añadir etiquetas personalizadas a mi modelo?

Sí, puedes añadir etiquetas personalizadas a tu modelo agregándolas al campo tags en los metadatos de la tarjeta del modelo. La interfaz de metadatos sugerirá algunas etiquetas populares, pero puedes añadir la que quieras. Por ejemplo, podrías indicar que tu modelo se centra en finanzas añadiendo la etiqueta finance.

Cómo puedo indicar que mi modelo no es apto para todos los públicos

Puedes añadir la etiqueta not-for-all-audiences a los metadatos de la tarjeta de tu modelo. Cuando esta etiqueta está presente, se mostrará un mensaje en la página del modelo indicando que el modelo no es apto para todos los públicos. Los usuarios pueden hacer clic en este mensaje para ver la tarjeta del modelo.

¿Cómo puedo mostrar imágenes diferentes para el modo oscuro y el modo claro?

Puede mostrar diferentes versiones de una imagen optimizadas para cada tema. Esto resulta especialmente útil para logotipos, diagramas o capturas de pantalla que requieren esquemas de color distintos para mantener la visibilidad y la estética en los modos claro y oscuro. Para usar esta función, debe proporcionar ambas versiones de su imagen.

Para las imágenes subidas a través del editor de markdown

Cuando subes una imagen directamente desde el editor de markdown (usando arrastrar y soltar), añade el fragmento de URI #hf-light-mode-only o #hf-dark-mode-only al final de la URL de la imagen para especificar en qué tema debe mostrarse:

Image only displays when viewing in light mode
![Logo](/static-proxy?url=https%3A%2F%2Fcdn-uploads.huggingface.co%2Fproduction%2Fuploads%2Flogo-light.png%23hf-light-mode-only%3C%2Fspan%3E)

Image only displays when viewing in dark mode
![Logo](/static-proxy?url=https%3A%2F%2Fcdn-uploads.huggingface.co%2Fproduction%2Fuploads%2Flogo-dark.png%23hf-dark-mode-only%3C%2Fspan%3E)%3C!----%3E%3C%2Fpre%3E%3C%2Fdiv%3E%3C!----%3E 
Para imágenes ya alojadas
 
Si deseas hacer referencia a imágenes que ya están alojadas sin volver a subirlas, usa etiquetas HTML <img> con las siguientes clases de Tailwind CSS para especificar en qué tema deben mostrarse:
 
 
 Copiado
 
// Image only displays when viewing in dark mode
<img class="hidden dark:block" src="https://hf.co/logo-dark.png" alt="Logo" />

// Image only displays when viewing in light mode
<img class="dark:hidden" src="https://hf.co/logo-light.png" alt="Logo" />
 
 ¿Puedo escribir LaTeX en la tarjeta de mi modelo?
 
¡Sí! El Hub utiliza la biblioteca de composición matemática KaTeX para renderizar las fórmulas matemáticas en el servidor antes de analizar el Markdown.
 
Debes usar los siguientes delimitadores:
 
$$ ... $$ para el modo de visualización
 
\\(...\\) para el modo en línea (sin espacio entre las barras y el paréntesis).
 
Entonces, podrás escribir: $$\LaTeX$$ $$\mathrm{MSE} = \left(\frac{1}{n}\right)\sum_{i=1}^{n}(y_{i} - x_{i})^{2}$$ $$E=mc^2$$
  Update on GitHub