Escribir documentación

Para contribuir a tfhub.dev, se debe proporcionar documentación en formato Markdown. Para obtener una descripción general completa del proceso de contribución de modelos a tfhub.devconsulte la guía de contribución de un modelo .

Tipos de documentación de Markdown

Hay 3 tipos de documentación Markdown utilizados en tfhub.dev:

  • Publisher Markdown: información sobre un editor ( consulte la sintaxis de Markdown)
  • Model Markdown: información sobre un modelo específico y cómo usarlo ( consulte la sintaxis de Markdown)
  • Collection Markdown: contiene información sobre una colección de modelos definida por el editor ( consulte la sintaxis de Markdown)

organización de contenido

Se requiere la siguiente organización de contenido al contribuir al repositorio de GitHub de TensorFlow Hub :

  • cada directorio de editor está en el directorio assets/docs
  • cada directorio de editor contiene models opcionales y directorios de collections
  • cada modelo debe tener su propio directorio en assets/docs/<publisher_name>/models
  • cada colección debe tener su propio directorio en assets/docs/<publisher_name>/collections

Las rebajas del editor no están versionadas, mientras que los modelos pueden tener diferentes versiones. Cada versión del modelo requiere un archivo Markdown separado con el nombre de la versión que describe (es decir, 1.md, 2). Las colecciones están versionadas, pero solo se admite una única versión (1).

Todas las versiones de modelo para un modelo determinado deben ubicarse en el directorio del modelo.

A continuación se muestra una ilustración de cómo se organiza el contenido de Markdown:

assets/docs
├── <publisher_name_a>
│   ├── <publisher_name_a>.md  -> Documentation of the publisher.
│   └── models
│       └── <model_name>       -> Model name with slashes encoded as sub-path.
│           ├── 1.md           -> Documentation of the model version 1.
│           └── 2.md           -> Documentation of the model version 2.
├── <publisher_name_b>
│   ├── <publisher_name_b>.md  -> Documentation of the publisher.
│   ├── models
│   │   └── ...
│   └── collections
│       └── <collection_name>
│           └── 1.md           -> Documentation for the collection.
├── <publisher_name_c>
│   └── ...
└── ...

Formato de descuento del editor

La documentación del editor se declara en el mismo tipo de archivos de rebajas que los modelos, con ligeras diferencias sintácticas.

La ubicación correcta para el archivo del editor en el repositorio de TensorFlow Hub es: tfhub.dev/assets/docs /<publisher_id>/<publisher_id.md>

Consulte el ejemplo de documentación mínima del editor para el editor "vtab":

# Publisher vtab
Visual Task Adaptation Benchmark

