Rédiger des documents

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Pour contribuer à tfhub.dev, une documentation au format Markdown doit être fournie. Pour un aperçu complet du processus de contribution de modèles à tfhub.devconsultez le guide de contribution d'un modèle .

Types de documentation Markdown

Il existe 3 types de documentation Markdown utilisés dans tfhub.dev:

  • Publisher Markdown - informations sur un éditeur ( voir syntaxe de démarque )
  • Modèle Markdown - informations sur un modèle spécifique et comment l'utiliser ( voir syntaxe de démarquage)
  • Collection Markdown - contient des informations sur une collection de modèles définie par l'éditeur ( voir syntaxe de démarquage)

Organisation du contenu

L'organisation de contenu suivante est requise lors de la contribution au dépôt GitHub de TensorFlow Hub :

  • chaque répertoire d'éditeur se trouve dans le répertoire assets/docs
  • chaque répertoire d'éditeur contient des répertoires de models et collections facultatifs
  • chaque modèle doit avoir son propre répertoire sous assets/docs/<publisher_name>/models
  • chaque collection doit avoir son propre répertoire sous assets/docs/<publisher_name>/collections

Les démarques de l'éditeur ne sont pas versionnées, tandis que les modèles peuvent avoir différentes versions. Chaque version de modèle nécessite un fichier Markdown distinct nommé d'après la version qu'il décrit (c'est-à-dire 1.md, 2). Les collections sont versionnées mais une seule version (1) est prise en charge.

Toutes les versions de modèle pour un modèle donné doivent se trouver dans le répertoire du modèle.

Vous trouverez ci-dessous une illustration de la manière dont le contenu Markdown est organisé :

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>
│   └── ...
└── ...

Format de démarque de l'éditeur

La documentation de l'éditeur est déclarée dans le même type de fichiers de démarquage que les modèles, avec de légères différences syntaxiques.

L'emplacement correct du fichier de l'éditeur sur le référentiel TensorFlow Hub est : tfhub.dev/assets/docs /<publisher_id>/<publisher_id.md>

Consultez l'exemple de documentation minimale de l'éditeur pour l'éditeur "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.

L'exemple ci-dessus spécifie l'identifiant de l'éditeur, le nom de l'éditeur, le chemin d'accès à l'icône à utiliser et une documentation de démarquage libre plus longue. Notez que l'identifiant de l'éditeur ne doit contenir que des lettres minuscules, des chiffres et des tirets.

Directive relative au nom de l'éditeur

Votre nom d'éditeur peut être votre nom d'utilisateur GitHub ou le nom de l'organisation GitHub que vous gérez.

Format de démarque de la page de modèle

La documentation du modèle est un fichier Markdown avec une syntaxe complémentaire. Voir l'exemple ci-dessous pour un exemple minimal ou un exemple de fichier Markdown plus réaliste .

Exemple de documentation

Une documentation de modèle de haute qualité contient des extraits de code, des informations sur la façon dont le modèle a été formé et l'utilisation prévue. Vous devez également utiliser les propriétés de métadonnées spécifiques au modèle expliquées ci-dessous afin que les utilisateurs puissent trouver vos modèles sur tfhub.dev plus rapidement.