[![Icon URL]](https://storage.googleapis.com/vtab/vtab_logo_120.png)

## VTAB
The Visual Task Adaptation Benchmark (VTAB) is a diverse, realistic and
challenging benchmark to evaluate image representations.

El ejemplo anterior especifica la identificación del editor, el nombre del editor, la ruta al ícono que se usará y una documentación de descuento de forma libre más larga. Tenga en cuenta que la identificación del editor solo debe contener letras minúsculas, dígitos y guiones.

Directrices sobre el nombre del editor

Su nombre de editor puede ser su nombre de usuario de GitHub o el nombre de la organización de GitHub que administra.

Formato de rebajas de la página del modelo

La documentación del modelo es un archivo Markdown con alguna sintaxis adicional. Consulte el siguiente ejemplo para ver un ejemplo mínimo o un ejemplo más realista de un archivo Markdown .

Documentación de ejemplo

Una documentación de modelo de alta calidad contiene fragmentos de código, información sobre cómo se entrenó el modelo y el uso previsto. También debe utilizar las propiedades de metadatos específicas del modelo que se explican a continuación para que los usuarios puedan encontrar sus modelos en tfhub.dev más rápido.

# Module google/text-embedding-model/1

Simple one sentence description.

<!-- asset-path: https://path/to/text-embedding-model/model.tar.gz -->
<!-- task: text-embedding -->
<!-- fine-tunable: true -->
<!-- format: saved_model_2 -->

## Overview

Here we give more information about the model including how it was trained,
expected use cases, and code snippets demonstrating how to use the model:

```
Code snippet demonstrating use (e.g. for a TF model using the tensorflow_hub library)

import tensorflow_hub as hub

model = hub.KerasLayer(<model name>)
inputs = ...
output = model(inputs)
```

Implementaciones de modelos y agrupaciones de implementaciones

tfhub.dev permite publicar implementaciones de TF.js, TFLite y Coral de un modelo guardado de TensorFlow.

La primera línea del archivo Markdown debe especificar el tipo de formato:

  • # Module publisher/model/version del módulo para modelos guardados
  • # Tfjs publisher/model/version de Tfjs para implementaciones de TF.js
  • # Lite publisher/model/version de Lite para implementaciones de Lite
  • # Coral publisher/model/version de Coral para implementaciones de Coral

Es una buena idea que estos diferentes formatos del mismo modelo conceptual aparezcan en la misma página de modelo en tfhub.dev. Para asociar una implementación determinada de TF.js, TFLite o Coral a un modelo de modelo guardado de TensorFlow, especifique la etiqueta del modelo principal:

<!-- parent-model: publisher/model/version -->

En ocasiones, es posible que desee publicar una o más implementaciones sin un modelo guardado de TensorFlow. En ese caso, deberá crear un modelo de marcador de posición y especificar su identificador en la etiqueta parent-model . El Markdown de marcador de posición es idéntico al Markdown del modelo de TensorFlow, excepto que la primera línea es: # Placeholder publisher/model/version de marcador de posición y no requiere la propiedad asset-path .

Propiedades de metadatos específicas de Model Markdown

Los archivos Markdown pueden contener propiedades de metadatos. Estos se utilizan para proporcionar filtros y etiquetas para ayudar a los usuarios a encontrar su modelo. Los atributos de metadatos se incluyen como comentarios de Markdown después de la breve descripción del archivo de Markdown, por ejemplo

# Module google/universal-sentence-encoder/1
Encoder of greater-than-word length text trained on a variety of data.

<!-- task: text-embedding -->
...

Se admiten las siguientes propiedades de metadatos:

  • format : Para modelos de TensorFlow: el formato de TensorFlow Hub del modelo. Los valores válidos son hub cuando el modelo se exportó a través del formato de concentrador TF1 heredado o saved_model_2 cuando el modelo se exportó a través de un modelo guardado de TF2 .
  • asset-path : la ruta remota legible en todo el mundo a los activos del modelo real para cargar, como a un depósito de Google Cloud Storage. Se debe permitir que el archivo robots.txt obtenga la URL (por este motivo, "https://github.com/. /releases/download/. " no es compatible, ya que está prohibido por https://github .com/robots.txt ). Consulte a continuación para obtener más información sobre el tipo de archivo y el contenido esperados.
  • parent-model : para modelos TF.js/TFLite/Coral: controlador del modelo guardado/marcador de posición adjunto
  • fine-tunable : booleano, si el usuario puede ajustar el modelo.
  • task : el dominio del problema, por ejemplo, "incrustación de texto". Todos los valores admitidos se definen en task.yaml .
  • conjunto de dataset : el conjunto de datos en el que se entrenó el modelo, por ejemplo, "wikipedia". Todos los valores admitidos se definen en dataset.yaml .
  • network-architecture : la arquitectura de red en la que se basa el modelo, por ejemplo, "mobilenet-v3". Todos los valores admitidos se definen en network_architecture.yaml .
  • language : el código de idioma del idioma en el que se entrenó un modelo de texto, por ejemplo, "en". Todos los valores admitidos se definen en language.yaml .
  • license : La licencia que se aplica al modelo, por ejemplo, "mit". La licencia asumida predeterminada para un modelo publicado es Licencia Apache 2.0 . Todos los valores admitidos se definen en license.yaml . Tenga en cuenta que la licencia custom requerirá una consideración especial caso por caso.
  • colab : URL HTTPS a un cuaderno que demuestra cómo se puede usar o entrenar el modelo ( ejemplo para bigbigan-resnet50 ). Debe conducir a colab.research.google.com . Tenga en cuenta que se puede acceder a los cuadernos de Jupyter alojados en GitHub a través de <a href="https://colab.research.google.com/github/ORGANIZATION/PROJECT/">https://colab.research.google.com/github/ORGANIZATION/PROJECT/</a> blob/master/.../my_notebook.ipynb .
  • demo : URL HTTPS a un sitio web que demuestra cómo se puede usar el modelo TF.js ( ejemplo para posenet ).
  • interactive-visualizer : nombre del visualizador que se debe incrustar en la página del modelo, por ejemplo, "visión". Mostrar un visualizador permite a los usuarios explorar las predicciones del modelo de forma interactiva. Todos los valores admitidos se definen en interactive_visualizer.yaml .

Los tipos de documentación de Markdown admiten diferentes propiedades de metadatos obligatorias y opcionales:

Tipo Requerido Opcional
Editor
Recopilación tarea conjunto de datos, idioma, arquitectura de red
Marcador de posición tarea conjunto de datos, ajustable, visualizador interactivo, idioma, licencia, arquitectura de red
Modelo guardado ruta de activos, tarea, ajustable, formato colab, conjunto de datos, visualizador interactivo, idioma, licencia, arquitectura de red
tfjs ruta de activos, modelo principal colab, demostración, visualizador interactivo
ligero ruta de activos, modelo principal colab, visualizador interactivo
Coral ruta de activos, modelo principal colab, visualizador interactivo

Contenido de activos específico del modelo

Según el tipo de modelo, se esperan los siguientes tipos de archivos y contenidos:

  • Modelo guardado: un archivo tar.gz que contiene contenido como este:
saved_model.tar.gz
├── assets/            # Optional.
├── assets.extra/      # Optional.
├── variables/
│     ├── variables.data-?????-of-?????
│     └──  variables.index
├── saved_model.pb
├── keras_metadata.pb  # Optional, only required for Keras models.
└── tfhub_module.pb    # Optional, only required for TF1 models.
  • TF.js: un archivo tar.gz que contiene contenido como este:
tf_js_model.tar.gz
├── group*
├── *.json
├── *.txt
└── *.pb
  • TFLite: un archivo .tflite
  • Coral: un archivo .tflite

Para archivos tar.gz: suponiendo que los archivos de su modelo estén en el directorio my_model (por ejemplo my_model/saved_model.pb para modelos guardados o my_model/model.json para modelos TF.js), puede crear un archivo tar.gz válido utilizando la herramienta tar a través cd my_model && tar -czvf ../model.tar.gz * .

Generalmente, todos los archivos y directorios (comprimidos o sin comprimir) deben comenzar con un carácter de palabra, por lo que, por ejemplo, los puntos no son prefijos válidos de nombres de archivos/directorios.

Formato de descuento de página de colección

Las colecciones son una característica de tfhub.dev que permite a los editores agrupar modelos relacionados para mejorar la experiencia de búsqueda del usuario.

Consulte la lista de todas las colecciones entfhub.dev.

La ubicación correcta para el archivo de colección en el repositorio github.com/tensorflow/tfhub.dev es assets/docs / publisher_name> /collections/ <collection_name> / 1 .Maryland

Aquí hay un ejemplo mínimo que entraría en assets/docs/ vtab /collections/ benchmark / 1 .md. Tenga en cuenta que el nombre de la colección en la primera línea no incluye las collections/ partes que se incluyen en la ruta del archivo.

# Collection vtab/benchmark/1
Collection of visual representations that have been evaluated on the VTAB
benchmark.

<!-- task: image-feature-vector -->

## Overview
This is the list of visual representations in TensorFlow Hub that have been
evaluated on VTAB. Results can be seen in
[google-research.github.io/task_adaptation/](https://google-research.github.io/task_adaptation/)

#### Models
|                   |
|-------------------|
| [vtab/sup-100/1](https://tfhub.dev/vtab/sup-100/1)   |
| [vtab/rotation/1](https://tfhub.dev/vtab/rotation/1) |
|------------------------------------------------------|

El ejemplo especifica el nombre de la colección, una breve descripción de una oración, metadatos del dominio del problema y documentación de rebajas de formato libre.