# 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)
```

Déploiements de modèles et regroupement de déploiements

tfhub.dev permet de publier les déploiements TF.js, TFLite et Coral d'un TensorFlow SavedModel.

La première ligne du fichier Markdown doit spécifier le type du format :

  • # Module publisher/model/version du module pour SavedModels
  • # Tfjs publisher/model/version Tfjs pour les déploiements TF.js
  • # Lite publisher/model/version Lite pour les déploiements Lite
  • # Coral publisher/model/version Coral pour les déploiements Coral

C'est une bonne idée que ces différents formats du même modèle conceptuel apparaissent sur la même page de modèle sur tfhub.dev. Pour associer un déploiement TF.js, TFLite ou Coral donné à un modèle TensorFlow SavedModel, spécifiez la balise parent-model :

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

Parfois, vous souhaiterez peut-être publier un ou plusieurs déploiements sans TensorFlow SavedModel. Dans ce cas, vous devrez créer un modèle Placeholder et spécifier son handle dans la balise parent-model . L'espace réservé Markdown est identique au Markdown du modèle TensorFlow, sauf que la première ligne est : # Placeholder publisher/model/version et qu'il ne nécessite pas la propriété asset-path .

Propriétés de métadonnées spécifiques au modèle Markdown

Les fichiers Markdown peuvent contenir des propriétés de métadonnées. Ceux-ci sont utilisés pour fournir des filtres et des balises pour aider les utilisateurs à trouver votre modèle. Les attributs de métadonnées sont inclus en tant que commentaires Markdown après la courte description du fichier Markdown, par exemple

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

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

Les propriétés de métadonnées suivantes sont prises en charge :

  • format : pour les modèles TensorFlow : le format TensorFlow Hub du modèle. Les valeurs valides sont hub lorsque le modèle a été exporté via le format de hub TF1 hérité ou saved_model_2 lorsque le modèle a été exporté via un modèle enregistré TF2 .
  • asset-path : le chemin d'accès distant lisible par le monde entier vers les ressources réelles du modèle à télécharger, par exemple vers un bucket Google Cloud Storage. L'URL doit pouvoir être récupérée par le fichier robots.txt (pour cette raison, "https://github.com/. /releases/download/. " n'est pas pris en charge car il est interdit par https://github .com/robots.txt ). Voir ci- dessous pour plus d'informations sur le type de fichier et le contenu attendus.
  • parent-model : Pour les modèles TF.js/TFLite/Coral : handle du SavedModel/Placeholder qui l'accompagne
  • fine-tunable : booléen, si le modèle peut être ajusté par l'utilisateur.
  • task : le domaine du problème, par exemple "text-embedding". Toutes les valeurs prises en charge sont définies dans task.yaml .
  • jeu de dataset : le jeu de données sur lequel le modèle a été formé, par exemple "wikipedia". Toutes les valeurs prises en charge sont définies dans dataset.yaml .
  • network-architecture : l'architecture de réseau sur laquelle le modèle est basé, par exemple "mobilenet-v3". Toutes les valeurs prises en charge sont définies dans network_architecture.yaml .
  • language : le code de langue de la langue sur laquelle un modèle de texte a été formé, par exemple "en". Toutes les valeurs prises en charge sont définies dans language.yaml .
  • license : La licence qui s'applique au modèle, par exemple "mit". La licence supposée par défaut pour un modèle publié est la licence Apache 2.0 . Toutes les valeurs prises en charge sont définies dans license.yaml . Notez que la licence custom nécessitera une attention particulière au cas par cas.
  • colab : URL HTTPS vers un bloc-notes qui montre comment le modèle peut être utilisé ou formé ( exemple pour bigbigan-resnet50 ). Doit mener à colab.research.google.com . Notez que les blocs-notes Jupyter hébergés sur GitHub sont accessibles via <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 vers un site Web qui montre comment le modèle TF.js peut être utilisé ( exemple pour posenet ).
  • interactive-visualizer : nom du visualiseur qui doit être intégré à la page du modèle, par exemple "vision". L'affichage d'un visualiseur permet aux utilisateurs d'explorer les prédictions du modèle de manière interactive. Toutes les valeurs prises en charge sont définies dans interactive_visualizer.yaml .

Les types de documentation Markdown prennent en charge différentes propriétés de métadonnées obligatoires et facultatives :

Taper Obligatoire Optionnel
Éditeur
Le recueil tâche jeu de données, langage, architecture réseau
Espace réservé tâche jeu de données, paramétrable, visualiseur-interactif, langage, licence, architecture-réseau
Modèle enregistré chemin d'accès à l'actif, tâche, réglage fin, format colab, jeu de données, visualiseur-interactif, langage, licence, architecture-réseau
Tfjs chemin d'accès à l'actif, modèle parent colab, démo, visualiseur interactif
léger chemin d'accès à l'actif, modèle parent Colab, visualiseur interactif
corail chemin d'accès à l'actif, modèle parent Colab, visualiseur interactif

Contenu d'actif spécifique au modèle

Selon le type de modèle, les types de fichiers et contenus suivants sont attendus :

  • SavedModel : une archive tar.gz contenant un contenu comme celui-ci :
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 : une archive tar.gz contenant un contenu comme celui-ci :
tf_js_model.tar.gz
├── group*
├── *.json
├── *.txt
└── *.pb
  • TFLite : un fichier .tflite
  • Coral : un fichier .tflite

Pour les archives tar.gz : en supposant que vos fichiers de modèle se trouvent dans le répertoire my_model (par exemple my_model/saved_model.pb pour SavedModels ou my_model/model.json pour les modèles TF.js), vous pouvez créer une archive tar.gz valide à l'aide de l'outil tar via cd my_model && tar -czvf ../model.tar.gz * .

Généralement, tous les fichiers et répertoires (qu'ils soient compressés ou non) doivent commencer par un caractère de mot, par exemple les points ne sont pas un préfixe valide des noms de fichiers/répertoires.

Format de démarque de la page de collection

Les collections sont une fonctionnalité de tfhub.dev qui permet aux éditeurs de regrouper des modèles associés pour améliorer l'expérience de recherche des utilisateurs.

Consultez la liste de toutes les collections surtfhub.dev.

L'emplacement correct du fichier de collection dans le référentiel github.com/tensorflow/tfhub.dev est assets/docs / publisher_name> /collections/ <collection_name> / 1 .Maryland

Voici un exemple minimal qui irait dans assets/docs/ vtab /collections/ benchmark / 1 .md. Notez que le nom de la collection dans la première ligne n'inclut pas la partie collections/ qui est incluse dans le chemin du fichier.

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

L'exemple spécifie le nom de la collection, une courte description d'une phrase, les métadonnées du domaine du problème et une documentation de démarquage de forme libre.